ForcePilot/backend/server/routers/channels/doctor_router.py

"""配置诊断 Router。

路由分一类：
    - 诊断端点（GET /checks / GET /checks/{check_id} / POST /checks/run-all /
      POST /checks/{check_id}/run / POST /checks/{check_id}/repair/preview /
      POST /checks/{check_id}/repair）：控制面操作，通过 DoctorPort 走
      控制面管道，统一执行认证 / 权限 / 限流 / 分派 / 审计五阶段（模板 A）。
      失败时通过 ``raiseOnControlFailure`` 反向重构异常交由全局 handler 映射。

端口装配：
    - ``use_cases.doctor`` 字段绑定到 ``ChannelControlService`` 同一实例
      （窄端口依赖，由 ``infrastructure/channel_use_cases.py`` 装配）

鉴权策略：
    - 全部端点使用 ``get_admin_user`` 依赖（管理员角色校验）
    - 无 Webhook 入站端点，无匿名访问
"""

from __future__ import annotations

from typing import Any

from fastapi import APIRouter, Depends, Request

from yuxi.channels.contract.dtos.channel import ChannelType
from yuxi.channels.contract.errors import InternalError, NotFoundError
from yuxi.storage.postgres.models_business import User

from server.routers.channels import (
    build_operator,
    get_channel_use_cases,
    raiseOnControlFailure,
    serialize_control_data,
)
from server.utils.auth_middleware import get_admin_user

doctor_router = APIRouter(tags=["channels-doctor"])


