b735e24428
主要修改: 1. 修复module-generator中服务重命名时的DI错误 - 对于重命名的服务，直接使用别名注册，避免TypeScript找不到原始名称 - 移除不必要的provide/useClass模式 2. 集成core层到主应用 - 在app.module.ts中导入wwjcloud-core的AppModule - 在wwjcloud-core/src/index.ts中导出AppModule 3. 构建结果 - 编译错误: 64+ -> 0 - 注册路由: 15 -> 678 - Docker服务全部正常启动 - API接口正常响应
241 lines
11 KiB
Markdown
241 lines
11 KiB
Markdown
# 🤖 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` |