style: 完善代码规范和测试覆盖

- 新增多个模块的单元测试文件，提升测试覆盖率 - 完善AI-Reading文档系统，包含7步代码检查流程 - 新增集成测试和属性测试框架 - 优化项目结构和配置文件 - 清理过时的规范文档，统一使用新的检查标准
2026-01-12 20:09:03 +08:00
parent 59128ea9a6
commit 5af44f95d5
22 changed files with 2595 additions and 2096 deletions
--- a/docs/ai-reading/step7-code-commit.md
+++ b/docs/ai-reading/step7-code-commit.md
@@ -1,5 +1,21 @@
 # 步骤7：代码提交

+## ⚠️ 执行前必读规范
+
+**🔥 重要：在执行本步骤之前，AI必须先完整阅读同级目录下的 `README.md` 文件！**
+
+该README文件包含：
+- 🎯 执行前准备和用户信息收集要求
+- 🔄 强制执行原则和分步执行流程  
+- 🔥 修改后立即重新执行当前步骤的强制规则
+- 📝 文件修改记录规范和版本号递增规则
+- 🧪 测试文件调试规范和测试指令使用规范
+- 🚨 全局约束和游戏服务器特殊要求
+
+**不阅读README直接执行步骤将导致执行不规范，违反项目要求！**
+
+---
+
 ## 🎯 检查目标
 完成代码修改后的规范化提交流程，确保代码变更记录清晰、分支管理规范、提交信息符合项目标准。

@@ -8,6 +24,37 @@
 - 所有修改的文件已更新修改记录和版本信息
 - 代码能够正常运行且通过测试

+## 🚨 协作规范和范围控制
+
+### 绝对禁止的操作
+**以下操作严格禁止，违反将影响其他AI的工作：**
+
+1. **禁止暂存范围外代码**
+   ```bash
+   # ❌ 绝对禁止
+   git stash push [范围外文件]
+   git stash push -m "消息" [范围外文件]
+   ```
+
+2. **禁止重置范围外代码**
+   ```bash
+   # ❌ 绝对禁止
+   git reset HEAD [范围外文件]
+   git checkout -- [范围外文件]
+   ```
+
+3. **禁止移动或隐藏范围外代码**
+   ```bash
+   # ❌ 绝对禁止
+   git mv [范围外文件] [其他位置]
+   git rm [范围外文件]
+   ```
+
+### 协作原则
+- **范围外代码必须保持原状**：其他AI需要处理这些代码
+- **只处理自己的范围**：严格按照检查任务的文件夹范围执行
+- **不影响其他工作流**：任何操作都不能影响其他AI的检查任务
+
 ## 🔍 Git变更检查与校验

 ### 1. 检查Git状态和变更内容
@@ -59,47 +106,113 @@ git diff --cached

 ## 🌿 分支管理规范

+### 🔥 重要原则：严格范围限制
+**🚨 绝对禁止：不得暂存、提交或以任何方式处理检查范围外的代码！**
+
+- ✅ **正确做法**：只提交当前检查任务涉及的文件和文件夹
+- ❌ **严格禁止**：提交其他模块、其他开发者负责的文件
+- ❌ **严格禁止**：使用git stash暂存其他范围的代码
+- ❌ **严格禁止**：以任何方式移动、隐藏或处理范围外的代码
+- ⚠️ **检查要求**：提交前必须确认所有变更文件都在当前检查范围内
+- 🔥 **协作原则**：其他范围的代码必须保持原状，供其他AI处理
+
 ### 分支命名规范
