wanwu/wwjcloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 重构sys模块架构，严格按admin/api/core分层
- 对齐所有sys实体与数据库表结构
- 实现完整的adminapi控制器，匹配PHP/Java契约
- 修复依赖注入问题，确保服务正确注册
- 添加自动迁移工具和契约验证
- 完善多租户支持和审计功能
- 统一命名规范，与PHP业务逻辑保持一致
This commit is contained in:
万物街
2025-09-21 21:29:28 +08:00
parent 2e361795d9
commit 127a4db1e3
839 changed files with 24932 additions and 57988 deletions
Download Patch File Download Diff File Expand all files Collapse all files

278
docs/AI-FRAMEWORK-COMPARISON.md Normal file
View File

@@ -0,0 +1,278 @@
# 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 怎么做的，我们就怎么做** (框架层面)
- **两者结合，发挥各自优势**
---
**注意**: 本文档是 AI 开发的重要参考，请严格按照平衡原则进行开发，既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致。

199
docs/AI-WORKFLOW-GUIDE.md Normal file
View File

@@ -0,0 +1,199 @@
# 🤖 AI智能体工作流程指南
## 📋 概述
本文档为AI开发者提供完整的智能体协作工作流程，确保AI能够高效、规范地完成NestJS项目开发，同时与PHP项目保持100%业务一致性。
## 🎯 核心目标
- **框架层面**: 100% 使用 NestJS 的方式
- **业务层面**: 与 PHP 项目保持 100% 一致
- **数据层面**: 与 PHP 项目数据库结构 100% 一致
## 🚫 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 规范、输出任务切分与验收标准
- **输入**: 业务需求/接口变更/对齐 PHP 的说明
- **输出**: 模块划分、路由表、DTO、实体字段清单、与 DB/ThinkPHP 对照
### S2 架构治理体(Architect)
- **职责**: 校验分层/依赖/目录规范，给出重构建议与边界清单
- **校验**: 模块目录、分层(Application/Core/Infrastructure)、依赖方向(App→Common→Core→Vendor)
- **输出**: 设计说明、端口(Repository/Provider)定义、删除/迁移建议
### S3 基建接入体(InfraOperator)
- **职责**: 接入/校验 Kafka、Redis、队列、事务与配置，提供接入差异与示例
- **接入**: Kafka/Redis/队列/事务的工程化接入与配置
- **产物**: 接入差异与示例代码，健康检查/配置项校验清单
### S4 开发执行体(Developer)
- **职责**: 按规范编码、编写测试、修复构建（严格禁止自创、假设、默认值）
- **实现**: Controller 仅路由+DTO校验；AppService 编排；Core 规则；Infra 实现；Entity 对齐 DB
- **接入**: 守卫(RBAC)、Pipes(JSON/Timestamp)、拦截器(请求日志)、事件与队列
- **测试**: 单测/集成/e2e，构建通过
### S5 安全基线体(SecurityGuard)
- **职责**: 检查守卫、跨租户(site_id)隔离、敏感信息暴露（开发中与提测前各执行一次）
- **检查**: 控制器守卫、site_id 隔离、敏感字段输出、配置权限
### S6 质量门禁体(QualityGate)
- **职责**: 聚合 ESLint/TS/覆盖率/e2e 结果，低于阈值阻断合并
- **指标**: ESLint/TS 无报错；覆盖率≥阈值；e2e 关键路径通过
- **动作**: 不达标阻断合并
### S7 规范审计体(Auditor)
- **职责**: 按清单逐项核查，出具差异报告与修复项
- **检查**: 规范清单，字段/命名/路由/守卫/事务/队列/事件 与 PHP/DB 对齐
- **产物**: 差异报告与修复任务
### S8 上线管控体(Release)
- **职责**: 构建、变更说明、灰度计划与回滚预案
- **产出**: 变更日志、部署步骤、数据迁移脚本、回滚预案
### S9 性能优化体(PerfTuner)
- **职责**: 建议缓存/异步化/批处理，识别大对象传输与 N+1（开发后期与上线后持续执行）
- **建议**: 缓存、异步化、批量化、索引与查询优化；识别 N+1、大对象传输
### S10 命名规范体(NamingGuard)
- **职责**: 检查文件/类/方法/变量命名规范，确保符合大厂标准（开发中持续执行）
- **检查**: 文件命名、类命名、方法命名、变量命名、数据库命名、API命名
- **输出**: 命名规范检查报告、不符合规范的命名列表、修复建议
## 🔄 串联流程（带顺序）
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** → 上线管控
## 🏗️ 架构设计三原则
### 1. 功能组织结构 → 参考 Java/Spring Boot 分层架构
- **模块化优先**：按业务域划分模块（如user、order、payment），而非按技术层级划分
- **单体向微服务演进**：每个模块内部完整包含Controller、Service、Entity、DTO等层级
- **模块自治**：每个模块可独立开发、测试、部署，为后续微服务拆分做准备
- **层级内聚**：模块内部按Spring Boot分层架构组织（Controller→Service→Repository→Entity）
- **模块间解耦**：模块间通过明确的接口和事件进行通信，避免直接依赖
### 2. 功能复写实现 → 参考 PHP项目 的业务逻辑
- 所有业务逻辑必须严格基于PHP项目真实代码
- API接口功能与PHP控制器保持100%一致
- 数据处理流程与PHP服务层保持100%一致
- 业务规则与PHP验证器保持100%一致
### 3. 框架特性使用 → 使用 NestJS 的技术特性
- 依赖注入(DI)：模块化管理，服务注入
- 装饰器(Decorators)：路由定义，参数验证，权限控制
- 管道(Pipes)：数据转换，输入验证
- 守卫(Guards)：身份认证，权限验证
- 拦截器(Interceptors)：请求响应处理，日志记录
- 模块化(Modules)：功能模块划分，依赖管理
## 🛠️ 自动化工具集成
### auto-mapping-checker.js 使用指南
```bash
# 检查PHP和NestJS项目对应关系
node auto-mapping-checker.js
# 检查结果解读：
# ✅ 表示文件对应正确
# ❌ 表示PHP存在但NestJS缺失
# 📊 统计信息：检查模块数、发现问题数
```
### 工具检查维度
- **模块对应性**: PHP模块与NestJS模块一一对应
- **分层完整性**: 控制器、服务、实体等层级完整
- **文件命名规范**: 确保命名符合各自框架规范
- **业务逻辑一致性**: 功能实现与PHP项目保持一致
## 📚 相关文档
- [三框架原则对比](./FRAMEWORK-PRINCIPLES.md)
- [AI开发禁止规则](./AI-DEVELOPMENT-RULES.md)
- [项目整体结构参考](./PROJECT-STRUCTURE.md)
- [AI框架功能对比](./AI-FRAMEWORK-COMPARISON.md)
- [命名规范指南](./NAMING-CONVENTIONS.md)
## 🎯 执行与验收（CI/PR 建议）
- PR 必须通过: build、单测/集成/e2e
- 审计体根据规范清单自动评论差异（字段/命名/路由/守卫/事务/队列/事件）
- 命名规范体(NamingGuard)检查所有文件命名、类命名、方法命名、变量命名
- 安全基线: 管理端控制器统一 `JwtAuthGuard + RolesGuard`；/adminapi 与 /api 路由前缀
## 🔗 核心约束
- 与 PHP 业务/数据100%一致；与 NestJS 规范100%匹配
- 禁止创建 DB 不存在字段；`sys_config.value(JSON)` 统一
- 管理端路由 `/adminapi`，前台 `/api`；统一守卫与响应格式
## 📝 基础能力检查点
### 事务处理
- 仅在 Application 开启；多仓储共享同一 EntityManager；Core 不直接操作事务对象
### 队列处理
- 用例完成后入队；载荷仅传关键 ID；处理器在 Infrastructure；按队列名分域
### 事件处理
- 统一用 DomainEventService；事件名 `domain.aggregate.action`；默认 DB Outbox，可切 Kafka
### Redis缓存
- 短缓存配置读取、上传限流/防刷（计数器）、幂等(SETNX+TTL)
---
**重要提醒**: 本文档是AI开发的核心指南，所有AI智能体必须严格遵循此工作流程，确保开发质量和规范一致性。

322
docs/API_INTERFACE_COMPARISON.md Normal file
View File

