Neo-ZQYY/apps/backend/app/routers/admin_ai.py

# -*- coding: utf-8 -*-
"""
管理端 — AI 监控后台路由。

端点清单（13 个，全部需要 JWT + admin 角色）：
- GET    /api/admin/ai/dashboard                — 总览统计
- GET    /api/admin/ai/trigger-jobs             — 调度任务分页列表
- GET    /api/admin/ai/trigger-jobs/{job_id}    — 调度任务详情
- POST   /api/admin/ai/trigger-jobs/{job_id}/retry — 手动重跑
- GET    /api/admin/ai/run-logs                 — 调用记录分页列表
- GET    /api/admin/ai/run-logs/{log_id}        — 调用记录详情
- POST   /api/admin/ai/cache/invalidate         — 缓存失效
- GET    /api/admin/ai/budget                   — Token 预算
- POST   /api/admin/ai/batch-run                — 创建批量执行（返回预估）
- POST   /api/admin/ai/batch-run/confirm        — 确认批量执行
- GET    /api/admin/ai/alerts                   — 告警列表
- POST   /api/admin/ai/alerts/{log_id}/ack      — 确认告警
- POST   /api/admin/ai/alerts/{log_id}/ignore   — 忽略告警

需求: A1.1, A2.1, A2.4, A3.1, A4.1, A4.3, A5.1, A6.1, A7.1, A7.3, A8.1, A8.2, A8.3, A9.1, A9.2, A9.3
"""

from __future__ import annotations

import logging
from typing import Optional

from fastapi import APIRouter, Depends, HTTPException, Query, status

from app.auth.dependencies import CurrentUser
from app.middleware.permission import require_permission
from app.schemas.admin_ai import (
    AlertActionResponse,
    AlertListResponse,
    BatchRunConfirm,
    BatchRunConfirmResponse,
    BatchRunEstimate,
    BatchRunRequest,
    BudgetResponse,
    CacheInvalidateRequest,
    CacheInvalidateResponse,
    DashboardResponse,
    RetryResponse,
    RunLogDetailResponse,
    RunLogListResponse,
    TriggerJobDetailResponse,
    TriggerJobListResponse,
)
from app.services.ai.admin_service import AdminAIService

logger = logging.getLogger(__name__)

router = APIRouter(prefix="/api/admin/ai", tags=["admin-ai"])


# ── 模块级服务实例 ────────────────────────────────────────
_admin_svc = AdminAIService()


# ── 权限依赖 ──────────────────────────────────────────────


def _require_admin():
    """
    管理端依赖：要求 JWT status=approved 且角色包含 site_admin 或 tenant_admin。
    """

    async def _dependency(
        user: CurrentUser = Depends(require_permission()),
    ) -> CurrentUser:
        admin_roles = {"site_admin", "tenant_admin"}
        if not admin_roles.intersection(user.roles):
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="需要管理员权限（site_admin 或 tenant_admin）",
            )
        return user

    return _dependency


# ── Dashboard ─────────────────────────────────────────────


@router.get("/dashboard", response_model=DashboardResponse)
async def get_dashboard(
    site_id: Optional[int] = Query(None, description="门店 ID 筛选"),
    user: CurrentUser = Depends(_require_admin()),
) -> DashboardResponse:
    """总览统计（支持 site_id 筛选）。"""
    data = await _admin_svc.get_dashboard(site_id=site_id)
    return DashboardResponse(**data)


# ── 调度任务 ──────────────────────────────────────────────


@router.get("/trigger-jobs", response_model=TriggerJobListResponse)
async def list_trigger_jobs(
    event_type: Optional[str] = Query(None),
    status_filter: Optional[str] = Query(None, alias="status"),
    site_id: Optional[int] = Query(None),
    date_from: Optional[str] = Query(None, description="起始日期 YYYY-MM-DD"),
    date_to: Optional[str] = Query(None, description="截止日期 YYYY-MM-DD"),
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=100),
    user: CurrentUser = Depends(_require_admin()),
) -> TriggerJobListResponse:
    """调度任务分页列表。"""
    filters: dict = {}
    if event_type is not None:
        filters["event_type"] = event_type
    if status_filter is not None:
        filters["status"] = status_filter
    if site_id is not None:
        filters["site_id"] = site_id
    if date_from is not None:
        filters["date_from"] = date_from
    if date_to is not None:
        filters["date_to"] = date_to

    data = await _admin_svc.list_trigger_jobs(filters, page=page, page_size=page_size)
    return TriggerJobListResponse(**data)


@router.get("/trigger-jobs/{job_id}", response_model=TriggerJobDetailResponse)
async def get_trigger_job(
    job_id: int,
    user: CurrentUser = Depends(_require_admin()),
) -> TriggerJobDetailResponse:
    """调度任务详情。"""
    data = await _admin_svc.get_trigger_job(job_id)
    if data is None:
        raise HTTPException(status_code=404, detail="调度任务不存在")
    return TriggerJobDetailResponse(**data)


@router.post("/trigger-jobs/{job_id}/retry", response_model=RetryResponse)
async def retry_trigger_job(
    job_id: int,
    user: CurrentUser = Depends(_require_admin()),
) -> RetryResponse:
    """手动重跑：创建新 trigger_job（is_forced=true），异步执行。"""
    try:
        new_job_id = await _admin_svc.retry_trigger_job(job_id)
    except ValueError as exc:
        raise HTTPException(status_code=404, detail=str(exc)) from exc
    return RetryResponse(trigger_job_id=new_job_id, status="pending")


