8.8 KiB
8.8 KiB
AI代码检查规范（简洁版）
执行原则
- 分步执行：每次只执行一个步骤，完成后等待用户确认
- 用户信息收集：开始前必须收集用户当前日期和名称
- 修改验证：每次修改后必须重新检查该步骤
检查步骤
步骤1：命名规范检查
- 文件/文件夹：snake_case（下划线分隔），严禁kebab-case
- 变量/函数：camelCase
- 类/接口：PascalCase
- 常量：SCREAMING_SNAKE_CASE
- 路由：kebab-case
- 文件夹优化：删除单文件文件夹，扁平化结构
- Core层命名：业务支撑模块用_core后缀，通用工具模块不用
文件夹结构检查要求
必须使用listDirectory工具详细检查每个文件夹的内容：
- 使用
listDirectory(path, depth=2)获取完整文件夹结构 - 统计每个文件夹内的文件数量
- 识别只有1个文件的文件夹（单文件文件夹）
- 将单文件文件夹中的文件移动到上级目录
- 更新所有相关的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类：文件名包含
- 方法覆盖：所有公共方法必须有测试
- 场景覆盖：正常、异常、边界情况
- 测试质量：真实有效的测试用例，不是空壳
- 集成测试：复杂Service需要.integration.spec.ts
- 测试执行：必须执行测试命令验证通过
步骤6：功能文档生成
- README结构：模块概述、对外接口、内部依赖、核心特性、潜在风险
- 接口描述：每个公共方法一句话功能说明
- 依赖分析：列出所有项目内部依赖及用途
- 特性识别：技术特性、功能特性、质量特性
- 风险评估：技术风险、业务风险、运维风险、安全风险
关键规则
命名规范
// 文件命名
✅ 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;
注释规范
/**
* 文件功能描述
*
* 功能描述：
* - 功能点1
* - 功能点2
*
* 最近修改：
* - [用户日期]: 修改类型 - 修改内容 (修改者: [用户名称])
*
* @author [处理后的作者名称]
* @version x.x.x
* @since [创建日期]
* @lastModified [用户日期]
*/
@author字段处理规则：
- 保留人名：如果@author是人名，必须保留不变
- 替换AI标识：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换
- 示例：
@author kiro→ 可替换为@author [用户名称]@author 张三→ 必须保留为@author 张三
架构分层
// 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后缀 - 通用工具模块：提供可复用的数据访问或基础服务 → 不使用后缀
测试覆盖
describe('UserService', () => {
describe('createUser', () => {
it('should create user successfully', () => {}); // 正常情况
it('should throw error when email exists', () => {}); // 异常情况
it('should handle empty name', () => {}); // 边界情况
});
});
执行模板
每步完成后使用此模板报告：
## 步骤X：[步骤名称]检查报告
### 🔍 检查结果
[发现的问题列表]
### 🛠️ 修正方案
[具体修正建议]
### ✅ 完成状态
- 检查项1 ✓/✗
- 检查项2 ✓/✗
**请确认修正方案，确认后进行下一步骤**
修改验证流程
修改后必须：
- 重新执行该步骤检查
- 提供验证报告
- 确认问题是否解决
- 等待用户确认
强制要求
- 用户信息：开始前必须收集用户日期和名称
- 分步执行：严禁一次执行多步骤
- 等待确认：每步完成后必须等待用户确认
- 修改验证：修改后必须重新检查验证
- 测试执行：步骤5必须执行实际测试命令
- 日期使用：所有日期字段使用用户提供的真实日期
- 作者字段保护：@author字段中的人名不得修改，只有AI标识才可替换
- 修改记录强制：每次修改文件必须添加修改记录和更新@lastModified