feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

apps/backend/app/routers/xcx_board.py

@@ -0,0 +1,74 @@
+"""
+看板路由：BOARD-1（助教）、BOARD-2（客户）、BOARD-3（财务）。
+
+前缀 /api/xcx/board，由 main.py 注册。
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+
+from app.auth.dependencies import CurrentUser
+from app.middleware.permission import require_permission
+from app.schemas.xcx_board import (
+    AreaFilterEnum,
+    BoardTimeEnum,
+    CoachBoardResponse,
+    CoachSortEnum,
+    CustomerBoardResponse,
+    CustomerDimensionEnum,
+    FinanceBoardResponse,
+    FinanceTimeEnum,
+    ProjectFilterEnum,
+    SkillFilterEnum,
+)
+from app.services import board_service
+
+router = APIRouter(prefix="/api/xcx/board", tags=["xcx-board"])
+
+
+@router.get("/coaches", response_model=CoachBoardResponse)
+async def get_coach_board(
+    sort: CoachSortEnum = Query(default=CoachSortEnum.perf_desc),
+    skill: SkillFilterEnum = Query(default=SkillFilterEnum.all),
+    time: BoardTimeEnum = Query(default=BoardTimeEnum.month),
+    user: CurrentUser = Depends(require_permission("view_board_coach")),
+):
+    """助教看板（BOARD-1）。"""
+    return await board_service.get_coach_board(
+        sort=sort.value, skill=skill.value, time=time.value,
+        site_id=user.site_id,
+    )
+
+
+@router.get("/customers", response_model=CustomerBoardResponse)
+async def get_customer_board(
+    dimension: CustomerDimensionEnum = Query(default=CustomerDimensionEnum.recall),
+    project: ProjectFilterEnum = Query(default=ProjectFilterEnum.all),
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=20, ge=1, le=100),
+    user: CurrentUser = Depends(require_permission("view_board_customer")),
+):
+    """客户看板（BOARD-2）。"""
+    return await board_service.get_customer_board(
+        dimension=dimension.value, project=project.value,
+        page=page, page_size=page_size, site_id=user.site_id,
+    )
+
+
+@router.get(
+    "/finance",
+    response_model=FinanceBoardResponse,
+    response_model_exclude_none=True,
+)
+async def get_finance_board(
+    time: FinanceTimeEnum = Query(default=FinanceTimeEnum.month),
+    area: AreaFilterEnum = Query(default=AreaFilterEnum.all),
+    compare: int = Query(default=0, ge=0, le=1),
+    user: CurrentUser = Depends(require_permission("view_board_finance")),
+):
+    """财务看板（BOARD-3）。"""
+    return await board_service.get_finance_board(
+        time=time.value, area=area.value, compare=compare,
+        site_id=user.site_id,
+    )