# 🤖 AI智能体工作流程指南

## 📋 概述

本文档为AI开发者提供完整的智能体协作工作流程，确保AI能够高效、规范地完成NestJS项目开发，同时与Java项目保持100%业务一致性。

## 🎯 核心目标

- **框架层面**: 100% 使用 NestJS 的方式
- **业务层面**: 与 Java 项目保持 100% 一致
- **数据层面**: 与 Java 项目数据库结构 100% 一致

## 🚫 AI开发严格约束条件（必须遵守）

### 绝对禁止的AI行为

1. **🚫 禁止自创业务逻辑** - 所有业务逻辑必须严格基于Java项目真实代码
2. **🚫 禁止假设数据结构** - 所有数据结构必须基于 `sql/wwjcloud.sql` 真实表结构
3. **🚫 禁止使用默认值** - 所有字段、方法、配置必须基于Java项目真实值
4. **🚫 禁止编写骨架代码** - 不允许生成空方法、TODO注释或占位符代码
5. **🚫 禁止写死数据** - 不允许硬编码任何业务数据或配置
6. **🚫 禁止猜测API接口** - 所有接口必须基于Java控制器真实方法
7. **🚫 禁止随意命名** - 所有命名必须遵循既定规范，不允许自由发挥
8. **🚫 禁止跳过验证** - 每个生成的文件都必须经过严格验证

### 必须遵循的数据源

- **数据库结构**: `sql/wwjcloud.sql` (唯一权威数据源)
- **Java控制器**: `niucloud-java/niucloud-core/src/main/java/.../controller/` (API接口定义)
- **Java服务层**: `niucloud-java/niucloud-core/src/main/java/.../service/` (业务逻辑实现)
- **Java实体**: `niucloud-java/niucloud-core/src/main/java/.../entity/` (数据模型定义)
- **Java验证器**: `niucloud-java/niucloud-core/src/main/java/.../validator/` (数据验证规则)

### AI开发质量标准

- **数据库字段映射准确率**: 100%
- **Java方法对应准确率**: 100%
- **业务逻辑一致性**: 100%
- **代码可直接运行**: 100%
- **命名规范符合率**: 100%

### AI开发检查清单

- [ ] 已查看对应的Java源码文件
- [ ] 已查看相关的数据库表结构
- [ ] 已理解真实的业务逻辑
- [ ] 已确认所有依赖关系
- [ ] 已验证生成代码的正确性
- [ ] 已使用auto-mapping-checker.js验证

## 🤖 智能体角色定义（按执行顺序标注）

### S1 需求分析体(Analyzer)
- **职责**: 解析需求、对应 Java/Nest 规范、输出任务切分与验收标准
- **输入**: 业务需求/接口变更/对齐 Java 的说明
- **输出**: 模块划分、路由表、DTO、实体字段清单、与 DB/Spring Boot 对照

### S2 架构治理体(Architect)
- **职责**: 校验分层/依赖/目录规范，给出重构建议与边界清单
- **校验**: 模块目录、分层(Application/Core/Infrastructure)、依赖方向(App→Common→Core→Vendor)
- **输出**: 设计说明、端口(Repository/Provider)定义、删除/迁移建议

### S3 基建接入体(InfraOperator)
- **职责**: 接入/校验 Kafka、Redis、队列、事务与配置，提供接入差异与示例
- **接入**: Kafka/Redis/队列/事务的工程化接入与配置
- **产物**: 接入差异与示例代码，健康检查/配置项校验清单

### S4 开发执行体(Developer)
- **职责**: 按规范编码、编写测试、修复构建（严格禁止自创、假设、默认值）
- **实现**: Controller 仅路由+DTO校验；AppService 编排；Core 规则；Infra 实现；Entity 对齐 DB
- **接入**: 守卫(RBAC)、Pipes(JSON/Timestamp)、拦截器(请求日志)、事件与队列
- **测试**: 单测/集成/e2e，构建通过

### S5 安全基线体(SecurityGuard)
- **职责**: 检查守卫、跨租户(site_id)隔离、敏感信息暴露（开发中与提测前各执行一次）
- **检查**: 控制器守卫、site_id 隔离、敏感字段输出、配置权限

### S6 质量门禁体(QualityGate)
- **职责**: 聚合 ESLint/TS/覆盖率/e2e 结果，低于阈值阻断合并
- **指标**: ESLint/TS 无报错；覆盖率≥阈值；e2e 关键路径通过
- **动作**: 不达标阻断合并

