wwjcloud-nest-v1/wwjcloud-nest-v1/docs/V1-GUIDE.md

WWJCloud Nest v1 一体化开发与运维指南

本指南一次性整合并补全 v1 模块的核心内容：目录结构、基础设施、AI 自愈系统、三方集成、配置清单与自动 Java 脚本迁移工具，便于开发/测试/上线统一参考。

概述与目标

• 统一入口：集中说明 v1 的结构、能力与配置，减少分散查找成本。
• 对齐原则：与 Java 保持业务与契约一致，Nest 端用框架化特性落地。
• 可观测、可回归：内置健康检查与指标，提供本地/CI 一致的验证清单。

目录结构（v1）

• apps/api/：主应用（建议端口 3001），统一前缀 GLOBAL_PREFIX=api。
• libs/wwjcloud-boot/：Boot 层能力（请求ID、异常、指标、i18n、DI 提供者）。
• src/：业务模块（Controller、Service、Entity、DTO），遵守命名与分层规范。
• docs/：v1 模块文档，仅在此维护（本页为总览）。

基础设施能力

• 请求ID：启用 REQUEST_ID_ENABLED，响应头携带 X-Request-Id，日志透传。
• 健康检查：GET /api/health、/api/health/quick（轻量无外部依赖）。
• 指标暴露：GET /api/metrics（PROMETHEUS_ENABLED=true），含 http_requests_total、ai_events_total 等。
• 弹性策略：ResilienceService 支持重试/超时/断路器，HttpClientService.getWithFallback 已集成。
• DI 导入规范：Boot 层提供与导出，业务按类型消费，不重复定义令牌/别名。
• Lang：BootLangModule（底层为 BootI18nModule）全局导入，apps/api/src/lang 存放多语言资源，拦截器/过滤器使用 i18n 翻译。

AI 自愈系统（恢复与守卫）

• 控制器与路由（受 RateLimitGuard，开发期可 @Public()）：
  • GET /api/ai/recovery/status → 队列大小 { size }
  • GET /api/ai/recovery/simulate-failure?taskId=...&severity=high|medium|low&reason=... → 触发失败事件
  • POST /api/ai/recovery/process-one → 手动处理一个 { ok }
  • POST /api/ai/recovery/drain → 清空/批量处理 { processed }
• 指标与验证：ai_events_total{event, severity, strategy}；覆盖失败→入队→处理→收敛闭环。
• 守卫建议：
  • 开发：便于联调，路由带 @Public() 或关闭 AUTH_ENABLED/RBAC_ENABLED。
  • 生产：开启 AUTH_ENABLED=true、RBAC_ENABLED=true，status 公开，其它端点受保护；网关/WAF 做来源与速率限制；可启用 RATE_LIMIT_ENABLED=true。

三方集成（规划与启用约定）

• Redis：缓存、分布式锁（Boot 层已具备缓存基础能力）。
• OSS/对象存储：ADDON_OSS_ENABLED=true 后续加载 OssAddonModule（待实现）。
• SMS/短信：ADDON_SMS_ENABLED=true 后续加载 SmsAddonModule（待实现）。
• 支付：ADDON_PAY_ENABLED=true 后续加载 PayAddonModule（待实现）。
• 邮件/通知：NotifyAddonModule（待实现）。
• 约定：ADDON_<NAME>_ENABLED=true|1|yes，由注册器动态加载；目前注册表待补齐。

配置清单（v1 关键环境变量）

• 应用与前缀：NODE_ENV、PORT、GLOBAL_PREFIX=api。
• 基础设施：REQUEST_ID_ENABLED、PROMETHEUS_ENABLED、METRICS_ENABLED、HEALTH_CHECK_ENABLED。
• AI 与守卫：
  • AI_ENABLED：启用 AI 层（采集事件与恢复策略）。
  • AI_SIMULATE_DIRECT_ENQUEUE：本地/e2e 直接入队，绕过事件总线。
  • RATE_LIMIT_ENABLED：启用速率限制守卫（与 RateLimitGuard 对应）。
  • AUTH_ENABLED、RBAC_ENABLED：鉴权与权限控制。
