whale-town-end/docs/development/AI代码检查规范.md

# AI代码检查规范（分步执行版）

本文档为AI助手提供分步骤的代码检查和修正指南，确保所有代码严格遵循项目规范。AI助手必须按照此文档要求，**每次只执行一个检查步骤**，避免遗漏任何规范。

**🎯 使用说明：AI助手每次只执行一个检查步骤，完成后等待用户确认再进行下一步。**

**📢 重要提醒：AI必须使用中文回复，不要创建多余的md文档。**

**👤 执行前必须操作：AI在开始任何检查步骤前，必须要求用户手动输入以下信息：**
- **当前日期**：用户需要提供准确的当前日期（格式：YYYY-MM-DD）
- **用户名称**：用户需要提供自己的名称，用于代码注释中的作者标识

**⚠️ 强制要求：**
- AI不能使用系统时间或预设日期，必须由用户手动提供
- 所有修改记录、@since、@lastModified、@author等字段都必须使用用户提供的信息
- 如果用户未提供这些信息，AI必须拒绝开始检查，并要求用户先提供

**📅 日期要求：所有修改记录的日期必须使用用户提供的真实日期时间，严禁使用示例日期或其他年份月份。**

**🔄 执行方式：分步骤执行，每步独立完成**

---

## 📋 分步检查流程

AI助手需要按照以下顺序，**每次只执行一个步骤**：

### 步骤1️⃣：命名规范检查
### 步骤2️⃣：注释规范检查  
### 步骤3️⃣：代码质量检查
### 步骤4️⃣：架构分层检查
### 步骤5️⃣：测试覆盖检查
### 步骤6️⃣：功能文档生成

**⚠️ 重要：每完成一个步骤后，AI必须停止并等待用户确认，然后再进行下一步骤。**

---

## 🔍 步骤1：命名规范检查

**本步骤专注：仅检查和修正命名规范问题**

### 检查范围
- 文件和文件夹命名
- 文件夹结构优化
- 文件夹安全删除处理
- 变量和函数命名
- 类和接口命名
- 常量命名
- 路由命名

### 文件和文件夹命名
**⚠️ 重要规则：必须使用下划线分隔（snake_case），严禁使用短横线（kebab-case）**

```typescript
✅ 正确示例：
- user_controller.ts
- player_service.ts  
- create_room_dto.ts
- base_users.service.ts
- users_memory.service.ts
- src/business/auth/
- src/core/db/users/

❌ 错误示例：
- UserController.ts          # 大驼峰命名
- playerService.ts           # 小驼峰命名
- createRoomDto.ts           # 小驼峰命名
- base-users.service.ts      # 短横线分隔（常见错误！）
- users-memory.service.ts    # 短横线分隔（常见错误！）
- src/Business/Auth/         # 大驼峰命名
```

### 文件夹结构优化规范

**⚠️ 重要规则：避免为单个文件创建独立文件夹，减少不必要的嵌套层级**

#### 需要合并的文件夹类型
```typescript
❌ 错误：过度嵌套的文件夹结构
src/
  guards/
    auth.guard.ts           # 只有一个文件，不需要单独文件夹
  interceptors/
    logging.interceptor.ts  # 只有一个文件，不需要单独文件夹
  pipes/
    validation.pipe.ts      # 只有一个文件，不需要单独文件夹
  filters/
    http-exception.filter.ts # 只有一个文件，不需要单独文件夹

✅ 正确：扁平化的文件结构
src/
  auth.guard.ts
  logging.interceptor.ts
  validation.pipe.ts
  http_exception.filter.ts
```

#### 文件夹创建判断标准
- **单文件规则**：如果文件夹内只有1个文件，应该将文件移到上级目录
- **少文件规则**：如果文件夹内只有2-3个相关文件，考虑是否需要独立文件夹
- **多文件规则**：如果文件夹内有4个或更多相关文件，可以保持独立文件夹
- **功能模块规则**：如果是完整的功能模块（如users、auth），即使文件较少也可以保持独立文件夹

#### 常见的过度嵌套场景
```typescript
❌ 需要优化的结构：
src/core/
  guards/
    jwt.guard.ts           # 移动到 src/core/jwt.guard.ts
  decorators/
    roles.decorator.ts     # 移动到 src/core/roles.decorator.ts
  middleware/
    cors.middleware.ts     # 移动到 src/core/cors.middleware.ts

✅ 优化后的结构：
src/core/
  jwt.guard.ts
  roles.decorator.ts
  cors.middleware.ts
  db/                      # 保留，因为是完整的功能模块
    users/
    accounts/
```

#### 框架文件类型识别
**以下NestJS框架文件类型容易被过度嵌套，需要重点检查：**
- Guards (*.guard.ts)
- Interceptors (*.interceptor.ts)
- Pipes (*.pipe.ts)
- Filters (*.filter.ts)
- Decorators (*.decorator.ts)
- Middleware (*.middleware.ts)
- Strategies (*.strategy.ts)
- Validators (*.validator.ts)

### 文件夹删除安全规范

**⚠️ 重要规则：删除文件夹前必须确保文件夹为空，并妥善处理其中的文件**

#### 文件夹删除流程

**步骤1：文件夹内容检查**
```typescript
// 检查文件夹是否为空
❌ 错误做法：
- 直接删除包含文件的文件夹
- 不检查文件夹内容就删除

✅ 正确做法：
1. 列出文件夹内所有文件
2. 逐个分析每个文件的用途和价值
3. 确认文件夹完全为空后再删除
```

**步骤2：文件价值评估**
```typescript
// 对每个文件进行价值评估
文件价值分类：

🟢 有用文件（需要保留）：
- 包含重要业务逻辑的代码文件
- 有效的测试文件
- 重要的配置文件
- 有价值的文档文件
- 被其他模块引用的文件

🟡 可能有用文件（需要仔细评估）：
- 未完成的功能代码
- 实验性代码
- 临时配置文件
- 草稿文档

🔴 无用文件（可以删除）：
- 空文件或只有注释的文件
- 重复的文件
- 过时的配置文件
- 无效的测试文件
- 临时文件和备份文件
```

**步骤3：文件处理策略**
```typescript
// 根据文件价值采取不同处理策略

🟢 有用文件处理：
1. 确定文件的合适位置
2. 移动到对应的目标文件夹
3. 更新相关的import路径
4. 验证移动后功能正常

🟡 可能有用文件处理：
1. 详细分析文件内容和用途
2. 咨询相关开发人员确认价值
3. 如确认有用，按有用文件处理
4. 如确认无用，按无用文件处理

🔴 无用文件处理：
1. 确认文件确实无用
2. 检查是否被其他文件引用
3. 安全删除文件
4. 清理相关的无效引用
```

**步骤4：文件夹删除确认**
```typescript
// 确保文件夹完全为空后再删除

删除前检查清单：
✅ 文件夹内所有文件已处理完毕
✅ 有用文件已移动到合适位置
✅ 无用文件已安全删除
✅ 相关import路径已更新
✅ 功能测试通过
✅ 文件夹确认为空

只有满足所有条件才能删除文件夹
```

#### 文件移动目标位置指南

**常见文件类型的推荐移动位置：**
```typescript
// Service文件
src/old_folder/user.service.ts
→ src/core/db/users_core/user.service.ts  (如果是Core层业务支撑)
→ src/business/users/user.service.ts      (如果是Business层业务逻辑)

// Controller文件
src/old_folder/user.controller.ts
→ src/business/users/controllers/user.controller.ts

// DTO文件
src/old_folder/user.dto.ts
→ src/business/users/dto/user.dto.ts      (Business层DTO)
→ src/core/db/users_core/user.dto.ts     (Core层DTO)

// 工具类文件
src/old_folder/utils.ts
→ src/core/utils/[category]/utils.ts      (通用工具)
→ src/common/utils/utils.ts               (公共工具)

// 测试文件
src/old_folder/user.service.spec.ts
→ 跟随对应的源文件移动到同一目录

// 配置文件
src/old_folder/config.ts
→ src/config/[category]/config.ts

// 文档文件
src/old_folder/README.md
→ 移动到对应功能模块的文件夹内
```

