PayrollManagementSystem/backend/app/api/v1/dashboard.py

"""工作台接口（M4 ⑧）：三区块聚合 + 最近动态分页。

准入：管理员/财务/领导（与报表、审批接口一致；FR-033/036 的「全部用户」
待业务权限清单 #6 答复后再放宽）。只读接口，不写操作日志。
"""

from typing import Annotated

from fastapi import APIRouter, Depends, Query

from app.api.deps import DbSession, require_roles
from app.core.constants import ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER
from app.core.response import ApiResponse, ok
from app.models import User
from app.schemas.dashboard import ActivityPageOut, ActivityQuery, DashboardOut
from app.services import dashboard_service

router = APIRouter(prefix="/dashboard", tags=["工作台"])

_DashboardUser = Annotated[
    User,
    Depends(require_roles(ROLE_ADMIN, ROLE_FINANCE, ROLE_LEADER, message="无权访问工作台")),
]


@router.get("", response_model=ApiResponse[DashboardOut], summary="工作台三区块")
def get_dashboard(
    session: DbSession,
    current_user: _DashboardUser,
    month: Annotated[
        str | None, Query(max_length=7, description="统计月份 YYYY-MM，默认当月")
    ] = None,
) -> ApiResponse[DashboardOut]:
    """一次返回经营总览/待办/风险预警（待办与预警实时派生）。

    待办按当前用户角色只返回其可操作节点（admin 可查看全部在途单）。
    最近动态是分页列表，走 `GET /dashboard/activities`。
    """
    return ok(dashboard_service.get_dashboard(session, month, current_user=current_user))


@router.get("/activities", response_model=ApiResponse[ActivityPageOut], summary="最近动态（分页）")
def list_dashboard_activities(
    session: DbSession,
    current_user: _DashboardUser,
    query: Annotated[ActivityQuery, Query()],
) -> ApiResponse[ActivityPageOut]:
    """分页查询最近动态，可按模块筛选。

    与聚合端点拆开：翻页只重取这张列表，不必重算总览/待办/预警。
    """
    return ok(dashboard_service.list_activities(session, query))