wwjcloud/docs/AI-FRAMEWORK-COMPARISON.md

# 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/          # 控制器目录
│   ├── userController.ts
│   └── orderController.ts
├── services/            # 服务目录
│   ├── user.service.ts
│   └── order.service.ts
├── entities/            # 实体目录
│   ├── user.entity.ts
│   └── order.entity.ts
└── dto/                 # DTO 目录
    ├── createUser.dto.ts
    └── updateUser.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 怎么做的，我们就怎么做** (框架层面)
- **两者结合，发挥各自优势**

---

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