#### 文件夹删除执行模板

```typescript
## 文件夹删除处理报告

### 📁 目标文件夹
- **路径**: [要删除的文件夹路径]
- **删除原因**: [说明为什么要删除这个文件夹]

### 📋 文件夹内容清单
1. **文件总数**: [数量]
2. **文件列表**:
   - [文件1路径] - [文件类型] - [价值评估]
   - [文件2路径] - [文件类型] - [价值评估]
   - ...

### 🔍 文件价值评估结果
1. **有用文件** ([数量]个):
   - [文件路径] → [目标位置] (原因: [说明])
   
2. **可能有用文件** ([数量]个):
   - [文件路径] - [需要进一步确认的原因]
   
3. **无用文件** ([数量]个):
   - [文件路径] - [确认无用的原因]

### 🛠️ 文件处理方案
1. **文件移动计划**:
   - [源文件] → [目标位置]
   - [需要更新的import路径]
   
2. **文件删除计划**:
   - [要删除的无用文件列表]
   
3. **需要确认的文件**:
   - [需要人工确认的文件列表]

### ⚠️ 风险提醒
- [列出可能的风险点]
- [需要特别注意的事项]

### ✅ 删除前检查清单
- [ ] 所有有用文件已移动
- [ ] 所有无用文件已删除
- [ ] Import路径已更新
- [ ] 功能测试通过
- [ ] 文件夹确认为空

**只有完成所有检查项目后才能安全删除文件夹**
```

#### 特殊情况处理

**情况1：文件夹包含重要配置**
- 必须确认配置是否仍在使用
- 如果在使用，移动到合适的配置目录
- 更新所有引用该配置的代码

**情况2：文件夹包含测试文件**
- 确认测试是否有效且必要
- 有效测试跟随源文件移动
- 无效测试可以删除

**情况3：文件夹包含文档**
- 确认文档是否仍然相关
- 相关文档移动到对应功能模块
- 过时文档可以删除

**情况4：文件夹被其他模块引用**
- 必须先更新所有引用
- 确保移动后路径正确
- 验证功能不受影响

**🚨 特别注意：短横线（kebab-case）是最常见的文件命名错误！**
- 很多开发者习惯使用 `base-users.service.ts`
- 但项目规范要求必须使用 `base_users.service.ts`
- AI检查时必须严格识别并修正此类问题

**⚠️ AI常见误判警告：**
- **绝对不要**因为看到NestJS或其他框架的示例使用短横线就认为短横线是正确的
- **绝对不要**因为文件"看起来合理"就跳过检查
- **必须严格**按照项目规范执行，项目规范明确要求使用下划线分隔
- **发现短横线命名时必须修正**，不管它看起来多么"标准"或"合理"

**真实案例：**
- ❌ 错误：`real-redis.service.ts` （看起来像NestJS标准，但违反项目规范）
- ✅ 正确：`real_redis.service.ts` （符合项目snake_case规范）
- ❌ 错误：`file-redis.service.ts` （看起来像NestJS标准，但违反项目规范）
- ✅ 正确：`file_redis.service.ts` （符合项目snake_case规范）

### 变量和函数命名
**规则：使用小驼峰命名（camelCase）**

```typescript
✅ 正确示例：
const userName = 'Alice';
function getUserInfo() { }
async function validateUser() { }
const isGameStarted = false;

❌ 错误示例：
const UserName = 'Alice';
function GetUserInfo() { }
const is_game_started = false;
```

### 类和接口命名
**规则：使用大驼峰命名（PascalCase）**

```typescript
✅ 正确示例：
class UserService { }
interface GameConfig { }
class CreateUserDto { }
enum UserStatus { }

❌ 错误示例：
class userService { }
interface gameConfig { }
class createUserDto { }
```

### 常量命名
**规则：全大写 + 下划线分隔（SCREAMING_SNAKE_CASE）**

```typescript
✅ 正确示例：
const PORT = 3000;
const MAX_PLAYERS = 10;
const SALT_ROUNDS = 10;
const DEFAULT_TIMEOUT = 5000;

❌ 错误示例：
const port = 3000;
const maxPlayers = 10;
const saltRounds = 10;
```

### 路由命名
**规则：全小写 + 短横线分隔（kebab-case）**

```typescript
✅ 正确示例：
@Get('user/get-info')
@Post('room/join-room')
@Put('player/update-position')

❌ 错误示例：
@Get('user/getInfo')
@Post('room/joinRoom')
@Put('player/update_position')
```

### 步骤1执行模板

```
## 步骤1：命名规范检查报告

### 🔍 检查结果

#### 发现的命名问题
1. **文件命名问题**
   - [具体问题描述]
   
2. **文件夹结构问题**
   - [列出过度嵌套的文件夹，如单文件文件夹]
   
3. **需要删除的文件夹**
   - [列出建议删除的文件夹及原因]
   
4. **变量命名问题**
   - [具体问题描述]
   
5. **常量命名问题**
   - [具体问题描述]

### 🛠️ 修正方案
[提供具体的命名修正建议，包括文件夹结构优化和安全删除方案]

#### 文件夹删除处理方案
**如果发现需要删除的文件夹：**
1. **文件夹内容分析**
   - [列出文件夹内所有文件]
   - [评估每个文件的价值]
   
2. **文件处理计划**
   - 有用文件移动方案: [源位置] → [目标位置]
   - 无用文件删除清单: [文件列表]
   
3. **删除执行顺序**
   - 先移动有用文件
   - 再删除无用文件
   - 最后删除空文件夹

### ⚠️ AI检查提醒
- 严格按照项目规范执行，不要被其他框架的命名习惯误导
- 发现短横线命名必须修正为下划线命名
- 检查并优化过度嵌套的文件夹结构
- **删除文件夹前必须确保文件夹为空且文件已妥善处理**
- 不要因为文件"看起来合理"就跳过检查

### ✅ 步骤1完成状态
- 文件命名检查 ✓/✗
- 文件夹结构优化 ✓/✗
- 文件夹删除处理 ✓/✗
- 变量命名检查 ✓/✗
- 类命名检查 ✓/✗
- 常量命名检查 ✓/✗
- 路由命名检查 ✓/✗

**请确认步骤1的修正方案，确认后我将进行步骤2：注释规范检查**
```

---

## 📝 步骤2：注释规范检查

**本步骤专注：仅检查和修正注释规范问题**

### 检查范围
- 文件头注释完整性
- 类注释规范性
- 方法注释三级标准
- 修改记录规范性
- 版本号管理

### 文件头注释（必须包含）

**⚠️ 日期和作者要求：所有日期和作者字段必须使用用户在检查开始前提供的信息！**

```typescript
/**
 * 文件功能描述
 * 
 * 功能描述：
 * - 主要功能点1
 * - 主要功能点2
 * - 主要功能点3
 * 
 * 职责分离：
 * - 职责描述1
 * - 职责描述2
 * 
 * 最近修改：
 * - [用户提供的日期]: 修改类型 - 具体修改内容描述 (修改者: [用户提供的名称])
 * - [用户提供的日期-1天]: 修改类型 - 具体修改内容描述 (修改者: [原修改者名称])
 * 
 * @author [原始作者名称] (如果是AI则替换为用户名称，如果是其他人则保留)
 * @version x.x.x
 * @since [文件创建日期] (创建日期：新文件使用用户提供日期，已存在文件保持原有日期)
 * @lastModified [用户提供的日期]
 */
```

**🚨 AI作者处理规则：**
- **@author字段处理**：
  - 如果当前@author是"AI"、"ai"、"Assistant"等AI标识，则替换为用户提供的名称
  - 如果当前@author是具体的人名，则保留原作者不变
  - 如果没有@author字段，则添加用户提供的名称作为作者
- **修改记录处理**：
  - 每条修改记录都要标明修改者：`(修改者: [修改者名称])`
  - 新增的修改记录使用用户提供的名称作为修改者
  - 保留原有修改记录的修改者信息
- **@lastModified字段**：必须更新为用户提供的日期
- **最近修改记录**：使用用户提供的修改日期，不能使用占位符

### 类注释（必须包含）

