wanwu/wwjcloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
v0.1.1-nest
wwjcloud/docs/AI-WORKFLOW-GUIDE.md
万物街 127a4db1e3 feat: 完成sys模块迁移，对齐PHP/Java框架 
- 重构sys模块架构，严格按admin/api/core分层
- 对齐所有sys实体与数据库表结构
- 实现完整的adminapi控制器，匹配PHP/Java契约
- 修复依赖注入问题，确保服务正确注册
- 添加自动迁移工具和契约验证
- 完善多租户支持和审计功能
- 统一命名规范，与PHP业务逻辑保持一致
2025-09-21 21:29:28 +08:00

9.0 KiB
Raw Permalink Blame History

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

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

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

工具检查维度

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

📚 相关文档

🎯 执行与验收（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智能体必须严格遵循此工作流程，确保开发质量和规范一致性。

Reference in New Issue View Git Blame Copy Permalink