forked from datawhale/whale-town-end
refactor:项目架构重构和命名规范化
- 统一文件命名为snake_case格式(kebab-case snake_case) - 重构zulip模块为zulip_core,明确Core层职责 - 重构user-mgmt模块为user_mgmt,统一命名规范 - 调整模块依赖关系,优化架构分层 - 删除过时的文件和目录结构 - 更新相关文档和配置文件 本次重构涉及大量文件重命名和模块重组, 旨在建立更清晰的项目架构和统一的命名规范。
This commit is contained in:
188
AI代码检查规范_简洁版.md
Normal file
188
AI代码检查规范_简洁版.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# 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个以上文件:通常保持独立文件夹
|
||||
- 完整功能模块:即使文件较少也可以保持独立(需特殊说明)
|
||||
|
||||
**常见错误:**
|
||||
- 只看文件夹名称,不检查内容
|
||||
- 凭印象判断,不使用工具获取准确数据
|
||||
- 遗漏3个文件以下文件夹的识别
|
||||
|
||||
### 步骤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后缀
|
||||
- **Business层**:专注业务逻辑,不含技术实现细节
|
||||
- **依赖关系**:Core层不能导入Business层,Business层通过依赖注入使用Core层
|
||||
- **职责分离**:确保各层职责清晰,边界明确
|
||||
|
||||
### 步骤5:测试覆盖检查
|
||||
- **测试文件存在性**:每个Service必须有.spec.ts文件
|
||||
- **方法覆盖**:所有公共方法必须有测试
|
||||
- **场景覆盖**:正常、异常、边界情况
|
||||
- **测试质量**:真实有效的测试用例,不是空壳
|
||||
- **集成测试**:复杂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层 - 技术实现
|
||||
@Injectable()
|
||||
export class RedisService {
|
||||
async set(key: string, value: any): Promise<void> {
|
||||
// 专注技术实现
|
||||
}
|
||||
}
|
||||
|
||||
// Business层 - 业务逻辑
|
||||
@Injectable()
|
||||
export class UserBusinessService {
|
||||
constructor(private readonly userCoreService: UserCoreService) {}
|
||||
|
||||
async registerUser(data: RegisterDto): Promise<User> {
|
||||
// 业务逻辑:验证、调用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
|
||||
Reference in New Issue
Block a user