Files

wanwujie c4e588a2fe feat: 完成PHP到NestJS迁移工具和代码生成

- ✅ 成功运行迁移工具，生成28个模块的完整NestJS代码
- ✅ 生成所有实体、服务、控制器、验证器等组件
- ✅ 修复npm依赖冲突，更新package-lock.json
- ✅ 添加Docker测试脚本和配置文件
- ✅ 完善迁移工具的调试日志和错误处理
- 🔧 包含增量更新工具和质量检查工具
- 📊 迁移统计：28个模块，数千个文件，耗时26.47秒

主要变更：
- wwjcloud-nest/src/core/* - 生成的业务模块代码
- tools/* - 迁移工具和辅助脚本
- wwjcloud-nest/package.json - 依赖更新
- docker/* - 容器化配置和测试脚本

2025-10-20 18:43:52 +08:00

32 KiB

Raw Blame History

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

🏗️ 架构设计三原则

功能组织结构 → 参考 Java/Spring Boot 分层架构，但采用微服务导向的模块化设计
- 模块化优先：按业务域划分模块（如user、order、payment），而非按技术层级划分
- 单体向微服务演进：每个模块内部完整包含Controller、Service、Entity、DTO等层级
- 模块自治：每个模块可独立开发、测试、部署，为后续微服务拆分做准备
- 层级内聚：模块内部按Spring Boot分层架构组织（Controller→Service→Repository→Entity）
- 模块间解耦：模块间通过明确的接口和事件进行通信，避免直接依赖
微服务架构层级规划：
- config层：框架配置中心微服务（数据库配置、环境变量、第三方服务配置）
- core层：基础通用业务微服务（认证、权限、日志、缓存等基础能力）
- common层：业务模块微服务集合（采用模块化设计，每个模块为独立的业务域）
common层模块化设计原则：
- 按业务域模块化组织：common/user/、common/order/、common/payment/
- 每个模块内部完整分层：controllers/、services/、entity/、dto/、module.ts
- 模块间通过接口和事件通信，避免直接文件导入依赖
- 为未来微服务拆分预留清晰的边界
功能复写实现 → 参考 PHP项目的业务逻辑
- 所有业务逻辑必须严格基于PHP项目真实代码
- API接口功能与PHP控制器保持100%一致
- 数据处理流程与PHP服务层保持100%一致
- 业务规则与PHP验证器保持100%一致
框架特性使用 → 使用 NestJS 的技术特性
- 依赖注入(DI)：模块化管理，服务注入
- 装饰器(Decorators)：路由定义，参数验证，权限控制
- 管道(Pipes)：数据转换，输入验证
- 守卫(Guards)：身份认证，权限验证
- 拦截器(Interceptors)：请求响应处理，日志记录
- 模块化(Modules)：功能模块划分，依赖管理

🤖 多智能体协作工作流程（AI开发规范）

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

绝对禁止的AI行为

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

必须遵循的数据源

数据库结构: ./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 规范、输出任务切分与验收标准
S2 架构治理体(Architect): 校验分层/依赖/目录规范，给出重构建议与边界清单
S3 基建接入体(InfraOperator): 接入/校验 Kafka、Redis、队列、事务与配置，提供接入差异与示例
S4 开发执行体(Developer): 按规范编码、编写测试、修复构建（严格禁止自创、假设、默认值）
S5 安全基线体(SecurityGuard): 检查守卫、跨租户(site_id)隔离、敏感信息暴露（开发中与提测前各执行一次）
S6 质量门禁体(QualityGate): 聚合 ESLint/TS/覆盖率/e2e 结果，低于阈值阻断合并
S7 规范审计体(Auditor): 按清单逐项核查，出具差异报告与修复项
S8 上线管控体(Release): 构建、变更说明、灰度计划与回滚预案
S9 性能优化体(PerfTuner): 建议缓存/异步化/批处理，识别大对象传输与 N+1（开发后期与上线后持续执行）
S10 命名规范体(NamingGuard): 检查文件/类/方法/变量命名规范，确保符合大厂标准（开发中持续执行）

🔄 串联流程（带顺序）

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

🛠️ 自动化工具集成

auto-mapping-checker.js 使用指南

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

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

工具检查维度

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

AI 框架功能对比图 - NestJS vs ThinkPHP

📋 概述

本文档为 AI 开发者提供 NestJS 和 ThinkPHP 框架的详细对比，包含功能映射、开发规范、命名约定和目录结构对比，确保 AI 能够更好地理解和开发功能。

重要原则：既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致

🔄 核心功能映射

1. 基础架构对比

功能模块	ThinkPHP	NestJS	对应关系	实现方式
路由系统	`Route::get()`	`@Get()`	✅ 直接对应	装饰器路由
控制器	`Controller`	`@Controller()`	✅ 直接对应	装饰器控制器
中间件	`Middleware`	`@UseGuards()`	✅ 功能对应	守卫/拦截器
依赖注入	`Container::get()`	`constructor()`	✅ 更强大	自动注入
数据验证	`Validate`	`@UsePipes()`	✅ 功能对应	验证管道
异常处理	`Exception`	`@UseFilters()`	✅ 功能对应	异常过滤器

2. 数据库操作对比

功能模块	ThinkPHP	NestJS	对应关系	实现方式
模型定义	`Model`	`@Entity()`	✅ 功能对应	TypeORM 实体
查询构建	`Db::table()`	`Repository`	✅ 功能对应	TypeORM 仓库
关联关系	`hasMany()`	`@OneToMany()`	✅ 功能对应	TypeORM 关联
事务处理	`Db::startTrans()`	`@Transaction()`	✅ 功能对应	TypeORM 事务
软删除	`SoftDelete`	`@DeleteDateColumn()`	✅ 功能对应	TypeORM 软删除

3. 缓存和会话

功能模块	ThinkPHP	NestJS	对应关系	实现方式
缓存管理	`Cache::get()`	`@Inject(CACHE_MANAGER)`	✅ 功能对应	Cache Manager
会话管理	`Session`	`@Session()`	✅ 功能对应	Session 装饰器
Redis 集成	`Redis::get()`	`@InjectRedis()`	✅ 功能对应	Redis 模块

🏗️ 目录结构对比

ThinkPHP 目录结构

thinkphp/
├── app/                    # 应用目录
│   ├── controller/        # 控制器
│   ├── model/            # 模型
│   ├── service/          # 服务层
│   └── middleware/       # 中间件
├── config/               # 配置文件
├── public/               # 公共资源
├── route/                # 路由定义
└── vendor/               # 第三方包

NestJS 目录结构

wwjcloud/
├── src/                  # 源代码目录
│   ├── common/           # 通用服务层 (对应 ThinkPHP app/)
│   │   ├── auth/         # 认证授权模块
│   │   ├── member/       # 会员管理模块
│   │   ├── sys/          # 系统管理模块
│   │   ├── site/         # 站点管理模块
│   │   ├── addon/        # 插件管理模块
│   │   ├── upload/       # 文件上传模块
│   │   └── ...           # 其他业务模块
│   ├── config/           # 配置管理层 (对应 ThinkPHP config/)
│   │   ├── database/     # 数据库配置
│   │   ├── redis/        # Redis配置
│   │   ├── jwt/          # JWT配置
│   │   └── app/          # 应用配置
│   ├── core/             # 核心基础设施层 (对应 ThinkPHP 核心)
│   │   ├── base/         # 基础类
│   │   ├── database/     # 数据库核心
│   │   ├── security/     # 安全核心
│   │   └── interceptors/ # 拦截器
│   └── vendor/           # 第三方服务适配层 (对应 ThinkPHP vendor/)
│       ├── payment/      # 支付适配器
│       ├── storage/      # 存储适配器
│       └── sms/          # 短信适配器
├── public/               # 公共资源
└── package.json          # 依赖管理

层级对应关系

层级	ThinkPHP	NestJS	说明
应用层	`app/`	`src/common/`	业务逻辑和通用服务
配置层	`config/`	`src/config/`	配置管理和环境变量
核心层	框架核心	`src/core/`	基础设施和核心功能
适配层	`vendor/`	`src/vendor/`	第三方服务集成

📝 命名规范和约束

1. 数据库命名规范

重要约束：与 PHP 项目共用数据库，必须保持命名一致

表名: 与 PHP 项目完全一致，包括前缀和命名方式
字段名: 与 PHP 项目完全一致，不能修改任何字段名
字段类型: 与 PHP 项目完全一致，不能修改字段类型
索引结构: 与 PHP 项目完全一致，不能添加或删除索引

原则：看到 PHP 项目怎么命名，我们就怎么命名，保持 100% 一致

2. 代码命名规范

类名规范

实体类: 使用 PascalCase，如 User, OrderDetail
服务类: 使用 PascalCase + Service，如 UserService, OrderService
控制器: 使用 PascalCase + Controller，如 UserController
DTO 类: 使用 PascalCase + Dto，如 CreateUserDto, UpdateUserDto

方法名规范

业务逻辑方法优先与 PHP 项目保持一致，NestJS 特有方法按 NestJS 规范：

CRUD 方法: 与 PHP 项目方法名保持一致
查询方法: 与 PHP 项目方法名保持一致
业务方法: 与 PHP 项目方法名保持一致
NestJS 生命周期方法: 按 NestJS 规范，如 onModuleInit(), onApplicationBootstrap()

原则：业务逻辑与 PHP 保持一致，NestJS 特性按 NestJS 规范

变量名规范

业务变量优先与 PHP 项目保持一致，NestJS 特有变量按 NestJS 规范：

业务变量: 与 PHP 项目变量名保持一致
业务常量: 与 PHP 项目常量名保持一致
NestJS 注入变量: 按 NestJS 规范，如 private readonly userService: UserService
TypeORM 相关变量: 按 TypeORM 规范，如 @InjectRepository(User)

原则：业务变量与 PHP 保持一致，NestJS 特性按 NestJS 规范

3. 文件命名规范

目录结构

src/common/{模块名}/
├── {模块名}.module.ts    # 模块定义文件
├── controllers/          # 控制器目录
│   ├── adminapi/        # 管理端控制器（可选）
│   └── api/             # 前台控制器（可选）
├── services/            # 服务目录
│   ├── admin/           # 管理端服务（可选）
│   ├── api/             # 前台服务（可选）
│   └── core/            # 核心服务
├── entity/              # 实体目录
│   ├── {实体名}.ts      # 实体文件（PascalCase.ts格式）
│   └── {配置实体}.ts    # 配置实体文件
├── dto/                 # DTO 目录
│   ├── admin/           # 管理端DTO（可选）
│   ├── api/             # 前台DTO（可选）
│   └── {操作}Dto.ts     # DTO文件（PascalCase.ts格式）
├── guards/              # 守卫目录（可选）
├── decorators/          # 装饰器目录（可选）
├── interfaces/          # 接口目录（可选）
└── enums/               # 枚举目录（可选）

实际示例（基于auth模块）：

src/common/auth/
├── auth.module.ts
├── controllers/
│   ├── AuthController.ts
│   ├── adminapi/
│   └── api/
├── services/
│   ├── AuthService.ts
│   ├── admin/
│   ├── api/
│   └── core/
├── entity/
│   └── AuthToken.ts
├── dto/
│   ├── AuthDto.ts
│   ├── admin/
│   └── api/
├── guards/
│   ├── GlobalAuthGuard.ts
│   ├── JwtAuthGuard.ts
│   └── RolesGuard.ts
├── decorators/
│   ├── RolesDecorator.ts
│   ├── public.decorator.ts
│   └── user-context.decorator.ts
└── interfaces/
    └── user.interface.ts

🏗️ 三大框架命名规范对比与统一标准

📋 框架命名规范对比表

1. PHP (ThinkPHP) 实际命名规范

基于对 niucloud-php 项目的实际分析：

文件类型	命名规范	实际示例	说明
控制器	`PascalCase.php`	`User.php`, `Order.php`	无Controller后缀
模型	`PascalCase.php`	`SysUser.php`, `MemberLevel.php`	直接使用业务名称
验证器	`PascalCase.php`	`User.php`, `Member.php`	无Validate后缀
服务	`PascalCase.php`	`UserService.php`, `OrderService.php`	有Service后缀
目录	`snake_case`	`adminapi/`, `validate/`, `model/`	小写下划线

2. Java (Spring Boot) 标准命名规范 1 2

文件类型	命名规范	标准示例	说明
控制器	`PascalCase + Controller.java`	`UserController.java`, `OrderController.java`	有Controller后缀
实体	`PascalCase.java`	`User.java`, `Order.java`	直接使用业务名称
服务	`PascalCase + Service.java`	`UserService.java`, `OrderService.java`	有Service后缀
DTO	`PascalCase + Dto.java`	`CreateUserDto.java`, `UserResponseDto.java`	有Dto后缀
仓储	`PascalCase + Repository.java`	`UserRepository.java`	有Repository后缀
目录	`camelCase`	`controller/`, `service/`, `dto/`	驼峰命名

3. NestJS 框架标准命名规范

文件类型	命名规范	标准示例	说明
控制器	`camelCase.controller.ts`	`user.controller.ts`, `order.controller.ts`	小写驼峰+后缀
实体	`camelCase.entity.ts`	`user.entity.ts`, `sysUser.entity.ts`	小写驼峰+后缀
服务	`camelCase.service.ts`	`user.service.ts`, `order.service.ts`	小写驼峰+后缀
DTO	`PascalCase.ts`	`CreateUserDto.ts`, `UpdateUserDto.ts`	项目实际使用格式
模块	`camelCase.module.ts`	`user.module.ts`, `admin.module.ts`	小写驼峰+后缀
目录	`camelCase`	`controller/`, `service/`, `dto/`	驼峰命名

🎯 统一命名标准（最终规范）

核心原则

业务对齐优先: 业务逻辑命名与PHP项目保持一致
框架规范遵循: NestJS特有文件类型按NestJS规范
可读性保证: 确保命名清晰、语义明确

文件命名规范（最终版）

实体文件命名

规范: {PHP模型名首字母小写}.entity.ts
对齐原则: 与PHP模型名保持业务一致性
示例:
- PHP SysUser.php → NestJS sysUser.entity.ts
- PHP SysConfig.php → NestJS sysConfig.entity.ts
- PHP MemberLevel.php → NestJS memberLevel.entity.ts

控制器文件命名

规范: {模块名}.controller.ts (NestJS 标准)
示例: user.controller.ts, order.controller.ts, admin.controller.ts

服务文件命名

规范: {模块名}.service.ts (NestJS 标准)
示例: user.service.ts, order.service.ts, admin.service.ts

DTO文件命名

规范: {操作动词}{模块名}Dto.ts (项目实际使用格式)
示例: CreateUserDto.ts, UpdateUserDto.ts, QueryAdminDto.ts

验证器文件命名

规范: {模块名}.validator.ts (区别于PHP无后缀)
示例: user.validator.ts, member.validator.ts

模块文件命名

规范: {模块名}.module.ts (NestJS 标准)
示例: user.module.ts, admin.module.ts, auth.module.ts

类命名规范（最终版）

实体类命名

规范: PascalCase (与PHP模型名保持一致)
示例: SysUser, SysConfig, MemberLevel

控制器类命名

规范: PascalCase + Controller
示例: UserController, AdminController, AuthController

服务类命名

规范: PascalCase + Service
示例: UserService, AdminService, AuthService

DTO类命名

规范: 操作动词 + 模块名 + Dto
示例: CreateUserDto, UpdateAdminDto, QueryMemberDto

方法命名规范（最终版）

业务方法命名

规范: 与PHP项目方法名保持一致 (camelCase)
示例:
- PHP getUserList() → NestJS getUserList()
- PHP addUser() → NestJS addUser()

NestJS生命周期方法

规范: 按NestJS标准 (camelCase)
示例: onModuleInit(), onApplicationBootstrap()

HTTP路由方法

规范: RESTful风格 (camelCase)
示例: findAll(), findOne(), create(), update(), remove()

变量命名规范（最终版）

业务变量

规范: 与PHP项目变量名保持一致 (camelCase)
示例: userId, userName, siteId

框架注入变量

规范: 按NestJS/TypeScript标准
示例: private readonly userService: UserService

常量命名

规范: UPPER_SNAKE_CASE
示例: MAX_RETRY_COUNT, DEFAULT_PAGE_SIZE

🔍 命名规范检查清单

PHP项目对齐检查

实体类名与PHP模型类名一致
业务方法名与PHP项目一致
业务变量名与PHP项目一致
数据库字段名与PHP项目一致

NestJS规范检查

文件名使用小写驼峰+后缀格式
类名使用大写驼峰格式
装饰器使用正确
模块导入导出正确

一致性检查

同一概念在不同文件中命名一致
缩写使用统一标准
特殊字符使用规范
语义表达清晰准确

🔍 自动化检查工具

使用 auto-mapping-checker.js 工具检查文件命名规范：

# 检查所有模块的文件对应关系
node auto-mapping-checker.js

# 重点检查项：
# 1. 实体文件是否对应PHP模型
# 2. 文件命名是否符合规范
# 3. 模块结构是否完整

原则：NestJS 特有的文件类型按 NestJS 规范，业务逻辑与 PHP 保持一致

🔧 开发约束和规范

1. 数据库约束

必须遵守的规则

表结构: 与 PHP 项目完全一致，不能修改任何结构
索引: 与 PHP 项目完全一致，不能修改索引
外键: 与 PHP 项目完全一致，不能修改外键
触发器: 与 PHP 项目完全一致，不能修改触发器

数据一致性

事务处理: 与 PHP 项目保持一致的事务处理方式
软删除: 与 PHP 项目保持一致的软删除方式
状态管理: 与 PHP 项目保持一致的状态管理方式

原则：PHP 项目怎么做，我们就怎么做，保持 100% 一致

2. API 设计约束

接口规范

URL 格式: 与 PHP 项目完全一致
请求方法: 与 PHP 项目完全一致
响应格式: 与 PHP 项目完全一致
错误处理: 与 PHP 项目完全一致

原则：PHP 项目怎么设计接口，我们就怎么设计，保持 100% 一致

权限控制

认证: 与 PHP 项目保持一致的认证方式
授权: 与 PHP 项目保持一致的授权方式
数据隔离: 与 PHP 项目保持一致的数据隔离方式

原则：PHP 项目怎么控制权限，我们就怎么控制，保持 100% 一致

3. 代码质量约束

类型安全

必须使用 TypeScript: 不允许使用 any 类型
接口定义: 所有 DTO 和响应对象必须有接口定义
类型检查: 启用严格模式，不允许隐式类型转换

错误处理

异常捕获: 与 PHP 项目保持一致的异常处理方式
日志记录: 与 PHP 项目保持一致的日志记录方式
错误响应: 与 PHP 项目保持一致的错误响应格式

原则：PHP 项目怎么处理错误，我们就怎么处理，保持 100% 一致

🚀 AI 开发指南

1. 开发流程

创建新功能模块

分析需求: 确定功能属于哪个层级 (common/config/core/vendor)
参考 PHP 项目: 查看 PHP 项目如何实现相同功能
保持一致性: 与 PHP 项目保持 100% 一致
创建组件: 按照 NestJS 规范创建相应的组件
配置模块: 在相应的模块中注册组件

开发原则

既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致

框架特性: 按照 NestJS 规范使用装饰器、依赖注入、管道等特性
业务逻辑: 与 PHP 项目保持 100% 一致
数据操作: 与 PHP 项目保持 100% 一致
接口设计: 与 PHP 项目保持 100% 一致

2. 常见问题解决

常见问题解决原则

遇到问题时，首先查看 PHP 项目是如何解决的，然后按照相同方式解决

数据库问题: 参考 PHP 项目的数据库配置和操作方式
权限问题: 参考 PHP 项目的权限控制方式
性能问题: 参考 PHP 项目的性能优化方式
业务问题: 参考 PHP 项目的业务实现方式

原则：PHP 项目怎么解决，我们就怎么解决，保持 100% 一致

3. 最佳实践

最佳实践原则

参考 PHP 项目的最佳实践，保持 100% 一致

代码组织: 与 PHP 项目保持一致的代码组织方式
错误处理: 与 PHP 项目保持一致的错误处理方式
测试策略: 与 PHP 项目保持一致的测试策略

原则：PHP 项目怎么组织代码，我们就怎么组织，保持 100% 一致

📚 参考资源

官方文档

项目相关

数据库结构: 参考 PHP 项目的数据库设计
API 接口: 参考 PHP 项目的接口文档
业务逻辑: 参考 PHP 项目的业务实现

🎯 总结

平衡原则

尊重 NestJS: 充分利用 NestJS 的装饰器、依赖注入、管道等特性
保持业务一致: 业务逻辑、数据操作、接口设计与 PHP 项目 100% 一致
框架适配: 用 NestJS 的方式实现 PHP 项目的功能

开发策略

看到 PHP 项目怎么做的，我们就怎么做 (业务层面)
看到 NestJS 怎么做的，我们就怎么做 (框架层面)
两者结合，发挥各自优势

开发检查清单

✅ 开发前检查

查看PHP模型字段定义
检查数据库表结构
确认字段类型和约束
了解业务逻辑关系

✅ 开发中检查

字段名与数据库一致
时间戳使用int类型
软删除使用is_del字段
关联关系正确定义
查询语法使用TypeORM操作符

✅ 开发后检查

npm run build 无错误
与PHP项目字段名100%一致
业务逻辑与PHP保持一致
类型安全无警告

🚀 简化处理步骤

三步快速修复法

看PHP → 找到对应字段名和类型
查数据库 → 确认实际字段结构
写NestJS → 使用框架特性实现相同逻辑

优先级处理顺序

高优先级：字段名不匹配（直接复用PHP）
中优先级：类型不匹配（遵守NestJS规范）
低优先级：语法优化（保持代码整洁）

一句话总结

"用NestJS的语法，写PHP的逻辑，保持数据库的一致性"

📋 执行检查清单（智能体开发规范）

开发前检查

对齐 PHP 模块/接口/字段
核对 DB 结构（表/字段/类型/索引）
明确路由分端（/adminapi, /api）与守卫

开发中检查

目录分层到位（Controller/Application/Core/Infrastructure/Entities/DTO）
实体字段与 DB 一致；配置表仅用 value(JSON)
Controller 只路由+DTO 校验；不写业务/不碰 ORM
Application 负责编排与事务；Core 写规则；Infra 实现仓储与适配
管理端控制器接 JwtAuthGuard + RolesGuard
启用必要 Pipes（JSON/Timestamp）
用例完成发布事件；耗时逻辑入队

开发后检查

npm run build 通过（无类型警告）
单测/集成/e2e 通过；关键路径有覆盖
Swagger 注解完整
变更清单与迁移说明

🔧 基础能力集成规范（Kafka / Redis / 队列 / 事务）

总览

目标: 将事件、任务、缓存、事务能力以统一规范接入 App/Core/Infrastructure 三层，替代"散落式调用"
约束: 由 Application 发起流程；Core 编排业务规则且不直接依赖外设；Infrastructure 提供具体实现

1. 事务（TypeORM）

发起层: Application（用例级事务边界）
使用方式:

// application/xxx.app.service.ts
constructor(private readonly dataSource: DataSource, private readonly core: XxxCoreService) {}

async runUseCase(dto: Dto) {
  return await this.dataSource.transaction(async (manager) => {
    // 将 manager 注入到仓储实现（通过请求域注入或方法透传）
    await this.core.handle(dto); // Core 内仅调用仓储接口
  });
}

规范:
- 事务只在 Application 层开启；Core 不直接操作事务对象
- 多仓储参与时基于同一 EntityManager

2. 队列（Bull/BullMQ 或 DB 队列）

发起层: Application（用例结束后入队）
接入点: UnifiedQueueService 或具体 Provider（如 BullQueueProvider/DatabaseQueueProvider）

// application/xxx.app.service.ts
constructor(private readonly queue: UnifiedQueueService) {}

await this.queue.addJob('media', 'generateThumbnail', { attId }, { attempts: 3, delay: 0 });

处理器建议放置: infrastructure/queues/xxx.processor.ts 或独立消费模块
规范: 入队数据为最小必要字段（ID/键）；大对象存储DB再查

3. 事件（Kafka / DB Outbox）

发起层: Application（领域事件在用例完成后发布）
接入点: DomainEventService（绑定 IEventBus，默认 DB Outbox，可切 Kafka）

// application/xxx.app.service.ts
constructor(private readonly events: DomainEventService) {}

await this.events.publishEvent(
  'system.settings.storage.updated',
  String(siteId),
  String(siteId),
  { storageType }
);

4. 缓存（Redis）

短缓存: 配置读取、上传限流/防刷（计数器）
幂等: SETNX+TTL
使用方式: 通过 @InjectRedis() 或 CacheManager

🗺️ 模块关系映射（PHP ↔ NestJS）

职责映射总览

职责	PHP（ThinkPHP风格）	NestJS（规范分层）	备注
控制器	`app/admin/controller/`、`app/api/controller/`	`controllers/adminapi/`、`controllers/api/`	仅路由与DTO校验（Nest特有：Guards/Pipes/Interceptors）
用例编排/流程	`app//service/`（可分 admin/api）	`application/*`（可分 `AdminXxxAppService`/`ApiXxxAppService`）	事务、聚合领域规则、发事件/入队
通用业务规则	`core/*` 或被两端复用的 service	`core/services/*`	不依赖外设（DDD）
仓储接口	与模型耦合在一起	`domain/repositories/*`	定义端口（接口）
仓储实现	模型(Model)直连DB	`infrastructure/repositories/*.typeorm.repository.ts`	TypeORM 实现，注入接口
实体/模型	`app//model/`	`entities/*`（TypeORM 实体）	字段与DB 100%一致
外部适配	SDK/Driver 封装	`infrastructure/providers/` 或 `vendor/`	存储/HTTP/SMS等
配置中心	`sys_config` + 配置文件	`settings/*` 统一读写 `sys_config.value(JSON)`	禁止 `config_value`、`app_type`

目录映射（标准化）

your-module/
├── your-module.module.ts                  # 模块定义（Nest特有）
├── controllers/
│   ├── adminapi/                          # 后台控制器（/adminapi）
│   └── api/                               # 前台控制器（/api）
├── application/                           # 用例编排（admin/api可分）
├── core/
│   ├── services/                          # 通用规则/策略（≈ PHP core）
│   ├── repositories/                      # 仓储接口（端口）
│   └── models|policies/                   # 值对象/策略（可选）
├── infrastructure/
│   ├── repositories/                      # TypeORM 实现
│   └── providers/                         # 外部系统适配
├── entities/                              # TypeORM实体（DB一致）
└── dto/                                   # DTO（class-validator）

命名映射规则

应用层: XxxAppService（如 AdminUploadAppService / ApiUploadAppService）
Core层: XxxCoreService
仓储接口: XxxRepository
仓储实现: XxxTypeormRepository
控制器: XxxController（位于 controllers/adminapi|api）
配置键: 常量化，如 UPLOAD_CONFIG_KEY = 'upload'，STORAGE_LOCAL_KEY = 'storage_local'

映射示例：Upload 模块

PHP 心智:
- admin/api 控制器 → 上传服务 → 模型写库（附件表）
NestJS 对应:
- 控制器：controllers/adminapi/upload.controller.ts、controllers/api/upload.controller.ts
- 应用：application/upload.app.service.ts（编排上传 → 领域校验 → Provider 落地 → 入库）
- Core：core/services/upload.core.service.ts（类型/大小/命名/路径策略）
- 仓储接口：core/repositories/attachment.repository.ts

注意: 本文档是 AI 开发的重要参考，请严格按照平衡原则进行开发，既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致。

32 KiB Raw Blame History Unescape Escape

🏗️ 架构设计三原则

🤖 多智能体协作工作流程（AI开发规范）