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 {
-  async set(key: string, value: any): Promise<void> {
-    // 专注技术实现
+export class LocationBroadcastCoreService {
+  async broadcastPosition(data: PositionData): Promise<void> {
+    // 为位置广播业务提供技术支撑
+  }
+}
+
+// Core层 - 通用工具模块（不使用后缀）
+@Injectable()
+export class UserProfilesService {
+  async findByUserId(userId: bigint): Promise<UserProfile> {
+    // 通用的用户档案数据访问服务
   }
 }
 
 // Business层 - 业务逻辑
 @Injectable() 
-export class UserBusinessService {
-  constructor(private readonly userCoreService: UserCoreService) {}
+export class LocationBroadcastService {
+  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', () => {