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

- 更新AI代码检查规范简洁版
- 完善开发者代码检查规范
- 扩展OpenAPI文档，添加新的接口定义

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

@@ -14,7 +14,7 @@
 - **常量**：SCREAMING_SNAKE_CASE
 - **路由**：kebab-case
 - **文件夹优化**：删除单文件文件夹，扁平化结构
-- **Core层命名**：业务支撑模块用_core后缀，工具模块不用
+- **Core层命名**：业务支撑模块用_core后缀，通用工具模块不用
 
 #### 文件夹结构检查要求
 **必须使用listDirectory工具详细检查每个文件夹的内容：**
@@ -28,11 +28,19 @@
 - 不超过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
@@ -44,22 +52,38 @@
   - **AI标识替换**：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
   - **判断示例**：`@author kiro` → 可替换，`@author 张三` → 必须保留
 - **版本号递增**：规范优化/Bug修复→修订版本+1，功能变更→次版本+1，重构→主版本+1
-- **时间更新**：每次修改必须更新@lastModified字段
+- **时间更新**：只有真正修改了文件内容时才更新@lastModified字段，仅检查不修改内容时不更新日期
 
 ### 步骤3：代码质量检查
 - **清理未使用**：导入、变量、方法
 - **常量定义**：使用SCREAMING_SNAKE_CASE
 - **方法长度**：建议不超过50行
 - **代码重复**：识别并消除重复代码
+- **魔法数字**：提取为常量定义
+- **工具函数**：抽象重复逻辑为可复用函数
 
 ### 步骤4：架构分层检查
-- **Core层**：专注技术实现，不含业务逻辑，业务支撑模块用_core后缀
+- **检查范围**：仅检查当前执行检查的文件夹，不考虑其他同层功能模块
+- **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工具类**：工具函数不需要测试文件
 - **方法覆盖**：所有公共方法必须有测试
 - **场景覆盖**：正常、异常、边界情况
 - **测试质量**：真实有效的测试用例，不是空壳
@@ -118,25 +142,40 @@
 
 ### 架构分层
 ```typescript
-// Core层 - 技术实现
+// Core层 - 业务支撑模块（使用_core后缀）
 @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层 - 业务逻辑
 @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`后缀
+- **通用工具模块**：提供可复用的数据访问或基础服务 → 不使用后缀
+
 ### 测试覆盖
 ```typescript
 describe('UserService', () => {

开发者代码检查规范.md

@@ -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
 ✅ 正确示例：
-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定义（重要）：**
+只有以下类型需要测试文件：
+- ✅ **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
-// ✅ 正确：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/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.spec.ts
 ```
 
+**扁平化要求：**
+- **强制扁平化**：所有tests/、test/、spec/、__tests__/等测试专用文件夹必须扁平化
+- **移动规则**：将测试文件移动到对应源文件的同一目录
+- **更新引用**：移动后必须更新所有import路径引用
+- **删除空文件夹**：移动完成后删除空的测试文件夹
+
 ### 🎯 测试用例覆盖完整性
 
 **要求：测试文件必须覆盖Service中的所有公共方法**
@@ -792,7 +845,7 @@ npx jest src/core/db/users --coverage --testPathIgnorePatterns="integration.spec
 - [ ] 常量使用SCREAMING_SNAKE_CASE（全大写+下划线）
 - [ ] 路由使用kebab-case（短横线分隔）
 - [ ] 避免过度嵌套的文件夹结构
-- [ ] Core层业务支撑模块使用_core后缀
+- [ ] Core层业务支撑模块使用_core后缀，通用工具模块不使用后缀
 
 #### 注释规范检查清单
 - [ ] 文件头注释包含功能描述、职责分离、修改记录