@doctor_router.get(
    "/{channel_type}/{account_id}/doctor/checks",
    response_model=dict,
)
async def list_doctor_checks(
    channel_type: ChannelType,
    account_id: str,
    request: Request,
    use_cases=Depends(get_channel_use_cases),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """查询诊断检查项列表（DOC-CHECK-01，FR-17）。

    对应控制面操作 ``doctor/checks``（由 ``ChannelControlService.getDoctorChecks``
    内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
    返回指定渠道账户的诊断检查项列表，包括插件声明的检查项与框架级
    默认检查项。渠道未注册诊断适配器时返回 501。
    """
    operator = build_operator(current_user, request)
    result = await use_cases.doctor.getDoctorChecks(
        channel_type=channel_type,
        account_id=account_id,
        operator=operator,
    )
    raiseOnControlFailure(result)
    return {"success": True, "data": serialize_control_data(result.data)}


@doctor_router.post(
    "/{channel_type}/{account_id}/doctor/checks/run-all",
    response_model=dict,
)
async def run_all_doctor_checks(
    channel_type: ChannelType,
    account_id: str,
    request: Request,
    use_cases=Depends(get_channel_use_cases),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """运行全部诊断检查（DOC-CHECK-03，FR-17，AC-19 / AC-64）。

    对应控制面操作 ``doctor/run``（由 ``ChannelControlService.runDoctorChecks``
    内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
    执行 6 项框架级默认检查（credential_validity / required_permissions /
    webhook_registered / webhook_reachable / rate_limit_status /
    whitelist_status）+ 适配器自定义检查项，聚合为诊断报告（含整体健康度、
    检查项结果列表、已应用迁移列表）。单项检查异常不中断整体流程
    （_safeRunItem 捕获非 DependencyError 降级为"未通过 + ERROR"）。
    """
    operator = build_operator(current_user, request)
    result = await use_cases.doctor.runDoctorChecks(
        channel_type=channel_type,
        account_id=account_id,
        operator=operator,
    )
    raiseOnControlFailure(result)
    return {"success": True, "data": serialize_control_data(result.data)}


@doctor_router.get(
    "/{channel_type}/{account_id}/doctor/checks/{check_id}",
    response_model=dict,
)
async def get_doctor_check(
    channel_type: ChannelType,
    account_id: str,
    check_id: str,
    request: Request,
    use_cases=Depends(get_channel_use_cases),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """查询单项检查项元信息（DOC-03，FR-17）。

    复用控制面操作 ``doctor/checks``（由 ``ChannelControlService.getDoctorChecks``
    内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。
    返回检查项清单后由 router 层按 ``check_id`` 筛选单项元信息（check_id /
    name / severity / description / auto_repairable）。检查项不存在返回 404。

    注意：本端点与 DOC-CHECK-01 共享同一端口方法 ``getDoctorChecks``，
    router 层从检查项列表中筛选指定 ``check_id``。这是协议层的字段筛选
    （从已有数据中按 ID 过滤，不涉及业务规则判断），符合 INV-8（驱动
    适配器无业务规则）。检查项不存在时抛 ``NotFoundError``（契约层异常，
    非 HTTPException），交由全局 handler 映射为 404。

    已知技术债务（GAP-06）：当前复用 ``getDoctorChecks`` 全量查询后筛选，
    未来应在端口层新增 ``getDoctorCheck`` 单项查询方法，避免全量查询开销。
    当前复用现有端口方法以最小化契约变更。
    """
    operator = build_operator(current_user, request)
    result = await use_cases.doctor.getDoctorChecks(
        channel_type=channel_type,
        account_id=account_id,
        operator=operator,
    )
    raiseOnControlFailure(result)
    if not isinstance(result.data, dict):
        raise InternalError(message="control pipeline returned malformed data for doctor checks")
    checks = result.data.get("checks", [])
    target = next((c for c in checks if c.get("check_id") == check_id), None)
    if target is None:
        raise NotFoundError(
            resource="doctor_check",
            id=check_id,
        )
    return {"success": True, "data": serialize_control_data(target)}


@doctor_router.post(
    "/{channel_type}/{account_id}/doctor/checks/{check_id}/run",
    response_model=dict,
)
async def run_doctor_check(
    channel_type: ChannelType,
    account_id: str,
    check_id: str,
    request: Request,
    use_cases=Depends(get_channel_use_cases),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """运行单项诊断检查（DOC-CHECK-02，FR-17）。

    对应控制面操作 ``doctor/checks/{check_id}/run``（由
    ``ChannelControlService.runDoctorCheck`` 内部构造 ``ControlCmd`` 并
    委托 ``_executeControl`` 执行控制面管道）。``check_id`` 格式由
    ``ChannelControlService._validateCheckId`` 校验（正则
    ``^[A-Za-z0-9_-]+$``），格式非法返回 400；检查项不存在返回 404；
    渠道未注册诊断适配器返回 501。
    """
    operator = build_operator(current_user, request)
    result = await use_cases.doctor.runDoctorCheck(
        channel_type=channel_type,
        account_id=account_id,
        check_id=check_id,
        operator=operator,
    )
    raiseOnControlFailure(result)
    return {"success": True, "data": serialize_control_data(result.data)}


@doctor_router.post(
    "/{channel_type}/{account_id}/doctor/checks/{check_id}/repair/preview",
    response_model=dict,
)
async def preview_doctor_repair(
    channel_type: ChannelType,
    account_id: str,
    check_id: str,
    request: Request,
    use_cases=Depends(get_channel_use_cases),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """修复方案预览（DOC-02，FR-17 / AC-40，dry-run）。

    对应控制面操作 ``doctor/checks/{check_id}/repair``（由
    ``ChannelControlService.repairDoctorCheck`` 内部构造 ``ControlCmd`` 并
    委托 ``_executeControl`` 执行控制面管道），传入 ``confirmed=False``。
    返回含修复方案（repair_plan）的检查结果，不执行修复。检查项不支持
    自动修复时返回 400；检查项不存在返回 404；渠道未注册诊断适配器返回 501。
    """
    operator = build_operator(current_user, request)
    result = await use_cases.doctor.repairDoctorCheck(
        channel_type=channel_type,
        account_id=account_id,
        check_id=check_id,
        confirmed=False,
        operator=operator,
    )
    raiseOnControlFailure(result)
    return {"success": True, "data": serialize_control_data(result.data)}


@doctor_router.post(
    "/{channel_type}/{account_id}/doctor/checks/{check_id}/repair",
    response_model=dict,
)
async def execute_doctor_repair(
    channel_type: ChannelType,
    account_id: str,
    check_id: str,
    request: Request,
    use_cases=Depends(get_channel_use_cases),
    current_user: User = Depends(get_admin_user),
) -> dict[str, Any]:
    """执行修复（DOC-REP-01，FR-17 / AC-40）。

    对应控制面操作 ``doctor/checks/{check_id}/repair``（由
    ``ChannelControlService.repairDoctorCheck`` 内部构造 ``ControlCmd`` 并
    委托 ``_executeControl`` 执行控制面管道），传入 ``confirmed=True``。
    执行 ``adapter.autoFix`` 修复后复检返回结果；修复失败时返回原检查结果
    "未通过"，不修改渠道配置（AC-40）。检查项不支持自动修复时返回 400；
    检查项不存在返回 404；渠道未注册诊断适配器返回 501。
    """
    operator = build_operator(current_user, request)
    result = await use_cases.doctor.repairDoctorCheck(
        channel_type=channel_type,
        account_id=account_id,
        check_id=check_id,
        confirmed=True,
        operator=operator,
    )
    raiseOnControlFailure(result)
    return {"success": True, "data": serialize_control_data(result.data)}