whale-town-end/AI代码检查规范_简洁版.md

# AI代码检查规范（简洁版）

## 执行原则
- **分步执行**：每次只执行一个步骤，完成后等待用户确认
- **用户信息收集**：开始前必须收集用户当前日期和名称
- **修改验证**：每次修改后必须重新检查该步骤

## 检查步骤

### 步骤1：命名规范检查
- **文件/文件夹**：snake_case（下划线分隔），严禁kebab-case
- **变量/函数**：camelCase
- **类/接口**：PascalCase  
- **常量**：SCREAMING_SNAKE_CASE
- **路由**：kebab-case
- **文件夹优化**：删除单文件文件夹，扁平化结构
- **Core层命名**：业务支撑模块用_core后缀，通用工具模块不用

#### 文件夹结构检查要求
**必须使用listDirectory工具详细检查每个文件夹的内容：**
1. 使用`listDirectory(path, depth=2)`获取完整文件夹结构
2. 统计每个文件夹内的文件数量
3. 识别只有1个文件的文件夹（单文件文件夹）
4. 将单文件文件夹中的文件移动到上级目录
5. 更新所有相关的import路径引用

**检查标准：**
- 不超过3个文件的文件夹：必须扁平化处理
- 4个以上文件：通常保持独立文件夹
- 完整功能模块：即使文件较少也可以保持独立（需特殊说明）
- **测试文件位置**：测试文件必须与对应源文件放在同一目录，不允许单独的tests文件夹

**测试文件位置规范（重要）：**
- ✅ 正确：`src/business/admin/admin.service.ts` 和 `src/business/admin/admin.service.spec.ts` 同目录
- ❌ 错误：`src/business/admin/tests/admin.service.spec.ts` 单独tests文件夹
- **强制要求**：所有tests/、test/等测试专用文件夹必须扁平化，测试文件移动到源文件同目录
- **扁平化处理**：包括tests/、test/、spec/、__tests__/等所有测试文件夹都必须扁平化

**常见错误：**
- 只看文件夹名称，不检查内容
- 凭印象判断，不使用工具获取准确数据
- 遗漏3个文件以下文件夹的识别
- **忽略测试文件夹**：认为tests文件夹是"标准结构"而不进行扁平化检查

### 步骤2：注释规范检查
- **文件头注释**：功能描述、职责分离、修改记录、@author、@version、@since、@lastModified
- **类注释**：职责、主要方法、使用场景
- **方法注释**：业务逻辑步骤、@param、@returns、@throws、@example
- **修改记录**：使用用户提供的日期和名称，格式"日期: 类型 - 内容 (修改者: 名称)"
- **@author处理规范**：
  - **保留原则**：人名必须保留，不得随意修改
  - **AI标识替换**：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
  - **判断示例**：`@author kiro` → 可替换，`@author 张三` → 必须保留
- **版本号递增**：规范优化/Bug修复→修订版本+1，功能变更→次版本+1，重构→主版本+1
- **时间更新**：只有真正修改了文件内容时才更新@lastModified字段，仅检查不修改内容时不更新日期

### 步骤3：代码质量检查
- **清理未使用**：导入、变量、方法
- **常量定义**：使用SCREAMING_SNAKE_CASE
- **方法长度**：建议不超过50行
- **代码重复**：识别并消除重复代码
- **魔法数字**：提取为常量定义
- **工具函数**：抽象重复逻辑为可复用函数

### 步骤4：架构分层检查
- **检查范围**：仅检查当前执行检查的文件夹，不考虑其他同层功能模块
- **Core层**：专注技术实现，不含业务逻辑
- **Core层命名规则**：
  - **业务支撑模块**：为特定业务功能提供技术支撑，使用`_core`后缀（如：`location_broadcast_core`）
  - **通用工具模块**：提供可复用的数据访问或技术服务，不使用后缀（如：`user_profiles`、`redis_cache`）
  - **判断方法**：检查模块是否专门为某个业务服务，如果是则使用`_core`后缀，如果是通用服务则不使用
- **Business层**：专注业务逻辑，不含技术实现细节
- **依赖关系**：Core层不能导入Business层，Business层通过依赖注入使用Core层
- **职责分离**：确保各层职责清晰，边界明确

