wwjcloud-nest-v1/wwjcloud-nest-v1/docs/AI-RECOVERY-DEV.md

AI 恢复端点开发指南

本指南汇总 AI 恢复相关端点、环境变量与本地验证步骤，帮助你快速完成端到端诊断与联调。

环境变量

• AI_ENABLED: 启用 AI 层（true|false）。启用后会注册监听器与控制器。
• GLOBAL_PREFIX: 全局前缀，默认 api，实际路由为 /api/...。
• AUTH_ENABLED: 启用鉴权（true|false）。开发环境建议关闭或将路由标记为 @Public()。
• RBAC_ENABLED: 启用 RBAC（true|false）。
• PROMETHEUS_ENABLED: 启用指标端点 /api/metrics。
• AI_SIMULATE_DIRECT_ENQUEUE: 本地/e2e 直接入队，绕过事件总线（true|false）。
• RATE_LIMIT_ENABLED: 启用速率限制守卫（与 RateLimitGuard 对应，true|false）。
• 队列相关（可选）：
  • QUEUE_ENABLED: 开启统一队列抽象（true|false）。
  • QUEUE_DRIVER: bullmq 或 kafka。禁用时使用内存/Redis 回退。
  • QUEUE_KAFKA_*: 当驱动为 kafka 时生效（BROKERS、CLIENT_ID、GROUP_ID、TOPIC_PREFIX）。
  • REDIS_ENABLED: Redis 可选（true|false）。默认 false 使用内存。

模块与端口

• apps/api（默认端口由 PORT 决定，示例为 3001）：
  • 全局守卫：AuthGuard + RbacGuard（可通过 @Public() 跳过鉴权）。
  • 导入 AiModule，包含 AiController 与监听器。
• 根应用 src/AppModule（示例端口 3000）：
  • 使用 WwjCloudPlatformPreset.full()；当 AI_ENABLED=true 时也会导入 AiModule。
  • 默认未注册全局鉴权守卫（更适合开发调试）。

路由速查（带 GLOBAL_PREFIX=api）

• AI 恢复控制器（公共路由，受 RateLimitGuard）：
  • GET /api/ai/recovery/status → 查看队列大小 { size }
  • GET /api/ai/recovery/process-one → 手动处理一个 { ok }
  • GET /api/ai/recovery/drain?max=10 → 批量处理 { processed }
  • GET /api/ai/recovery/simulate-failure?taskId=...&severity=high|medium|low&reason=... → 触发失败事件 { emitted:true }
• 基础设施：
  • GET /api/metrics → Prometheus 指标（包含 ai_events_total、task.failed、task.recovery.requested 等）
  • GET /api/health → Terminus 健康检查

本地验证示例（无令牌）

# 查询队列大小
curl -sS http://localhost:3001/api/ai/recovery/status

# 触发失败事件（高严重度将走 fallback 策略，其它走 retry）
curl -sS "http://localhost:3001/api/ai/recovery/simulate-failure?taskId=manual-1&severity=high&reason=cli"

# 再次查询队列大小（应增长）
curl -sS http://localhost:3001/api/ai/recovery/status

# 处理一个并复查
curl -sS http://localhost:3001/api/ai/recovery/process-one
sleep 0.5
curl -sS http://localhost:3001/api/ai/recovery/status

# 查看指标
curl -sS http://localhost:3001/api/metrics | head -n 50

生产建议

• 安全策略：
  • 对外仅开放只读的 status；将 process-one、drain、simulate-failure 置为鉴权保护或内网访问。
  • 开启 AUTH_ENABLED=true 与 RBAC，使用角色/权限限制操作类端点。
• 队列驱动：
  • 跨进程协同时开启 QUEUE_ENABLED=true 并选择 bullmq 或 kafka，避免内存队列只能单进程消费的限制。
• 观测与稳定性：
  • 开启 PROMETHEUS_ENABLED=true 并抓取 /api/metrics 指标。
  • HttpExceptionFilter 已适配带前缀的 /api/metrics 与 /api/health，异常时保留原始 HTTP 状态码。

常见问题

• Kafka ECONNREFUSED：未启动 Kafka 时会打印连接错误日志，不影响内存模式；禁用队列驱动或改用 BullMQ/Redis。
• 404 路由：确认使用的是 apps/api 应用并带上 GLOBAL_PREFIX=api；根应用在 AI_ENABLED=true 时也会包含同样的 AI 控制器。
• 鉴权误拦截：确保需要公开的路由带 @Public()，或在开发环境临时关闭 AUTH_ENABLED。