"""健康检查域 Router（HLT-AGG-01 / HLT-AGG-02 / HLT-EXP-01 / HLT-SINGLE / HLT-PROBE）。 本 router 实现渠道健康检查域的全部 HTTP 端点，覆盖聚合健康（简略 / 详细）、 诊断导出、单渠道健康、主动探测共 5 个操作。 模板选型： - HLT-AGG-01 / HLT-AGG-02 / HLT-EXP-01：模板 B（数据面端口路由）， 经 ``use_cases.health_check`` 端口调用 ``HealthCheckService`` 类型化 方法，不经控制面管道。 - HLT-SINGLE / HLT-PROBE：模板 A（控制面端口路由），经 ``use_cases.health_check_control`` 端口调用 ``ChannelControlService`` 类型化方法，走控制面管道五阶段（auth → permission → rate_limit → dispatch → audit）。 鉴权策略：HLT-AGG-01 无鉴权（K8s 探针 + 公开状态页）；其余端点使用 ``get_admin_user`` 依赖，要求管理员角色。角色校验由依赖函数完成，router 内不做角色判断（规范 §4）。 路径设计：静态路径（``/health`` / ``/health/detail`` / ``/health/diagnostics/export``）先于动态路径 （``/{channel_type}/{account_id}/health`` / ``/{channel_type}/{account_id}/probe``）声明，避免 ``/health`` 被捕获为 ``channel_type="health"``（规范 §6.5）。子 router 不自行设置 prefix， 根前缀 ``/channels`` 由 ``channels_router`` 聚合 router 统一追加。 注册顺序：``health_router`` 必须在 ``channels_router`` 聚合中先于含 ``/{channel_type}`` 动态路径的 router（如 ``account_router`` / ``login_router`` / ``directory_router`` 等）注册。 端点清单（对应《健康检查域设计方案》§2.1 + P1 缺口 §2.3.17）： - GET /health HLT-AGG-01 get_health - GET /health/detail HLT-AGG-02 get_health_detail - POST /health/diagnostics/export HLT-EXP-01 export_diagnostics - GET /{channel_type}/{account_id}/health HLT-SINGLE get_single_health - POST /{channel_type}/{account_id}/probe HLT-PROBE probe_channel """ from __future__ import annotations from typing import Any, Literal from fastapi import APIRouter, Depends, Query, Request from pydantic import BaseModel, ConfigDict, Field from yuxi.channels.contract.dtos.channel import ChannelType from yuxi.channels.contract.dtos.health import ( DiagnosticsExportRequest, HealthQuery, ) from yuxi.channels.contract.dtos.health_check import ProbeCmd, SingleHealthQuery from yuxi.storage.postgres.models_business import User from server.routers.channels import ( build_operator, dataclass_to_dict, get_channel_use_cases, raiseOnControlFailure, serialize_control_data, ) from server.utils.auth_middleware import get_admin_user # build_operator 仅在需要构造 Operator 注入端口方法时使用（HLT-EXP-01）。 # HLT-AGG-01 / HLT-AGG-02 的 checkHealth(query) 契约不接受 operator，不构造。 health_router = APIRouter(tags=["channels-health"]) # ---------------- 静态路径端点（须先于动态路径声明） ---------------- @health_router.get("/health", response_model=dict) async def get_health( use_cases=Depends(get_channel_use_cases), ) -> dict[str, Any]: """聚合健康检查（简略，HLT-AGG-01，FR-35）。 无鉴权端点，适用于 K8s liveness/readiness 探针与公开状态页。 返回简略视图：status / version / degraded_components / 简化渠道列表 （channel_type / plugin_state），不暴露 account_id / last_error / worker_status / db_connection_pool_status / circuit_breaker_state 等 运维细节与业务标识，避免无鉴权端点信息泄露。 编排链路：HTTP 入参 → 构造 HealthQuery（with_probe=False）→ use_cases.health_check.checkHealth(query) 直接调用端口方法 → 从 HealthSnapshot 提取简略字段构造响应 dict。 采用模板 B（数据面）：不经过控制面管道，不调用 raiseOnControlFailure， 契约异常由全局 unified_error_handler 统一映射为 HTTP 响应。响应遵循 ``{"success": True, "data": ...}`` 统一结构，K8s 探针仅依赖 HTTP 200 状态码判定存活，不解析响应体结构。 """ query = HealthQuery() snapshot = await use_cases.health_check.checkHealth(query) return { "success": True, "data": { "status": snapshot.status, "version": snapshot.version, "degraded_components": list(snapshot.degraded_components), "channels": [ { "channel_type": ch.channel_type, "plugin_state": ch.plugin_state, } for ch in snapshot.channels ], }, } @health_router.get("/health/detail", response_model=dict) async def get_health_detail( channel_type: ChannelType | None = Query(default=None, description="按渠道过滤（None 表示全渠道）"), with_probe: bool = Query(default=False, description="是否绕过缓存触发实时聚合（非调用 probeChannel）"), use_cases=Depends(get_channel_use_cases), current_user: User = Depends(get_admin_user), ) -> dict[str, Any]: """聚合健康检查（详细，HLT-AGG-02，FR-35）。 管理员鉴权端点，适用于运维排障。返回完整 HealthSnapshot，含 worker_status / redis_stream_status / db_connection_pool_status / 各渠道 circuit_breaker_state / queue_depth / connection_pool_status / trace_id / error_code 等运维字段。 编排链路：HTTP 入参（channel_type / with_probe）→ 构造 HealthQuery（channel_filter / with_probe）→ use_cases.health_check.checkHealth(query) 直接调用端口方法 → dataclass_to_dict(snapshot) 序列化完整快照返回。 采用模板 B（数据面）：不经过控制面管道，不调用 raiseOnControlFailure。 with_probe 参数语义：with_probe=True 绕过短期缓存触发实时聚合， 非调用 probeChannel 端口方法（详见设计方案 §1.5 决策 5）。 checkHealth(query: HealthQuery) 契约不接受 operator 参数（只读无副作用 查询），current_user 仅用于鉴权（get_admin_user 依赖副作用），不在 函数体使用。 """ query = HealthQuery(channel_filter=channel_type, with_probe=with_probe) snapshot = await use_cases.health_check.checkHealth(query) return {"success": True, "data": dataclass_to_dict(snapshot)} # ---------------- Request Schemas ---------------- class DiagnosticsExportPayload(BaseModel): """诊断导出请求体（HLT-EXP-01，Router 层 Pydantic schema）。 字段对齐契约层 DiagnosticsExportRequest DTO，但 operator 由 router 构造（从认证用户），不在 body 中。命名为 ``Payload`` 后缀以区分 Router 层 schema 与契约层 DTO，避免同名冲突（规范反模式：别名导入降低可读性）。 """ model_config = ConfigDict(frozen=True) channel_filter: ChannelType | None = Field(default=None, description="按渠道过滤（None 表示全渠道）") include_audit_logs: bool = Field(default=True, description="是否包含审计日志") audit_log_count: int = Field(default=100, ge=1, le=500, description="审计日志条数上限") include_error_logs: bool = Field(default=True, description="是否包含错误日志") error_log_count: int = Field(default=100, ge=1, le=500, description="错误日志条数上限") # ---------------- Endpoints ---------------- @health_router.post("/health/diagnostics/export", response_model=dict) async def export_diagnostics( payload: DiagnosticsExportPayload, request: Request, use_cases=Depends(get_channel_use_cases), current_user: User = Depends(get_admin_user), ) -> dict[str, Any]: """导出诊断信息包（HLT-EXP-01，FR-35）。 管理员鉴权端点，适用于故障排障。导出 manifest 快照 + 插件状态 + 审计日志 + 错误日志 + 队列深度 + Worker / Redis / DB 池状态， 敏感字段已脱敏（部分遮蔽 app_secret / encrypt_key / verification_token / access_token / refresh_token；全量遮蔽 webhook_secret / webhook_url / password / api_key），审计日志写入 fail-closed。 编排链路：HTTP 入参 → build_operator 构造操作人 → 构造 DiagnosticsExportRequest DTO → use_cases.health_check.exportDiagnostics(request) 直接调用端口方法 → dataclass_to_dict(bundle) 序列化诊断包返回。 对应数据面端口方法 exportDiagnostics（非控制面管道路径）， 不调用 raiseOnControlFailure。敏感字段脱敏由 framework 层 DiagnosticsExporter 完成，router 层不重复脱敏。鉴权由 framework 层 ``get_admin_user`` 守门，对齐端口契约 ``@pre: operator 已通过权限校验 （管理员角色）``，用例服务不重复校验权限（避免双重鉴权）。 """ operator = build_operator(current_user, request) export_request = DiagnosticsExportRequest( operator=operator, channel_filter=payload.channel_filter, include_audit_logs=payload.include_audit_logs, audit_log_count=payload.audit_log_count, include_error_logs=payload.include_error_logs, error_log_count=payload.error_log_count, ) bundle = await use_cases.health_check.exportDiagnostics(export_request) return {"success": True, "data": dataclass_to_dict(bundle)} # ---------------- 动态路径端点（须在静态路径之后声明） ---------------- class ProbeRequest(BaseModel): """主动探测请求体（HLT-PROBE，Router 层 Pydantic schema）。 字段对齐契约层 ``ProbeCmd`` DTO 的非操作人部分，``operator`` 由 router 构造（从认证用户），不在 body 中。``probe_type`` 仅允许 ``connectivity`` 或 ``full``，由 Pydantic Literal 约束在 HTTP 边界即拒绝非法值， 契约层 ``ProbeCmd.__post_init__`` 与控制面管道 dispatch_stage 重复校验 （防御深度）。 """ model_config = ConfigDict(frozen=True) probe_type: Literal["connectivity", "full"] = Field( default="connectivity", description="探测类型（connectivity 仅测连通性，full 含凭据/权限/Webhook 全项检查）", ) timeout_ms: int = Field( default=5000, ge=1000, le=30000, description="探测超时毫秒数（默认 5000，上限 30000）", ) @health_router.get( "/{channel_type}/{account_id}/health", response_model=dict, ) async def get_single_health( 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]: """查询单渠道健康详情（HLT-SINGLE）。 对应控制面操作 ``health/single``（由 ``ChannelControlService.getSingleHealth`` 内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。 聚合指定渠道账户的账户状态、熔断器状态、队列深度、插件状态、连接池状态、 worker 状态等健康指标，供运维排障定位单渠道健康问题。本端点为纯读聚合 （GET 安全方法语义），不触发渠道 API 调用；主动深度探测由 ``POST /{channel_type}/{account_id}/probe``（HLT-PROBE）承担。 编排链路：HTTP 入参 → ``build_operator`` 构造操作人 → 构造 ``SingleHealthQuery`` → ``use_cases.health_check_control.getSingleHealth`` 调用控制面端口方法 → ``ControlResult`` 经 ``raiseOnControlFailure`` 转译 失败 → ``serialize_control_data`` 序列化单渠道健康结果返回。 采用模板 A（控制面）：经 ``health_check_control`` 端口（与数据面 ``health_check`` 字段分离）调用 ``ChannelControlService`` 类型化方法， 走控制面管道五阶段。 """ operator = build_operator(current_user, request) query = SingleHealthQuery( channel_type=channel_type, account_id=account_id, ) result = await use_cases.health_check_control.getSingleHealth(query, operator=operator) raiseOnControlFailure(result) return {"success": True, "data": serialize_control_data(result.data)} @health_router.post( "/{channel_type}/{account_id}/probe", response_model=dict, ) async def probe_channel( channel_type: ChannelType, account_id: str, request: Request, body: ProbeRequest, use_cases=Depends(get_channel_use_cases), current_user: User = Depends(get_admin_user), ) -> dict[str, Any]: """主动深度探测指定渠道（HLT-PROBE）。 对应控制面操作 ``health/probe``（由 ``ChannelControlService.probeChannelDeep`` 内部构造 ``ControlCmd`` 并委托 ``_executeControl`` 执行控制面管道）。 管理员发起的主动深度探测，通过插件 ``ProbeableAdapter.probeDeep`` 执行深度探测（``connectivity`` 仅测连通性，``full`` 含凭据 / 权限 / Webhook 全项检查）。渠道未实现 ``probeDeep`` 时控制面返回 501。 编排链路：HTTP 入参 → ``build_operator`` 构造操作人 → 构造 ``ProbeCmd`` → ``use_cases.health_check_control.probeChannelDeep`` 调用控制面端口方法 → ``ControlResult`` 经 ``raiseOnControlFailure`` 转译失败 → ``serialize_control_data`` 序列化探测结果返回。 采用模板 A（控制面）：经 ``health_check_control`` 端口调用 ``ChannelControlService`` 类型化方法，走控制面管道五阶段。探测可触发 副作用（调用渠道 API），审计事务策略 INDEPENDENT（best-effort）。 """ operator = build_operator(current_user, request) cmd = ProbeCmd( channel_type=channel_type, account_id=account_id, operator=operator, probe_type=body.probe_type, timeout_ms=body.timeout_ms, ) result = await use_cases.health_check_control.probeChannelDeep(cmd) raiseOnControlFailure(result) return {"success": True, "data": serialize_control_data(result.data)}