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

## 🏗️ 架构设计三原则

1. **功能组织结构** → 参考 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`
   - 模块间通过接口和事件通信，避免直接文件导入依赖
   - 为未来微服务拆分预留清晰的边界

2. **功能复写实现** → 参考 PHP项目 的业务逻辑
   - 所有业务逻辑必须严格基于PHP项目真实代码
   - API接口功能与PHP控制器保持100%一致
   - 数据处理流程与PHP服务层保持100%一致
   - 业务规则与PHP验证器保持100%一致

3. **框架特性使用** → 使用 NestJS 的技术特性
   - 依赖注入(DI)：模块化管理，服务注入
   - 装饰器(Decorators)：路由定义，参数验证，权限控制
   - 管道(Pipes)：数据转换，输入验证
   - 守卫(Guards)：身份认证，权限验证
   - 拦截器(Interceptors)：请求响应处理，日志记录
   - 模块化(Modules)：功能模块划分，依赖管理

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

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

## 🚫 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 规范、输出任务切分与验收标准
- **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)**: 检查文件/类/方法/变量命名规范，确保符合大厂标准（开发中持续执行）

## 🔄 串联流程（带顺序）
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** → 上线管控

## 🛠️ 自动化工具集成

### auto-mapping-checker.js 使用指南
```bash
# 检查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) 标准命名规范 <mcreference link="https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html" index="1">1</mcreference> <mcreference link="https://medium.com/@manickalai/spring-boot-api-best-practices-0ed30e0315d7" index="2">2</mcreference>

| 文件类型 | 命名规范 | 标准示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `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/` | 驼峰命名 |

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

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

### 文件命名规范（最终版）

#### 实体文件命名
- **规范**: `{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` 工具检查文件命名规范：
```bash
# 检查所有模块的文件对应关系
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. 开发流程

#### 创建新功能模块
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 怎么做的，我们就怎么做** (框架层面)
- **两者结合，发挥各自优势**

### 开发检查清单
✅ **开发前检查**
- [ ] 查看PHP模型字段定义
- [ ] 检查数据库表结构
- [ ] 确认字段类型和约束
- [ ] 了解业务逻辑关系

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

✅ **开发后检查**
- [ ] npm run build 无错误
- [ ] 与PHP项目字段名100%一致
- [ ] 业务逻辑与PHP保持一致
- [ ] 类型安全无警告

### 🚀 简化处理步骤

#### 三步快速修复法
1. **看PHP** → 找到对应字段名和类型
2. **查数据库** → 确认实际字段结构
3. **写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（用例级事务边界）
- **使用方式**:
```typescript
// 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`）
```typescript
// 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）
```typescript
// 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 项目业务逻辑保持一致。