```typescript
/**
 * 类功能描述
 * 
 * 职责：
 * - 主要职责1
 * - 主要职责2
 * 
 * 主要方法：
 * - method1() - 方法1功能
 * - method2() - 方法2功能
 * 
 * 使用场景：
 * - 场景描述
 */
@Injectable()
export class ExampleService {
  // 类实现
}
```

### 方法注释（三级注释标准 - 必须包含）

```typescript
/**
 * 用户登录验证
 * 
 * 业务逻辑：
 * 1. 验证用户名或邮箱格式
 * 2. 查找用户记录
 * 3. 验证密码哈希值
 * 4. 检查用户状态是否允许登录
 * 5. 记录登录日志
 * 6. 返回认证结果
 * 
 * @param loginRequest 登录请求数据
 * @returns 认证结果，包含用户信息和认证状态
 * @throws UnauthorizedException 用户名或密码错误时
 * @throws ForbiddenException 用户状态不允许登录时
 * 
 * @example
 * ```typescript
 * const result = await loginService.validateUser({
 *   identifier: 'user@example.com',
 *   password: 'password123'
 * });
 * ```
 */
async validateUser(loginRequest: LoginRequest): Promise<AuthResult> {
  // 实现代码
}
```

### 修改记录规范（重要）

**⚠️ 关键要求：所有日期必须使用用户在检查开始前提供的真实日期，严禁使用示例日期！**

**修改类型定义：**
- `代码规范优化` - 命名规范、注释规范、代码清理等
- `功能新增` - 添加新的功能或方法
- `功能修改` - 修改现有功能的实现
- `Bug修复` - 修复代码缺陷
- `性能优化` - 提升代码性能
- `重构` - 代码结构调整但功能不变

**格式要求（使用用户提供的真实日期）：**
```typescript
/**
 * 最近修改：
 * - [用户提供的日期]: 代码规范优化 - 清理未使用的导入(EmailSendResult, crypto) (修改者: [用户提供的名称])
 * - [用户提供的日期]: 代码规范优化 - 修复常量命名(saltRounds -> SALT_ROUNDS) (修改者: [用户提供的名称])
 * - [用户提供的日期-1天]: 功能新增 - 添加用户验证码登录功能 (修改者: [原修改者名称])
 * - [用户提供的日期-2天]: Bug修复 - 修复邮箱验证逻辑错误 (修改者: [原修改者名称])
 * - [用户提供的日期-3天]: 性能优化 - 优化数据库查询性能 (修改者: [原修改者名称])
 * 
 * @version 1.0.1 (修改后需要递增版本号)
 * @lastModified [用户提供的日期]
 * @author [处理后的作者名称]
 */
```

**🚨 AI执行警告：**
- **绝对不能**使用示例中的日期作为模板复制
- **必须使用**用户在检查开始前提供的日期
- **严禁随意**修改到其他年份或月份
- **每次修改**都要更新@lastModified为用户提供的日期
- **@author字段处理**：
  - 如果原@author是"AI"相关标识，替换为用户提供的名称
  - 如果原@author是具体人名，保留原作者不变
- **修改记录标识**：每条修改记录都必须标明修改者
- **AI必须**根据用户提供的信息和现有作者信息正确处理

**修改者标识规则：**
- 新增修改记录格式：`- 日期: 修改类型 - 修改内容 (修改者: 修改者名称)`
- 保留原有修改记录的修改者信息
- 如果原有修改记录没有修改者标识，可以标记为`(修改者: 未知)`或根据git记录推断

**⚠️ 重要限制：修改记录只保留最近5次修改，超出时删除最旧记录，保持注释简洁。**

**版本号递增规则：**
- 代码规范优化、Bug修复 → 修订版本 +1 (1.0.0 → 1.0.1)
- 功能新增、功能修改 → 次版本 +1 (1.0.1 → 1.1.0)
- 重构、架构变更 → 主版本 +1 (1.1.0 → 2.0.0)

### 步骤2执行模板

```
## 步骤2：注释规范检查报告

### 📋 用户信息确认
- **用户提供的当前日期**: [确认用户提供的日期]
- **用户提供的名称**: [确认用户提供的名称]
- **信息收集状态**: ✓已收集 / ✗未收集

### 🔍 检查结果

#### 发现的注释问题
1. **文件头注释问题**
   - [具体问题描述]
   
2. **方法注释问题**
   - [具体问题描述]
   
3. **修改记录问题**
   - [具体问题描述]

4. **日期和作者规范问题**
   - [检查所有日期是否使用用户提供的真实日期]
   - [检查@author字段：AI标识是否替换，人名是否保留]
   - [检查修改记录是否标明修改者]

### 🛠️ 修正方案
[提供具体的注释修正建议，使用用户提供的真实信息]

### ⚠️ 用户信息应用重点
- 确保所有@since、@lastModified、修改记录中的日期都使用用户提供的真实日期
- 正确处理@author字段：AI标识替换为用户名称，人名保留不变
- 确保所有修改记录都标明修改者信息
- 不能使用示例日期、模板占位符或系统预设信息

### ✅ 步骤2完成状态
- 用户信息收集 ✓/✗
- 文件头注释 ✓/✗
- 类注释 ✓/✗
- 方法注释 ✓/✗
- 修改记录 ✓/✗
- 日期和作者规范 ✓/✗
- 版本号管理 ✓/✗

**请确认步骤2的修正方案，确认后我将进行步骤3：代码质量检查**
```

---

## 🔧 步骤3：代码质量检查

**本步骤专注：仅检查和修正代码质量问题**

### 检查范围
- 未使用的导入清理
- 未使用的变量和方法清理
- 常量定义规范
- 方法长度合理性
- 代码重复检查

### 导入清理检查

```typescript
// ✅ 正确：只导入使用的模块
import { Injectable, NotFoundException } from '@nestjs/common';
import { User } from './user.entity';

// ❌ 错误：导入未使用的模块
import { Injectable, NotFoundException, BadRequestException } from '@nestjs/common';
import { User, Admin } from './user.entity';
import * as crypto from 'crypto'; // 未使用
```

### 常量定义检查

```typescript
// ✅ 正确：使用全大写+下划线
const SALT_ROUNDS = 10;
const MAX_LOGIN_ATTEMPTS = 5;
const DEFAULT_PAGE_SIZE = 20;

// ❌ 错误：使用小驼峰
const saltRounds = 10;
const maxLoginAttempts = 5;
```

### 未使用代码检查

```typescript
// ❌ 需要删除：未使用的私有方法
private generateVerificationCode(): string {
  // 如果这个方法没有被调用，应该删除
}

// ❌ 需要删除：未使用的变量
const unusedVariable = 'test';
```

### 方法长度检查

```typescript
// ✅ 正确：方法长度合理（建议不超过50行）
async createUser(userData: CreateUserDto): Promise<User> {
  // 简洁的实现
}

// ❌ 错误：方法过长，需要拆分
async complexMethod() {
  // 超过50行的复杂逻辑，应该拆分成多个小方法
}
```

### 步骤3执行模板

```
## 步骤3：代码质量检查报告

### 🔍 检查结果

#### 发现的代码质量问题
1. **未使用代码问题**
   - [具体问题描述]
   
2. **代码结构问题**
   - [具体问题描述]
   
3. **性能相关问题**
   - [具体问题描述]

### 🛠️ 修正方案
[提供具体的代码质量修正建议]

### ✅ 步骤3完成状态
- 导入清理 ✓/✗
- 未使用代码清理 ✓/✗
- 常量定义 ✓/✗
- 方法长度 ✓/✗
- 代码重复 ✓/✗

**请确认步骤3的修正方案，确认后我将进行步骤4：架构分层检查**
```

---

## 🛡️ 步骤4：架构分层检查

**本步骤专注：检查当前文件夹内的代码是否符合其所在层级的架构要求**

### 检查范围
- 当前文件夹的层级定位分析
- 文件夹内代码的架构合规性
- 职责分离正确性
- 依赖关系合理性
- 代码实现质量

### 架构层级识别

**⚠️ 重要：AI必须首先识别当前检查的文件夹属于哪个架构层级**