# ── 调用记录 ──────────────────────────────────────────────


@router.get("/run-logs", response_model=RunLogListResponse)
async def list_run_logs(
    app_type: Optional[str] = Query(None),
    status_filter: Optional[str] = Query(None, alias="status"),
    trigger_type: Optional[str] = Query(None),
    site_id: Optional[int] = Query(None),
    date_from: Optional[str] = Query(None, description="起始日期 YYYY-MM-DD"),
    date_to: Optional[str] = Query(None, description="截止日期 YYYY-MM-DD"),
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=100),
    user: CurrentUser = Depends(_require_admin()),
) -> RunLogListResponse:
    """调用记录分页列表。"""
    filters: dict = {}
    if app_type is not None:
        filters["app_type"] = app_type
    if status_filter is not None:
        filters["status"] = status_filter
    if trigger_type is not None:
        filters["trigger_type"] = trigger_type
    if site_id is not None:
        filters["site_id"] = site_id
    if date_from is not None:
        filters["date_from"] = date_from
    if date_to is not None:
        filters["date_to"] = date_to

    data = await _admin_svc.list_run_logs(filters, page=page, page_size=page_size)
    return RunLogListResponse(**data)


@router.get("/run-logs/{log_id}", response_model=RunLogDetailResponse)
async def get_run_log(
    log_id: int,
    user: CurrentUser = Depends(_require_admin()),
) -> RunLogDetailResponse:
    """调用记录详情（含完整 prompt/response/error，不脱敏）。"""
    data = await _admin_svc.get_run_log(log_id)
    if data is None:
        raise HTTPException(status_code=404, detail="调用记录不存在")
    return RunLogDetailResponse(**data)


# ── 缓存管理 ──────────────────────────────────────────────


@router.post("/cache/invalidate", response_model=CacheInvalidateResponse)
async def invalidate_cache(
    body: CacheInvalidateRequest,
    user: CurrentUser = Depends(_require_admin()),
) -> CacheInvalidateResponse:
    """批量缓存失效：将匹配条件的 ai_cache.status 设为 invalidated。"""
    affected = await _admin_svc.invalidate_cache(
        site_id=body.site_id,
        app_type=body.app_type,
        member_id=body.member_id,
    )
    return CacheInvalidateResponse(affected_count=affected)


# ── Token 预算 ────────────────────────────────────────────


@router.get("/budget", response_model=BudgetResponse)
async def get_budget(
    user: CurrentUser = Depends(_require_admin()),
) -> BudgetResponse:
    """Token 预算使用情况：日/月已用量、上限、百分比。"""
    data = await _admin_svc.get_budget()
    return BudgetResponse(**data)


# ── 批量执行 ──────────────────────────────────────────────


@router.post("/batch-run", response_model=BatchRunEstimate)
async def create_batch_run(
    body: BatchRunRequest,
    user: CurrentUser = Depends(_require_admin()),
) -> BatchRunEstimate:
    """创建批量执行请求，返回预估（不立即执行）。"""
    data = await _admin_svc.estimate_batch(
        app_types=body.app_types,
        member_ids=body.member_ids,
        site_id=body.site_id,
    )
    return BatchRunEstimate(**data)


@router.post("/batch-run/confirm", response_model=BatchRunConfirmResponse)
async def confirm_batch_run(
    body: BatchRunConfirm,
    user: CurrentUser = Depends(_require_admin()),
) -> BatchRunConfirmResponse:
    """确认批量执行，后台异步执行。"""
    try:
        await _admin_svc.confirm_batch(batch_id=body.batch_id)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc
    return BatchRunConfirmResponse(status="started")


# ── 告警管理 ──────────────────────────────────────────────


@router.get("/alerts", response_model=AlertListResponse)
async def list_alerts(
    alert_status: Optional[str] = Query(None, description="pending / acknowledged / ignored"),
    site_id: Optional[int] = Query(None),
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=100),
    user: CurrentUser = Depends(_require_admin()),
) -> AlertListResponse:
    """告警列表（ai_run_logs WHERE status IN ('failed','timeout','circuit_open')）。"""
    data = await _admin_svc.list_alerts(
        alert_status=alert_status,
        site_id=site_id,
        page=page,
        page_size=page_size,
    )
    return AlertListResponse(**data)


@router.post("/alerts/{log_id}/ack", response_model=AlertActionResponse)
async def ack_alert(
    log_id: int,
    user: CurrentUser = Depends(_require_admin()),
) -> AlertActionResponse:
    """确认告警：alert_status → acknowledged。"""
    new_status = await _admin_svc.ack_alert(log_id)
    return AlertActionResponse(id=log_id, alert_status=new_status)


@router.post("/alerts/{log_id}/ignore", response_model=AlertActionResponse)
async def ignore_alert(
    log_id: int,
    user: CurrentUser = Depends(_require_admin()),
) -> AlertActionResponse:
    """忽略告警：alert_status → ignored。"""
    new_status = await _admin_svc.ignore_alert(log_id)
    return AlertActionResponse(id=log_id, alert_status=new_status)