track-LICA/backend/app/api/v1/endpoints/screen.py

"""大屏 API — 面向管理层**日常运营与督导**的轻量聚合接口

视角：当月吞吐 / 当前卡点 / 系统活跃度。

与 /dashboard 的区别：/dashboard 面向 PC 后台明细下钻（返回大列表），
/screen 只返回图表直接可用的扁平聚合数据，字段少、无分页、供高频轮询。

⚠️ 2026-09 起不再是「上帝视角」：三个端点都挂了 get_data_scope，
   结果按当前用户的业务分组范围过滤（超管不受限），且不再允许匿名访问。
"""
from fastapi import APIRouter, Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession

from app.core.database import get_db
from app.core.deps import get_data_scope
from app.services.data_scope_service import DataScope
from app.services.screen_service import (
    get_monthly_metrics, MonthlyMetrics,
    get_wip_distribution, WipDistributionResponse,
    get_active_users, ActiveUsersResponse,
)

router = APIRouter(prefix="/screen", tags=["大屏统计"])


@router.get("/monthly-metrics", response_model=MonthlyMetrics)
async def monthly_metrics(
    db: AsyncSession = Depends(get_db),
    scope: DataScope = Depends(get_data_scope),
):
    """
    当月吞吐 — 大屏顶部四张数字卡（按当前用户的数据范围）。

    返回：本月生产流转 / 本月已入库 / 本月已出库 / 本月返厂回流。
    统计区间为北京时间当月 1 日 00:00 至此刻。
    """
    return await get_monthly_metrics(db, scope)


@router.get("/wip-distribution", response_model=WipDistributionResponse)
async def wip_distribution(
    db: AsyncSession = Depends(get_db),
    scope: DataScope = Depends(get_data_scope),
):
    """
    工序积压分布 — 当前数据范围内未完结设备按 overall_status 聚合的**纯数量**。

    返回固定阶段列表（含 0 值），保证柱状图类目稳定、不因缺数据而塌陷；
    工序柱本身也按数据范围裁剪（不属于本组阶段的工序不画）。
    """
    return await get_wip_distribution(db, scope)


@router.get("/active-users", response_model=ActiveUsersResponse)
async def active_users(
    top_n: int = Query(5, ge=1, le=20, description="返回的活跃人员数量"),
    db: AsyncSession = Depends(get_db),
    scope: DataScope = Depends(get_data_scope),
):
    """
    本月系统使用活跃度排行 — 接收 / 转交 / 上传备注次数（按当前用户的数据范围）。

    桥接 /dashboard/user-operations 的统计口径，仅返回本月确实有操作的人员。
    """
    return await get_active_users(db, scope, top_n=top_n)