## AI 规划师：底座完善路线图（面向微服务的一次性落地）

### 目标
- 一次性补齐“微服务刚需底座”，保证当前单体可用、未来可无感切分。
- 全程遵循项目约束：与 PHP 业务/数据一致；与 NestJS 规范一致；最小可行改动。

### 阶段划分与里程碑
- M1 基础通信与契约（D1-D2）
  - 统一错误码与异常过滤器（全局 Filter）
  - 统一响应包装（Interceptor）
  - API 版本化（v1/v2）与 Swagger 分组（/api、/adminapi）
  - 配置中心 Schema 校验（Joi/Zod），启动即校验
  - 验收：/docs OK；错误码/响应统一；配置校验失败阻断启动

- M2 事务与数据访问（D2-D3）
  - 事务助手（Application 开启，共享 EntityManager）
  - 仓储基类（withManager、分页/排序/过滤白名单）
  - 分布式锁（Redis Lock + 看门狗）
  - 验收：示例用例通过；并发压测无脏写；锁可重入/续租

- M3 安全与多租（D3）
  - SiteIdScopeGuard（多租隔离）
  - 幂等（Idempotency-Key + Redis SETNX + TTL）
  - 限流（IP/UID/接口级 令牌桶）
  - 审计日志最小版（配置/权限/删除变更）
  - 验收：关键接口具备限流/幂等；审计写入成功

- M4 事件与队列（D4）
  - 事件总线：DB Outbox 默认，Kafka 可切换；事件契约（事件名/版本/载荷 Schema）
  - 任务队列：Bull/BullMQ 或 DB Jobs；重试/死信/命名规范
  - Saga/补偿基类（占位）
  - 验收：发布/消费示例跑通；切 Kafka 仅改配置；死信与重试可观测

- M5 可观测与稳定性（D4-D5）
  - 健康聚合（DB/Redis/队列/事件/对象存储）
  - 指标（Prometheus）：HTTP/DB/队列/事件/存储基础指标
  - 追踪（OpenTelemetry）：HTTP↔队列↔事件 traceparent 贯通
  - 结构化日志（JSON + traceId + site_id + 采样）
  - 验收：/health 聚合齐全；/metrics 输出基础指标；trace 在链路可见

- M6 vendor 外设标准（并行推进）
  - storage（方案B）：接口+adapters(local/aliyun/qcloud/qiniu)+按 site_id 解析工厂+契约测试
  - providers/registry：多实例缓存 Map<siteId, adapter> + TTL
  - 健康与 Schema：厂商配置校验与健康钩子
  - 验收：站点启用 > 跟随系统 > 本地兜底 生效；契约测试通过

### 目录落位（仅技术底座）
- core/
  - config/{schema.ts, feature-flags.service.ts}
  - http/{filters/http-exception.filter.ts, interceptors/response.interceptor.ts, client/http.client.ts}
  - database/{transaction.manager.ts, base-repository.ts, redis-lock.service.ts}
  - security/{site-scope.guard.ts, idempotency.service.ts, rate-limit.service.ts}
  - event-bus/{outbox.provider.ts, kafka.provider.ts, contracts/*.schema.ts}
  - queue/{bull.provider.ts, db-queue.provider.ts, naming.ts, dead-letter.ts}
  - observability/{health/aggregator.ts, metrics/http.metrics.ts, tracing/otel.ts, logging/logger.ts}
- vendor/
  - storage/（接口+adapters+providers+health+schema+tests）

### 执行顺序（对齐多智能体 S1-S9）
- S1/S2 分析与架构：冻结上述目录与规范
- S3 基建接入体：落地 core 与 vendor 骨架；接入 Kafka/Redis/队列/事务
- S4 开发执行体：实现各模块最小能力与示例接入（settings/storage、upload）
- S5 安全基线体：多租/限流/幂等/权限核查
- S6 质量门禁体：lint/ts/test/e2e/覆盖率阈值
- S7 规范审计体：对照 checklists 差异清单
- S8 发布：变更/迁移/回滚说明
- S9 性能优化体：缓存/异步化/批量化建议

### 验收清单（通过即视为底座完成）
- /health、/metrics、/docs 与追踪链路可用；错误码+响应统一
- 事务助手/仓储基类/锁/限流/幂等 有实例与测试
- 事件总线 Outbox→Kafka 可切；队列有重试/死信与可视化
- vendor/storage 支持站点启用/平台默认/本地兜底；契约测试通过

### 依赖与风险
- 依赖：Redis、数据库可用；Kafka 按需
- 风险：配置校验与权限基线放开可能影响旧路由；需灰度启用与回滚脚本

### 文档联动
- 参见：`./workflow.md`（S1-S9）、`./integration.md`（能力接入）、`../project/vendor.md`（vendor 规范） 