#### 层级识别规则
```typescript
// Core层识别
src/core/                    # Core层根目录
src/core/db/users_core/      # Core层业务支撑模块
src/core/utils/logger/       # Core层底层工具模块
src/core/redis/              # Core层技术工具模块

// Business层识别
src/business/                # Business层根目录
src/business/users/          # Business层业务模块
src/business/auth/           # Business层业务模块

// 其他层级
src/common/                  # 公共层
src/config/                  # 配置层
```

#### 检查策略
- **仅检查当前文件夹**：只分析当前检查的文件夹内的代码
- **层级专项检查**：根据文件夹所在层级应用对应的架构要求
- **不跨层检查**：不检查其他层级的文件夹是否存在或规范

### Core层文件夹检查（仅当检查Core层文件夹时执行）

**检查条件：当前检查的文件夹路径包含`src/core/`时执行此检查**

#### Core层命名规范检查

**⚠️ 重要规则：Core层模块必须根据其职责类型进行正确命名**

**命名规则：**
- **业务支撑模块**：为Business层提供业务相关的技术实现，必须使用`_core`后缀
- **底层工具模块**：提供纯技术功能，不涉及具体业务概念，不使用`_core`后缀

```typescript
✅ 正确示例：

// 业务支撑模块（必须带_core后缀）
src/core/db/users_core/              # 为business/users提供数据层支撑
src/core/login_core/                 # 为business/auth提供登录技术实现
src/core/admin_core/                 # 为business/admin提供管理功能支撑

// 底层工具模块（不带_core后缀）
src/core/redis/                      # 纯Redis技术封装
src/core/utils/logger/               # 纯日志工具
src/core/utils/email/                # 纯邮件发送工具

❌ 错误示例：
src/core/db/users/                   # 应该是users_core
src/core/redis_core/                 # 应该是redis
```

#### Core层职责合规性检查

**技术实现能力检查**
```typescript
// ✅ 正确：Core层专注技术实现
@Injectable()
export class RedisService {
  /**
   * 设置缓存数据
   * 
   * 技术实现：
   * 1. 验证key格式
   * 2. 序列化数据
   * 3. 设置过期时间
   * 4. 处理连接异常
   */
  async set(key: string, value: any, ttl?: number): Promise<void> {
    // 专注Redis技术实现细节
  }
}

// ❌ 错误：Core层包含业务逻辑
@Injectable()
export class RedisService {
  async setUserSession(userId: string, sessionData: any): Promise<void> {
    // 错误：包含了用户会话的业务概念
  }
}
```

#### Core层依赖关系检查

**检查当前Core文件夹内的import依赖：**
- ✅ 允许：导入其他Core层模块
- ✅ 允许：导入第三方技术库
- ✅ 允许：导入Node.js内置模块
- ❌ 禁止：导入Business层模块
- ❌ 禁止：包含具体业务概念的命名

### Business层文件夹检查（仅当检查Business层文件夹时执行）

**检查条件：当前检查的文件夹路径包含`src/business/`时执行此检查**

#### Business层职责合规性检查

**Business层职责：专注业务逻辑实现，不关心底层技术细节**

#### 业务逻辑完备性检查
```typescript
// ✅ 正确：完整的业务逻辑
@Injectable()
export class UserBusinessService {
  /**
   * 用户注册业务流程
   * 
   * 业务逻辑：
   * 1. 验证用户信息完整性
   * 2. 检查用户名/邮箱是否已存在
   * 3. 验证邮箱格式和域名白名单
   * 4. 生成用户唯一标识
   * 5. 设置默认用户权限
   * 6. 发送欢迎邮件
   * 7. 记录注册日志
   * 8. 返回注册结果
   */
  async registerUser(registerData: RegisterUserDto): Promise<UserResult> {
    // 完整的业务逻辑实现
  }
}

// ❌ 错误：业务逻辑不完整
@Injectable()
export class UserBusinessService {
  async registerUser(registerData: RegisterUserDto): Promise<User> {
    // 只是简单调用数据库保存，缺少业务验证和流程
    return this.userRepository.save(registerData);
  }
}
```

#### Business层依赖关系检查

**检查当前Business文件夹内的import依赖：**
- ✅ 允许：导入对应的Core层业务支撑模块
- ✅ 允许：导入Core层通用工具模块
- ✅ 允许：导入其他Business层模块（谨慎使用）
- ✅ 允许：导入第三方业务库
- ❌ 禁止：直接导入底层技术实现（如数据库连接、Redis客户端等）
- ❌ 禁止：包含技术实现细节

#### 业务场景覆盖检查
```typescript
// ✅ 正确：覆盖各种业务场景
@Injectable()
export class OrderBusinessService {
  // 正常流程
  async createOrder(orderData: CreateOrderDto): Promise<OrderResult> { }
  
  // 异常场景
  async handlePaymentFailure(orderId: string): Promise<void> { }
  async handleInventoryShortage(orderId: string): Promise<void> { }
  
  // 边界情况
  async handleDuplicateOrder(orderData: CreateOrderDto): Promise<OrderResult> { }
  async handleExpiredPromotion(orderId: string): Promise<void> { }
  
  // 业务规则
  async validateOrderRules(orderData: CreateOrderDto): Promise<ValidationResult> { }
  async applyBusinessDiscounts(order: Order): Promise<Order> { }
}

// ❌ 错误：业务场景覆盖不全
@Injectable()
export class OrderBusinessService {
  async createOrder(orderData: CreateOrderDto): Promise<Order> {
    // 只处理正常流程，缺少异常处理和边界情况
  }
}
```

#### Business层架构要求
- **业务完整性**：覆盖完整的业务流程和各种场景
- **逻辑清晰性**：业务规则明确，流程清晰
- **技术无关性**：不关心数据库类型、缓存实现等技术细节
- **可维护性**：业务变更时容易修改和扩展

### 其他层级文件夹检查

**检查条件：当前检查的文件夹不属于Core或Business层时执行**

#### 公共层检查（src/common/）
- 确保只包含通用的工具函数、常量、类型定义
- 不包含特定业务逻辑或技术实现细节
- 可被任何层级安全导入使用

#### 配置层检查（src/config/）
- 确保只包含配置相关的代码
- 不包含业务逻辑或复杂的技术实现
- 配置项清晰明确，易于维护

### 当前文件夹架构违规检查

**⚠️ 重要：只检查当前文件夹内的代码，不跨文件夹检查**

#### 常见违规模式检查

**如果当前文件夹属于Business层：**
```typescript
// ❌ 错误：Business层包含技术实现细节
@Injectable()
export class UserBusinessService {
  async createUser(userData: CreateUserDto): Promise<User> {
    // 违规：直接操作Redis连接
    const redis = new Redis({ host: 'localhost', port: 6379 });
    await redis.set(`user:${userData.id}`, JSON.stringify(userData));
    
    // 违规：直接写SQL语句
    const sql = 'INSERT INTO users (name, email) VALUES (?, ?)';
    await this.database.query(sql, [userData.name, userData.email]);
  }
}
```

**如果当前文件夹属于Core层：**
```typescript
// ❌ 错误：Core层包含业务逻辑
@Injectable()
export class DatabaseService {
  async saveUser(userData: CreateUserDto): Promise<User> {
    // 违规：包含用户注册的业务验证
    if (userData.age < 18) {
      throw new BadRequestException('用户年龄必须大于18岁');
    }
    
    // 违规：包含业务规则
    if (userData.email.endsWith('@competitor.com')) {
      throw new ForbiddenException('不允许竞争对手注册');
    }
  }
}
```

#### 正确的分层实现示例

**Business层正确实现：**
```typescript
// ✅ 正确：Business层调用Core层服务
@Injectable()
export class UserBusinessService {
  constructor(
    private readonly userCoreService: UserCoreService,
    private readonly cacheService: CacheService,
    private readonly emailService: EmailService,
  ) {}

  async createUser(userData: CreateUserDto): Promise<User> {
    // 业务验证
    await this.validateUserBusinessRules(userData);
    
    // 调用Core层服务
    const user = await this.userCoreService.create(userData);
    await this.cacheService.set(`user:${user.id}`, user);
    await this.emailService.sendWelcomeEmail(user.email);
    
    return user;
  }
}
```

