199 lines
9.0 KiB
Markdown
199 lines
9.0 KiB
Markdown
|
# 🤖 AI智能体工作流程指南
|
|||
|
|
|
|||
|
|
## 📋 概述
|
|||
|
|
|
|||
|
|
本文档为AI开发者提供完整的智能体协作工作流程，确保AI能够高效、规范地完成NestJS项目开发，同时与PHP项目保持100%业务一致性。
|
|||
|
|
|
|||
|
|
## 🎯 核心目标
|
|||
|
|
|
|||
|
|
- **框架层面**: 100% 使用 NestJS 的方式
|
|||
|
|
- **业务层面**: 与 PHP 项目保持 100% 一致
|
|||
|
|
- **数据层面**: 与 PHP 项目数据库结构 100% 一致
|
|||
|
|
|
|||
|
|
## 🚫 AI开发严格约束条件（必须遵守）
|
|||
|
|
|
|||
|
|
### 绝对禁止的AI行为
|
|||
|
|
|
|||
|
|
1. **🚫 禁止自创业务逻辑** - 所有业务逻辑必须严格基于PHP项目真实代码
|
|||
|
|
2. **🚫 禁止假设数据结构** - 所有数据结构必须基于 `g:\wwjcloud-nestjs\sql\wwjcloud.sql` 真实表结构
|
|||
|
|
3. **🚫 禁止使用默认值** - 所有字段、方法、配置必须基于PHP项目真实值
|
|||
|
|
4. **🚫 禁止编写骨架代码** - 不允许生成空方法、TODO注释或占位符代码
|
|||
|
|
5. **🚫 禁止写死数据** - 不允许硬编码任何业务数据或配置
|
|||
|
|
6. **🚫 禁止猜测API接口** - 所有接口必须基于PHP控制器真实方法
|
|||
|
|
7. **🚫 禁止随意命名** - 所有命名必须遵循既定规范，不允许自由发挥
|
|||
|
|
8. **🚫 禁止跳过验证** - 每个生成的文件都必须经过严格验证
|
|||
|
|
|
|||
|
|
### 必须遵循的数据源
|
|||
|
|
|
|||
|
|
- **数据库结构**: `g:\wwjcloud-nestjs\sql\wwjcloud.sql` (唯一权威数据源)
|
|||
|
|
- **PHP控制器**: `niucloud-php\niucloud\app\adminapi\controller\` (API接口定义)
|
|||
|
|
- **PHP服务层**: `niucloud-php\niucloud\app\service\` (业务逻辑实现)
|
|||
|
|
- **PHP模型**: `niucloud-php\niucloud\app\model\` (数据模型定义)
|
|||
|
|
- **PHP验证器**: `niucloud-php\niucloud\app\validate\` (数据验证规则)
|
|||
|
|
|
|||
|
|
### AI开发质量标准
|
|||
|
|
|
|||
|
|
- **数据库字段映射准确率**: 100%
|
|||
|
|
- **PHP方法对应准确率**: 100%
|
|||
|
|
- **业务逻辑一致性**: 100%
|
|||
|
|
- **代码可直接运行**: 100%
|
|||
|
|
- **命名规范符合率**: 100%
|
|||
|
|
|
|||
|
|
### AI开发检查清单
|
|||
|
|
|
|||
|
|
- [ ] 已查看对应的PHP源码文件
|
|||
|
|
- [ ] 已查看相关的数据库表结构
|
|||
|
|
- [ ] 已理解真实的业务逻辑
|
|||
|
|
- [ ] 已确认所有依赖关系
|
|||
|
|
- [ ] 已验证生成代码的正确性
|
|||
|
|
- [ ] 已使用auto-mapping-checker.js验证
|
|||
|
|
|
|||
|
|
## 🤖 智能体角色定义（按执行顺序标注）
|
|||
|
|
|
|||
|
|
### S1 需求分析体(Analyzer)
|
|||
|
|
- **职责**: 解析需求、对应 PHP/Nest 规范、输出任务切分与验收标准
|
|||
|
|
- **输入**: 业务需求/接口变更/对齐 PHP 的说明
|
|||
|
|
- **输出**: 模块划分、路由表、DTO、实体字段清单、与 DB/ThinkPHP 对照
|
|||
|
|
|
|||
|
|
### 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)
|
|||
|
|
- **职责**: 按清单逐项核查，出具差异报告与修复项
|
|||
|
|
- **检查**: 规范清单，字段/命名/路由/守卫/事务/队列/事件 与 PHP/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. 功能复写实现 → 参考 PHP项目 的业务逻辑
|
|||
|
|
|
|||
|
|
- 所有业务逻辑必须严格基于PHP项目真实代码
|
|||
|
|
- API接口功能与PHP控制器保持100%一致
|
|||
|
|
- 数据处理流程与PHP服务层保持100%一致
|
|||
|
|
- 业务规则与PHP验证器保持100%一致
|
|||
|
|
|
|||
|
|
### 3. 框架特性使用 → 使用 NestJS 的技术特性
|
|||
|
|
|
|||
|
|
- 依赖注入(DI)：模块化管理，服务注入
|
|||
|
|
- 装饰器(Decorators)：路由定义，参数验证，权限控制
|
|||
|
|
- 管道(Pipes)：数据转换，输入验证
|
|||
|
|
- 守卫(Guards)：身份认证，权限验证
|
|||
|
|
- 拦截器(Interceptors)：请求响应处理，日志记录
|
|||
|
|
- 模块化(Modules)：功能模块划分，依赖管理
|
|||
|
|
|
|||
|
|
## 🛠️ 自动化工具集成
|
|||
|
|
|
|||
|
|
### auto-mapping-checker.js 使用指南
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 检查PHP和NestJS项目对应关系
|
|||
|
|
node auto-mapping-checker.js
|
|||
|
|
|
|||
|
|
# 检查结果解读：
|
|||
|
|
# ✅ 表示文件对应正确
|
|||
|
|
# ❌ 表示PHP存在但NestJS缺失
|
|||
|
|
# 📊 统计信息：检查模块数、发现问题数
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 工具检查维度
|
|||
|
|
|
|||
|
|
- **模块对应性**: PHP模块与NestJS模块一一对应
|
|||
|
|
- **分层完整性**: 控制器、服务、实体等层级完整
|
|||
|
|
- **文件命名规范**: 确保命名符合各自框架规范
|
|||
|
|
- **业务逻辑一致性**: 功能实现与PHP项目保持一致
|
|||
|
|
|
|||
|
|
## 📚 相关文档
|
|||
|
|
|
|||
|
|
- [三框架原则对比](./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 路由前缀
|
|||
|
|
|
|||
|
|
## 🔗 核心约束
|
|||
|
|
|
|||
|
|
- 与 PHP 业务/数据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智能体必须严格遵循此工作流程，确保开发质量和规范一致性。
|