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 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 可查看全部在途单）。
    """
    return ok(
        dashboard_service.get_dashboard(session, month, current_user=current_user)
    )