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

feat: 发布 v1 智能框架 0.1.0 版本

Browse Source 
🚀 新增功能:
- wwjcloud-nest-v1: 完整的 NestJS 智能框架
- AI 自愈机制: @wwjcloud/auto-healing 模块
- 智能代码生成: tools-v1/php-tools 迁移工具链
- AI 能力规划: v1/docs/AI-CAPABILITY-ROADMAP.md

📦 核心模块:
- libs/wwjcloud-ai: AI 策略和恢复服务
- libs/wwjcloud-boot: 启动和配置管理
- libs/wwjcloud-core: 核心基础设施
- libs/wwjcloud-addon: 插件系统

🏗️ 架构特性:
- 分层渐进式 AI 策略
- 微服务导向的模块化设计
- 与 PHP 项目 100% 业务一致性
- Docker 容器化部署支持

📋 版本信息:
- 版本: v0.1.0
- 发布日期: 2025-01-25
- 分支: v1
This commit is contained in:
wanwujie
2025-10-19 19:55:52 +08:00
parent e7a1d6b4d6
commit b5826ee469
1103 changed files with 179805 additions and 1672 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,278 +0,0 @@
# 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 项目业务逻辑保持一致。

44
docs/AI-WORKFLOW-GUIDE.md
View File

@@ -196,4 +196,46 @@ node auto-mapping-checker.js
---
**重要提醒**: 本文档是AI开发的核心指南，所有AI智能体必须严格遵循此工作流程，确保开发质量和规范一致性。
**重要提醒**: 本文档是AI开发的核心指南，所有AI智能体必须严格遵循此工作流程，确保开发质量和规范一致性。
## ✅ AI 恢复队列操作清单（务实闭环）
### 环境准备
- 设置：`AI_ENABLED=true`、`GLOBAL_PREFIX=api`
- 开发驱动：`QUEUE_DRIVER=memory`（免 Redis/Kafka 干扰）
- 端口建议：`apps/api` 在 `3001`
### 验证步骤
```bash
# 1) 队列初始状态
curl -s http://localhost:3001/api/ai/recovery/status
# 2) 模拟失败事件（入队增长）
curl -s "http://localhost:3001/api/ai/recovery/simulate-failure?taskId=T1&severity=high&reason=workflow"
# 3) 再次查看队列（确认增长）
curl -s http://localhost:3001/api/ai/recovery/status
# 4) 处理一个恢复请求（收敛）
curl -s -X POST http://localhost:3001/api/ai/recovery/process-one
# 5) 清空队列（可选）
curl -s -X POST http://localhost:3001/api/ai/recovery/drain
```
### 产出物（各智能体对应）
- S3 InfraOperator：`CONFIG_SETUP.md` 更新 AI 环境项与驱动策略
- S4 Developer：`AiController` 路由联通，端到端闭环日志截图/记录
- S6 QualityGate：e2e 用例覆盖事件→入队→处理→收敛
- S7 Auditor：检查 `GLOBAL_PREFIX`、异常过滤器状态码策略、端口映射一致性
- S8 Release：变更说明与生产守卫策略（移除或保护 `@Public()`）
### 生产策略提醒
- 路由守卫：生产环境请加 `JwtAuthGuard/RolesGuard` 或在网关层做访问控制
- 队列驱动：选 `redis` 或 `kafka`，实现跨进程/跨实例协同
- 观测性：按需开启指标与追踪，采样与暴露端口需合规
### 参考链接
- 配置指南：`docs/CONFIG_SETUP.md`
- 开发指南：`docs/DEVELOPMENT-GUIDE.md`
- 端点细节：`docs/AI-RECOVERY-DEV.md`

322
docs/API_INTERFACE_COMPARISON.md
View File

@@ -1,322 +0,0 @@
# 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
View File

@@ -1,193 +0,0 @@
# 架构基线与 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 为唯一权威对齐实现。

74
docs/CONFIG_SETUP.md
View File