@@ -0,0 +1,322 @@
# NestJS vs PHP 框架 API 接口对比分析
## 📊 总体统计
| 项目 | NestJS | PHP | 差异 |
|------|--------|-----|------|
| 控制器总数 | 164 | 200+ | -36 |
| API接口总数 | 800+ | 1000+ | -200+ |
| 管理端接口 | 120+ | 150+ | -30+ |
| 前台接口 | 40+ | 80+ | -40+ |
## 🔍 详细对比分析
### 1. 系统管理模块 (sys)
#### ✅ NestJS 已实现
- `admin/sys/role` - 角色管理
- `admin/sys/config` - 系统配置
- `admin/sys/area` - 地区管理
- `admin/sys/attachment` - 附件管理
- `admin/sys/schedule` - 定时任务
- `admin/sys/agreement` - 协议管理
- `admin/sys/menu` - 菜单管理
- `admin/sys/common` - 通用接口
- `admin/sys/export` - 导出功能
- `admin/sys/printer` - 打印管理
- `admin/sys/poster` - 海报管理
- `admin/sys/channel` - 渠道管理
- `admin/sys/app` - 应用管理
- `admin/sys/ueditor` - 编辑器
- `api/sys/home` - 首页接口
- `api/sys/settings` - 设置接口
- `api/sys/task` - 任务接口
- `api/sys/area` - 地区接口
- `api/sys/scan` - 扫描接口
#### ❌ NestJS 缺失
- `admin/sys/dict` - 字典管理
- `admin/sys/log` - 日志管理
- `admin/sys/monitor` - 系统监控
- `admin/sys/cache` - 缓存管理
- `admin/sys/backup` - 备份管理
- `admin/sys/upgrade` - 升级管理
### 2. 站点管理模块 (site)
#### ✅ NestJS 已实现
- `adminapi/site` - 站点管理
- `adminapi/site/group` - 站点分组
- `adminapi/site/user` - 站点用户
- `adminapi/site/user-log` - 用户日志
- `adminapi/site/account` - 站点账户
- `adminapi/site/account-log` - 账户日志
#### ❌ NestJS 缺失
- `admin/site/domain` - 域名管理
- `admin/site/theme` - 主题管理
- `admin/site/template` - 模板管理
- `admin/site/plugin` - 插件管理
### 3. 会员管理模块 (member)
#### ✅ NestJS 已实现
- `adminapi/member/member` - 会员管理
- `adminapi/member/level` - 会员等级
- `adminapi/member/address` - 会员地址
- `adminapi/member/account` - 会员账户
- `adminapi/member/cash-out` - 提现管理
- `adminapi/member/sign` - 签到管理
- `adminapi/member/label` - 会员标签
- `adminapi/member/config` - 会员配置
- `api/member/member` - 会员接口
- `api/member/level` - 等级接口
- `api/member/address` - 地址接口
- `api/member/account` - 账户接口
- `api/member/cash-out` - 提现接口
#### ❌ NestJS 缺失
- `admin/member/point` - 积分管理
- `admin/member/coupon` - 优惠券管理
- `admin/member/group` - 会员分组
- `admin/member/statistics` - 会员统计
### 4. 支付管理模块 (pay)
#### ✅ NestJS 已实现
- `adminapi/pay` - 支付管理
- `adminapi/pay-channel` - 支付渠道
- `adminapi/pay/transfer` - 转账管理
- `adminapi/pay/refund` - 退款管理
- `api/pay/pay` - 支付接口
- `api/pay/transfer` - 转账接口
#### ❌ NestJS 缺失
- `admin/pay/order` - 订单管理
- `admin/pay/bill` - 账单管理
- `admin/pay/statistics` - 支付统计
- `admin/pay/report` - 支付报表
### 5. 微信管理模块 (wechat)
#### ✅ NestJS 已实现
- `adminapi/wechat/config` - 微信配置
- `api/wechat/serve` - 微信服务
- `api/wechat/wechat` - 微信接口
#### ❌ NestJS 缺失
- `admin/wechat/menu` - 微信菜单
- `admin/wechat/template` - 微信模板
- `admin/wechat/reply` - 自动回复
- `admin/wechat/media` - 素材管理
- `admin/wechat/qrcode` - 二维码管理
- `admin/wechat/user` - 微信用户
- `admin/wechat/statistics` - 微信统计
### 6. 小程序管理模块 (weapp)
#### ✅ NestJS 已实现
- `adminapi/weapp/config` - 小程序配置
- `api/weapp/serve` - 小程序服务
- `api/weapp/weapp` - 小程序接口
#### ❌ NestJS 缺失
- `admin/weapp/version` - 版本管理
- `admin/weapp/template` - 模板管理
- `admin/weapp/package` - 包管理
- `admin/weapp/delivery` - 发布管理
- `admin/weapp/statistics` - 小程序统计
### 7. 插件管理模块 (addon)
#### ✅ NestJS 已实现
- `adminapi/addon/addon` - 插件管理
- `adminapi/addon/backup` - 备份管理
- `adminapi/addon/upgrade` - 升级管理
- `adminapi/addon/develop` - 开发管理
- `adminapi/addon/app` - 应用管理
- `api/addon` - 插件接口
#### ❌ NestJS 缺失
- `admin/addon/install` - 安装管理
- `admin/addon/uninstall` - 卸载管理
- `admin/addon/config` - 插件配置
- `admin/addon/log` - 插件日志
### 8. 文件管理模块 (upload)
#### ✅ NestJS 已实现
- `adminapi/upload` - 文件上传
- `adminapi/upload/storage` - 存储管理
- `api/upload` - 上传接口
#### ❌ NestJS 缺失
- `admin/upload/category` - 文件分类
- `admin/upload/watermark` - 水印管理
- `admin/upload/compress` - 压缩管理
### 9. 认证管理模块 (auth)
#### ✅ NestJS 已实现
- `adminapi/auth/captcha` - 验证码
- `adminapi/auth/login-config` - 登录配置
- `api/login/config` - 登录配置接口
- `api/login/register` - 注册接口
#### ❌ NestJS 缺失
- `admin/auth/user` - 用户管理
- `admin/auth/role` - 角色管理
- `admin/auth/permission` - 权限管理
- `admin/auth/session` - 会话管理
### 10. 通知管理模块 (notice)
#### ✅ NestJS 已实现
- `adminapi/notice/notice-log` - 通知日志
#### ❌ NestJS 缺失
- `admin/notice/sms` - 短信管理
- `admin/notice/email` - 邮件管理
- `admin/notice/push` - 推送管理
- `admin/notice/template` - 模板管理
- `admin/notice/statistics` - 通知统计
### 11. 统计管理模块 (stat)
#### ✅ NestJS 已实现
- `adminapi/stat/site-stat` - 站点统计
#### ❌ NestJS 缺失
- `admin/stat/visitor` - 访客统计
- `admin/stat/order` - 订单统计
- `admin/stat/member` - 会员统计
- `admin/stat/pay` - 支付统计
- `admin/stat/report` - 报表管理
### 12. DIY管理模块 (diy)
#### ✅ NestJS 已实现
- `api/diy/diy` - DIY接口
- `api/diy/form` - 表单接口
#### ❌ NestJS 缺失
- `admin/diy/config` - DIY配置
- `admin/diy/route` - 路由管理
- `admin/diy/template` - 模板管理
- `admin/diy/component` - 组件管理
### 13. 其他模块
#### ✅ NestJS 已实现
- `adminapi/niucloud/module` - 模块管理
- `adminapi/niucloud/cloud` - 云服务
- `adminapi/verify/verifier` - 验证器
- `adminapi/verify/verify` - 验证管理
- `adminapi/dict/dict` - 字典管理
- `adminapi/generator/generator` - 代码生成器
- `adminapi/poster/poster` - 海报管理
- `adminapi/aliapp/config` - 支付宝小程序配置
- `adminapi/wxoplatform/config` - 微信开放平台配置
- `adminapi/wxoplatform/weapp-version` - 微信小程序版本
- `adminapi/wxoplatform/server` - 服务器管理
- `adminapi/wxoplatform/oplatform` - 开放平台
- `adminapi/applet/site-version` - 应用版本
- `adminapi/applet/version` - 版本管理
- `adminapi/applet/version-download` - 版本下载
- `adminapi/channel/h5` - H5渠道
- `adminapi/channel/pc` - PC渠道
- `adminapi/home/site` - 首页站点
- `adminapi/user/user` - 用户管理
#### ❌ NestJS 缺失
- `admin/cms/article` - 文章管理
- `admin/cms/category` - 分类管理
- `admin/cms/tag` - 标签管理
- `admin/cms/comment` - 评论管理
- `admin/mall/goods` - 商品管理
- `admin/mall/category` - 商品分类
- `admin/mall/order` - 订单管理
- `admin/mall/cart` - 购物车
- `admin/mall/coupon` - 优惠券
- `admin/mall/promotion` - 促销活动
- `admin/mall/inventory` - 库存管理
- `admin/mall/shipping` - 物流管理
- `admin/mall/refund` - 退款管理
- `admin/mall/review` - 评价管理
- `admin/mall/statistics` - 商城统计
## 🚨 关键缺失分析
### 1. 电商核心功能缺失
- **商品管理**: 商品CRUD、分类、标签、属性
- **订单管理**: 订单流程、状态管理、物流跟踪
- **购物车**: 购物车管理、结算流程
- **优惠券**: 优惠券系统、促销活动
- **库存管理**: 库存控制、预警系统
- **物流管理**: 物流跟踪、配送管理
### 2. 内容管理功能缺失
- **CMS系统**: 文章、分类、标签管理
- **评论系统**: 评论管理、审核流程
- **媒体管理**: 图片、视频、文档管理
### 3. 高级功能缺失
- **系统监控**: 性能监控、日志分析
- **缓存管理**: 缓存策略、清理机制
- **备份恢复**: 数据备份、恢复功能
- **升级管理**: 系统升级、版本管理
### 4. 统计分析功能缺失
- **业务统计**: 订单、会员、支付统计
- **访客分析**: 访问统计、用户行为
- **报表系统**: 各类业务报表
## 📈 完整性评估
| 模块 | 完成度 | 缺失接口数 | 优先级 |
|------|--------|------------|--------|
| 系统管理 | 85% | 6 | 高 |
| 站点管理 | 75% | 4 | 高 |
| 会员管理 | 80% | 4 | 高 |
| 支付管理 | 70% | 4 | 高 |
| 微信管理 | 40% | 6 | 中 |
| 小程序管理 | 40% | 5 | 中 |
| 插件管理 | 75% | 4 | 中 |
| 文件管理 | 60% | 3 | 中 |
| 认证管理 | 50% | 4 | 高 |
| 通知管理 | 20% | 5 | 中 |
| 统计管理 | 20% | 5 | 中 |
| DIY管理 | 40% | 4 | 低 |
| 电商模块 | 0% | 15+ | 高 |
| 内容管理 | 0% | 5+ | 中 |
## 🎯 建议修复优先级
### 高优先级 (必须修复)
1. **电商核心功能** - 商品、订单、购物车管理
2. **认证权限系统** - 用户、角色、权限管理
3. **系统管理完善** - 字典、日志、监控功能
4. **支付系统完善** - 订单、账单、统计功能
### 中优先级 (建议修复)
1. **微信小程序功能** - 菜单、模板、用户管理
2. **通知系统** - 短信、邮件、推送功能
3. **统计分析** - 各类业务统计报表
4. **文件管理** - 分类、水印、压缩功能
### 低优先级 (可选修复)
1. **DIY系统** - 模板、组件管理
2. **内容管理** - CMS、评论系统
3. **高级功能** - 监控、备份、升级
## 📝 总结
NestJS框架目前实现了约**60%**的API接口，主要缺失：
1. **电商核心功能** - 这是最大的功能缺口
2. **微信小程序完整功能** - 菜单、模板、用户管理
3. **统计分析系统** - 各类业务统计和报表
4. **内容管理系统** - 文章、分类、评论管理
5. **高级系统功能** - 监控、备份、升级管理
建议优先实现电商核心功能，这是业务系统的核心，其他功能可以逐步完善。

