wwjcloud/.trae/rules/common-layer-standards.md

# 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
```

检查项目：
- [ ] 模块目录完整性
- [ ] 必需文件存在性
- [ ] 命名规范符合性
- [ ] 模块依赖关系
- [ ] 微服务边界清晰度