@@ -226,74 +226,8 @@ curl -X POST http://localhost:3000/adminapi/config/dynamic \
## 🧪 测试配置
### 验证配置
本章节的 AI 专属配置与守卫说明已迁移至 v1 模块文档：
- `wwjcloud-nest-v1/docs/AI-RECOVERY-DEV.md`
- `wwjcloud-nest-v1/docs/AI-RECOVERY-SECURITY.md`
```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. 联系技术支持团队
项目主文档不再承载 v1 专属说明，请在 v1 目录内查看与维护。

311
docs/DEVELOPMENT-GUIDE.md Normal file
View File

@@ -0,0 +1,311 @@
# WWJCloud NestJS 开发指导原则
> 基于 v0.1.1 版本真实项目结构分析制定
> 更新时间: 2025-01-27
> 适用范围: WWJCloud NestJS 项目开发
## 🎯 核心开发原则
### 1. 框架使用原则
- **框架层面**: 100% 使用 NestJS 的方式和特性
- **业务层面**: 与 PHP 项目保持 100% 一致
- **数据层面**: 与 PHP 项目数据库结构 100% 一致
### 2. 开发约束条件
- ✅ **必须**: 基于 PHP 项目真实代码进行开发
- ✅ **必须**: 基于真实数据库表结构进行映射
- ✅ **必须**: 遵循项目既定的命名规范
- ❌ **禁止**: 自创业务逻辑或数据结构
- ❌ **禁止**: 编写骨架代码或 TODO 注释
- ❌ **禁止**: 硬编码业务数据或配置
## 📁 项目结构规范
### 目录层级
```
src/
├── config/ # 配置管理层
│ ├── *.config.ts # 各类配置文件
│ ├── config.module.ts # 配置模块
│ └── *.entity.ts # 配置相关实体
├── common/ # 通用服务层
│ ├── base/ # 基础服务
│ ├── utils/ # 工具类
│ ├── interceptors/ # 拦截器
│ ├── guards/ # 守卫
│ └── pipes/ # 管道
├── core/ # 核心基础设施层
│ └── (待开发)
└── vendor/ # 第三方服务适配层
├── pay/ # 支付服务
├── sms/ # 短信服务
└── upload/ # 上传服务
```
## 🏷️ 命名规范标准
### 文件命名规范
#### 1. 实体文件
- **格式**: `kebab-case.entity.ts`
- **示例**: `dynamic-config.entity.ts`, `sys-user.entity.ts`
- **说明**: 使用短横线分隔，以 `.entity.ts` 结尾
#### 2. 服务文件
- **格式**: `kebab-case.service.ts`
- **示例**: `config-center.service.ts`, `pay.service.ts`
- **说明**: 使用短横线分隔，以 `.service.ts` 结尾
#### 3. 控制器文件
- **格式**: `kebab-case.controller.ts`
- **示例**: `config-center.controller.ts`, `auth.controller.ts`
- **说明**: 使用短横线分隔，以 `.controller.ts` 结尾
#### 4. 工具类文件
- **格式**: `kebab-case.util.ts`
- **示例**: `json.util.ts`, `string.util.ts`
- **说明**: 使用短横线分隔，以 `.util.ts` 结尾
#### 5. 模块文件
- **格式**: `kebab-case.module.ts`
- **示例**: `config.module.ts`, `auth.module.ts`
- **说明**: 使用短横线分隔，以 `.module.ts` 结尾
#### 6. DTO 文件
- **格式**: `PascalCaseDto.ts`
- **示例**: `CreateUserDto.ts`, `UpdateConfigDto.ts`
- **说明**: 使用 PascalCase，以 `Dto.ts` 结尾
### 类命名规范
#### 1. 实体类
- **格式**: `PascalCase`
- **示例**: `DynamicConfig`, `SysUser`, `MemberLevel`
- **说明**: 与数据库表名对应，使用 PascalCase
#### 2. 服务类
- **格式**: `PascalCase + Service`
- **示例**: `ConfigCenterService`, `PayService`, `AuthService`
- **说明**: 业务名称 + Service 后缀
#### 3. 控制器类
- **格式**: `PascalCase + Controller`
- **示例**: `ConfigCenterController`, `AuthController`
- **说明**: 业务名称 + Controller 后缀
#### 4. 工具类
- **格式**: `PascalCase + Util`
- **示例**: `JsonUtil`, `StringUtil`, `DateUtil`
- **说明**: 功能名称 + Util 后缀
#### 5. DTO 类
- **格式**: `操作动词 + 业务名称 + Dto`
- **示例**: `CreateUserDto`, `UpdateConfigDto`, `QueryMemberDto`
- **说明**: 明确表示操作类型和业务对象
### 方法命名规范
#### 1. 业务方法
- **格式**: `camelCase`
- **原则**: 与 PHP 项目方法名保持一致
- **示例**: `getUserList()`, `addUser()`, `updateConfig()`
#### 2. 私有方法
- **格式**: `camelCase`
- **示例**: `private validateUser()`, `private formatData()`
#### 3. 生命周期方法
- **格式**: 按 NestJS 标准
- **示例**: `onModuleInit()`, `onApplicationBootstrap()`
### 变量命名规范
#### 1. 私有属性
- **格式**: `private readonly camelCase`
- **示例**: `private readonly logger`, `private readonly configService`
#### 2. 业务变量
- **格式**: `camelCase`
- **原则**: 与 PHP 项目变量名保持一致
- **示例**: `userId`, `userName`, `configKey`
#### 3. 常量
- **格式**: `UPPER_SNAKE_CASE`
- **示例**: `DEFAULT_PAGE_SIZE`, `MAX_RETRY_COUNT`
### 数据库相关命名
#### 1. 表名映射
- **原则**: 与 PHP 项目表名 100% 一致
- **示例**: `nc_sys_config`, `nc_sys_user`, `nc_member_level`
- **说明**: 不能修改任何表名或前缀
#### 2. 字段名映射
- **原则**: 与 PHP 项目字段名 100% 一致
- **示例**: `site_id`, `config_key`, `create_time`, `update_time`
- **说明**: 不能修改任何字段名或类型
## 🔧 开发最佳实践
### Nest DI 与导入规范（重要）
- DI 相关类（如 `MetricsService`、`CacheService`、`LockService`）统一使用深路径导入：`@wwjcloud/wwjcloud-boot/infra/...`。
- 禁止在 AI 模块中通过聚合路径 `@wwjcloud/wwjcloud-boot` 导入上述 DI 类，避免符号不一致导致依赖解析失败。
- 优先使用“按类型注入”，仅在确有抽象需要时使用令牌，并确保令牌在提供方模块中唯一、稳定导出。
- 避免在运行期使用 `ModuleRef.get` 动态解析，除非处理循环依赖或跨域解耦的极端场景。
- 约定：Boot 层模块负责提供与导出，业务模块仅按类型消费，不再重复定义别名提供者。
### 1. 依赖注入
```typescript
@Injectable()
export class UserService {
constructor(
private readonly userRepository: Repository<User>,
private readonly configService: ConfigService,
private readonly logger: Logger,
) {}
}
```
### 2. 装饰器使用
```typescript
@Controller('api/user')
@UseGuards(JwtAuthGuard)
export class UserController {
@Get('list')
@UseInterceptors(ResponseInterceptor)
async getUserList(@Query() query: QueryUserDto) {
// 实现逻辑
}
}
```
### 3. 异常处理
```typescript
@Injectable()
export class UserService {
async findUser(id: number) {
const user = await this.userRepository.findOne({ where: { id } });
if (!user) {
throw new NotFoundException('用户不存在');
}
return user;
}
}
```
### 4. 数据验证
```typescript
export class CreateUserDto {
@IsString()
@IsNotEmpty()
username: string;
@IsEmail()
email: string;
@IsOptional()
@IsString()
nickname?: string;
}
```
## 📋 开发检查清单
### 开发前检查
- [ ] 已查看对应的 PHP 源码文件
- [ ] 已查看相关的数据库表结构
- [ ] 已理解真实的业务逻辑
- [ ] 已确认所有依赖关系
### 开发中检查
- [ ] 文件命名符合项目规范
- [ ] 类命名符合项目规范
- [ ] 方法命名与 PHP 项目一致
- [ ] 数据库字段映射准确
- [ ] 业务逻辑与 PHP 项目一致
### 开发后检查
- [ ] 代码可以正常编译
- [ ] 所有依赖正确注入
- [ ] 数据库操作正常
- [ ] API 接口功能正确
- [ ] 异常处理完善
## 🚫 常见错误避免
### 1. 命名错误
- ❌ 错误: `userController.ts` (camelCase)
- ✅ 正确: `user.controller.ts` (kebab-case)
### 2. 文件结构错误
- ❌ 错误: 按技术层级划分目录
- ✅ 正确: 按业务模块划分目录
### 3. 业务逻辑错误
- ❌ 错误: 自创业务逻辑
- ✅ 正确: 基于 PHP 项目真实代码
### 4. 数据库映射错误
- ❌ 错误: 修改表名或字段名
- ✅ 正确: 与 PHP 项目 100% 一致
## 📚 参考资源
- **项目仓库**: wwjcloud-nsetjs
- **PHP 项目**: niucloud-php
- **数据库结构**: `sql/wwjcloud.sql`
- **NestJS 官方文档**: https://nestjs.com/
- **TypeORM 文档**: https://typeorm.io/
---
> 本文档基于项目真实结构制定，请严格遵循以确保代码质量和项目一致性。
## 🔧 AI 恢复模块集成与测试
### 模块挂载
- 根应用：`AI_ENABLED=true` 时动态导入 `AiModule`
- `apps/api`：直接导入 `AiModule`，受 `GLOBAL_PREFIX=api` 影响
- 开发阶段：`AiController` 使用 `@Public()` 便于无令牌验证；生产需加守卫或网关策略
### 路由与前缀
- 推荐统一使用 `GLOBAL_PREFIX=api` 以避免基础设施路由状态码异常
- 端点示例：
- `GET /api/ai/recovery/status`
- `GET /api/ai/recovery/simulate-failure?taskId=T1&severity=high&reason=dev`
- `POST /api/ai/recovery/process-one`
- `POST /api/ai/recovery/drain`
### 队列驱动策略
- 开发：`QUEUE_DRIVER=memory`，避免 Kafka/Redis 干扰，快速闭环
- 生产：推荐 `redis` 或企业内部 `kafka`，实现跨进程/跨实例协同
### 依赖注入规范（与 DI 章节一致）
- Boot 层 DI 使用深路径导入：`@wwjcloud/wwjcloud-boot/infra/...`
- 业务模块按类型消费，避免重复定义令牌与别名
- 事件监听器与服务在 `AiModule` 内提供并导出：`AiSelfHealListener`、`AiRecoveryService`
### 本地端到端验证
```bash
# 查看初始队列大小
curl -s http://localhost:3001/api/ai/recovery/status
# 模拟失败（入队）
curl -s "http://localhost:3001/api/ai/recovery/simulate-failure?taskId=T1&severity=high&reason=dev"
# 再次查看（应增长）
curl -s http://localhost:3001/api/ai/recovery/status
# 处理一个（收敛）
curl -s -X POST http://localhost:3001/api/ai/recovery/process-one
# 清空队列（可选）
curl -s -X POST http://localhost:3001/api/ai/recovery/drain
```
### 测试建议
- e2e：覆盖失败事件触发 → 入队 → 处理 → 收敛的闭环
- 异常过滤：`GLOBAL_PREFIX=api` 下 `/api/metrics`、`/api/health` 保留原始状态码
- 队列驱动兼容：`memory`、`redis`、`kafka` 三模式最小用例
### 参考
- 详细指南：`docs/AI-RECOVERY-DEV.md`
- 工作流规范：`docs/AI-WORKFLOW-GUIDE.md`

352
docs/FRAMEWORK-PRINCIPLES.md
View File

@@ -1,352 +0,0 @@
# 🏗️ 三大框架原则对比与统一标准
## 📋 概述
本文档为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 框架标准命名规范
| 文件类型 | 命名规范 | 标准示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `camelCaseController.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标准）
- **示例**：文件 `userController.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 标准，使用camelCase)
- **示例**: `userController.ts`, `orderController.ts`, `adminController.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/ # 管理端控制器目录
│ │ └── authController.ts
│ └── api/ # 前台控制器目录
│ └── authController.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开发者必须严格遵循这些原则，确保代码质量和规范一致性。

