wanwu/wwjcloud-nest-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
wwjcloud-nest-v1/docs/AI-WORKFLOW-GUIDE.md
wanwu 7ede50739b chore: push latest changes
2025-11-16 22:13:57 +08:00

12 KiB
Raw Permalink Blame History

🤖 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 使用指南

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

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

工具检查维度

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

📚 相关文档

🎯 执行与验收（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

验证步骤

# 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 文件确认路由/方法/参数/返回结构一致；异常信息一致。
    • 合并前必须满足《开发指导原则》的“验收标准”。
Reference in New Issue View Git Blame Copy Permalink