127a4db1e3
- 重构sys模块架构，严格按admin/api/core分层 - 对齐所有sys实体与数据库表结构 - 实现完整的adminapi控制器，匹配PHP/Java契约 - 修复依赖注入问题，确保服务正确注册 - 添加自动迁移工具和契约验证 - 完善多租户支持和审计功能 - 统一命名规范，与PHP业务逻辑保持一致
152 lines
5.4 KiB
Markdown
152 lines
5.4 KiB
Markdown
# Common层模块化设计标准
|
||
|
||
## 📋 概述
|
||
|
||
本文档定义了 `wwjcloud/src/common/` 层的模块化设计标准，确保每个业务模块符合微服务导向的架构设计原则。
|
||
|
||
## 🏗️ 模块化设计原则
|
||
|
||
### 1. 模块完整性原则
|
||
每个业务模块必须包含完整的分层结构，为未来微服务拆分做准备。
|
||
|
||
### 2. 模块自治性原则
|
||
模块间通过明确的接口和事件进行通信，避免直接文件导入依赖。
|
||
|
||
### 3. 分层内聚原则
|
||
模块内部按照Spring Boot分层架构组织，确保职责清晰。
|
||
|
||
## 📁 标准目录结构
|
||
|
||
### 🎯 命名规范策略
|
||
- **文件名对齐PHP**：所有业务文件名与PHP项目保持一致（如 `User.ts`, `SysUser.ts`, `UserService.ts`）
|
||
- **目录结构参考Java**：采用Java/Spring Boot分层架构组织方式
|
||
- **避免NestJS文件命名风格**：不使用 `user.controller.ts` 风格，使用 `User.ts` 风格
|
||
|
||
### 完整模块结构（必需）
|
||
```
|
||
src/common/{module-name}/
|
||
├── {module-name}.module.ts # 模块定义文件（必需，NestJS特有）
|
||
├── controllers/ # 控制器层（必需）
|
||
│ ├── adminapi/ # 管理端控制器
|
||
│ │ └── {Name}.ts # 对齐PHP: User.php → User.ts
|
||
│ └── api/ # 前台控制器
|
||
│ └── {Name}.ts # 对齐PHP: User.php → User.ts
|
||
├── services/ # 服务层（必需）
|
||
│ ├── admin/ # 管理端服务
|
||
│ │ └── {Name}Service.ts # 对齐PHP: UserService.php → UserService.ts
|
||
│ ├── api/ # 前台服务
|
||
│ │ └── {Name}Service.ts # 对齐PHP: UserService.php → UserService.ts
|
||
│ └── core/ # 核心业务服务
|
||
│ └── {Name}Service.ts # 对齐PHP: UserService.php → UserService.ts
|
||
├── entity/ # 实体层（必需）
|
||
│ └── {Name}.ts # 对齐PHP: SysUser.php → SysUser.ts
|
||
├── dto/ # 数据传输对象（必需）
|
||
│ ├── admin/
|
||
│ │ └── {Name}Dto.ts # 对齐PHP验证器命名
|
||
│ └── api/
|
||
│ └── {Name}Dto.ts # 对齐PHP验证器命名
|
||
├── interfaces/ # 接口定义（可选）
|
||
│ └── {Name}Interface.ts # 对齐PHP接口命名
|
||
├── decorators/ # 装饰器（可选）
|
||
│ └── {Name}Decorator.ts # 对齐PHP特性命名
|
||
├── guards/ # 守卫（可选）
|
||
│ └── {Name}Guard.ts # 对齐PHP中间件命名
|
||
└── enums/ # 枚举（可选）
|
||
└── {Name}Enum.ts # 对齐PHP枚举命名
|
||
```
|
||
|
||
### 最小模块结构（基本要求）
|
||
```
|
||
src/common/{module-name}/
|
||
├── {module-name}.module.ts # 模块定义文件
|
||
├── controllers/ # 至少包含一个控制器
|
||
├── services/ # 至少包含一个服务
|
||
├── entity/ # 至少包含一个实体（如果有数据库操作）
|
||
└── dto/ # 至少包含一个DTO（如果有API接口）
|
||
```
|
||
|
||
## 🔍 当前模块分析结果
|
||
|
||
### ✅ 完整模块（26个）
|
||
符合标准的模块：
|
||
- addon, agreement, aliapp, applet, auth, diy, member, niucloud, pay, poster, site, sys, user, weapp
|
||
|
||
### ⚠️ 不完整模块（11个）
|
||
需要修复的模块：
|
||
|
||
#### 缺失DTO的模块（8个）
|
||
- channel: 缺失dto目录
|
||
- dict: 缺失dto目录
|
||
- generator: 缺失dto目录
|
||
- notice: 缺失dto目录
|
||
- schedule: 缺失dto目录
|
||
- stat: 缺失dto目录
|
||
- verify: 缺失dto目录
|
||
- wechat: 缺失dto目录
|
||
- wxoplatform: 缺失dto目录
|
||
|
||
#### 缺失Entity的模块（3个）
|
||
- home: 缺失entity目录
|
||
- login: 缺失entity目录
|
||
- upload: 缺失entity目录
|
||
|
||
#### 特殊模块（1个）
|
||
- lang: 缺失所有核心层级（controllers, services, entity, dto）
|
||
|
||
## 🛠️ 整治计划
|
||
|
||
### 阶段1：修复不完整模块
|
||
1. **为缺失DTO的模块添加DTO层**
|
||
- 基于控制器方法分析所需的DTO
|
||
- 创建标准的admin和api DTO目录结构
|
||
|
||
2. **为缺失Entity的模块添加Entity层**
|
||
- 分析模块功能确定是否需要数据库实体
|
||
- 如不需要数据库操作，可创建接口或配置类
|
||
|
||
3. **处理特殊模块**
|
||
- lang模块：评估是否需要完整的模块结构，或作为配置模块处理
|
||
|
||
### 阶段2：标准化目录结构
|
||
1. **统一命名规范**
|
||
- 确保所有文件命名符合NestJS规范
|
||
- 统一目录组织方式
|
||
|
||
2. **优化模块依赖**
|
||
- 检查模块间的导入关系
|
||
- 确保通过接口和事件通信
|
||
|
||
### 阶段3：验证模块自治性
|
||
1. **依赖关系检查**
|
||
- 识别跨模块直接导入
|
||
- 重构为接口或事件通信
|
||
|
||
2. **边界清晰化**
|
||
- 明确模块职责边界
|
||
- 为微服务拆分做准备
|
||
|
||
## 📊 质量标准
|
||
|
||
### 模块完整性指标
|
||
- ✅ 必需文件存在率：100%
|
||
- ✅ 目录结构规范率：100%
|
||
- ✅ 命名规范符合率：100%
|
||
|
||
### 模块自治性指标
|
||
- ✅ 跨模块直接导入：0个
|
||
- ✅ 接口通信覆盖率：100%
|
||
- ✅ 事件通信覆盖率：100%
|
||
|
||
## 🔧 自动化检查
|
||
|
||
使用 `auto-mapping-checker.js` 进行自动化检查：
|
||
```bash
|
||
node auto-mapping-checker.js --check-common-structure
|
||
```
|
||
|
||
检查项目：
|
||
- [ ] 模块目录完整性
|
||
- [ ] 必需文件存在性
|
||
- [ ] 命名规范符合性
|
||
- [ ] 模块依赖关系
|
||
- [ ] 微服务边界清晰度 |