### S7 规范审计体(Auditor)
- **职责**: 按清单逐项核查，出具差异报告与修复项
- **检查**: 规范清单，字段/命名/路由/守卫/事务/队列/事件 与 Java/DB 对齐
- **产物**: 差异报告与修复任务

### S8 上线管控体(Release)
- **职责**: 构建、变更说明、灰度计划与回滚预案
- **产出**: 变更日志、部署步骤、数据迁移脚本、回滚预案

### S9 性能优化体(PerfTuner)
- **职责**: 建议缓存/异步化/批处理，识别大对象传输与 N+1（开发后期与上线后持续执行）
- **建议**: 缓存、异步化、批量化、索引与查询优化；识别 N+1、大对象传输

### S10 命名规范体(NamingGuard)
- **职责**: 检查文件/类/方法/变量命名规范，确保符合大厂标准（开发中持续执行）
- **检查**: 文件命名、类命名、方法命名、变量命名、数据库命名、API命名
- **输出**: 命名规范检查报告、不符合规范的命名列表、修复建议

## 🔄 串联流程（带顺序）

1. **S1 Analyzer** → 输入业务需求，输出模块划分、路由表、DTO、实体字段清单
2. **S2 Architect** → 校验模块目录、分层、依赖方向，输出设计说明
3. **S3 InfraOperator** → 接入基础设施，产出接入差异与示例代码
4. **S4 Developer** → 实现业务逻辑，接入守卫、管道、拦截器
5. **S5 SecurityGuard（第一次）** → 开发阶段安全检查
6. **S6 QualityGate** → CI阶段质量检查，不达标阻断合并
7. **S7 Auditor** → 提测前规范审计
8. **S5 SecurityGuard（第二次）** → 提测前安全复检
9. **S9 PerfTuner** → 性能优化建议（并行/持续）
10. **S10 NamingGuard** → 命名规范检查（开发中持续执行）
11. **S8 Release** → 上线管控

## 🏗️ 架构设计三原则

### 1. 功能组织结构 → 参考 Java/Spring Boot 分层架构

- **模块化优先**：按业务域划分模块（如user、order、payment），而非按技术层级划分
- **单体向微服务演进**：每个模块内部完整包含Controller、Service、Entity、DTO等层级
- **模块自治**：每个模块可独立开发、测试、部署，为后续微服务拆分做准备
- **层级内聚**：模块内部按Spring Boot分层架构组织（Controller→Service→Repository→Entity）
- **模块间解耦**：模块间通过明确的接口和事件进行通信，避免直接依赖

### 2. 功能复写实现 → 参考 Java项目 的业务逻辑

- 所有业务逻辑必须严格基于Java项目真实代码
- API接口功能与Java控制器保持100%一致
- 数据处理流程与Java服务层保持100%一致
- 业务规则与Java验证器保持100%一致

### 3. 框架特性使用 → 使用 NestJS 的技术特性

- 依赖注入(DI)：模块化管理，服务注入
- 装饰器(Decorators)：路由定义，参数验证，权限控制
- 管道(Pipes)：数据转换，输入验证
- 守卫(Guards)：身份认证，权限验证
- 拦截器(Interceptors)：请求响应处理，日志记录
- 模块化(Modules)：功能模块划分，依赖管理

## 🛠️ 自动化工具集成

### auto-mapping-checker.js 使用指南

```bash
# 检查Java和NestJS项目对应关系
node auto-mapping-checker.js

# 检查结果解读：
# ✅ 表示文件对应正确
# ❌ 表示Java存在但NestJS缺失
# 📊 统计信息：检查模块数、发现问题数
```

### 工具检查维度

- **模块对应性**: Java模块与NestJS模块一一对应
- **分层完整性**: 控制器、服务、实体等层级完整
- **文件命名规范**: 确保命名符合各自框架规范
- **业务逻辑一致性**: 功能实现与Java项目保持一致

## 📚 相关文档

- [三框架原则对比](./FRAMEWORK-PRINCIPLES.md)
- [AI开发禁止规则](./AI-DEVELOPMENT-RULES.md)
- [项目整体结构参考](./PROJECT-STRUCTURE.md)
- [AI框架功能对比](./AI-FRAMEWORK-COMPARISON.md)
- [命名规范指南](./NAMING-CONVENTIONS.md)

## 🎯 执行与验收（CI/PR 建议）

