feat: 完成sys模块迁移，对齐PHP/Java框架

- 重构sys模块架构，严格按admin/api/core分层 - 对齐所有sys实体与数据库表结构 - 实现完整的adminapi控制器，匹配PHP/Java契约 - 修复依赖注入问题，确保服务正确注册 - 添加自动迁移工具和契约验证 - 完善多租户支持和审计功能 - 统一命名规范，与PHP业务逻辑保持一致
2025-09-21 21:29:28 +08:00
parent 2e361795d9
commit 127a4db1e3
839 changed files with 24932 additions and 57988 deletions
--- a/.trae/rules/project_rules.md
+++ b/.trae/rules/project_rules.md
@@ -1,6 +1,123 @@
 框架层面: 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

 ## 📋 概述
@@ -61,19 +178,23 @@ thinkphp/
 wwjcloud/
 ├── src/                  # 源代码目录
 │   ├── common/           # 通用服务层 (对应 ThinkPHP app/)
-│   │   ├── admin/        # 管理端服务
-│   │   ├── member/       # 会员服务
-│   │   ├── rbac/         # 权限管理
-│   │   └── settings/     # 系统设置
+│   │   ├── auth/         # 认证授权模块
+│   │   ├── member/       # 会员管理模块
+│   │   ├── sys/          # 系统管理模块
+│   │   ├── site/         # 站点管理模块
+│   │   ├── addon/        # 插件管理模块
+│   │   ├── upload/       # 文件上传模块
+│   │   └── ...           # 其他业务模块
 │   ├── config/           # 配置管理层 (对应 ThinkPHP config/)
-│   │   ├── entity/       # 实体配置
 │   │   ├── database/     # 数据库配置
-│   │   └── env/          # 环境配置
+│   │   ├── redis/        # Redis配置
+│   │   ├── jwt/          # JWT配置
+│   │   └── app/          # 应用配置
 │   ├── core/             # 核心基础设施层 (对应 ThinkPHP 核心)
 │   │   ├── base/         # 基础类
-│   │   ├── traits/       # 特性类
 │   │   ├── database/     # 数据库核心
-│   │   └── security/     # 安全核心
+│   │   ├── security/     # 安全核心
+│   │   └── interceptors/ # 拦截器
 │   └── vendor/           # 第三方服务适配层 (对应 ThinkPHP vendor/)
 │       ├── payment/      # 支付适配器
 │       ├── storage/      # 存储适配器
@@ -136,29 +257,213 @@ wwjcloud/

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

-#### 文件命名
-**NestJS 特有的文件类型，按照 NestJS 规范命名：**
+**实际示例（基于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
+```

- **控制器**: `{模块名}.controller.ts` (NestJS 规范)
- **服务**: `{模块名}.service.ts` (NestJS 规范)  
- **实体**: `{模块名}.entity.ts` (TypeORM 规范，对应 PHP 的模型)
- **DTO**: `{操作}-{模块名}.dto.ts` (NestJS 规范，对应 PHP 的验证器)
- **模块**: `{模块名}.module.ts` (NestJS 规范)
+# 🏗️ 三大框架命名规范对比与统一标准
+
+## 📋 框架命名规范对比表
+
+### 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 保持一致**

@@ -276,39 +581,172 @@ src/common/admin/
 - **看到 NestJS 怎么做的，我们就怎么做** (框架层面)
 - **两者结合，发挥各自优势**

+### 开发检查清单
+✅ **开发前检查**
+- [ ] 查看PHP模型字段定义
+- [ ] 检查数据库表结构
+- [ ] 确认字段类型和约束
+- [ ] 了解业务逻辑关系
+
+✅ **开发中检查**
+- [ ] 字段名与数据库一致
+- [ ] 时间戳使用int类型
+- [ ] 软删除使用is_del字段
+- [ ] 关联关系正确定义
+- [ ] 查询语法使用TypeORM操作符
+
+✅ **开发后检查**
+- [ ] npm run build 无错误
+- [ ] 与PHP项目字段名100%一致
+- [ ] 业务逻辑与PHP保持一致
+- [ ] 类型安全无警告
+
+### 🚀 简化处理步骤
+
+#### 三步快速修复法
+1. **看PHP** → 找到对应字段名和类型
+2. **查数据库** → 确认实际字段结构
+3. **写NestJS** → 使用框架特性实现相同逻辑
+
+#### 优先级处理顺序
+- **高优先级**：字段名不匹配（直接复用PHP）
+- **中优先级**：类型不匹配（遵守NestJS规范）
+- **低优先级**：语法优化（保持代码整洁）
+
+#### 一句话总结
+**"用NestJS的语法，写PHP的逻辑，保持数据库的一致性"**
+
 ---
-时间戳 → 使用 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的逻辑，保持数据库的一致性"
+
+## 📋 执行检查清单（智能体开发规范）
+
+### 开发前检查
+- [ ] 对齐 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 项目业务逻辑保持一致。