193
docs/ARCHITECTURE-BASELINE-AND-COMMON-GUIDE.md Normal file
View File

@@ -0,0 +1,193 @@
# 架构基线与 Common 层开发指引（Config/Core/Common）
适用范围：本项目已定版的三层架构（config/core/common），以及与 Java/Spring Boot 与 PHP/ThinkPHP 的对标关系与实践规则。目标：在不自创业务的前提下，指导 AI 基于真实 PHP 代码与数据库结构高一致地开发 common 层模块。
---
## 1. 三层职责与使用方式
### 1.1 Config 层（配置中心与环境治理）
- 职责
- 环境与配置集中管理（env.* 与模块化配置）
- 外部服务与框架能力的参数化（DB、Redis、JWT、队列等）
- 使用规则
- 严禁编写业务逻辑，仅做“配置与适配”
- 新增配置项：优先读取 env，统一通过 ConfigService 暴露
- 敏感配置不可写死；可按需对接密钥服务
- 参考位置
- 项目：wwjcloud/src/config
- 环境文件：wwjcloud/env.*
### 1.2 Core 层（基础能力与横切关注）
- 职责
- 全局管道/拦截器/过滤器/守卫基线
- 观测与日志、链路追踪（X-Trace-Id）、统一响应/异常
- 限流、CORS、Swagger 文档、调度与事件
- 使用规则
- 仅提供通用规则与“可复用能力”，不承载具体业务
- 全局基线已启用：
- 参数校验：Global ValidationPipe
- 统一响应：ResponseInterceptor（含 traceId）
- 统一异常：HttpExceptionFilter（含 traceId）
- 链路追踪：TracingInterceptor + X-Trace-Id 贯通
- 速率限制：ThrottlerGuard（按需配置）
- CORS：app.enableCors()
- 文档：Swagger（/adminapi 与 /api 分文档）
- 参考位置
- 全局注册：wwjcloud/src/app.module.ts
- 启动入口：wwjcloud/src/main.ts
- Swagger 拆分：wwjcloud/src/config/modules/swagger/swaggerService.ts
- Tracing/响应/异常：wwjcloud/src/core/**/*
### 1.3 Common 层（业务域模块化实现）
- 职责
- 面向具体业务域（如 user/order/payment）
- 内部完整分层：Controller → Service → Repository/Entity → DTO
- 与 PHP 项目代码与数据库 100% 一致
- 使用规则
- 文件结构示例（以 user 为例）：
- src/common/user/
- user.module.ts（模块）
- controllers/（管理端/前台可分 adminapi/ 与 api/）
- services/
- entity/
- dto/
- guards/（可选）
- 管理端路由前缀：/adminapi；前台：/api
- Controller 只做：路由与 DTO 校验，禁止写业务
- Service 编排业务流程（必要时开启应用层事务）
- Repository/Entity 与数据库字段 100% 对齐（禁止新增字段）
- DTO/验证规则与 PHP 验证器一致
---
## 2. 三框架对标对照（轻量/功能/性能）
### 2.1 总览对比
| 维度 | Java / Spring Boot | NestJS（本项目基线） | PHP / ThinkPHP |
|---|---|---|---|
| 轻量/启动 | 中等偏重、启动慢但稳定 | 轻量、启动快、按需模块 | 最轻、FPM 请求模型 |
| 功能完备度 | 企业级最全（安全/事务/监控） | Web/微服务常用能力齐全 | Web 基础能力齐全 |
| 性能取向 | 高吞吐、高并发、CPU 密集强 | 低延迟 I/O 强、BFF/聚合强 | 请求短、实现快 |
| 并发模型 | 线程池 | 事件循环 + 异步 I/O | 多进程/请求 |
| 可观测性 | Actuator/Micrometer | 健康/日志/Tracing 已落地 | 需组合/扩展 |
| 安全基线 | Spring Security 完备 | 守卫/装饰器灵活 | 中间件/验证器为主 |
### 2.2 分层对比（config/core/common）
| 能力项 | Spring Boot | NestJS（本项目） | ThinkPHP |
|---|---|---|---|
| Config | profiles + 强类型绑定 | env + ConfigModule（已启用） | env + config/*.php |
| Core | Validation/Advice/Actuator | ValidationPipe/Filter/Interceptor/Throttler/CORS/Swagger（已启用） | Validate/中间件 |
| Common | 分包+组件化 | 业务域模块自治（强约束对齐 PHP/DB） | app/{模块} |
### 2.3 性能视角（工程实践）
| 场景 | Spring Boot | NestJS | ThinkPHP |
|---|---|---|---|
| API 聚合/BFF | 可做，线程开销更高 | 强项 | 适合后台接口 |
| CPU 密集 | 强项 | 建议 offload 至 worker/微服务 | 不推荐 |
| I/O 密集 | 稳定 | 强项 | 常规 |
| 冷启动/弹性 | 相对慢 | 快 | 快 |
---
## 3. AI 开发 Common 层的使用方法（强约束版）
> 目标：严格遵循 PHP 源码与数据库结构，使用 NestJS 特性实现相同业务语义；禁止自创和假设。
### 3.1 约束来源（必须核对）
- 数据库表结构：/sql/wwjcloud.sql（唯一权威）
- PHP 控制器：/niucloud-php/niucloud/app/adminapi/controller/
- PHP 服务层：/niucloud-php/niucloud/app/service/
- PHP 模型：/niucloud-php/niucloud/app/model/
- PHP 验证器：/niucloud-php/niucloud/app/validate/
### 3.2 开发流程（S1 → S10）
- S1 需求分析体
- 定位对应的 PHP 控制器/服务/验证器/模型与数据库表
- 输出：模块边界、路由表（/adminapi 与 /api）、DTO 字段清单、实体字段清单
- S2 架构治理体
- 校验目录与依赖：common/{module}/ 按 Controller→Service→Entity→DTO 组织
- 确保依赖方向：App(Controller) → Service → Infra/Repository → Entity
- S3 基建接入体
- 若涉及 Redis/队列/事务：按 core 规范接入（事务仅在应用层开启，共享 EntityManager）
- S4 开发执行体
- Controller：只做路由/DTO 校验；响应交给全局拦截器统一处理
- Service：编排业务，与 PHP 服务层一致；必要时开启事务（禁止在 Core 开启）
- Entity/Repository：字段与 /sql/wwjcloud.sql 100% 对齐（禁止新增字段）
- 接入守卫：管理端统一 JwtAuthGuard + RolesGuard（或 AdminCheckTokenGuard）
- S5 安全基线体（开发阶段）
- 检查：site_id 隔离、越权、敏感字段输出、/adminapi 守卫
- S6 质量门禁体
- ESLint/TS 0 报错；覆盖率与 e2e 关键路径通过
- S7 规范审计体
- 命名/路由/守卫/事务/事件/队列 与 PHP/DB 对齐
- S5 安全基线体（提测前）
- 重点接口越权与敏感输出复检
- S9 性能优化体
- 建议缓存、批处理、异步化，识别 N+1 与大对象
- S10 命名规范体
- 文件/类/方法/变量命名符合既定规范
- S8 上线管控体
- 变更说明、部署步骤、灰度与回滚预案
### 3.3 模块落地清单（逐项核对）
- 路由前缀：管理端 /adminapi；前台 /api（与 PHP 对齐）
- 守卫：管理端控制器默认 JwtAuthGuard + RolesGuard（或 AdminCheckTokenGuard）
- DTO：字段与 PHP 验证器一致；使用 class-validator + ValidationPipe
- 实体：字段/类型/索引与 wwjcloud.sql 100% 一致；禁止新增字段
- 服务：方法名与 PHP 服务层一致；流程一致；必要时开启事务（应用层）
- 统一响应：无需手工封装，交由 ResponseInterceptor；traceId 自动注入
- 异常处理：只抛出 HttpException/自定义异常；由 HttpExceptionFilter 统一处理
- 日志与链路：无需重复生成 traceId；使用 request.traceId（已在 Core 透传）
- 文档：自动生成 Swagger，按 /adminapi 与 /api 拆分
### 3.4 命名与目录规范（强规则）
- 目录名：camelCase；文件名：camelCase.ts
- 类名：PascalCase；接口名：IPascalCase；DTO：PascalCase + Dto
- API 命名：camelCase；HTTP 方法规范化
- 数据库命名：snake_case（表/字段/索引/外键）
- PHP 业务命名优先（在不违反 Nest 规范前提下）
### 3.5 事务/队列/事件（基线约束）
- 事务：仅在 Application（Service 层）开启；多仓储共享同一 EntityManager；Core 不直接操作事务对象
- 队列：仅入队关键 ID，处理器放在 Infrastructure；按队列名分域
- 事件：统一 DomainEventService，事件名 domain.aggregate.action；默认 DB Outbox，可切 Kafka
- Redis：短缓存/限流/幂等（SETNX+TTL）按需接入
### 3.6 提交与验收
- PR 必须通过：构建、单测/集成/e2e
- 审计项：字段/命名/路由/守卫/事务/队列/事件 与 PHP/DB 对齐
- 命名规范：严格执行大厂标准，提交命名检查报告
---
## 4. 实操模板（创建首个 common 模块时）
- 选定 PHP 源：定位对应 controller/service/validate/model 与 wwjcloud.sql 表
- 创建目录：src/common/{module}/（module 使用业务域名，camelCase）
- 落地文件：
- {module}.module.ts
- controllers/{module}.controller.ts（必要时 adminapi/ 与 api/ 分目录）
- services/{module}.service.ts
- entity/{Entity}.entity.ts（名称与 PHP 模型一致的业务语义）
- dto/{Operation}{Entity}Dto.ts（如 CreateUserDto）
- 接入守卫：管理端默认接入鉴权与角色守卫
- 编写测试：单测/集成/e2e 涵盖关键路径（校验/守卫/事务）
- 运行验收：确保全局拦截器/过滤器与 traceId 链路正常
---
## 5. 关键基线位置（便于检索）
- 全局模块注册：src/app.module.ts
- 启动入口：src/main.ts（CORS/Swagger）
- Swagger 拆分：src/config/modules/swagger/swaggerService.ts
- 链路追踪：src/core/tracing/tracingInterceptor.ts
- 统一响应：src/core/http/interceptors/responseInterceptor.ts
- 统一异常：src/core/http/filters/httpExceptionFilter.ts
- HTTP 日志：src/core/interceptors/httpLoggingInterceptor.ts
- 安全守卫（示例）：src/core/security/guards/adminCheckToken.guard.ts
---
结论：
- Config/Core 已定版、与 Spring Boot/ThinkPHP 对标的核心能力就绪，traceId 与统一响应/异常/限流/CORS/Swagger 等基线已贯通。
- 按本文档清单可直接开始 common 层业务模块开发，严格以 PHP 源码与 wwjcloud.sql 为唯一权威对齐实现。

177
docs/AUTHENTICATION_GUIDE.md Normal file
View File

@@ -0,0 +1,177 @@
# NestJS 认证处理指南
## 认证架构对比
### 1. PHP ThinkPHP (传统方式)
```php
// 通过中间件全局处理
class AdminCheckToken {
public function handle(Request $request, Closure $next) {
// 检查token，某些路由可以跳过
}
}
```
### 2. Java Spring Boot (注解方式)
```java
@RestController
public class AuthController {
@SaCheckLogin // 需要登录
@GetMapping("/user/info")
public UserInfo getUserInfo() {}
@SaNotCheckLogin // 免登录
@PostMapping("/login")
public LoginResult login() {}
}
```
### 3. NestJS (装饰器方式) - 更像Java
```typescript
@Controller('adminapi/auth')
export class AuthController {
@Public() // 免登录
@Post('login')
async login() {}
@Get('user/info') // 需要登录（默认）
async getUserInfo() {}
}
```
## NestJS 认证处理方式
### 核心原则
1. **默认需要登录** - 所有接口默认需要认证
2. **@Public()装饰器** - 标记免登录接口
3. **全局守卫** - 统一处理认证逻辑
### 实现方式
#### 1. 全局守卫配置
```typescript
// app.module.ts
@Module({
providers: [
{ provide: APP_GUARD, useClass: GlobalAuthGuard },
],
})
export class AppModule {}
```
#### 2. 全局守卫实现
```typescript
// GlobalAuthGuard.ts
@Injectable()
export class GlobalAuthGuard implements CanActivate {
async canActivate(context: ExecutionContext): Promise<boolean> {
// 检查是否有 @Public() 装饰器
const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
context.getHandler(),
context.getClass(),
]);
if (isPublic) {
return true; // 免登录接口直接通过
}
// 需要认证的接口使用JWT认证
return this.jwtAuthGuard.canActivate(context);
}
}
```
#### 3. 免登录装饰器
```typescript
// public.decorator.ts
export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);
```
### 接口分类
#### 1. 免登录接口 (使用 @Public())
- **登录相关**: `/adminapi/login/*`
- **验证码相关**: `/adminapi/captcha/*`
- **公开配置**: `/api/sys/*` (前台公开接口)
- **管理端公开**: `/adminapi/sys/web/*` (管理端公开接口)
#### 2. 需要登录接口 (默认)
- **用户管理**: `/adminapi/auth/*`
- **系统管理**: `/adminapi/sys/*` (除公开接口外)
- **站点管理**: `/adminapi/site/*`
- **其他业务接口**: 所有其他接口
### 路由路径对齐
#### PHP → NestJS 路径映射
```typescript
// PHP: /adminapi/sys/get/website
// NestJS: @Get('get/website') 在 @Controller('adminapi/sys')
// PHP: /adminapi/login
// NestJS: @Get('login') 在 @Controller('adminapi') + @Public()
// PHP: /adminapi/captcha/create
// NestJS: @Get('create') 在 @Controller('adminapi/captcha') + @Public()
```
### 最佳实践
#### 1. 控制器级别设置
```typescript
// 免登录控制器
@Controller('adminapi/login')
@Public() // 整个控制器免登录
export class LoginController {}
// 需要登录控制器
@Controller('adminapi/sys')
@UseGuards(JwtAuthGuard, RolesGuard) // 整个控制器需要登录
export class ConfigController {}
```
#### 2. 方法级别设置
```typescript
@Controller('adminapi/sys')
export class ConfigController {
@Public() // 单个方法免登录
@Get('web/website')
async getWebWebsite() {}
@Get('get/website') // 默认需要登录
async getWebsite() {}
}
```
#### 3. 路径命名规范
- **PHP方法名**: `getWebsite()` → **NestJS路径**: `get/website`
- **PHP方法名**: `setWebsite()` → **NestJS路径**: `set/website`
- **PHP方法名**: `getSceneDomain()` → **NestJS路径**: `get/scene/domain`
### 验证方法
#### 1. 检查免登录接口
```bash
# 这些接口应该不需要token就能访问
curl http://localhost:3001/adminapi/login
curl http://localhost:3001/adminapi/captcha/create
curl http://localhost:3001/api/sys/website
```
#### 2. 检查需要登录接口
```bash
# 这些接口需要token才能访问
curl -H "Authorization: Bearer <token>" http://localhost:3001/adminapi/sys/get/website
curl -H "Authorization: Bearer <token>" http://localhost:3001/adminapi/site/lists
```
### 总结
NestJS的认证处理方式**更像Java Spring Boot**，使用装饰器模式：
1. **@Public()** = Java的 **@SaNotCheckLogin**
2. **默认需要登录** = Java的 **@SaCheckLogin**
3. **全局守卫** = Java的 **拦截器**
这种方式比PHP的中间件方式更加灵活和类型安全，符合现代框架的设计理念。

299
docs/CONFIG_SETUP.md Normal file
View File

@@ -0,0 +1,299 @@
# WWJCloud Backend 配置设置指南
## 📋 概述
本文档说明如何设置 WWJCloud Backend 的环境变量配置。
## 🚀 快速开始
### 1. 复制配置文件
```bash
# 复制示例配置文件
cp env.example .env
# 或者复制特定环境的配置
cp env.development .env # 开发环境
cp env.production .env # 生产环境
```
### 2. 修改配置
根据你的实际环境修改 `.env` 文件中的配置项。
## 📁 配置文件说明
### 配置文件类型
- `env.example` - 配置示例文件（包含所有配置项）
- `env.development` - 开发环境配置
- `env.production` - 生产环境配置
- `.env` - 实际使用的配置文件（需要手动创建）
### 配置优先级
1. **环境变量** (最高优先级)
2. **默认配置** (最低优先级)
## 🔧 必需配置项
### 应用基础配置
```bash
# 应用名称
APP_NAME=WWJCloud Backend
# 应用端口
PORT=3000
# 运行环境
NODE_ENV=development # development, production, test
```
### 数据库配置
```bash
# 数据库主机
DB_HOST=localhost
# 数据库端口
DB_PORT=3306
# 数据库用户名
DB_USERNAME=root
# 数据库密码
DB_PASSWORD=your_password
# 数据库名称
DB_DATABASE=wwjcloud
# 是否同步数据库结构（生产环境必须为 false）
DB_SYNC=false
# 是否启用数据库日志
DB_LOGGING=false
```
### Redis 配置
```bash
# Redis 主机
REDIS_HOST=localhost
# Redis 端口
REDIS_PORT=6379
# Redis 密码
REDIS_PASSWORD=
# Redis 数据库编号
REDIS_DB=0
# Redis 键前缀
REDIS_KEY_PREFIX=wwjcloud:
```
### JWT 配置
```bash
# JWT 密钥（生产环境必须修改）
JWT_SECRET=your-super-secret-jwt-key
# JWT 过期时间
JWT_EXPIRES_IN=7d
# JWT 算法
JWT_ALGORITHM=HS256
```
## 🌍 环境特定配置
### 开发环境
```bash
# 复制开发环境配置
cp env.development .env
# 主要特点：
# - 启用详细日志 (LOG_LEVEL=debug)
# - 启用数据库日志 (DB_LOGGING=true)
# - 使用本地服务 (localhost)
# - 启用调试工具 (DEBUG_ENABLED=true)
```
### 生产环境
```bash
# 复制生产环境配置
cp env.production .env
# 主要特点：
# - 关闭详细日志 (LOG_LEVEL=warn)
# - 关闭数据库日志 (DB_LOGGING=false)
# - 使用生产服务器
# - 关闭调试工具 (DEBUG_ENABLED=false)
# - 启用监控 (PROMETHEUS_ENABLED=true)
```
## 🔐 安全配置
### 生产环境安全要求
1. **修改所有密钥**
```bash
JWT_SECRET=your-super-secret-jwt-key-at-least-32-characters
SESSION_SECRET=production-session-secret-key
COOKIE_SECRET=production-cookie-secret-key
```
2. **设置强密码**
```bash
DB_PASSWORD=your-strong-database-password
REDIS_PASSWORD=your-strong-redis-password
```
3. **配置 CORS**
```bash
CORS_ORIGIN=https://your-domain.com
```
4. **设置域名白名单**
```bash
ALLOWED_DOMAINS=your-domain.com,api.your-domain.com
```
## 📊 监控配置
### 启用监控
```bash
# 启用指标收集
METRICS_ENABLED=true
METRICS_PORT=9090
# 启用 Prometheus 监控
PROMETHEUS_ENABLED=true
# 启用健康检查
HEALTH_CHECK_ENABLED=true
HEALTH_CHECK_INTERVAL=30000
```
### 追踪配置
```bash
# 启用分布式追踪
TRACING_ENABLED=true
# Jaeger 端点
JAEGER_ENDPOINT=http://jaeger:14268/api/traces
```
## 🔄 动态配置
### 启用动态配置
```bash
# 启用动态配置功能
ENABLE_DYNAMIC_CONFIG=true
# 配置缓存时间
CONFIG_CACHE_TTL=300
```
### 动态配置示例
通过 API 接口管理动态配置：
```bash
# 设置邮件配置
curl -X POST http://localhost:3000/adminapi/config/dynamic \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-token" \
-d '{
"key": "email.smtp",
"value": {
"host": "smtp.gmail.com",
"port": 587,
"secure": false
},
"description": "SMTP 服务器配置",
"category": "email",
"isPublic": false
}'
```
## 🧪 测试配置
### 验证配置
```bash
# 启动应用后访问配置验证接口
curl http://localhost:3000/adminapi/config/validate
# 查看系统配置
curl http://localhost:3000/adminapi/config/system
```
### 配置检查清单
- [ ] 数据库连接正常
- [ ] Redis 连接正常
- [ ] JWT 密钥已设置
- [ ] 日志级别合适
- [ ] 文件上传路径存在
- [ ] 第三方服务配置正确
## 🚨 常见问题
### 1. 配置不生效
**问题**：修改了 `.env` 文件但配置没有生效
**解决**：
- 确保 `.env` 文件在项目根目录
- 重启应用
- 检查环境变量名称是否正确
### 2. 数据库连接失败
**问题**：无法连接到数据库
**解决**：
- 检查 `DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD`
- 确保数据库服务正在运行
- 检查防火墙设置
### 3. Redis 连接失败
**问题**：无法连接到 Redis
**解决**：
- 检查 `REDIS_HOST`、`REDIS_PORT`、`REDIS_PASSWORD`
- 确保 Redis 服务正在运行
- 检查 Redis 配置
### 4. JWT 错误
**问题**：JWT 相关错误
**解决**：
- 确保 `JWT_SECRET` 已设置且足够复杂
- 检查 `JWT_EXPIRES_IN` 格式
- 验证 `JWT_ALGORITHM` 设置
## 📚 相关文档
- [配置中心使用指南](../src/config/README.md)
- [API 文档](http://localhost:3000/docs)
- [健康检查](http://localhost:3000/health)
## 🤝 支持
如果遇到配置问题，请：
1. 检查本文档的常见问题部分
2. 查看应用日志
3. 使用配置验证接口检查配置
4. 联系技术支持团队

352
docs/FRAMEWORK-PRINCIPLES.md Normal file
View File

@@ -0,0 +1,352 @@
# 🏗️ 三大框架原则对比与统一标准
## 📋 概述
本文档为AI开发者提供NestJS、ThinkPHP、Spring Boot三大框架的详细对比，包含功能映射、开发规范、命名约定和目录结构对比，确保AI能够更好地理解和开发功能。
**重要原则：既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致**
## 🔄 核心功能映射
### 1. 基础架构对比
| 功能模块 | ThinkPHP | NestJS | Spring Boot | 对应关系 | 实现方式 |
|---------|----------|---------|-------------|----------|----------|
| **路由系统** | `Route::get()` | `@Get()` | `@GetMapping()` | ✅ 直接对应 | 装饰器路由 |
| **控制器** | `Controller` | `@Controller()` | `@RestController` | ✅ 直接对应 | 装饰器控制器 |
| **中间件** | `Middleware` | `@UseGuards()` | `@Component` | ✅ 功能对应 | 守卫/拦截器 |
| **依赖注入** | `Container::get()` | `constructor()` | `@Autowired` | ✅ 更强大 | 自动注入 |
| **数据验证** | `Validate` | `@UsePipes()` | `@Valid` | ✅ 功能对应 | 验证管道 |
| **异常处理** | `Exception` | `@UseFilters()` | `@ExceptionHandler` | ✅ 功能对应 | 异常过滤器 |
### 2. 数据库操作对比
| 功能模块 | ThinkPHP | NestJS | Spring Boot | 对应关系 | 实现方式 |
|---------|----------|---------|-------------|----------|----------|
| **模型定义** | `Model` | `@Entity()` | `@Entity` | ✅ 功能对应 | TypeORM/JPA 实体 |
| **查询构建** | `Db::table()` | `Repository` | `JpaRepository` | ✅ 功能对应 | TypeORM/JPA 仓库 |
| **关联关系** | `hasMany()` | `@OneToMany()` | `@OneToMany` | ✅ 功能对应 | ORM 关联 |
| **事务处理** | `Db::startTrans()` | `@Transaction()` | `@Transactional` | ✅ 功能对应 | 声明式事务 |
| **软删除** | `SoftDelete` | `@DeleteDateColumn()` | `@SQLDelete` | ✅ 功能对应 | ORM 软删除 |
### 3. 缓存和会话
| 功能模块 | ThinkPHP | NestJS | Spring Boot | 对应关系 | 实现方式 |
|---------|----------|---------|-------------|----------|----------|
| **缓存管理** | `Cache::get()` | `@Inject(CACHE_MANAGER)` | `@Cacheable` | ✅ 功能对应 | Cache Manager |
| **会话管理** | `Session` | `@Session()` | `HttpSession` | ✅ 功能对应 | Session 装饰器 |
| **Redis 集成** | `Redis::get()` | `@InjectRedis()` | `@Autowired RedisTemplate` | ✅ 功能对应 | Redis 模块 |
## 🏗️ 目录结构对比
### ThinkPHP 目录结构
```
thinkphp/
├── app/ # 应用目录
│ ├── controller/ # 控制器
│ ├── model/ # 模型
│ ├── service/ # 服务层
│ └── middleware/ # 中间件
├── config/ # 配置文件
├── public/ # 公共资源
├── route/ # 路由定义
└── vendor/ # 第三方包
```
### Spring Boot 目录结构
```
spring-boot/
├── src/main/java/
│ ├── controller/ # 控制器层
│ ├── service/ # 服务层
│ ├── repository/ # 数据访问层
│ ├── entity/ # 实体层
│ ├── dto/ # 数据传输对象
│ └── config/ # 配置类
├── src/main/resources/
│ ├── application.yml # 配置文件
│ └── static/ # 静态资源
└── pom.xml # 依赖管理
```
### 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 | Spring Boot | NestJS | 说明 |
|------|----------|-------------|---------|------|
| **应用层** | `app/` | `src/main/java/` | `src/common/` | 业务逻辑和通用服务 |
| **配置层** | `config/` | `src/main/resources/` | `src/config/` | 配置管理和环境变量 |
| **核心层** | 框架核心 | Spring框架 | `src/core/` | 基础设施和核心功能 |
| **适配层** | `vendor/` | 第三方依赖 | `src/vendor/` | 第三方服务集成 |
## 📝 命名规范对比
### 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) 标准命名规范
| 文件类型 | 命名规范 | 标准示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `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` | `userController.ts`, `userProfileController.ts` | camelCase + 后缀 |
| **实体** | `camelCase.entity.ts` | `userEntity.ts`, `sysUser.entity.ts` | camelCase + 后缀 |
| **服务** | `camelCase.service.ts` | `userService.ts`, `userProfileService.ts` | camelCase + 后缀 |
| **DTO** | `camelCase.dto.ts` | `createUser.dto.ts`, `updateUser.dto.ts` | camelCase + 后缀 |
| **模块** | `camelCase.module.ts` | `userModule.ts`, `adminModule.ts` | camelCase + 后缀 |
| **目录** | `camelCase` | `controllers/`, `services/`, `dto/` | camelCase 目录 |
**重要说明**：
- **文件名**：使用 `camelCase.suffix.ts` 格式（本项目统一规范）
- **类名**：使用 `PascalCase` 格式（TypeScript标准）
- **示例**：文件 `user.controller.ts` 导出类 `UserController`
## 🎯 统一命名标准（最终规范）
### 核心原则
1. **业务对齐优先**: 业务逻辑命名与PHP项目保持一致
2. **框架规范遵循**: NestJS特有文件类型按NestJS规范
3. **可读性保证**: 确保命名清晰、语义明确
### 文件命名规范（最终版）
#### 实体文件命名
- **规范**: `{PHP模型名首字母小写}.entity.ts`
- **对应关系**: 与PHP模型文件一一对应，但使用PascalCase命名
- **示例**:
- PHP `SysUser.php` → NestJS `SysUser.entity.ts`
- PHP `SysConfig.php` → NestJS `SysConfig.entity.ts`
- PHP `MemberLevel.php` → NestJS `MemberLevel.entity.ts`
#### 控制器文件命名
- **规范**: `{模块名}.controller.ts` (NestJS 标准，使用PascalCase)
- **示例**: `User.controller.ts`, `Order.controller.ts`, `Admin.controller.ts`
#### 服务文件命名
- **规范**: `{模块名}.service.ts` (NestJS 标准，使用PascalCase)
- **示例**: `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`, `OrderService`, `AdminService`
#### DTO类命名
- **规范**: `PascalCase + Dto`
- **示例**: `CreateUserDto`, `UpdateUserDto`, `QueryAdminDto`
### 方法命名规范（最终版）
#### 业务逻辑方法
**优先与 PHP 项目保持一致，NestJS 特有方法按 NestJS 规范：**
- **CRUD 方法**: 与 PHP 项目方法名保持一致
- **查询方法**: 与 PHP 项目方法名保持一致
- **业务方法**: 与 PHP 项目方法名保持一致
- **NestJS 生命周期方法**: 按 NestJS 规范，如 `onModuleInit()`, `onApplicationBootstrap()`
#### 变量命名规范
**业务变量优先与 PHP 项目保持一致，NestJS 特有变量按 NestJS 规范：**
- **业务变量**: 与 PHP 项目变量名保持一致
- **业务常量**: 与 PHP 项目常量名保持一致
- **NestJS 注入变量**: 按 NestJS 规范，如 `private readonly userService: UserService`
- **TypeORM 相关变量**: 按 TypeORM 规范，如 `@InjectRepository(User)`
## 🔧 数据库命名规范
### 重要约束：与 PHP 项目共用数据库，必须保持命名一致
- **表名**: 与 PHP 项目完全一致，包括前缀和命名方式
- **字段名**: 与 PHP 项目完全一致，不能修改任何字段名
- **字段类型**: 与 PHP 项目完全一致，不能修改字段类型
- **索引结构**: 与 PHP 项目完全一致，不能添加或删除索引
**原则：看到 PHP 项目怎么命名，我们就怎么命名，保持 100% 一致**
## 🏗️ 模块目录结构规范
### 标准模块目录结构
```
src/common/{模块名}/
├── {模块名}.module.ts # 模块定义文件
├── controllers/ # 控制器目录
│ ├── adminapi/ # 管理端控制器目录（对应PHP adminapi/controller）
│ │ └── {模块名}.controller.ts
│ └── api/ # 前台控制器目录（对应PHP api/controller）
│ └── {模块名}.controller.ts
├── services/ # 服务目录
│ ├── admin/ # 管理端服务目录（对应PHP service/admin）
│ │ └── {模块名}.service.ts
│ ├── api/ # 前台服务目录（对应PHP service/api）
│ │ └── {模块名}.service.ts
│ └── core/ # 核心服务目录（对应PHP service/core）
│ └── {模块名}.service.ts
├── entity/ # 实体目录（对应PHP model）
│ ├── {实体名}.entity.ts # 实体文件（PascalCase.entity.ts格式）
│ └── {配置实体}.entity.ts # 配置实体文件
├── dto/ # DTO 目录（对应PHP validate）
│ ├── admin/ # 管理端DTO目录
│ │ ├── Create{模块名}Dto.ts
│ │ └── Update{模块名}Dto.ts
│ └── api/ # 前台DTO目录
│ ├── {操作}Dto.ts
│ └── {操作}Dto.ts
├── guards/ # 守卫目录（可选）
├── decorators/ # 装饰器目录（可选）
├── interfaces/ # 接口目录（可选）
└── enums/ # 枚举目录（可选）
```
### 实际示例（基于auth模块）
```
src/common/auth/
├── auth.module.ts
├── controllers/
│ ├── adminapi/ # 管理端控制器目录
│ │ └── Auth.controller.ts
│ └── api/ # 前台控制器目录
│ └── Auth.controller.ts
├── services/
│ ├── admin/ # 管理端服务目录
│ │ └── Auth.service.ts
│ ├── api/ # 前台服务目录
│ │ └── Auth.service.ts
│ └── core/ # 核心服务目录
│ └── Auth.service.ts
├── entity/
│ └── AuthToken.entity.ts
├── dto/
│ ├── admin/ # 管理端DTO目录
│ │ ├── CreateAuthDto.ts
│ │ └── UpdateAuthDto.ts
│ └── api/ # 前台DTO目录
│ ├── LoginDto.ts
│ └── RegisterDto.ts
├── guards/
│ ├── GlobalAuthGuard.ts
│ ├── JwtAuthGuard.ts
│ └── RolesGuard.ts
├── decorators/
│ ├── RolesDecorator.ts
│ ├── public.decorator.ts
│ └── user-context.decorator.ts
└── interfaces/
└── user.interface.ts
```
## 🔄 模块间通信规范
### 模块依赖管理
## 🎯 框架特性对比
### 依赖注入对比
| 框架 | 实现方式 | 示例 |
|------|----------|------|
| **ThinkPHP** | 容器获取 | `Container::get('UserService')` |
| **Spring Boot** | 注解注入 | `@Autowired private UserService userService;` |
| **NestJS** | 构造函数注入 | `constructor(private userService: UserService) {}` |
### 装饰器对比
| 功能 | ThinkPHP | Spring Boot | NestJS |
|------|----------|-------------|---------|
| **路由** | `Route::get()` | `@GetMapping()` | `@Get()` |
| **验证** | `validate()` | `@Valid` | `@UsePipes()` |
| **事务** | `Db::startTrans()` | `@Transactional` | `@Transaction()` |
| **缓存** | `Cache::remember()` | `@Cacheable` | `@UseInterceptors()` |
## 📚 最佳实践
### 1. 业务逻辑迁移原则
- 严格按照PHP项目的业务逻辑实现
- 保持API接口的输入输出格式一致
- 维护相同的数据验证规则
- 确保错误处理机制一致
### 2. 框架特性使用原则
- 充分利用NestJS的依赖注入特性
- 使用装饰器简化代码编写
- 采用模块化设计提高代码可维护性
- 利用TypeScript的类型系统提高代码质量
### 3. 性能优化原则
- 合理使用缓存机制
- 优化数据库查询
- 实现异步处理
- 采用批量操作减少数据库访问
---
**重要提醒**: 本文档是三框架对比的权威指南，AI开发者必须严格遵循这些原则，确保代码质量和规范一致性。

269
docs/NAMING-CONVENTIONS.md Normal file
View File

@@ -0,0 +1,269 @@
# 🏷️ 命名规范指南
## 📋 概述
本文档为AI开发者提供完整的命名规范指南，确保NestJS项目与PHP项目在业务层面保持100%一致，同时遵循NestJS框架特性。
## 🎯 核心原则
1. **业务对齐优先**: 业务逻辑命名与PHP项目保持一致
2. **框架规范遵循**: NestJS特有文件类型按NestJS规范
3. **可读性保证**: 确保命名清晰、语义明确
4. **数据库一致性**: 与PHP项目共用数据库，命名必须完全一致
## 🏗️ 三大框架命名规范对比
### 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) 标准命名规范
| 文件类型 | 命名规范 | 标准示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `PascalCase + Controller.java` | `UserController.java` | 有Controller后缀 |
| **实体** | `PascalCase.java` | `User.java`, `Order.java` | 直接使用业务名称 |
| **服务** | `PascalCase + Service.java` | `UserService.java` | 有Service后缀 |
| **DTO** | `PascalCase + Dto.java` | `CreateUserDto.java` | 有Dto后缀 |
| **仓储** | `PascalCase + Repository.java` | `UserRepository.java` | 有Repository后缀 |
### 3. NestJS 框架标准命名规范
| 文件类型 | 命名规范 | 标准示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `camelCase.controller.ts` | `userController.ts`, `userProfileController.ts` | camelCase + 后缀 |
| **实体** | `camelCase.entity.ts` | `userEntity.ts`, `sysUser.entity.ts` | camelCase + 后缀 |
| **服务** | `camelCase.service.ts` | `userService.ts`, `userProfileService.ts` | camelCase + 后缀 |
| **DTO** | `camelCase.dto.ts` | `createUser.dto.ts`, `updateUser.dto.ts` | camelCase + 后缀 |
| **模块** | `camelCase.module.ts` | `userModule.ts`, `adminModule.ts` | camelCase + 后缀 |
**重要说明**：
- **文件名**：使用 `camelCase.suffix.ts` 格式（项目统一规范）
- **类名**：使用 `PascalCase` 格式（TypeScript 标准）
- **示例**：文件 `userController.ts` 导出类 `UserController`
## 🎯 统一命名标准（最终规范）
### 文件命名规范（camelCase + 后缀）
#### 实体文件命名
- **规范**: `{PHP模型名转camelCase}.entity.ts`
- **对应关系**: 与 PHP 模型文件一一对应，但使用 camelCase 命名
- **示例**:
- PHP `SysUser.php` → NestJS `sysUser.entity.ts`
- PHP `SysConfig.php` → NestJS `sysConfig.entity.ts`
- PHP `MemberLevel.php` → NestJS `memberLevel.entity.ts`
#### 控制器文件命名
- **规范**: `{模块名}.controller.ts`（使用 camelCase）
- **示例**: `userController.ts`, `orderController.ts`, `adminController.ts`
#### 服务文件命名
- **规范**: `{模块名}.service.ts`（使用 camelCase）
- **示例**: `userService.ts`, `orderService.ts`, `adminService.ts`
#### DTO文件命名
- **规范**: `{操作动词}{模块名}.dto.ts`（使用 camelCase）
- **示例**: `createUser.dto.ts`, `updateUser.dto.ts`, `queryAdmin.dto.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`, `OrderService`, `AdminService`
#### DTO类命名
- **规范**: `{操作动词}{模块名}Dto`
- **示例**: `CreateUserDto`, `UpdateOrderDto`, `QueryMemberDto`
### 方法命名规范
#### 业务逻辑方法
**优先与PHP项目保持一致，NestJS特有方法按NestJS规范**
- **CRUD方法**: 与PHP项目方法名保持一致
- **查询方法**: 与PHP项目方法名保持一致
- **业务方法**: 与PHP项目方法名保持一致
- **NestJS生命周期方法**: 按NestJS规范，如 `onModuleInit()`, `onApplicationBootstrap()`
#### 变量命名规范
**业务变量优先与PHP项目保持一致，NestJS特有变量按NestJS规范**
- **业务变量**: 与PHP项目变量名保持一致
- **业务常量**: 与PHP项目常量名保持一致
- **NestJS注入变量**: 按NestJS规范，如 `private readonly userService: UserService`
- **TypeORM相关变量**: 按TypeORM规范，如 `@InjectRepository(User)`
## 🗄️ 数据库命名规范
### 重要约束
**与PHP项目共用数据库，必须保持命名100%一致**
- **表名**: 与PHP项目完全一致，包括前缀和命名方式
- **字段名**: 与PHP项目完全一致，不能修改任何字段名
- **字段类型**: 与PHP项目完全一致，不能修改字段类型
- **索引结构**: 与PHP项目完全一致，不能添加或删除索引
### 实体映射规范
```typescript
// 正确示例：与PHP模型SysUser.php对应
@Entity('sys_user') // 表名与PHP项目一致
export class SysUser {
@PrimaryGeneratedColumn()
id: number; // 字段名与PHP项目一致
@Column({ name: 'username', length: 50 })
username: string; // 字段名与PHP项目一致
@Column({ name: 'created_at', type: 'timestamp' })
createdAt: Date; // 字段名与PHP项目一致
}
```
## 📁 目录结构命名规范
### 标准模块目录结构
```
src/common/{模块名}/
├── {模块名}.module.ts # 模块定义文件
├── controllers/ # 控制器目录
│ ├── adminapi/ # 管理端控制器目录（对应PHP adminapi/controller）
│ │ └── {模块名}.controller.ts
│ └── api/ # 前台控制器目录（对应PHP api/controller）
│ └── {模块名}.controller.ts
├── services/ # 服务目录
│ ├── admin/ # 管理端服务目录（对应PHP service/admin）
│ │ └── {模块名}.service.ts
│ ├── api/ # 前台服务目录（对应PHP service/api）
│ │ └── {模块名}.service.ts
│ └── core/ # 核心服务目录（对应PHP service/core）
│ └── {模块名}.service.ts
├── entity/ # 实体目录（对应PHP model）
│ ├── {实体名}.entity.ts # 实体文件（camelCase.entity.ts 格式）
│ └── {配置实体}.entity.ts # 配置实体文件
├── dto/ # DTO 目录（对应PHP validate）
│ ├── admin/ # 管理端DTO目录
│ │ ├── create-{模块名}.dto.ts
│ │ └── update-{模块名}.dto.ts
│ └── api/ # 前台DTO目录
│ ├── {操作}-{模块}.dto.ts
│ └── {操作}-{模块}.dto.ts
├── guards/ # 守卫目录（可选）
├── decorators/ # 装饰器目录（可选）
├── interfaces/ # 接口目录（可选）
└── enums/ # 枚举目录（可选）
```
### 实际示例（基于auth模块）
```
src/common/auth/
├── auth.module.ts
├── controllers/
│ ├── adminapi/
│ │ └── auth.controller.ts # 管理端控制器
│ └── api/
│ └── auth.controller.ts # 前台控制器
├── services/
│ ├── admin/
│ │ └── auth.service.ts # 管理端服务
│ ├── api/
│ │ └── auth.service.ts # 前台服务
│ └── core/
│ └── auth.service.ts # 核心服务
├── entity/
│ └── auth-token.entity.ts # 实体文件
├── dto/
│ ├── admin/
│ │ ├── create-auth.dto.ts # 管理端DTO
│ │ └── update-auth.dto.ts
│ └── api/
│ ├── login.dto.ts # 前台DTO
│ └── register.dto.ts
├── guards/
│ ├── global-auth.guard.ts
│ ├── jwt-auth.guard.ts
│ └── roles.guard.ts
├── decorators/
│ ├── roles.decorator.ts
│ ├── public.decorator.ts
│ └── user-context.decorator.ts
└── interfaces/
└── user.interface.ts
```
## 🚫 命名禁止规则
### 绝对禁止的命名行为
1. **🚫 禁止修改数据库相关命名**
- 不能修改表名、字段名、索引名
- 不能修改字段类型和长度
- 必须与PHP项目数据库结构100%一致
2. **🚫 禁止自创业务方法名**
- 业务方法名必须与PHP项目对应方法保持一致
- 不能随意创造新的业务方法名
3. **🚫 禁止使用非标准缩写**
- 避免使用不明确的缩写，如 `usr` 代替 `user`
- 避免使用中文拼音命名
4. **🚫 禁止混合命名风格**
- 同一项目内必须保持命名风格一致
- 不能在同一文件中混用不同的命名规范
## ✅ 命名检查清单
### 开发前检查
- [ ] 已查看对应的PHP源码文件命名
- [ ] 已确认数据库表结构和字段命名
- [ ] 已理解业务逻辑和方法命名
- [ ] 已确认模块目录结构规范
### 开发中检查
- [ ] 实体类名与PHP模型名保持一致
- [ ] 数据库表名和字段名与PHP项目一致
- [ ] 业务方法名与PHP项目对应方法一致
- [ ] 文件命名符合NestJS规范
### 开发后检查
- [ ] 所有命名符合统一标准
- [ ] 没有使用禁止的命名方式
- [ ] 目录结构清晰规范
- [ ] 文档和注释命名准确
## 📚 相关文档
- [AI智能体工作流程指南](./AI-WORKFLOW-GUIDE.md)
- [AI开发禁止规则](./AI-DEVELOPMENT-RULES.md)
- [三框架原则对比](./FRAMEWORK-PRINCIPLES.md)
- [项目整体结构参考](./PROJECT-STRUCTURE.md)
---
**重要提醒**: 命名规范是代码质量的基础，所有AI开发者必须严格遵循此命名规范，确保项目的一致性和可维护性。

48
docs/SYS-API-MAPPING.md Normal file
View File

@@ -0,0 +1,48 @@
# SYS API 对照与缺口清单
- 管理端 /adminapi
- config
- GET /adminapi/config/system → 系统配置快照（PHP/Java 同等能力）
- GET /adminapi/config/dynamic → 动态配置列表
- GET /adminapi/config/dynamic/:key → 单项配置
- POST /adminapi/config/dynamic → 创建配置
- PUT /adminapi/config/dynamic/:key → 更新配置
- DELETE /adminapi/config/dynamic/:key → 删除配置
- POST /adminapi/config/refresh-cache → 刷新缓存（占位）
- GET /adminapi/config/validate, /metadata, /stats → 运营辅助
- sys/menu
- GET /adminapi/sys/menu/list, /tree → 菜单查询
- POST /adminapi/sys/menu → 创建
- PUT /adminapi/sys/menu/:id → 更新
- DELETE /adminapi/sys/menu/:id → 删除
- sys/dict
- GET /adminapi/sys/dict/types, /items?type=xxx → 查询
- POST /adminapi/sys/dict/type, /item → 创建
- PUT /adminapi/sys/dict/type/:id, /item/:id → 更新
- DELETE /adminapi/sys/dict/type/:id, /item/:id → 删除
- sys/area
- GET /adminapi/sys/area/list, /tree → 区域查询
- 前台 /api
- config
- GET /api/config/:key → 单项
- GET /api/config?keys=a,b,c → 批量（新增）
- dict
- GET /api/dict/:type/items → 项列表
- area
- GET /api/area/tree → 区域树
- 鉴权/租户/权限
- 管理端：Jwt + SiteScope + @Roles（全局 RolesGuard 已启用）
- 前台：可选鉴权 + SiteScope
- 与 PHP/Java 对齐情况
- 路由结构：已对齐 admin/api 分层
- 业务能力：config/dict/menu/area 已具备常见 CRUD/查询
- 审计：config/dict/menu 写操作已记录
- 多租户：site_id 查询隔离
- 缺口与建议
- e2e：补齐鉴权/租户/权限关键路径（进行中）
- 缓存：dict/menu 已加短缓存；如需可扩展至 area
- 文档：Swagger 分组与 Token 访问控制（可选）