-根据修改类型创建对应的分支：
+根据修改类型和检查范围创建对应的分支：

 ```bash
-# 代码规范优化分支
-feature/code-standard-optimization-[日期]
-# 示例：feature/code-standard-optimization-20240112
+# 代码规范优化分支（指定检查范围）
+feature/code-standard-[模块名称]-[日期]
+# 示例：feature/code-standard-auth-20240112
+# 示例：feature/code-standard-zulip-20240112

-# Bug修复分支  
-fix/[具体问题描述]
-# 示例：fix/room-concurrency-issue
+# Bug修复分支（指定模块）
+fix/[模块名称]-[具体问题描述]
+# 示例：fix/auth-login-validation-issue
+# 示例：fix/zulip-message-handling-bug

-# 功能新增分支
-feature/[功能名称]
-# 示例：feature/user-authentication
+# 功能新增分支（指定模块）
+feature/[模块名称]-[功能名称]
+# 示例：feature/auth-multi-factor-authentication
+# 示例：feature/zulip-message-encryption

-# 重构分支
-refactor/[模块名称]
-# 示例：refactor/room-management
+# 重构分支（指定模块）
+refactor/[模块名称]-[重构内容]
+# 示例：refactor/auth-service-architecture
+# 示例：refactor/zulip-websocket-handler

-# 性能优化分支
-perf/[优化内容]
-# 示例：perf/database-query-optimization
+# 性能优化分支（指定模块）
+perf/[模块名称]-[优化内容]
+# 示例：perf/auth-token-validation
+# 示例：perf/zulip-message-processing

-# 文档更新分支
-docs/[文档类型]
-# 示例：docs/api-documentation
+# 文档更新分支（指定范围）
+docs/[模块名称]-[文档类型]
+# 示例：docs/auth-api-documentation
+# 示例：docs/zulip-integration-guide
 ```

 ### 创建和切换分支
 ```bash
-# 确保在主分支上
-git checkout main
-# 或者
-git checkout develop
+# 🔥 重要：在当前分支基础上创建新分支（不切换到主分支）
+# 查看当前分支状态
+git status
+git branch

-# 拉取最新代码
-git pull origin main
+# 直接在当前分支基础上创建并切换到新分支（包含检查范围标识）
+git checkout -b feature/code-standard-[模块名称]-[日期]

-# 创建并切换到新分支
-git checkout -b feature/code-standard-optimization-20240112
+# 示例：如果当前检查auth模块
+git checkout -b feature/code-standard-auth-20240112
+
+# 示例：如果当前检查zulip模块  
+git checkout -b feature/code-standard-zulip-20240112
+```
+
+### 🔍 提交前范围检查
+在执行任何git操作前，必须进行范围检查：
+
+```bash
+# 1. 查看当前变更的文件
+git status
+
+# 2. 检查变更文件是否都在检查范围内
+git diff --name-only
+
+# 3. 🚨 重要：如果发现范围外的文件，绝对不能暂存或提交！
+# 正确做法：只添加范围内的文件，忽略范围外的文件
+git add [范围内的具体文件路径]
+
+# 4. ❌ 错误做法：不要使用以下命令处理范围外文件
+# git stash push [范围外文件]  # 禁止！会影响其他AI
+# git reset HEAD [范围外文件]  # 禁止！会影响其他AI
+# git add -i  # 谨慎使用，容易误选范围外文件
+```
+
+### 📂 检查范围示例
+
+#### 正确的范围控制
+```bash
+# 如果检查任务是 "auth 模块代码规范优化"
+# ✅ 应该包含的文件：
+src/business/auth/
+src/core/auth/
+test/business/auth/
+test/core/auth/
+docs/auth/
+
+# ❌ 不应该包含的文件：
+src/business/zulip/          # 其他模块
+src/business/user-mgmt/      # 其他模块
+client/                      # 前端代码
+config/                      # 配置文件（除非明确要求）
+```
+
+#### 范围检查命令
+```bash
+# 检查当前变更是否超出范围
+git diff --name-only | grep -v "^src/business/auth/" | grep -v "^test/.*auth" | grep -v "^docs/.*auth"
+
+# 如果上述命令有输出，说明存在范围外的文件，需要排除
 ```

 ## 📝 提交信息规范
@@ -125,8 +238,9 @@ git checkout -b feature/code-standard-optimization-20240112

 ### 提交信息格式
 ```bash
-<类型>：<简短描述>
+<类型>(<范围>)：<简短描述>

+范围：<具体的文件/文件夹范围>
 [可选的详细描述]

 [可选的关联信息]
@@ -134,34 +248,38 @@ git checkout -b feature/code-standard-optimization-20240112

 ### 提交信息示例

-#### 单一类型修改
+#### 单一类型修改（明确范围）
 ```bash
 # 代码规范优化
-git commit -m "style：统一命名规范和注释格式
+git commit -m "style(auth)：统一命名规范和注释格式

+范围：src/business/auth/, src/core/auth/
 - 调整文件和变量命名符合项目规范
 - 优化注释格式和内容完整性
 - 清理代码格式和缩进问题"

 # Bug修复