• 队列驱动：QUEUE_DRIVER=memory|redis|kafka；Redis：REDIS_ENABLED/REDIS_*；Kafka：KAFKA_ENABLED/KAFKA_*。
• 弹性与外部请求：HTTP_CLIENT_TIMEOUT_MS、RESILIENCE_*（重试/超时/断路器）。
• Lang：OTEL/语言无强制依赖；语言资源位于 apps/api/src/lang。

自动 Java 脚本迁移工具

• 位置：tools/tools-v1/java-tools/ 与 tools/tools-uni/。
• 用途：从 Java 源仓提取控制器/服务/实体信息，生成或校验 NestJS 端的路由/DTO/实体映射；辅助一致性迁移与验证。
• 建议流程：
  • 配置源路径（如 niucloud-java/*、sql/wwjcloud.sql）。
  • 运行脚本产出映射报告与待生成清单。
  • 按报告同步生成/修复 NestJS 模块，并以 CI/e2e 验证闭环。

本地与 CI 验证清单

• 启动：PORT=3001、GLOBAL_PREFIX=api、AI_ENABLED=true、QUEUE_DRIVER=memory。
• 健康与指标：GET /api/health、GET /api/metrics 存在并返回合理状态与指标。
• AI 闭环：
  • GET /api/ai/recovery/status 初始大小
  • GET /api/ai/recovery/simulate-failure?... 队列增长
  • POST /api/ai/recovery/process-one 收敛
• 守卫切换：开发无令牌可访问；生产开启 AUTH/RBAC 后仅 status 公开，其余需 admin 角色。

参考与扩展

• 详细 AI 开发与安全：AI-RECOVERY-DEV.md、AI-RECOVERY-SECURITY.md
• 基础设施与配置：V11-INFRA-SETUP.md
• 一致性与对齐：CONSISTENCY-GUIDE.md
• 国际化接入：LANG-GUIDE.md

---

注：本页为 v1 的“一体化总览”，作为开发与运维的统一入口。若新增能力（如 Addon 注册、OpenTelemetry、速率限制扩展），请在此页与对应子文档同步更新。

别名与模块边界约定（强制）

• 别名映射：

  • @wwjBoot → 顶层平台装配与入口（BootModule、preset），不用于引入具体基础设施。
  • @wwjCommon → 跨领域基础设施（http/*、response/*、metrics/*、cache/*、queue/*、auth/*、tenant/*、lang/*）。
  • @wwjVendor → 第三方驱动适配（pay/*、sms/*、upload/*、notice/*），按接口/Token 注入，保持“可选”。
  • @wwjAi → AI 能力（Tuner/Safe/Manager/Healing 等），允许依赖 @wwjCommon，禁止反向依赖 @wwjBoot。

• 使用规则：

  • 业务与 AI 层只从 @wwjCommon/* 引入基础设施；禁用 @wwjBoot/infra/* 形式（语义不一致）。
  • BootLangModule（软别名）用于在应用层一次性导入 i18n；拦截器/过滤器对 i18n 采取软依赖与兜底，详见 LANG-GUIDE.md。
  • Vendor 驱动均为“可选”并按接口注入，业务避免直接耦合具体实现；文档需标注启用条件与默认存根行为。

• 预设入口（建议）：

  • preset.core：不含 AI，仅基础设施（Boot 核心）。
  • preset.full：含 AI（当前默认）。应用可按 AI_ENABLED 切换或选择入口以降低编译耦合。

• 代码规范（建议）：

  • ESLint no-restricted-imports 禁止 @wwjBoot/infra/* 导入；统一走 @wwjCommon/*。
  • 文档在 CONSISTENCY-GUIDE.md 与本页保持别名与边界约定的一致说明。