- PR 必须通过: build、单测/集成/e2e
- 审计体根据规范清单自动评论差异（字段/命名/路由/守卫/事务/队列/事件）
- 命名规范体(NamingGuard)检查所有文件命名、类命名、方法命名、变量命名
- 安全基线: 管理端控制器统一 `JwtAuthGuard + RolesGuard`；/adminapi 与 /api 路由前缀

## 🔗 核心约束

- 与 Java 业务/数据100%一致；与 NestJS 规范100%匹配
- 禁止创建 DB 不存在字段；`sys_config.value(JSON)` 统一
- 管理端路由 `/adminapi`，前台 `/api`；统一守卫与响应格式

## 📝 基础能力检查点

### 事务处理
- 仅在 Application 开启；多仓储共享同一 EntityManager；Core 不直接操作事务对象

### 队列处理
- 用例完成后入队；载荷仅传关键 ID；处理器在 Infrastructure；按队列名分域

### 事件处理
- 统一用 DomainEventService；事件名 `domain.aggregate.action`；默认 DB Outbox，可切 Kafka

### Redis缓存
- 短缓存配置读取、上传限流/防刷（计数器）、幂等(SETNX+TTL)

---

**重要提醒**: 本文档是AI开发的核心指南，所有AI智能体必须严格遵循此工作流程，确保开发质量和规范一致性。

## ✅ AI 恢复队列操作清单（务实闭环）

### 环境准备
- 设置：`AI_ENABLED=true`、`GLOBAL_PREFIX=api`
- 开发驱动：`QUEUE_DRIVER=memory`（免 Redis/Kafka 干扰）
- 端口建议：`apps/api` 在 `3001`

### 验证步骤
```bash
# 1) 队列初始状态
curl -s http://localhost:3001/api/ai/recovery/status

# 2) 模拟失败事件（入队增长）
curl -s "http://localhost:3001/api/ai/recovery/simulate-failure?taskId=T1&severity=high&reason=workflow"

# 3) 再次查看队列（确认增长）
curl -s http://localhost:3001/api/ai/recovery/status

# 4) 处理一个恢复请求（收敛）
curl -s -X POST http://localhost:3001/api/ai/recovery/process-one

# 5) 清空队列（可选）
curl -s -X POST http://localhost:3001/api/ai/recovery/drain
```

### 产出物（各智能体对应）
- S3 InfraOperator：`CONFIG_SETUP.md` 更新 AI 环境项与驱动策略
- S4 Developer：`AiController` 路由联通，端到端闭环日志截图/记录
- S6 QualityGate：e2e 用例覆盖事件→入队→处理→收敛
- S7 Auditor：检查 `GLOBAL_PREFIX`、异常过滤器状态码策略、端口映射一致性
- S8 Release：变更说明与生产守卫策略（移除或保护 `@Public()`）

### 生产策略提醒
- 路由守卫：生产环境请加 `JwtAuthGuard/RolesGuard` 或在网关层做访问控制
- 队列驱动：选 `redis` 或 `kafka`，实现跨进程/跨实例协同
- 观测性：按需开启指标与追踪，采样与暴露端口需合规

### 参考链接
- 配置指南：`docs/CONFIG_SETUP.md`
- 开发指南：`docs/DEVELOPMENT-GUIDE.md`
- 端点细节：`docs/AI-RECOVERY-DEV.md`
### 代码对齐执行流程（必须）
- 步骤 1：全量扫描
  - 匹配模式：`getSiteId\(\)\s*\|\|\s*0`、`Number\(this\.requestContext\.getSiteId\(\) \|\| 0\)`、`RequestUtils\.channel\(\) \|\|\s*['"]h5['"]`、控制器手工注入上下文字段（如 `param.siteId = ...`）。
- 步骤 2：按批次修改
  - 批次 A：统一改为 `RequestContextService.getSiteId()` 或使用 `param.siteId/param.memberId`，禁止默认值。
  - 批次 B：渠道来源改为 `RequestUtils.channel()`，默认值由方法内部提供。
  - 批次 C：控制器移除手工注入上下文字段；服务层从上下文或 `param` 读取。
  - 批次 D：参数名/路由/返回结构与 VO 子对象对齐 Java（示例：`out_trade_no`、微信 `{ data: '<json-string>' }`、提现 `transfer` 子对象）。
- 步骤 3：验证与验收
  - 运行扫描自检，确保批次关键模式清零。
  - 对照 Java 文件确认路由/方法/参数/返回结构一致；异常信息一致。
  - 合并前必须满足《开发指导原则》的“验收标准”。