-git commit -m "fix：修复用户注册时的邮箱验证问题
+git commit -m "fix(zulip)：修复消息处理时的并发问题

- 修复邮箱格式验证逻辑错误
- 添加重复邮箱检查机制
+范围：src/business/zulip/services/
+- 修复消息队列处理逻辑错误
+- 添加并发控制机制
 - 优化错误提示信息"

 # 功能新增
-git commit -m "feat：实现用户权限管理系统
+git commit -m "feat(auth)：实现多因素认证系统

- 添加角色和权限定义
- 实现权限验证中间件
- 支持动态权限分配"
+范围：src/business/auth/, src/core/auth/
+- 添加TOTP验证支持
+- 实现短信验证功能
+- 支持备用验证码"
 ```

-#### 多文件相关修改
+#### 多文件相关修改（明确范围）
 ```bash
-git commit -m "refactor：重构用户管理模块架构
+git commit -m "refactor(user-mgmt)：重构用户管理模块架构

+范围：src/business/user-mgmt/, src/core/db/users/
 涉及文件：
 - src/business/user-mgmt/user.service.ts
 - src/business/user-mgmt/user.controller.ts  
@@ -175,61 +293,118 @@ git commit -m "refactor：重构用户管理模块架构

 ## 🔄 提交执行流程

-### 1. 分阶段提交（推荐）
+### 🔥 范围控制原则
+**🚨 在执行任何提交操作前，必须确保所有变更文件都在当前检查任务的范围内！**
+**🚨 绝对禁止暂存、重置或以任何方式处理范围外的代码！**
+
+### 1. 范围检查与文件筛选
+```bash
+# 第一步：查看所有变更文件
+git status
+git diff --name-only
+
+# 第二步：识别范围内和范围外的文件
+# 假设当前检查任务是 "auth 模块优化"
+# 范围内文件示例：
+# - src/business/auth/
+# - src/core/auth/  
+# - test/business/auth/
+# - test/core/auth/
+# - docs/auth/
+
+# 第三步：🚨 重要 - 只添加范围内的文件，绝对不处理范围外文件
+git add src/business/auth/
+git add src/core/auth/
+git add test/business/auth/
+git add test/core/auth/
+git add docs/auth/
+
+# ❌ 禁止使用交互式添加（容易误选范围外文件）
+# git add -i  # 不推荐，风险太高
+```
+
+### 2. 分阶段提交（推荐）
 将不同类型的修改分别提交，保持提交历史清晰：

 ```bash
-# 第一步：提交代码规范优化
-git add src/business/auth/
-git commit -m "style：优化auth模块代码规范
+# 第一步：提交代码规范优化（仅限检查范围内）
+git add src/business/auth/ src/core/auth/
+git commit -m "style(auth)：优化auth模块代码规范

+范围：src/business/auth/, src/core/auth/
 - 统一命名规范和注释格式
 - 清理未使用的导入
 - 调整代码结构和缩进"

-# 第二步：提交功能改进（如果有）
-git add src/business/user-mgmt/
-git commit -m "feat：添加用户状态管理功能
+# 第二步：提交功能改进（如果有，仅限范围内）
+git add src/business/auth/enhanced-features/
+git commit -m "feat(auth)：添加用户状态管理功能

+范围：src/business/auth/
 - 实现用户激活/禁用功能
 - 添加状态变更日志记录
 - 支持批量状态操作"

-# 第三步：提交测试相关（如果有）
-git add test/
-git commit -m "test：完善用户管理模块测试覆盖
+# 第三步：提交测试相关（仅限范围内）
+git add test/business/auth/ test/core/auth/
+git commit -m "test(auth)：完善auth模块测试覆盖

+范围：test/business/auth/, test/core/auth/
 - 添加缺失的单元测试
 - 补充集成测试用例
 - 提升测试覆盖率到95%以上"

-# 第四步：提交文档更新（如果有）
-git add docs/ src/**/README.md
-git commit -m "docs：更新用户管理模块文档
+# 第四步：提交文档更新（仅限范围内）
+git add docs/auth/ src/business/auth/README.md src/core/auth/README.md
+git commit -m "docs(auth)：更新auth模块文档

+范围：docs/auth/, auth模块README文件
 - 完善API接口文档
 - 更新功能模块README
 - 添加使用示例和注意事项"
 ```