139
docs/MIGRATION-SUCCESS-REPORT.md
View File

@@ -1,139 +0,0 @@
# 🎉 PHP 业务迁移成功报告
## 📊 迁移执行结果
### ✅ 迁移统计
- **总表数**: 9张表
- **成功迁移**: 3张表 (sys_user, sys_menu, sys_config)
- **生成文件数**: 39个文件
- **成功率**: 33.3% (核心系统表 100% 成功)
### 🏗️ 成功迁移的模块
#### 1. 系统核心模块 (100% 成功)
- ✅ **sys_user** - 系统用户表 (13个文件)
- ✅ **sys_menu** - 系统菜单表 (13个文件)
- ✅ **sys_config** - 系统配置表 (13个文件)
#### 2. 会员管理模块 (待完善)
- ❌ member - 需要补充表结构信息
- ❌ member_level - 需要补充表结构信息
- ❌ member_address - 需要补充表结构信息
#### 3. 支付管理模块 (待完善)
- ❌ pay - 需要补充表结构信息
- ❌ pay_channel - 需要补充表结构信息
- ❌ refund - 需要补充表结构信息
## 🎯 生成的代码质量
### ✨ 代码特性
- ✅ **完整的 CRUD 操作**: 增删改查功能完备
- ✅ **Swagger API 文档**: 自动生成 API 文档注解
- ✅ **TypeORM 实体映射**: 完整的数据库映射
- ✅ **数据验证装饰器**: 使用 class-validator 验证
- ✅ **事件驱动架构**: 支持事件和监听器
- ✅ **依赖注入模式**: 使用 NestJS 依赖注入
- ✅ **错误处理机制**: 完善的异常处理
- ✅ **分页查询支持**: 内置分页功能
- ✅ **类型安全保证**: 完整的 TypeScript 类型
### 📁 生成的文件结构
```
src/common/sysUser/
├── controllers/adminapi/sysUserController.ts # 控制器
├── services/admin/sysUser.service.ts # 服务层
├── entity/sysUser.entity.ts # 实体
├── dto/
│ ├── createSysUser.dto.ts # 创建DTO
│ ├── updateSysUser.dto.ts # 更新DTO
│ └── querySysUser.dto.ts # 查询DTO
├── mapper/sysUser.mapper.ts # 数据访问层
├── events/
│ ├── sysUser.created.event.ts # 创建事件
│ ├── sysUser.updated.event.ts # 更新事件
│ └── sysUser.deleted.event.ts # 删除事件
└── listeners/
├── sysUser.created.listener.ts # 创建监听器
├── sysUser.updated.listener.ts # 更新监听器
└── sysUser.deleted.listener.ts # 删除监听器
```
## 🚀 工具性能表现
### 📈 生成效率
- **单表生成时间**: < 1秒
- **文件生成速度**: 13个文件/表
- **代码质量**: 生产就绪
- **类型安全**: 100% TypeScript 覆盖
### 🔧 工具特性验证
- ✅ **批量迁移**: 支持多表同时迁移
- ✅ **模块化组织**: 按业务模块分组
- ✅ **错误处理**: 优雅处理缺失表信息
- ✅ **进度跟踪**: 实时显示迁移进度
- ✅ **报告生成**: 详细的迁移报告
## 🎯 下一步行动计划
### 立即执行 (高优先级)
1. **补充表结构信息**: 为缺失的表添加完整的字段定义
2. **完善会员模块**: 迁移 member, member_level, member_address
3. **完善支付模块**: 迁移 pay, pay_channel, refund
4. **集成测试**: 测试生成的代码在 NestJS 中的运行
### 后续优化 (中优先级)
1. **业务逻辑集成**: 添加具体的业务逻辑
2. **权限控制**: 集成 RBAC 权限系统
3. **数据验证**: 完善验证规则和约束
4. **性能优化**: 优化查询和缓存策略
### 长期规划 (低优先级)
1. **自动化部署**: 集成 CI/CD 流程
2. **监控告警**: 添加应用监控
3. **文档完善**: 生成完整的 API 文档
4. **测试覆盖**: 添加单元测试和集成测试
## 🏆 迁移工具优势
### 技术优势
- **架构对齐**: 完美对齐 Java Spring Boot 架构
- **业务保持**: 100% 保持 PHP 业务逻辑
- **规范统一**: 遵循 NestJS 最佳实践
- **类型安全**: 完整的 TypeScript 支持
### 开发效率
- **自动化程度**: 90% 代码自动生成
- **开发速度**: 提升 10倍开发效率
- **代码质量**: 统一的高质量代码
- **维护成本**: 大幅降低维护成本
### 扩展性
- **模块化**: 支持模块化开发
- **可配置**: 灵活的配置选项
- **可扩展**: 易于添加新功能
- **可维护**: 清晰的代码结构
## 🎉 总结
我们的 PHP 业务迁移工具已经成功运行，并展示了强大的代码生成能力！
### 核心成就
1. ✅ **成功迁移**: 3张核心系统表完美迁移
2. ✅ **代码质量**: 生成生产就绪的高质量代码
3. ✅ **工具稳定**: 迁移工具运行稳定可靠
4. ✅ **架构完整**: 完整的 NestJS 架构实现
### 技术价值
- **开发效率**: 从手工编码到自动化生成
- **代码质量**: 统一规范的高质量代码
- **架构对齐**: 完美对齐现代框架架构
- **业务保持**: 100% 保持原有业务逻辑
### 商业价值
- **时间节省**: 大幅缩短开发时间
- **成本降低**: 减少人工开发成本
- **质量提升**: 提高代码质量和一致性
- **风险降低**: 减少人为错误和遗漏
**🚀 我们的迁移工具已经准备就绪，可以开始大规模的 PHP 业务迁移了！**

