wwjcloud-nest-v1/.trae/rules/project_rules.md

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

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/)
│   │   ├── admin/        # 管理端服务
│   │   ├── member/       # 会员服务
│   │   ├── rbac/         # 权限管理
│   │   └── settings/     # 系统设置
│   ├── config/           # 配置管理层 (对应 ThinkPHP config/)
│   │   ├── entity/       # 实体配置
│   │   ├── database/     # 数据库配置
│   │   └── env/          # 环境配置
│   ├── core/             # 核心基础设施层 (对应 ThinkPHP 核心)
│   │   ├── base/         # 基础类
│   │   ├── traits/       # 特性类
│   │   ├── database/     # 数据库核心
│   │   └── security/     # 安全核心
│   └── 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/admin/
├── controllers/          # 控制器目录
│   ├── user.controller.ts
│   └── order.controller.ts
├── services/            # 服务目录
│   ├── user.service.ts
│   └── order.service.ts
├── entities/            # 实体目录
│   ├── user.entity.ts
│   └── order.entity.ts
└── dto/                 # DTO 目录
    ├── create-user.dto.ts
    └── update-user.dto.ts

文件命名

NestJS 特有的文件类型，按照 NestJS 规范命名：

• 控制器: {模块名}.controller.ts (NestJS 规范)
• 服务: {模块名}.service.ts (NestJS 规范)
• 实体: {模块名}.entity.ts (TypeORM 规范，对应 PHP 的模型)
• DTO: {操作}-{模块名}.dto.ts (NestJS 规范，对应 PHP 的验证器)
• 模块: {模块名}.module.ts (NestJS 规范)

原则：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. 开发流程

创建新功能模块

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

开发原则

既要尊重 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% 一致

📚 参考资源

官方文档

• NestJS: https://nest.nodejs.cn/
• TypeORM: https://typeorm.io/
• ThinkPHP: https://doc.thinkphp.cn/

项目相关

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

🎯 总结

平衡原则

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

开发策略

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

---

时间戳 → 使用 TypeORM 的 @CreateDateColumn, @UpdateDateColumn，但指定 type: 'int' 软删除 → 使用 @Column 手动定义 is_del 和 delete_time，都是 number 类型 JSON 字段 → 使用 @Column('json') 状态管理 → 使用 NestJS 的 ValidationPipe 注意: 本文档是 AI 开发的重要参考，请严格按照平衡原则进行开发，既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致。 开发步骤和注意事项 开发检查清单 ✅ 开发前检查 [ ] 查看PHP模型字段定义 [ ] 检查数据库表结构 [ ] 确认字段类型和约束 [ ] 了解业务逻辑关系 ✅ 开发中检查 [ ] 字段名与数据库一致 [ ] 时间戳使用int类型 [ ] 软删除使用is_del字段 [ ] 关联关系正确定义 [ ] 查询语法使用TypeORM操作符 ✅ 开发后检查 [ ] npm run build 无错误 [ ] 与PHP项目字段名100%一致，并列出php的model层，数据库，nestjs字段名清单。 [ ] 业务逻辑与PHP保持一致，并列出，php与nestjs的，命名规范对比清单 [ ] 类型安全无警告 🚀 简化处理步骤 三步快速修复法 看PHP → 找到对应字段名和类型 查数据库 → 确认实际字段结构 写NestJS → 使用框架特性实现相同逻辑 优先级处理顺序 高优先级：字段名不匹配（直接复用PHP） 中优先级：类型不匹配（遵守NestJS规范） 低优先级：语法优化（保持代码整洁） 一句话总结 " 用NestJS的语法，写PHP的逻辑，保持数据库的一致性"