dingdanquanliucheng/backend/app/api/reports.py

"""
数据报表路由模块

提供业务数据统计与导出接口，包括：
- 业绩统计报表（支持按月/自定义时间段，可按产品分类筛选）
- 业绩报表导出（支持CSV格式）

URL 前缀：/api/reports
权限要求：manager/admin 角色
"""

from fastapi import APIRouter, Depends, Query
from sqlalchemy.orm import Session

from backend.app.api.deps import require_permissions, require_roles
from backend.app.db import get_db_session
from backend.app.schemas.common import success_payload
from backend.app.services.report_service import report_service

router = APIRouter(prefix="/api/reports", tags=["reports"])


@router.get("/performance")
def performance_report(
    stat_type: str = Query(default="month"),  # 统计类型：month（按月）/ custom（自定义时间段）
    start_date: str | None = Query(default=None),  # 自定义开始日期，格式 YYYY-MM-DD
    end_date: str | None = Query(default=None),  # 自定义结束日期，格式 YYYY-MM-DD
    category_id: int | None = Query(default=None, gt=0),  # 产品分类ID筛选，必须大于0
    exclude_ecommerce: bool = Query(default=False),  # 是否排除电商渠道订单
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("manager", "admin")),  # 当前登录用户，仅manager和admin
    _permission_user: dict = Depends(require_permissions("report:performance:view")),  # 权限校验：业绩报表查看权限
) -> dict:
    """
    获取业绩统计报表

    根据统计类型（按月/自定义时间段）和可选的分类筛选，返回业绩统计数据。

    请求参数：
        stat_type: 统计类型，month 或 custom（默认 month）
        start_date: 开始日期，仅 custom 时有效（可选）
        end_date: 结束日期，仅 custom 时有效（可选）
        category_id: 产品分类ID，可选筛选条件
        exclude_ecommerce: 是否排除电商订单（默认 False）

    返回值：
        业绩统计数据，包含各维度的销售汇总

    权限要求：manager、admin 角色，需 report:performance:view 权限
    """
    return success_payload(
        report_service.performance_report(
            {
                "stat_type": stat_type,
                "start_date": start_date,
                "end_date": end_date,
                "category_id": category_id,
                "exclude_ecommerce": exclude_ecommerce,
            },
            session,
        )
    )


@router.get("/performance/export")
def export_performance_report(
    stat_type: str = Query(default="month"),  # 统计类型：month 或 custom
    start_date: str | None = Query(default=None),  # 自定义开始日期
    end_date: str | None = Query(default=None),  # 自定义结束日期
    category_id: int | None = Query(default=None, gt=0),  # 产品分类ID
    exclude_ecommerce: bool = Query(default=False),  # 是否排除电商渠道订单
    export_format: str = Query(default="csv"),  # 导出格式，默认 csv
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("manager", "admin")),  # 当前登录用户
    _permission_user: dict = Depends(require_permissions("report:performance:export")),  # 权限校验：业绩报表导出权限
) -> dict:
    """
    导出业绩统计报表

    将业绩统计数据导出为文件，支持CSV等格式。参数与业绩查询接口一致，额外支持导出格式选择。

    请求参数：
        stat_type: 统计类型（默认 month）
        start_date: 开始日期（custom 模式可选）
        end_date: 结束日期（custom 模式可选）
        category_id: 产品分类ID（可选）
        exclude_ecommerce: 是否排除电商订单（默认 False）
        export_format: 导出格式，默认 csv

    返回值：
        导出文件的下载链接或文件内容

    权限要求：manager、admin 角色，需 report:performance:export 权限
    """
    return success_payload(
        report_service.export_performance_report(
            {
                "stat_type": stat_type,
                "start_date": start_date,
                "end_date": end_date,
                "category_id": category_id,
                "exclude_ecommerce": exclude_ecommerce,
                "export_format": export_format,
            },
            session,
        )
    )