**Core层正确实现：**
```typescript
// ✅ 正确：Core层提供技术能力
@Injectable()
export class UserCoreService {
  async create(userData: any): Promise<User> {
    // 技术实现：数据持久化
    return this.repository.save(userData);
  }
  
  async findById(id: string): Promise<User> {
    // 技术实现：数据查询
    return this.repository.findOne({ where: { id } });
  }
}
```

### 步骤4执行模板

```
## 步骤4：架构分层检查报告

### 📋 当前文件夹分析
- **检查路径**: [当前检查的文件夹路径]
- **层级识别**: [Core层/Business层/其他层级]
- **模块类型**: [业务支撑模块/底层工具模块/业务模块/配置模块等]

### 🔍 检查结果

#### 层级专项检查结果
**[根据识别的层级执行对应检查]**

**如果是Core层文件夹：**
1. **Core层命名规范**
   - [检查是否正确使用_core后缀]
   
2. **技术实现合规性**
   - [检查是否专注技术实现，避免业务逻辑]
   
3. **依赖关系检查**
   - [检查import依赖是否合规]

**如果是Business层文件夹：**
1. **业务逻辑完备性**
   - [检查业务流程是否完整]
   
2. **业务场景覆盖**
   - [检查是否覆盖各种业务场景]
   
3. **依赖关系检查**
   - [检查是否避免直接技术实现]

**如果是其他层级文件夹：**
1. **层级职责合规性**
   - [检查是否符合该层级的职责要求]

#### 架构违规问题
1. **分层违规问题**
   - [列出当前文件夹内发现的分层违规问题]
   
2. **依赖关系问题**
   - [列出不合理的依赖关系]

### 🛠️ 修正方案
[提供针对当前文件夹的架构修正建议]

### ⚠️ 架构检查重点
- 只检查当前文件夹内的代码架构合规性
- 根据文件夹所在层级应用对应的架构要求
- 不跨文件夹检查其他层级的代码
- 重点关注当前文件夹的职责定位和实现方式

### ✅ 步骤4完成状态
- 层级识别 ✓/✗
- 命名规范检查 ✓/✗
- 职责合规性检查 ✓/✗
- 依赖关系检查 ✓/✗
- 架构违规检查 ✓/✗

**步骤4完成，请确认修正方案后我将进行步骤5：测试覆盖检查**
```

---

## 🧪 步骤5：测试覆盖检查

**本步骤专注：检查测试文件的完整性和覆盖率**

### 检查范围
- Service文件测试文件存在性
- 测试用例覆盖完整性
- 测试场景真实性
- 测试代码质量
- 集成测试完备性

### Service测试文件存在性检查

**规则：每个Service都必须有对应的.spec.ts测试文件**

```typescript
// ✅ 正确：Service与测试文件一一对应
src/core/db/users/users.service.ts
src/core/db/users/users.service.spec.ts

src/core/db/users/users_memory.service.ts
src/core/db/users/users_memory.service.spec.ts

src/core/redis/real_redis.service.ts
src/core/redis/real_redis.service.spec.ts

// ❌ 错误：缺少测试文件
src/core/login_core/login_core.service.ts
# 缺少：src/core/login_core/login_core.service.spec.ts
```

### 测试用例覆盖完整性检查

**要求：测试文件必须覆盖Service中的所有公共方法**

```typescript
// 示例Service
@Injectable()
export class UserService {
  async createUser(userData: CreateUserDto): Promise<User> { }
  async findUserById(id: string): Promise<User> { }
  async updateUser(id: string, updateData: UpdateUserDto): Promise<User> { }
  async deleteUser(id: string): Promise<void> { }
  async findUsersByStatus(status: UserStatus): Promise<User[]> { }
}

// ✅ 正确：完整的测试覆盖
describe('UserService', () => {
  // 每个公共方法都有对应的测试
  describe('createUser', () => {
    it('should create user successfully', () => { });
    it('should throw error when email already exists', () => { });
    it('should throw error when required fields missing', () => { });
  });

  describe('findUserById', () => {
    it('should return user when found', () => { });
    it('should throw NotFoundException when user not found', () => { });
    it('should throw error when id is invalid', () => { });
  });

  describe('updateUser', () => {
    it('should update user successfully', () => { });
    it('should throw NotFoundException when user not found', () => { });
    it('should throw error when update data is invalid', () => { });
  });

  describe('deleteUser', () => {
    it('should delete user successfully', () => { });
    it('should throw NotFoundException when user not found', () => { });
  });

  describe('findUsersByStatus', () => {
    it('should return users with specified status', () => { });
    it('should return empty array when no users found', () => { });
    it('should throw error when status is invalid', () => { });
  });
});

// ❌ 错误：测试覆盖不完整
describe('UserService', () => {
  describe('createUser', () => {
    it('should create user', () => { });
    // 缺少异常情况测试
  });
  
  // 缺少其他方法的测试
});
```

### 测试场景真实性检查

**要求：每个方法必须测试正常情况、异常情况和边界情况**

```typescript
// ✅ 正确：完整的测试场景
describe('createUser', () => {
  // 正常情况
  it('should create user with valid data', async () => {
    const userData = { name: 'John', email: 'john@example.com' };
    const result = await service.createUser(userData);
    expect(result).toBeDefined();
    expect(result.name).toBe('John');
  });

  // 异常情况
  it('should throw ConflictException when email already exists', async () => {
    const userData = { name: 'John', email: 'existing@example.com' };
    await expect(service.createUser(userData)).rejects.toThrow(ConflictException);
  });

  it('should throw BadRequestException when required fields missing', async () => {
    const userData = { name: 'John' }; // 缺少email
    await expect(service.createUser(userData)).rejects.toThrow(BadRequestException);
  });

  // 边界情况
  it('should handle empty name gracefully', async () => {
    const userData = { name: '', email: 'test@example.com' };
    await expect(service.createUser(userData)).rejects.toThrow(BadRequestException);
  });

  it('should handle very long name', async () => {
    const userData = { name: 'a'.repeat(1000), email: 'test@example.com' };
    await expect(service.createUser(userData)).rejects.toThrow(BadRequestException);
  });
});

// ❌ 错误：测试场景不完整
describe('createUser', () => {
  it('should create user', async () => {
    // 只测试了正常情况，缺少异常和边界情况
  });
});
```

### 测试代码质量检查

**要求：测试代码必须清晰、可维护、真实有效**

```typescript
// ✅ 正确：高质量的测试代码
describe('UserService', () => {
  let service: UserService;
  let mockRepository: jest.Mocked<Repository<User>>;

  beforeEach(async () => {
    const mockRepo = {
      save: jest.fn(),
      findOne: jest.fn(),
      find: jest.fn(),
      delete: jest.fn(),
    };

    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UserService,
        { provide: getRepositoryToken(User), useValue: mockRepo },
      ],
    }).compile();

    service = module.get<UserService>(UserService);
    mockRepository = module.get(getRepositoryToken(User));
  });

  afterEach(() => {
    jest.clearAllMocks();
  });

  describe('findUserById', () => {
    it('should return user when found', async () => {
      // Arrange
      const userId = '123';
      const expectedUser = { id: userId, name: 'John', email: 'john@example.com' };
      mockRepository.findOne.mockResolvedValue(expectedUser);

      // Act
      const result = await service.findUserById(userId);

      // Assert
      expect(result).toEqual(expectedUser);
      expect(mockRepository.findOne).toHaveBeenCalledWith({ where: { id: userId } });
    });

    it('should throw NotFoundException when user not found', async () => {
      // Arrange
      const userId = '999';
      mockRepository.findOne.mockResolvedValue(null);

      // Act & Assert
      await expect(service.findUserById(userId)).rejects.toThrow(NotFoundException);
      expect(mockRepository.findOne).toHaveBeenCalledWith({ where: { id: userId } });
    });
  });
});

// ❌ 错误：低质量的测试代码
describe('UserService', () => {
  it('test user', () => {
    // 测试描述不清晰
    // 缺少proper setup
    // 没有真实的断言
    expect(true).toBe(true);
  });
});
```