-### 2. 使用交互式暂存（精确控制）
+### 3. 使用交互式暂存（精确控制）
 ```bash
-# 交互式选择要提交的代码块
+# 交互式选择要提交的代码块（仅限范围内文件）
 git add -p src/business/auth/login.service.ts

 # 选择代码规范相关的修改
 # 提交第一部分
-git commit -m "style：优化login.service代码规范"
+git commit -m "style(auth)：优化login.service代码规范"

 # 暂存剩余的功能修改
 git add src/business/auth/login.service.ts
-git commit -m "feat：添加多因素认证支持"
+git commit -m "feat(auth)：添加多因素认证支持"
 ```

-### 3. 提交前最终检查
+### 4. 范围外文件处理
+🚨 **重要：绝对不能处理范围外的文件！**
+
 ```bash
-# 检查暂存区内容
-git diff --cached
+# ✅ 正确做法：查看范围外的文件，但不做任何处理
+git status | findstr /v "auth"  # 假设检查范围是auth模块，查看非auth文件
+
+# ✅ 正确做法：只添加范围内的文件
+git add src/business/auth/
+git add src/core/auth/
+git add test/business/auth/
+
+# ❌ 错误做法：不要重置、暂存或移动范围外文件
+# git checkout -- src/business/zulip/some-file.ts  # 禁止！
+# git stash push src/business/zulip/  # 禁止！会影响其他AI
+# git reset HEAD src/business/user-mgmt/  # 禁止！会影响其他AI
+
+# 🔥 协作原则：范围外文件必须保持原状，供其他AI处理
+```
+
+### 5. 提交前最终检查
+```bash
+# 检查暂存区内容（确保只有范围内文件）
+git diff --cached --name-only
+
+# 确认所有文件都在检查范围内
+git diff --cached --name-only | grep -E "^(src|test|docs)/(business|core)/auth/"

 # 确认提交信息准确性
 git commit --dry-run
@@ -240,8 +415,30 @@ git commit -m "提交信息"

 ## 📄 合并文档生成

+### 🔥 重要规范：独立合并文档生成
+**在完成代码提交后，必须在docs目录中生成一个独立的合并md文档，方便最后统一完成合并操作。**
+
+#### 合并文档命名规范
+```
+docs/merge-requests/[模块名称]-code-standard-[日期].md
+```
+
+#### 合并文档存放位置
+- **目录路径**：`docs/merge-requests/`
+- **文件命名**：`[模块名称]-code-standard-[日期].md`
+- **示例文件名**：
+  - `auth-code-standard-20240112.md`
+  - `zulip-code-standard-20240112.md`
+  - `user-mgmt-code-standard-20240112.md`
+
+#### 创建合并文档目录
+如果`docs/merge-requests/`目录不存在，需要先创建：
+```bash
+mkdir -p docs/merge-requests
+```
+
 ### 合并请求文档模板
-完成所有提交后，生成合并文档：
+完成所有提交后，在`docs/merge-requests/`目录中生成独立的合并文档：

 ```markdown
 # 代码规范优化合并请求
