datawhale/whale-town-end
3
4
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs：更新代码检查规范和API文档

Browse Source 
- 更新AI代码检查规范简洁版
- 完善开发者代码检查规范
- 扩展OpenAPI文档，添加新的接口定义
This commit is contained in:
moyin
2026-01-08 23:03:40 +08:00
parent bb796a2469
commit dd5cc48b49
3 changed files with 1797 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
AI代码检查规范_简洁版.md
View File

@@ -14,7 +14,7 @@
- **常量**：SCREAMING_SNAKE_CASE - **常量**：SCREAMING_SNAKE_CASE
- **路由**：kebab-case - **路由**：kebab-case
- **文件夹优化**：删除单文件文件夹，扁平化结构 - **文件夹优化**：删除单文件文件夹，扁平化结构
- **Core层命名**：业务支撑模块用_core后缀，工具模块不用 - **Core层命名**：业务支撑模块用_core后缀，通用工具模块不用
#### 文件夹结构检查要求 #### 文件夹结构检查要求
**必须使用listDirectory工具详细检查每个文件夹的内容：** **必须使用listDirectory工具详细检查每个文件夹的内容：**
@@ -28,11 +28,19 @@
- 不超过3个文件的文件夹：必须扁平化处理 - 不超过3个文件的文件夹：必须扁平化处理
- 4个以上文件：通常保持独立文件夹 - 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个文件以下文件夹的识别 - 遗漏3个文件以下文件夹的识别
- **忽略测试文件夹**：认为tests文件夹是"标准结构"而不进行扁平化检查
### 步骤2：注释规范检查 ### 步骤2：注释规范检查
- **文件头注释**：功能描述、职责分离、修改记录、@author、@version、@since、@lastModified - **文件头注释**：功能描述、职责分离、修改记录、@author、@version、@since、@lastModified
@@ -44,22 +52,38 @@
- **AI标识替换**：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称 - **AI标识替换**：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
- **判断示例**：`@author kiro` → 可替换，`@author 张三` → 必须保留 - **判断示例**：`@author kiro` → 可替换，`@author 张三` → 必须保留
- **版本号递增**：规范优化/Bug修复→修订版本+1，功能变更→次版本+1，重构→主版本+1 - **版本号递增**：规范优化/Bug修复→修订版本+1，功能变更→次版本+1，重构→主版本+1
- **时间更新**：每次修改必须更新@lastModified字段 - **时间更新**：只有真正修改了文件内容时才更新@lastModified字段，仅检查不修改内容时不更新日期
### 步骤3：代码质量检查 ### 步骤3：代码质量检查
- **清理未使用**：导入、变量、方法 - **清理未使用**：导入、变量、方法
- **常量定义**：使用SCREAMING_SNAKE_CASE - **常量定义**：使用SCREAMING_SNAKE_CASE
- **方法长度**：建议不超过50行 - **方法长度**：建议不超过50行
- **代码重复**：识别并消除重复代码 - **代码重复**：识别并消除重复代码
- **魔法数字**：提取为常量定义
- **工具函数**：抽象重复逻辑为可复用函数
### 步骤4：架构分层检查 ### 步骤4：架构分层检查
- **Core层**：专注技术实现，不含业务逻辑，业务支撑模块用_core后缀 - **检查范围**：仅检查当前执行检查的文件夹，不考虑其他同层功能模块
- **Core层**：专注技术实现，不含业务逻辑
- **Core层命名规则**：
- **业务支撑模块**：为特定业务功能提供技术支撑，使用`_core`后缀（如：`location_broadcast_core`）
- **通用工具模块**：提供可复用的数据访问或技术服务，不使用后缀（如：`user_profiles`、`redis_cache`）
- **判断方法**：检查模块是否专门为某个业务服务，如果是则使用`_core`后缀，如果是通用服务则不使用
- **Business层**：专注业务逻辑，不含技术实现细节 - **Business层**：专注业务逻辑，不含技术实现细节
- **依赖关系**：Core层不能导入Business层，Business层通过依赖注入使用Core层 - **依赖关系**：Core层不能导入Business层，Business层通过依赖注入使用Core层
- **职责分离**：确保各层职责清晰，边界明确 - **职责分离**：确保各层职责清晰，边界明确
### 步骤5：测试覆盖检查 ### 步骤5：测试覆盖检查
- **测试文件存在性**：每个Service必须有.spec.ts文件 - **测试文件存在性**：每个Service必须有.spec.ts文件
- **Service定义**：只有以下类型需要测试文件
- ✅ **Service类**：文件名包含`.service.ts`的业务逻辑类
- ✅ **Controller类**：文件名包含`.controller.ts`的控制器类
- ✅ **Gateway类**：文件名包含`.gateway.ts`的WebSocket网关类
- ❌ **Middleware类**：中间件不需要测试文件
- ❌ **Guard类**：守卫不需要测试文件
- ❌ **DTO类**：数据传输对象不需要测试文件
- ❌ **Interface文件**：接口定义不需要测试文件
- ❌ **Utils工具类**：工具函数不需要测试文件
- **方法覆盖**：所有公共方法必须有测试 - **方法覆盖**：所有公共方法必须有测试
- **场景覆盖**：正常、异常、边界情况 - **场景覆盖**：正常、异常、边界情况
- **测试质量**：真实有效的测试用例，不是空壳 - **测试质量**：真实有效的测试用例，不是空壳
@@ -118,25 +142,40 @@
### 架构分层 ### 架构分层
```typescript ```typescript
// Core层 - 技术实现 // Core层 - 业务支撑模块（使用_core后缀）
@Injectable() @Injectable()
export class RedisService { export class LocationBroadcastCoreService {
async set(key: string, value: any): Promise<void> { async broadcastPosition(data: PositionData): Promise<void> {
// 专注技术实现 // 为位置广播业务提供技术支撑
}
}
// Core层 - 通用工具模块（不使用后缀）
@Injectable()
export class UserProfilesService {
async findByUserId(userId: bigint): Promise<UserProfile> {
// 通用的用户档案数据访问服务
} }
} }
// Business层 - 业务逻辑 // Business层 - 业务逻辑
@Injectable() @Injectable()
export class UserBusinessService { export class LocationBroadcastService {
constructor(private readonly userCoreService: UserCoreService) {} constructor(
private readonly locationBroadcastCore: LocationBroadcastCoreService,
private readonly userProfiles: UserProfilesService
) {}
async registerUser(data: RegisterDto): Promise<User> { async updateUserLocation(userId: string, position: Position): Promise<void> {
// 业务逻辑：验证、调用Core层、返回结果 // 业务逻辑：验证、调用Core层、返回结果
} }
} }
``` ```
**Core层命名判断标准：**
- **业务支撑模块**：专门为某个业务功能提供技术支撑 → 使用`_core`后缀
- **通用工具模块**：提供可复用的数据访问或基础服务 → 不使用后缀
### 测试覆盖 ### 测试覆盖
```typescript ```typescript
describe('UserService', () => { describe('UserService', () => {

1690
docs/api/openapi.yaml
View File

File diff suppressed because it is too large Load Diff

79
开发者代码检查规范.md
View File

@@ -273,7 +273,7 @@ async validateUser(loginRequest: LoginRequest): Promise<AuthResult> {
**修改记录更新要求：** **修改记录更新要求：**
- **必须添加**：每次修改文件后，必须在"最近修改"部分添加新的修改记录 - **必须添加**：每次修改文件后，必须在"最近修改"部分添加新的修改记录
- **信息完整**：包含修改日期、修改类型、修改内容、修改者姓名 - **信息完整**：包含修改日期、修改类型、修改内容、修改者姓名
- **时间更新**：同时更新@lastModified字段为当前修改时间 - **时间更新**：只有真正修改了文件内容时才更新@lastModified字段，仅检查不修改内容时不更新日期
- **版本递增**：根据修改类型适当递增版本号 - **版本递增**：根据修改类型适当递增版本号
**版本号递增规则：** **版本号递增规则：**
@@ -364,19 +364,43 @@ src/
**职责：专注技术实现，不包含业务逻辑** **职责：专注技术实现，不包含业务逻辑**
#### 命名规范 #### 命名规范
- **业务支撑模块**：使用`_core`后缀（如`users_core`、`login_core`） - **检查范围**：仅检查当前执行检查的文件夹，不考虑其他同层功能模块
- **底层工具模块**：不使用`_core`后缀（如`redis`、`logger`） - **业务支撑模块**：专门为特定业务功能提供技术支撑，使用`_core`后缀（如`location_broadcast_core`、`user_auth_core`）
- **通用工具模块**：提供可复用的数据访问或基础技术服务，不使用`_core`后缀（如`user_profiles`、`redis_cache`、`logger`）
**判断标准：**
- **业务支撑模块**：模块名称体现特定业务领域，为该业务提供技术实现 → 使用`_core`后缀
- **通用工具模块**：模块提供通用的数据访问或技术服务，可被多个业务复用 → 不使用后缀
**判断流程：**
```
1. 模块是否专门为某个特定业务功能服务？
├─ 是 → 检查模块名称是否体现业务领域
│ ├─ 是 → 使用 _core 后缀 (如: location_broadcast_core)
│ └─ 否 → 重新设计模块职责
└─ 否 → 模块是否提供通用的技术服务？
├─ 是 → 不使用 _core 后缀 (如: user_profiles, redis)
└─ 否 → 重新评估模块定位
2. 实际案例判断：
- user_profiles: 通用的用户档案数据访问 → 不使用后缀 ✓
- location_broadcast_core: 专门为位置广播业务服务 → 使用_core后缀 ✓
- redis: 通用的缓存技术服务 → 不使用后缀 ✓
- user_auth_core: 专门为用户认证业务服务 → 使用_core后缀 ✓
```
```typescript ```typescript
✅ 正确示例： ✅ 正确示例：
src/core/db/users_core/ # 为business/users提供数据层支撑 src/core/location_broadcast_core/ # 专门为位置广播业务提供技术支撑
src/core/login_core/ # 为business/auth提供登录技术实现 src/core/user_auth_core/ # 专门为用户认证业务提供技术支撑
src/core/redis/ # 纯Redis技术封装 src/core/db/user_profiles/ # 通用的用户档案数据访问服务
src/core/utils/logger/ # 纯日志工具 src/core/redis/ # 通用的Redis技术封装
src/core/utils/logger/ # 通用的日志工具服务
❌ 错误示例： ❌ 错误示例：
src/core/db/users/ # 应该是users_core src/core/location_broadcast/ # 应该是location_broadcast_core
src/core/redis_core/ # 应该是redis src/core/db/user_profiles_core/ # 应该是user_profiles（通用工具）
src/core/redis_core/ # 应该是redis（通用工具）
``` ```
#### 技术实现示例 #### 技术实现示例
@@ -530,19 +554,48 @@ export class DatabaseService {
**规则：每个Service都必须有对应的.spec.ts测试文件** **规则：每个Service都必须有对应的.spec.ts测试文件**
**⚠️ Service定义（重要）：**
只有以下类型需要测试文件：
- ✅ **Service类**：文件名包含`.service.ts`的业务逻辑类
- ✅ **Controller类**：文件名包含`.controller.ts`的控制器类
- ✅ **Gateway类**：文件名包含`.gateway.ts`的WebSocket网关类
**❌ 以下类型不需要测试文件：**
- ❌ **Middleware类**：中间件（`.middleware.ts`）不需要测试文件
- ❌ **Guard类**：守卫（`.guard.ts`）不需要测试文件
- ❌ **DTO类**：数据传输对象（`.dto.ts`）不需要测试文件
- ❌ **Interface文件**：接口定义（`.interface.ts`）不需要测试文件
- ❌ **Utils工具类**：工具函数（`.utils.ts`）不需要测试文件
- ❌ **Config文件**：配置文件（`.config.ts`）不需要测试文件
**测试文件位置规范（重要）：**
- ✅ **正确位置**：测试文件必须与对应源文件放在同一目录
- ❌ **错误位置**：测试文件放在单独的tests/、test/、spec/、__tests__/等文件夹中
```typescript ```typescript
// ✅ 正确：Service与测试文件一一对应 // ✅ 正确：测试文件与源文件同目录
src/core/db/users/users.service.ts src/core/db/users/users.service.ts
src/core/db/users/users.service.spec.ts src/core/db/users/users.service.spec.ts
src/core/db/users/users_memory.service.ts src/business/admin/admin.service.ts
src/core/db/users/users_memory.service.spec.ts src/business/admin/admin.service.spec.ts
// ❌ 错误：测试文件在单独文件夹
src/business/admin/admin.service.ts
src/business/admin/tests/admin.service.spec.ts # 错误位置
src/business/admin/__tests__/admin.service.spec.ts # 错误位置
// ❌ 错误：缺少测试文件 // ❌ 错误：缺少测试文件
src/core/login_core/login_core.service.ts src/core/login_core/login_core.service.ts
# 缺少：src/core/login_core/login_core.service.spec.ts # 缺少：src/core/login_core/login_core.service.spec.ts
``` ```
**扁平化要求：**
- **强制扁平化**：所有tests/、test/、spec/、__tests__/等测试专用文件夹必须扁平化
- **移动规则**：将测试文件移动到对应源文件的同一目录
- **更新引用**：移动后必须更新所有import路径引用
- **删除空文件夹**：移动完成后删除空的测试文件夹
### 🎯 测试用例覆盖完整性 ### 🎯 测试用例覆盖完整性
**要求：测试文件必须覆盖Service中的所有公共方法** **要求：测试文件必须覆盖Service中的所有公共方法**
@@ -792,7 +845,7 @@ npx jest src/core/db/users --coverage --testPathIgnorePatterns="integration.spec
- [ ] 常量使用SCREAMING_SNAKE_CASE（全大写+下划线） - [ ] 常量使用SCREAMING_SNAKE_CASE（全大写+下划线）
- [ ] 路由使用kebab-case（短横线分隔） - [ ] 路由使用kebab-case（短横线分隔）
- [ ] 避免过度嵌套的文件夹结构 - [ ] 避免过度嵌套的文件夹结构
- [ ] Core层业务支撑模块使用_core后缀 - [ ] Core层业务支撑模块使用_core后缀，通用工具模块不使用后缀
#### 注释规范检查清单 #### 注释规范检查清单
- [ ] 文件头注释包含功能描述、职责分离、修改记录 - [ ] 文件头注释包含功能描述、职责分离、修改记录