### 集成测试完备性检查

**要求：复杂Service需要集成测试文件(.integration.spec.ts)**

```typescript
// ✅ 正确：提供集成测试
src/core/db/users/users.service.ts
src/core/db/users/users.service.spec.ts          # 单元测试
src/core/db/users/users.integration.spec.ts     # 集成测试

// 集成测试示例
describe('UserService Integration', () => {
  let app: INestApplication;
  let service: UserService;
  let dataSource: DataSource;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [
        TypeOrmModule.forRoot({
          type: 'sqlite',
          database: ':memory:',
          entities: [User],
          synchronize: true,
        }),
        TypeOrmModule.forFeature([User]),
      ],
      providers: [UserService],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();
    
    service = moduleFixture.get<UserService>(UserService);
    dataSource = moduleFixture.get<DataSource>(DataSource);
  });

  afterAll(async () => {
    await app.close();
  });

  beforeEach(async () => {
    await dataSource.synchronize(true); // 清理数据库
  });

  it('should create and retrieve user from real database', async () => {
    // 真实的数据库操作测试
    const userData = { name: 'John', email: 'john@example.com' };
    const createdUser = await service.createUser(userData);
    
    const foundUser = await service.findUserById(createdUser.id);
    expect(foundUser).toEqual(createdUser);
  });
});
```

### 测试覆盖率检查

**要求：检查测试是否真实执行了所有代码路径**

```typescript
// ✅ 正确：覆盖所有代码路径
describe('validateUserData', () => {
  it('should pass validation for valid data', async () => {
    const validData = { name: 'John', email: 'john@example.com', age: 25 };
    const result = await service.validateUserData(validData);
    expect(result.isValid).toBe(true);
  });

  it('should fail validation for missing name', async () => {
    const invalidData = { email: 'john@example.com', age: 25 };
    const result = await service.validateUserData(invalidData);
    expect(result.isValid).toBe(false);
    expect(result.errors).toContain('Name is required');
  });

  it('should fail validation for invalid email', async () => {
    const invalidData = { name: 'John', email: 'invalid-email', age: 25 };
    const result = await service.validateUserData(invalidData);
    expect(result.isValid).toBe(false);
    expect(result.errors).toContain('Invalid email format');
  });

  it('should fail validation for underage user', async () => {
    const invalidData = { name: 'John', email: 'john@example.com', age: 17 };
    const result = await service.validateUserData(invalidData);
    expect(result.isValid).toBe(false);
    expect(result.errors).toContain('User must be 18 or older');
  });
});

// ❌ 错误：未覆盖所有代码路径
describe('validateUserData', () => {
  it('should validate user data', async () => {
    // 只测试了一种情况，其他if/else分支未覆盖
    const validData = { name: 'John', email: 'john@example.com', age: 25 };
    const result = await service.validateUserData(validData);
    expect(result.isValid).toBe(true);
  });
});
```

### 测试执行验证

**⚠️ 重要要求：测试覆盖检查完成后，必须执行实际的测试命令验证测试通过**

#### 测试执行策略
- **精准测试**：只执行被检查文件夹相关的测试，避免运行全部测试浪费时间
- **Windows环境**：使用适合Windows系统的测试命令
- **失败处理**：测试失败时必须分析原因并提供修正建议

#### 测试命令规范

**根据项目具体情况选择合适的测试命令：**

```bash
# 1. 针对特定文件夹的测试（推荐）- 排除集成测试
npx jest src/core/db/users --testPathIgnorePatterns="integration.spec.ts"

# 2. 针对特定文件的测试
npx jest src/core/db/users/users.service.spec.ts
npx jest src/core/db/users/users_memory.service.spec.ts

# 3. 运行文件夹内所有测试（包括集成测试，可能需要数据库环境）
npx jest src/core/db/users

# 4. 使用通配符模式运行多个文件
npx jest src/core/db/users/*.spec.ts

# 5. 带覆盖率的测试执行
npx jest src/core/db/users --coverage --testPathIgnorePatterns="integration.spec.ts"

# 6. 静默模式执行（减少输出）
npx jest src/core/db/users --silent --testPathIgnorePatterns="integration.spec.ts"
```

**Windows CMD环境下的命令示例：**
```cmd
# 基本测试执行（推荐）
npx jest src/core/db/users --testPathIgnorePatterns="integration.spec.ts"

# 执行特定测试文件
npx jest src/core/db/users/users.service.spec.ts

# 静默模式执行
npx jest src/core/db/users --silent --testPathIgnorePatterns="integration.spec.ts"
```

**⚠️ 重要提醒：**
- **优先使用单元测试**：使用`--testPathIgnorePatterns="integration.spec.ts"`排除集成测试，避免数据库依赖问题
- **精准测试路径**：使用完整的相对路径`src/core/db/users`而不是模糊匹配
- **避免全局测试**：不要使用`npm test`运行所有测试，会浪费时间且可能有环境依赖问题

#### 测试执行流程

1. **确定测试范围**：根据检查的文件夹确定需要执行的测试文件
2. **选择测试命令**：根据项目配置选择最合适的测试命令
3. **执行测试**：运行测试命令并监控输出
4. **分析结果**：检查测试通过情况和覆盖率
5. **处理失败**：如有测试失败，分析原因并提供修正建议

#### 测试失败处理

**常见测试失败原因及处理方式：**

```typescript
// 1. Mock配置错误
// 问题：TypeError: Cannot read property 'mockResolvedValue' of undefined
// 解决：检查Mock对象的配置和方法名称

// 2. 异步测试处理错误  
// 问题：Test timeout或Promise rejection
// 解决：确保使用await或return Promise

// 3. 依赖注入问题
// 问题：Nest can't resolve dependencies
// 解决：检查TestingModule的providers配置

// 4. 数据库连接问题
// 问题：Connection refused或Database not found
// 解决：使用内存数据库或Mock Repository

// 5. 环境变量缺失
// 问题：Configuration validation error
// 解决：在测试中设置必要的环境变量
```

### 步骤5执行模板

```
## 步骤5：测试覆盖检查报告

### 🔍 检查结果

#### Service测试文件存在性
1. **缺少测试文件的Service**
   - [列出所有缺少.spec.ts文件的Service]
   
2. **缺少集成测试的Service**
   - [列出需要但缺少.integration.spec.ts文件的Service]

#### 测试用例覆盖完整性
1. **方法覆盖不完整**
   - [列出测试文件中未覆盖的公共方法]
   
2. **测试场景不完整**
   - [列出缺少异常情况或边界情况测试的方法]

#### 测试代码质量
1. **测试代码质量问题**
   - [列出测试代码中的质量问题]
   
2. **测试真实性问题**
   - [列出不真实或无效的测试用例]

### 🛠️ 修正方案
[提供具体的测试覆盖修正建议]

### 🧪 测试执行验证

#### 执行的测试命令
```bash
[显示实际执行的测试命令]
```

#### 测试执行结果
```
[显示测试执行的输出结果]
```

#### 测试通过情况
- 单元测试通过率: X/Y (XX%)
- 集成测试通过率: X/Y (XX%)
- 总体测试通过率: X/Y (XX%)

#### 测试失败分析（如有）
1. **失败的测试用例**
   - [列出失败的测试用例和原因]
   
2. **修正建议**
   - [提供具体的修正建议]

### ⚠️ 测试检查重点
- 确保每个Service都有对应的.spec.ts文件
- 验证所有公共方法都有测试覆盖
- 检查正常、异常、边界情况是否都有测试
- 确保测试用例真实有效，不是空壳测试
- **必须执行测试命令验证测试通过**

### ✅ 步骤5完成状态
- Service测试文件存在性 ✓/✗
- 方法覆盖完整性 ✓/✗
- 测试场景完整性 ✓/✗
- 测试代码质量 ✓/✗
- 集成测试完备性 ✓/✗
- **测试执行验证 ✓/✗**

**步骤5完成，请确认修正方案后我将进行步骤6：功能文档生成**
```

---

## 📚 步骤6：功能文档生成

**本步骤专注：为检查的文件夹生成完整的功能文档**

