dingdanquanliucheng/backend/app/api/reminders.py

"""
提醒通知路由模块

提供系统提醒的查询、已读标记及各类自动检测接口，包括：
- 提醒列表查询（支持按类型、状态、接收人筛选）
- 提醒仪表盘（汇总未读/已读数量）
- 标记提醒为已读
- 欠款提醒检测、不活跃客户检测、物流超时检测
- 一键检测全部提醒

URL 前缀：/api/reminders
权限要求：salesman/manager/admin 角色，部分检测接口仅 manager/admin
"""

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

from backend.app.api.deps import require_roles
from backend.app.db import get_db_session
from backend.app.schemas.common import success_payload
from backend.app.services.reminder_service import reminder_service

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


@router.get("")
def list_reminders(
    reminder_type: str | None = Query(default=None),  # 提醒类型筛选（如 arrears/logistics_timeout/inactive_customer）
    status: str | None = Query(default=None),  # 提醒状态筛选（pending/read）
    receiver_user_id: int | None = Query(default=None),  # 接收人用户ID筛选
    page_no: int = Query(default=1),  # 页码，从1开始
    page_size: int = Query(default=20),  # 每页条数
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("salesman", "manager", "admin")),  # 当前登录用户
) -> dict:
    """
    获取提醒列表

    支持按提醒类型、状态、接收人进行筛选，分页返回。
    业务员角色只能查看自己的提醒，管理员和经理可查看所有。

    请求参数：
        reminder_type: 提醒类型（可选）
        status: 状态（可选）
        receiver_user_id: 接收人ID（可选，业务员自动过滤为本人）
        page_no: 页码（默认1）
        page_size: 每页条数（默认20）

    返回值：
        分页的提醒列表数据

    权限要求：salesman、manager、admin 角色
    """
    filters = {
        "reminder_type": reminder_type,
        "status": status,
        "receiver_user_id": receiver_user_id,
        "page_no": page_no,
        "page_size": page_size,
    }
    if current_user.get("role_code") == "salesman":
        filters["receiver_user_id"] = current_user.get("user_id")
    return success_payload(reminder_service.list_reminders(session, filters))


@router.get("/dashboard")
def reminder_dashboard(
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("salesman", "manager", "admin")),  # 当前登录用户
) -> dict:
    """
    获取提醒仪表盘数据

    返回提醒的汇总统计信息（总数、待处理数、已读数）及最新提醒列表。
    业务员只看自己的提醒，管理员和经理可看所有。

    返回值：
        包含以下字段的字典：
        - summary: 汇总统计（total 总数、pending 待处理数、read 已读数）
        - list: 提醒列表（最多200条）
        - checked_at: 最后检查时间

    权限要求：salesman、manager、admin 角色
    """
    filters = {"page_no": 1, "page_size": 200}
    if current_user.get("role_code") == "salesman":
        filters["receiver_user_id"] = current_user.get("user_id")
    reminders = reminder_service.list_reminders(session, filters)
    return success_payload(
        {
            "summary": {
                "total": reminders["total"],
                "pending": len([item for item in reminders["list"] if item["status"] == "pending"]),
                "read": len([item for item in reminders["list"] if item["status"] == "read"]),
            },
            "list": reminders["list"],
            "checked_at": "",
        }
    )


@router.post("/{reminder_id}/read")
def read_reminder(
    reminder_id: int,  # 提醒ID
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("salesman", "manager", "admin")),  # 当前登录用户
) -> dict:
    """
    标记提醒为已读

    将指定ID的提醒标记为已读状态。

    请求参数：
        reminder_id: 路径参数，提醒ID

    返回值：
        操作结果

    权限要求：salesman、manager、admin 角色
    """
    return success_payload(reminder_service.read_reminder(reminder_id, session, current_user))


@router.post("/arrears/check")
def check_arrears_reminders(
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("manager", "admin")),  # 当前登录用户，仅manager和admin
) -> dict:
    """
    检测欠款提醒

    扫描系统中存在欠款的客户，自动生成欠款提醒通知相关业务员。

    返回值：
        检测结果，包含新生成的提醒数量等信息

    权限要求：manager、admin 角色
    """
    return success_payload(reminder_service.check_arrears(session))


@router.post("/inactive-customers/check")
def check_inactive_customer_reminders(
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("manager", "admin")),  # 当前登录用户，仅manager和admin
) -> dict:
    """
    检测不活跃客户提醒

    扫描长期无交易的客户，自动生成不活跃客户提醒通知相关业务员跟进。

    返回值：
        检测结果，包含新生成的提醒数量等信息

    权限要求：manager、admin 角色
    """
    return success_payload(reminder_service.check_inactive_customers(session))


@router.post("/logistics-timeout/check")
def check_logistics_timeout_reminders(
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("manager", "admin")),  # 当前登录用户，仅manager和admin
) -> dict:
    """
    检测物流超时提醒

    扫描超出预计时间未完成的物流任务，自动生成物流超时提醒通知相关人员。

    返回值：
        检测结果，包含新生成的提醒数量等信息

    权限要求：manager、admin 角色
    """
    return success_payload(reminder_service.check_logistics_timeout(session))


@router.post("/check-all")
def check_all_reminders(
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("manager", "admin")),  # 当前登录用户，仅manager和admin
) -> dict:
    """
    一键检测全部提醒

    依次执行欠款检测、不活跃客户检测和物流超时检测，统一生成所有类型的提醒。

    返回值：
        各项检测的汇总结果

    权限要求：manager、admin 角色
    """
    return success_payload(reminder_service.check_all(session))