### 步骤5：测试覆盖检查
- **测试文件存在性**：每个Service必须有.spec.ts文件
- **Service定义**：只有以下类型需要测试文件
  - ✅ **Service类**：文件名包含`.service.ts`的业务逻辑类
  - ✅ **Controller类**：文件名包含`.controller.ts`的控制器类
  - ✅ **Gateway类**：文件名包含`.gateway.ts`的WebSocket网关类
  - ❌ **Middleware类**：中间件不需要测试文件
  - ❌ **Guard类**：守卫不需要测试文件
  - ❌ **DTO类**：数据传输对象不需要测试文件
  - ❌ **Interface文件**：接口定义不需要测试文件
  - ❌ **Utils工具类**：工具函数不需要测试文件
- **方法覆盖**：所有公共方法必须有测试
- **场景覆盖**：正常、异常、边界情况
- **测试质量**：真实有效的测试用例，不是空壳
- **集成测试**：复杂Service需要.integration.spec.ts
- **测试执行**：必须执行测试命令验证通过

### 步骤6：功能文档生成
- **README结构**：模块概述、对外接口、内部依赖、核心特性、潜在风险
- **接口描述**：每个公共方法一句话功能说明
- **依赖分析**：列出所有项目内部依赖及用途
- **特性识别**：技术特性、功能特性、质量特性
- **风险评估**：技术风险、业务风险、运维风险、安全风险

## 关键规则

### 命名规范
```typescript
// 文件命名
✅ user_service.ts, create_user_dto.ts
❌ user-service.ts, UserService.ts

// 变量命名  
✅ const userName = 'test';
❌ const UserName = 'test';

// 常量命名
✅ const MAX_RETRY_COUNT = 3;
❌ const maxRetryCount = 3;
```

### 注释规范
```typescript
/**
 * 文件功能描述
 * 
 * 功能描述：
 * - 功能点1
 * - 功能点2
 * 
 * 最近修改：
 * - [用户日期]: 修改类型 - 修改内容 (修改者: [用户名称])
 * 
 * @author [处理后的作者名称]
 * @version x.x.x
 * @since [创建日期]
 * @lastModified [用户日期]
 */
```

**@author字段处理规则：**
- **保留人名**：如果@author是人名，必须保留不变
- **替换AI标识**：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换
- **示例**：
  - `@author kiro` → 可替换为 `@author [用户名称]`
  - `@author 张三` → 必须保留为 `@author 张三`

### 架构分层
```typescript
// Core层 - 业务支撑模块（使用_core后缀）
@Injectable()
export class LocationBroadcastCoreService {
  async broadcastPosition(data: PositionData): Promise<void> {
    // 为位置广播业务提供技术支撑
  }
}

// Core层 - 通用工具模块（不使用后缀）
@Injectable()
export class UserProfilesService {
  async findByUserId(userId: bigint): Promise<UserProfile> {
    // 通用的用户档案数据访问服务
  }
}

// Business层 - 业务逻辑
@Injectable() 
export class LocationBroadcastService {
  constructor(
    private readonly locationBroadcastCore: LocationBroadcastCoreService,
    private readonly userProfiles: UserProfilesService
  ) {}
  
  async updateUserLocation(userId: string, position: Position): Promise<void> {
    // 业务逻辑：验证、调用Core层、返回结果
  }
}
```

**Core层命名判断标准：**
- **业务支撑模块**：专门为某个业务功能提供技术支撑 → 使用`_core`后缀
- **通用工具模块**：提供可复用的数据访问或基础服务 → 不使用后缀

### 测试覆盖
```typescript
describe('UserService', () => {
  describe('createUser', () => {
    it('should create user successfully', () => {}); // 正常情况
    it('should throw error when email exists', () => {}); // 异常情况  
    it('should handle empty name', () => {}); // 边界情况
  });
});
```

## 执行模板

每步完成后使用此模板报告：

```
## 步骤X：[步骤名称]检查报告

### 🔍 检查结果
[发现的问题列表]

### 🛠️ 修正方案  
[具体修正建议]

### ✅ 完成状态
- 检查项1 ✓/✗
- 检查项2 ✓/✗

**请确认修正方案，确认后进行下一步骤**
```

## 修改验证流程

修改后必须：
1. 重新执行该步骤检查
2. 提供验证报告
3. 确认问题是否解决
4. 等待用户确认

## 强制要求

- **用户信息**：开始前必须收集用户日期和名称
- **分步执行**：严禁一次执行多步骤
- **等待确认**：每步完成后必须等待用户确认
- **修改验证**：修改后必须重新检查验证
- **测试执行**：步骤5必须执行实际测试命令
- **日期使用**：所有日期字段使用用户提供的真实日期
- **作者字段保护**：@author字段中的人名不得修改，只有AI标识才可替换
- **修改记录强制**：每次修改文件必须添加修改记录和更新@lastModified