### 检查范围
- 文件夹功能总结
- 对外接口梳理
- 内部依赖分析
- 功能特性说明
- 潜在风险评估

### 文档结构规范

**要求：必须在文件夹根目录创建或更新README.md文件，按照以下结构组织内容**

#### 1. 模块概述（必须包含）

**格式要求：**
```markdown
# [模块名称] [中文描述]

[模块名称] 是 [一段话总结文件夹的整体功能和作用，说明其在项目中的定位和价值]。
```

**示例：**
```markdown
# Users 用户数据管理模块

Users 是应用的核心用户数据管理模块，提供完整的用户数据存储、查询、更新和删除功能，支持数据库和内存两种存储模式，具备统一的异常处理、日志记录和性能监控能力。
```

#### 2. 对外提供的接口（必须包含）

**格式要求：**
```markdown
## [功能分类名称]

### methodName()
[一句话说明该方法的功能和用途]

### anotherMethod()
[一句话说明该方法的功能和用途]
```

**分类原则：**
- 按功能逻辑分组（如：用户数据操作、高级查询功能、权限管理等）
- 每个方法用一句话简洁说明功能
- 突出方法的核心价值和使用场景

**示例：**
```markdown
## 用户数据操作

### create()
创建新用户记录，支持数据验证和唯一性检查。

### findByEmail()
根据邮箱地址查询用户，用于登录验证和账户找回。
```

#### 3. 使用的项目内部依赖（必须包含）

**格式要求：**
```markdown
## 使用的项目内部依赖

### DependencyName (来自 path/to/dependency)
[一句话说明如何使用这个依赖，以及它在当前模块中的作用]

### AnotherDependency (本模块)
[一句话说明这个内部依赖的用途和价值]
```

**分析要求：**
- 列出所有import的项目内部模块、类、接口、枚举等
- 说明每个依赖在当前模块中的具体用途
- 区分外部依赖（来自其他模块）和内部依赖（本模块内）

**示例：**
```markdown
## 使用的项目内部依赖

### UserStatus (来自 business/user-mgmt/enums/user-status.enum)
用户状态枚举，定义用户的激活、禁用、待验证等状态值。

### CreateUserDto (本模块)
用户创建数据传输对象，提供完整的数据验证规则和类型定义。
```

#### 4. 核心特性（必须包含）

**格式要求：**
```markdown
## 核心特性

### 特性名称1
- 特性描述1
- 特性描述2
- 特性描述3

### 特性名称2
- 特性描述1
- 特性描述2

### 特性名称3
- 特性描述1
- 特性描述2
```

**特性分类：**
- 技术特性：架构设计、性能优化、安全机制等
- 功能特性：核心能力、扩展性、兼容性等
- 质量特性：可靠性、可维护性、可测试性等

**示例：**
```markdown
## 核心特性

### 双存储模式支持
- 数据库模式：使用TypeORM连接MySQL，适用于生产环境
- 内存模式：使用Map存储，适用于开发测试和故障降级
- 动态模块配置：通过UsersModule.forDatabase()和forMemory()灵活切换

### 数据完整性保障
- 唯一性约束检查：用户名、邮箱、手机号、GitHub ID
- 数据验证：使用class-validator进行输入验证
- 事务支持：批量操作支持回滚机制
```

#### 5. 潜在风险（必须包含）

**格式要求：**
```markdown
## 潜在风险

### 风险名称1
- 风险描述和可能的影响
- 触发条件和场景
- 建议的预防或缓解措施

### 风险名称2
- 风险描述和可能的影响
- 触发条件和场景
- 建议的预防或缓解措施
```

**风险分类：**
- 技术风险：性能瓶颈、并发问题、数据丢失等
- 业务风险：数据一致性、业务逻辑缺陷等
- 运维风险：配置错误、环境依赖、监控盲点等
- 安全风险：权限漏洞、数据泄露、注入攻击等

**示例：**
```markdown
## 潜在风险

### 内存模式数据丢失
- 内存存储在应用重启后数据会丢失
- 不适用于生产环境的持久化需求
- 建议仅在开发测试环境使用

### 并发操作风险
- 内存模式的ID生成锁机制相对简单
- 高并发场景可能存在性能瓶颈
- 建议在生产环境使用数据库模式
```

#### 6. 补充信息（可选）

**可选章节：**
- 使用示例：提供代码示例展示典型用法
- 模块配置：说明模块的配置方式和参数
- 版本信息：记录版本号、作者、创建时间等
- 已知问题和改进建议：列出当前限制和未来改进方向

### 文档质量要求

#### 内容质量标准
- **准确性**：所有信息必须与代码实现一致
- **完整性**：覆盖所有公共接口和重要功能
- **简洁性**：每个说明控制在一句话内，突出核心要点
- **实用性**：提供对开发者有价值的信息和建议

#### 语言表达规范
- 使用中文进行描述，专业术语可保留英文
- 语言简洁明了，避免冗长的句子
- 统一术语使用，保持前后一致
- 避免主观评价，客观描述功能和特性

#### 格式规范要求
- 严格按照Markdown格式编写
- 使用统一的标题层级和列表格式
- 代码示例使用正确的语法高亮
- 保持良好的文档结构和可读性

### 文档生成流程

#### 1. 代码分析阶段
- 扫描文件夹内所有源代码文件
- 识别所有公共类、方法、接口、枚举等
- 分析import依赖关系和模块结构
- 提取关键的业务逻辑和技术实现

#### 2. 信息整理阶段
- 按功能逻辑对接口进行分类
- 分析每个方法的参数、返回值和功能
- 识别核心特性和技术亮点
- 评估潜在的风险点和限制

#### 3. 文档编写阶段
- 按照规范结构组织内容
- 编写简洁准确的功能描述
- 提供实用的使用建议和风险提示
- 确保文档的完整性和一致性

#### 4. 质量检查阶段
- 验证所有信息的准确性
- 检查文档格式和语言表达
- 确保覆盖所有重要功能点
- 验证风险评估的合理性

### 步骤6执行模板

```
## 步骤6：功能文档生成报告

### 📋 文档生成范围
- **目标文件夹**: [检查的文件夹路径]
- **包含文件数**: [统计源代码文件数量]
- **主要文件类型**: [列出主要的文件类型，如Service、Controller、DTO等]

### 🔍 代码分析结果

#### 对外接口统计
1. **[功能分类1]**
   - [方法名1]: [功能描述]
   - [方法名2]: [功能描述]
   
2. **[功能分类2]**
   - [方法名1]: [功能描述]
   - [方法名2]: [功能描述]

#### 内部依赖分析
1. **外部依赖**
   - [依赖名1] (来自 [路径]): [用途说明]
   - [依赖名2] (来自 [路径]): [用途说明]
   
2. **内部依赖**
   - [依赖名1] (本模块): [用途说明]
   - [依赖名2] (本模块): [用途说明]

#### 核心特性识别
1. **[特性分类1]**
   - [特性描述1]
   - [特性描述2]
   
2. **[特性分类2]**
   - [特性描述1]
   - [特性描述2]

#### 潜在风险评估
1. **[风险分类1]**
   - [风险名称1]: [风险描述和建议]
   - [风险名称2]: [风险描述和建议]
   
2. **[风险分类2]**
   - [风险名称1]: [风险描述和建议]
   - [风险名称2]: [风险描述和建议]

### 📚 生成的文档内容

#### 文档结构
- ✅ 模块概述
- ✅ 对外接口 ([数量]个方法)
- ✅ 内部依赖 ([数量]个依赖)
- ✅ 核心特性 ([数量]个特性)
- ✅ 潜在风险 ([数量]个风险点)
- ✅ 补充信息 (可选)

#### 文档质量检查
- 内容准确性 ✓/✗
- 信息完整性 ✓/✗
- 语言简洁性 ✓/✗
- 格式规范性 ✓/✗

### 🛠️ 文档生成方案
[说明将要创建或更新的README.md文件路径和主要内容]

### ⚠️ 文档生成重点
- 确保所有公共接口都有准确的功能描述
- 分析所有项目内部依赖的使用情况
- 识别模块的核心技术特性和业务价值
- 评估潜在风险并提供合理的建议
- 保持文档内容与代码实现的一致性

### ✅ 步骤6完成状态
- 代码分析 ✓/✗
- 接口梳理 ✓/✗
- 依赖分析 ✓/✗
- 特性识别 ✓/✗
- 风险评估 ✓/✗
- 文档生成 ✓/✗

**步骤6完成，所有检查步骤已完成！功能文档已生成。**
```