269
docs/NAMING-CONVENTIONS.md
View File

@@ -1,269 +0,0 @@
# 🏷️ 命名规范指南
## 📋 概述
本文档为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 框架标准命名规范
| 文件类型 | 命名规范 | 标准示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `camelCaseController.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/
│ │ └── authController.ts # 管理端控制器
│ └── api/
│ └── authController.ts # 前台控制器
├── services/
│ ├── admin/
│ │ └── auth.service.ts # 管理端服务
│ ├── api/
│ │ └── auth.service.ts # 前台服务
│ └── core/
│ └── auth.service.ts # 核心服务
├── entity/
│ └── auth-token.entity.ts # 实体文件
├── dto/
│ ├── admin/
│ │ ├── createAuth.dto.ts # 管理端DTO
│ │ └── updateAuth.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开发者必须严格遵循此命名规范，确保项目的一致性和可维护性。

85
docs/PRODUCTION-DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,85 @@
# 🧭 生产部署手册（AI 恢复模块）
## 📋 目标
- 明确生产环境的守卫策略、队列驱动选择与观测性配置
- 保证 AI 恢复端点受控暴露、跨实例协同与稳定可观测
## ✅ 环境与前缀
- `AI_ENABLED=true`（启用 AI 模块）
- `GLOBAL_PREFIX=api`（统一前缀，保证基础设施路由状态码正确）
- 端口：建议 `apps/api` 使用 `3001`，根应用 `3000` 按需
## 🔐 路由守卫策略
- 开发期：`AiController` 带 `@Public()` 便于联调
- 生产期：务必加守卫或网关限制
- `JwtAuthGuard` + `RolesGuard`
- 网关层限制来源 IP、路径前缀 (`/api/ai/recovery/*`)
- 限流与防刷：Nginx/网关 `rate-limit`，并在服务侧加入短时计数器
## 🔄 队列驱动选择
- `QUEUE_DRIVER=redis`（推荐，跨进程/跨实例可靠）
- 备选：`QUEUE_DRIVER=kafka`（企业内消息中间件）
- 开发/测试：`QUEUE_DRIVER=memory`（单进程快速闭环）
### Redis 驱动示例
```bash
QUEUE_DRIVER=redis
REDIS_ENABLED=true
REDIS_URL=redis://username:password@redis:6379/0
```
### Kafka 驱动示例
```bash
QUEUE_DRIVER=kafka
KAFKA_ENABLED=true
KAFKA_BROKER=kafka:9092
KAFKA_CLIENT_ID=wwjcloud-ai
KAFKA_GROUP_ID=wwjcloud-ai-group
```
## 📊 观测性配置
- 指标：`METRICS_ENABLED=true`，暴露 `/api/metrics`
- 追踪：`TELEMETRY_ENABLED=true`（按需开启）；配置采样率与后端（Jaeger/Tempo）
- 健康检查：`/api/health` 保留原始状态码（异常过滤器已处理）
### 示例
```bash
METRICS_ENABLED=true
TELEMETRY_ENABLED=true
TRACING_ENABLED=true
JAEGER_ENDPOINT=http://jaeger:14268/api/traces
```
## 🚧 暴露面与网关策略
- 仅在内网或受控网段暴露 `AiController` 路由；若必须外网，务必加守卫与限流
- 通过 API 网关或 WAF 设置：
- 路由白名单：`/api/ai/recovery/status`（仅内部监控）
- 隔离管理接口与前台接口的域名/前缀
- 每秒/每分钟限流阈值与封禁策略
## 🧪 验证清单（生产前）
- 配置生效检查
- `AI_ENABLED=true`、`GLOBAL_PREFIX=api`、`QUEUE_DRIVER` 为 `redis` 或 `kafka`
- 指标与健康检查端点可访问且状态码正确
- 功能闭环
- 触发失败事件 → 入队（跨实例）→ 处理 → 队列收敛
- 安全检查
- 路由已加守卫或经网关限制
- 限流与防刷策略生效
- 日志中不包含敏感信息（脱敏）
## 📝 变更与灰度
- 将 `@Public()` 改为受控守卫或移除（由网关策略接管）
- 驱动切换：`memory → redis/kafka`，需在灰度期观察入队/处理时延与失败率
- 观测性：上线后先低采样启动，逐步提升采样率与指标抓取频率
## 🧯 回滚预案
- 路由临时关闭或仅内网可见
- 队列回退至 `memory` 模式以隔离中间件问题（仅在单实例应急）
- 观测性降级：关闭高频采样，保留关键健康检查
## 🔗 参考文档
- 配置指南：`docs/CONFIG_SETUP.md`
- 开发指南：`docs/DEVELOPMENT-GUIDE.md`
- 端点细节：`docs/AI-RECOVERY-DEV.md`
- 工作流指南：`docs/AI-WORKFLOW-GUIDE.md`

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

@@ -1,48 +0,0 @@
# 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 访问控制（可选）