@@ -308,12 +505,89 @@ git commit -m "提交信息"
 - **监控要点**：关注 [具体的监控指标]
 ```

+### 📝 独立合并文档创建示例
+
+#### 1. 创建合并文档目录（如果不存在）
+```bash
+mkdir -p docs/merge-requests
+```
+
+#### 2. 生成具体的合并文档
+假设当前检查的是auth模块，日期是2024-01-12，则创建文件：
+`docs/merge-requests/auth-code-standard-20240112.md`
+
+#### 3. 合并文档内容示例
+```markdown
+# Auth模块代码规范优化合并请求
+
+## 📋 变更概述
+本次合并请求包含对Auth模块的代码规范优化和质量提升，涉及登录、注册、权限验证等核心功能。
+
+## 🔍 主要变更内容
+
+### 代码规范优化
+- **命名规范**：统一service、controller、entity文件命名
+- **注释规范**：完善JSDoc注释，添加参数和返回值说明
+- **代码清理**：移除未使用的导入和死代码
+- **格式统一**：统一TypeScript代码缩进和换行
+
+### 功能改进
+- **错误处理**：完善异常捕获和错误提示
+- **类型安全**：添加缺失的TypeScript类型定义
+- **性能优化**：优化数据库查询和缓存策略
+
+### 测试完善
+- **测试覆盖**：补充登录服务和注册控制器的单元测试
+- **集成测试**：添加JWT认证流程的集成测试
+- **E2E测试**：完善用户注册登录的端到端测试
+
+## 📊 影响范围
+- **修改文件数量**：15个文件
+- **涉及模块**：src/business/auth/, src/core/auth/, test/business/auth/
+- **新增代码行数**：+245行
+- **删除代码行数**：-89行
+- **测试覆盖率**：从78%提升到95%
+
+## 🧪 测试验证
+- [x] 所有单元测试通过 (npm run test:auth:unit)
+- [x] 集成测试通过 (npm run test:auth:integration)
+- [x] E2E测试通过 (npm run test:auth:e2e)
+- [x] 手动功能验证通过
+
+## 🔗 相关信息
+- **分支名称**：feature/code-standard-auth-20240112
+- **远程仓库**：origin
+- **检查日期**：2024-01-12
+- **检查人员**：[用户名称]
+
+## 📝 合并后操作
+1. 验证生产环境功能正常
+2. 监控登录注册成功率
+3. 关注系统性能指标
+4. 更新相关文档链接
+
+---
+**文档生成时间**：2024-01-12
+**对应分支**：feature/code-standard-auth-20240112
+**合并状态**：待合并
+```
+
+#### 4. 在PR中引用合并文档
+创建Pull Request时，在描述中添加：
+```markdown
+## 📄 详细合并文档
+请查看独立合并文档：`docs/merge-requests/auth-code-standard-20240112.md`
+
+该文档包含完整的变更说明、测试验证结果和合并后操作指南。
+```
+
 ## 🔧 执行步骤总结

 ### 完整执行流程
 1. **Git变更检查**
   - 执行 `git status` 和 `git diff` 查看变更
-   - 确认所有修改文件都在预期范围内
+   - 确认所有修改文件都在当前检查任务的范围内
+   - 排除或暂存范围外的文件

 2. **修改记录校验**
   - 逐个检查修改文件的头部注释
@@ -321,29 +595,99 @@ git commit -m "提交信息"
   - 如有不一致，立即修正

 3. **创建功能分支**
-   - 根据修改类型创建合适的分支
-   - 使用规范的分支命名格式
+   - 🔥 **在当前分支基础上**创建新分支（不切换到主分支）
+   - 根据修改类型和检查范围创建合适的分支
+   - 使用规范的分支命名格式（包含模块标识）

 4. **分类提交代码**
   - 按修改类型分别提交（style、feat、fix、docs等）
-   - 使用规范的提交信息格式
+   - 使用规范的提交信息格式（包含范围标识）
   - 每次提交保持原子性（一次提交只做一件事）
+   - 确保每次提交只包含检查范围内的文件

-5. **生成合并文档**
-   - 创建详细的合并请求文档
-   - 说明变更内容、影响范围、测试情况
-   - 提供审查要点和部署说明
+5. **推送到指定远程仓库**
+   - 询问用户要推送到哪个远程仓库
+   - 使用 `git push [远程仓库名] [分支名]` 推送到指定远程仓库
+   - 验证推送结果和分支状态

-6. **推送和创建PR**
-   - 推送分支到远程仓库
-   - 创建Pull Request并关联合并文档
+6. **生成独立合并文档**
+   - 在 `docs/merge-requests/` 目录中创建独立的合并md文档
+   - 使用规范的文件命名：`[模块名称]-code-standard-[日期].md`
+   - 包含完整的变更概述、影响范围、测试验证等信息
+   - 方便后续统一进行合并操作管理
+
+7. **创建PR和关联文档**
+   - 在指定的远程仓库创建Pull Request
+   - 在PR描述中引用独立合并文档的路径
+   - 明确标注检查范围和变更内容
+
+## 🚀 推送到远程仓库
+
+### 📋 执行前询问
+**在推送前，AI必须询问用户以下信息：**
+1. **目标远程仓库名称**：要推送到哪个远程仓库？（如：origin、whale-town-end、upstream等）
+2. **确认分支名称**：确认要推送的分支名称是否正确
+
+### 推送新分支到指定远程仓库
+完成所有提交后，将分支推送到用户指定的远程仓库：
+
+```bash
+# 推送新分支到指定远程仓库（[远程仓库名]由用户提供）
+git push [远程仓库名] feature/code-standard-[模块名称]-[日期]
+
+# 示例：推送到origin远程仓库
+git push origin feature/code-standard-auth-20240112
+
+# 示例：推送到whale-town-end远程仓库
+git push whale-town-end feature/code-standard-auth-20240112
+
+# 示例：推送到upstream远程仓库
+git push upstream feature/code-standard-zulip-20240112
+
+# 如果是首次推送该分支，设置上游跟踪
+git push -u [远程仓库名] feature/code-standard-auth-20240112
+```
+
+### 验证推送结果
+```bash
+# 查看远程分支状态
+git branch -r
+
+# 确认分支已成功推送到指定远程仓库
+git ls-remote [远程仓库名] | grep feature/code-standard-[模块名称]-[日期]
+
+# 查看指定远程仓库的所有分支
+git ls-remote [远程仓库名]
+```
+
+### 远程仓库配置检查
+如果推送时遇到问题，可以检查远程仓库配置：
+
+```bash
+# 查看当前配置的所有远程仓库
+git remote -v
+
+# 如果没有指定的远程仓库，需要添加
+git remote add [远程仓库名] [仓库URL]
+
+# 验证指定远程仓库连接
+git remote show [远程仓库名]
+```
+
+### 🔍 常见远程仓库名称
+- **origin**：通常是默认的远程仓库
+- **upstream**：通常指向原始项目仓库
+- **whale-town-end**：项目特定的远程仓库名
+- **fork**：个人fork的仓库
+- **dev**：开发环境仓库

 ## ⚠️ 重要注意事项

 ### 提交原则
+- **范围限制**：只提交当前检查任务范围内的文件，不涉及其他模块
 - **原子性**：每次提交只包含一个逻辑改动
 - **完整性**：每次提交的代码都应该能正常运行
- **描述性**：提交信息要清晰描述改动内容和原因
+- **描述性**：提交信息要清晰描述改动内容、范围和原因
 - **一致性**：文件修改记录必须与实际修改内容一致

 ### 质量保证
@@ -354,6 +698,7 @@ git commit -m "提交信息"

 ### 协作规范
 - 遵循项目的分支管理策略
+- 推送前询问并确认目标远程仓库
 - 提供清晰的合并请求说明
 - 及时响应代码审查意见
 - 保持提交历史的清晰和可追溯性
@@ -365,4 +710,33 @@ git commit -m "提交信息"
 - ✅ 执行修改 → 🔥 立即重新执行步骤7 → 提供验证报告 → 等待用户确认
 - ❌ 执行修改 → 直接结束检查（错误做法）

-**不能跳过重新检查环节！**
+**🚨 重要强调：纯检查步骤不更新修改记录**
+**如果检查发现代码提交已经符合规范，无需任何修改，则：**
+- ❌ **禁止添加检查记录**：不要添加"AI代码检查步骤7：代码提交检查和优化"
+- ❌ **禁止更新时间戳**：不要修改@lastModified字段
+- ❌ **禁止递增版本号**：不要修改@version字段
+- ✅ **仅提供检查报告**：说明检查结果，确认符合规范
+
+**不能跳过重新检查环节！**
+
+### 🔥 合并文档生成强制要求
+**每次完成代码提交后，必须在docs/merge-requests/目录中生成独立的合并md文档！**
+
+- ✅ 完成提交 → 生成独立合并文档 → 在PR中引用文档路径
+- ❌ 完成提交 → 直接创建PR（缺少独立文档）
+
+**独立合并文档是统一管理合并操作的重要依据，不能省略！**
+
+## 📋 执行前必须询问的信息
+
+**在执行推送操作前，AI必须询问用户：**
+
+1. **目标远程仓库名称**
+   - 问题：请问要推送到哪个远程仓库？
+   - 示例回答：origin / whale-town-end / upstream / 其他
+
+2. **确认分支名称**
+   - 问题：确认要推送的分支名称是：feature/code-standard-[模块名称]-[日期] 吗？
+   - 等待用户确认或提供正确的分支名称
+
+**只有获得用户明确回答后，才能执行推送操作！**