---

## 🤖 AI分步执行指南

### 执行原则

1. **单步执行**：每次只执行一个检查步骤
2. **等待确认**：完成一步后必须等待用户确认
3. **专注单一**：每步只关注该步骤的规范问题
4. **完整报告**：每步都要提供完整的检查报告
5. **状态跟踪**：清楚标记每步的完成状态
6. **修改验证**：对步骤进行修改后，必须重新检查验证

### 执行流程

```
用户请求代码检查
    ↓
AI执行步骤1：命名规范检查
    ↓
提供步骤1检查报告
    ↓
等待用户确认 ← 用户可以要求修改或继续
    ↓
[如果用户要求修改] → AI执行修改 → 重新检查步骤1 → 提供验证报告 → 等待确认
    ↓
AI执行步骤2：注释规范检查
    ↓
提供步骤2检查报告
    ↓
等待用户确认 ← 用户可以要求修改或继续
    ↓
[如果用户要求修改] → AI执行修改 → 重新检查步骤2 → 提供验证报告 → 等待确认
    ↓
AI执行步骤3：代码质量检查
    ↓
提供步骤3检查报告
    ↓
等待用户确认 ← 用户可以要求修改或继续
    ↓
[如果用户要求修改] → AI执行修改 → 重新检查步骤3 → 提供验证报告 → 等待确认
    ↓
AI执行步骤4：架构分层检查
    ↓
提供步骤4检查报告
    ↓
等待用户确认 ← 用户可以要求修改或继续
    ↓
[如果用户要求修改] → AI执行修改 → 重新检查步骤4 → 提供验证报告 → 等待确认
    ↓
AI执行步骤5：测试覆盖检查
    ↓
提供步骤5检查报告
    ↓
等待用户确认 ← 用户可以要求修改或继续
    ↓
[如果用户要求修改] → AI执行修改 → 重新检查步骤5 → 提供验证报告 → 等待确认
    ↓
AI执行步骤6：功能文档生成
    ↓
提供步骤6检查报告 - 所有步骤完成
```

### 用户交互指令

用户可以使用以下指令控制检查流程：

- **"继续下一步"** - 继续执行下一个检查步骤
- **"重新检查步骤X"** - 重新执行指定步骤（X为1-6）
- **"跳过步骤X"** - 跳过指定步骤（X为1-6）
- **"修改步骤X的方案"** - 修改指定步骤的修正方案（X为1-6）
- **"应用修改并验证"** - 应用当前步骤的修正方案并重新检查验证
- **"执行所有修正"** - 应用所有步骤的修正方案
- **"生成最终报告"** - 生成所有步骤的汇总报告

### 修改验证流程

**⚠️ 重要规则：每当AI对某个步骤进行修改后，必须自动重新检查该步骤**

#### 修改验证步骤：
1. **执行修改**：根据用户确认的方案进行代码修改
2. **重新检查**：对修改后的代码重新执行该步骤的检查
3. **验证报告**：提供修改验证报告，说明修改效果
4. **状态确认**：确认该步骤是否完全通过检查
5. **等待确认**：等待用户确认验证结果

#### 验证报告模板：
```
## 步骤X修改验证报告

### 🔧 已执行的修改
- [列出具体执行的修改操作]
- [修改的文件和内容]

### 🔍 重新检查结果
- [该步骤的重新检查结果]
- [是否还存在问题]

### ✅ 验证状态
- 修改执行 ✓/✗
- 问题解决 ✓/✗
- 步骤通过 ✓/✗

### ⚠️ 发现的新问题（如有）
- [列出修改过程中可能引入的新问题]

**验证结果：该步骤 [已完全通过/仍有问题需要处理]**
```

#### 验证失败处理：
- 如果重新检查发现仍有问题，提供进一步的修正建议
- 如果修改引入了新问题，说明问题原因并提供解决方案
- 继续修改-验证循环，直到该步骤完全通过检查

### 特殊情况处理

1. **发现严重问题**：立即停止并报告，等待用户决定
2. **步骤间冲突**：优先保证前面步骤的修正结果
3. **用户要求跳过**：记录跳过原因，在最终报告中说明
4. **修正失败**：提供替代方案或建议手动修正
5. **修改验证失败**：继续修改-验证循环，直到问题完全解决
6. **修改引入新问题**：立即报告新问题并提供解决方案

### 修改验证质量保证

#### 验证检查要点：
- **完整性检查**：确保所有计划的修改都已执行
- **正确性检查**：验证修改是否解决了原有问题
- **一致性检查**：确保修改没有破坏其他部分的规范
- **新问题检查**：识别修改过程中可能引入的新问题

#### 验证失败的常见原因：
- 修改不完整，遗漏了某些文件或代码片段
- 修改方向错误，没有解决根本问题
- 修改引入了新的规范违规问题
- 修改破坏了代码的功能性或一致性

#### 验证成功的标准：
- 原有问题完全解决
- 没有引入新的规范问题
- 代码功能保持正常
- 符合项目的整体规范要求

---

## ⚠️ 重要提醒

### AI必须遵循的分步原则

1. **严格分步**：绝对不能一次性执行多个步骤
2. **等待确认**：每步完成后必须等待用户明确确认
3. **专注单一**：每步只关注该步骤的规范，不涉及其他
4. **完整报告**：每步都要提供详细的检查结果和修正方案
5. **状态跟踪**：清楚记录每步的执行状态和结果
6. **用户主导**：用户可以随时要求修改、跳过或重新执行某步骤

### 分步执行的优势

1. **减少遗漏**：专注单一规范，避免同时处理多个问题时的遗漏
2. **便于调试**：问题定位更精确，修正更有针对性
3. **用户控制**：用户可以控制检查节奏和重点
4. **质量保证**：每步都有独立的质量检查和确认
5. **灵活调整**：可以根据实际情况调整检查策略

---

**🎯 AI助手请严格按照分步执行方式进行代码检查，每次只执行一个步骤，确保100%符合项目规范要求！**

**⚠️ 特别提醒：必须等待用户确认后才能进行下一步骤，绝不能一次性执行多个步骤！**

**🔄 修改验证强制要求：每当对某个步骤进行修改后，必须重新检查该步骤并提供验证报告，确保修改正确且没有引入新问题！**

**📅 日期和作者规范强制要求：**
- **执行前必须收集**：AI必须在开始任何检查步骤前要求用户提供当前日期和名称
- **用户信息应用**：所有修改记录、@since、@lastModified等字段必须使用用户提供的信息
- **@author字段处理**：AI标识替换为用户名称，其他人名保留原作者
- **修改记录标识**：每条修改记录都必须标明修改者信息
- **严禁使用预设信息**：不能使用系统时间、示例日期、模板占位符或预设作者名
- **信息格式要求**：日期格式为YYYY-MM-DD，修改记录格式为"日期: 类型 - 内容 (修改者: 名称)"
- **强制验证**：如果用户未提供这些信息，AI必须拒绝开始检查

**🏗️ 架构分层要求：**
- **Core文件夹**：专注底层技术实现，关注功能实现与效果，不包含业务逻辑
- **Business文件夹**：专注业务逻辑完备性，不关心底层技术实现细节
- **严格分层**：确保各层职责清晰，依赖关系合理

**🧪 测试覆盖要求：**
- **Service测试强制性**：每个Service都必须有对应的.spec.ts测试文件
- **测试覆盖完整性**：所有公共方法都必须有测试覆盖
- **测试场景真实性**：必须测试正常情况、异常情况和边界情况
- **测试代码质量**：测试用例必须真实有效，不能是空壳测试
- **集成测试要求**：复杂Service需要提供.integration.spec.ts集成测试
- **测试执行验证**：测试覆盖检查完成后必须执行实际测试命令验证通过