# 步骤7：代码提交

## ⚠️ 执行前必读规范

**🔥 重要：在执行本步骤之前，AI必须先完整阅读同级目录下的 `README.md` 文件！**

该README文件包含：
- 🎯 执行前准备和用户信息收集要求
- 🔄 强制执行原则和分步执行流程  
- 🔥 修改后立即重新执行当前步骤的强制规则
- 📝 文件修改记录规范和版本号递增规则
- 🧪 测试文件调试规范和测试指令使用规范
- 🚨 全局约束和游戏服务器特殊要求

**不阅读README直接执行步骤将导致执行不规范，违反项目要求！**

---

## 🎯 检查目标
完成代码修改后的规范化提交流程，确保代码变更记录清晰、分支管理规范、提交信息符合项目标准。

## 📋 执行前置条件
- 已完成前6个步骤的代码检查和修改
- 所有修改的文件已更新修改记录和版本信息
- 代码能够正常运行且通过测试

## 🚨 协作规范和范围控制

### 绝对禁止的操作
**以下操作严格禁止，违反将影响其他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状态和变更内容
```bash
# 查看当前工作区状态
git status

# 查看具体变更内容
git diff

# 查看已暂存的变更
git diff --cached
```

### 2. 文件修改记录校验
**重要**：检查每个修改文件的头部信息是否与实际修改内容一致

#### 校验内容包括：
- **修改记录**：最新的修改记录是否准确描述了本次变更
- **修改类型**：记录的修改类型（代码规范优化、功能新增等）是否与实际修改匹配
- **修改者信息**：是否使用了正确的用户名称
- **修改日期**：是否使用了用户提供的真实日期
- **版本号**：是否按照规则正确递增
- **@lastModified**：是否更新为当前修改日期

#### 校验方法：
1. 逐个检查修改文件的头部注释
2. 对比git diff显示的实际修改内容
3. 确认修改记录描述与实际变更一致
4. 如发现不一致，立即修正文件头部信息

### 3. 修改记录不一致的处理
如果发现文件头部的修改记录与实际修改内容不符：

```typescript
// ❌ 错误示例：记录说是"功能新增"，但实际只是代码清理
/**
 * 最近修改：
 * - 2024-01-12: 功能新增 - 添加新的用户验证功能 (修改者: 张三)
 */
// 实际修改：只是删除了未使用的导入和注释优化

// ✅ 正确修正：
/**
 * 最近修改：
 * - 2024-01-12: 代码规范优化 - 清理未使用导入和优化注释 (修改者: 张三)
 */
```

## 🌿 分支管理规范

### 🔥 重要原则：严格范围限制
**🚨 绝对禁止：不得暂存、提交或以任何方式处理检查范围外的代码！**

- ✅ **正确做法**：只提交当前检查任务涉及的文件和文件夹
- ❌ **严格禁止**：提交其他模块、其他开发者负责的文件
- ❌ **严格禁止**：使用git stash暂存其他范围的代码
- ❌ **严格禁止**：以任何方式移动、隐藏或处理范围外的代码
- ⚠️ **检查要求**：提交前必须确认所有变更文件都在当前检查范围内
- 🔥 **协作原则**：其他范围的代码必须保持原状，供其他AI处理

### 分支命名规范
根据修改类型和检查范围创建对应的分支：

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

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

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

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

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

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

### 创建和切换分支
```bash
# 🔥 重要：在当前分支基础上创建新分支（不切换到主分支）
# 查看当前分支状态
git status
git branch

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

# 示例：如果当前检查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"

# 如果上述命令有输出，说明存在范围外的文件，需要排除
```

## 📝 提交信息规范

### 提交类型映射
根据实际修改内容选择正确的提交类型：

| 修改内容 | 提交类型 | 示例 |
|---------|---------|------|
| 命名规范调整、注释优化、代码清理 | `style` | `style：统一TypeScript代码风格和注释规范` |
| 清理未使用代码、优化导入 | `refactor` | `refactor：清理未使用的导入和死代码` |
| 添加新功能、新方法 | `feat` | `feat：添加用户身份验证功能` |
| 修复Bug、错误处理 | `fix` | `fix：修复用户登录时的并发问题` |
| 性能改进、算法优化 | `perf` | `perf：优化数据库查询性能` |
| 代码结构调整、重构 | `refactor` | `refactor：重构用户管理服务架构` |
| 添加或修改测试 | `test` | `test：添加用户服务单元测试` |
| 更新文档、README | `docs` | `docs：更新API接口文档` |
| API接口相关 | `api` | `api：添加用户信息查询接口` |
| 数据库相关 | `db` | `db：创建用户表结构` |
| WebSocket相关 | `websocket` | `websocket：实现实时消息推送` |
| 认证授权相关 | `auth` | `auth：实现JWT身份验证机制` |
| 配置文件相关 | `config` | `config：添加Redis缓存配置` |

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

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

[可选的关联信息]
```

### 提交信息示例

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

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

# Bug修复
git commit -m "fix(zulip)：修复消息处理时的并发问题

范围：src/business/zulip/services/
- 修复消息队列处理逻辑错误
- 添加并发控制机制
- 优化错误提示信息"

# 功能新增
git commit -m "feat(auth)：实现多因素认证系统

范围：src/business/auth/, src/core/auth/
- 添加TOTP验证支持
- 实现短信验证功能
- 支持备用验证码"
```

#### 多文件相关修改（明确范围）
```bash
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  
- src/core/db/users/users.repository.ts

主要改进：
- 分离业务逻辑和数据访问层
- 优化服务接口设计
- 提升代码可维护性"
```

## 🔄 提交执行流程

### 🔥 范围控制原则
**🚨 在执行任何提交操作前，必须确保所有变更文件都在当前检查任务的范围内！**
**🚨 绝对禁止暂存、重置或以任何方式处理范围外的代码！**

### 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/ src/core/auth/
git commit -m "style(auth)：优化auth模块代码规范

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

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

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

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

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

# 第四步：提交文档更新（仅限范围内）
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
- 添加使用示例和注意事项"
```

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

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

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

### 4. 范围外文件处理
🚨 **重要：绝对不能处理范围外的文件！**

```bash
# ✅ 正确做法：查看范围外的文件，但不做任何处理
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

# 执行提交
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
# 代码规范优化合并请求

## 📋 变更概述
本次合并请求包含对 [具体模块/功能] 的代码规范优化和质量提升。

## 🔍 主要变更内容

### 代码规范优化
- **命名规范**：调整文件、类、方法命名符合项目规范
- **注释规范**：完善注释内容，统一注释格式
- **代码清理**：移除未使用的导入、变量和死代码
- **格式统一**：统一代码缩进、换行和空格使用

### 功能改进（如适用）
- **新增功能**：[具体描述新增的功能]
- **Bug修复**：[具体描述修复的问题]
- **性能优化**：[具体描述优化的内容]

### 测试完善（如适用）
- **测试覆盖**：补充缺失的单元测试和集成测试
- **测试质量**：提升测试用例的完整性和准确性

### 文档更新（如适用）
- **API文档**：更新接口文档和使用说明
- **README文档**：完善功能模块说明和使用指南

## 📊 影响范围
- **修改文件数量**：[数量] 个文件
- **新增代码行数**：+[数量] 行
- **删除代码行数**：-[数量] 行
- **测试覆盖率**：从 [原覆盖率]% 提升到 [新覆盖率]%

## 🧪 测试验证
- [ ] 所有单元测试通过
- [ ] 集成测试通过  
- [ ] E2E测试通过
- [ ] 性能测试通过（如适用）
- [ ] 手动功能验证通过

## 🔗 相关链接
- 相关Issue：#[Issue编号]
- 设计文档：[链接]
- API文档：[链接]

## 📝 审查要点
请重点关注以下方面：
1. **代码规范**：命名、注释、格式是否符合项目标准
2. **功能正确性**：新增或修改的功能是否按预期工作
3. **测试完整性**：测试用例是否充分覆盖变更内容
4. **文档准确性**：文档是否与代码实现保持一致
5. **性能影响**：变更是否对系统性能产生负面影响

## ⚠️ 注意事项
- 本次变更主要为代码质量提升，不涉及业务逻辑重大变更
- 所有修改都经过充分测试验证
- 建议在非高峰期进行合并部署

## 🚀 部署说明
- **部署环境**：[测试环境/生产环境]
- **部署时间**：[建议的部署时间]
- **回滚方案**：如有问题可快速回滚到上一版本
- **监控要点**：关注 [具体的监控指标]
```

### 📝 独立合并文档创建示例

#### 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. **修改记录校验**
   - 逐个检查修改文件的头部注释
   - 确认修改记录与实际变更内容一致
   - 如有不一致，立即修正

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

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

5. **推送到指定远程仓库**
   - 询问用户要推送到哪个远程仓库
   - 使用 `git push [远程仓库名] [分支名]` 推送到指定远程仓库
   - 验证推送结果和分支状态

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**：开发环境仓库

## ⚠️ 重要注意事项

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

### 质量保证
- 提交前必须验证代码能正常运行
- 确保所有测试通过
- 检查代码格式和规范符合项目标准
- 验证文档与代码实现保持一致

### 协作规范
- 遵循项目的分支管理策略
- 推送前询问并确认目标远程仓库
- 提供清晰的合并请求说明
- 及时响应代码审查意见
- 保持提交历史的清晰和可追溯性

## 🔥 重要提醒

**如果在本步骤中执行了任何修改操作（修正文件头部信息、调整提交内容、更新文档等），必须立即重新执行步骤7的完整检查！**

- ✅ 执行修改 → 🔥 立即重新执行步骤7 → 提供验证报告 → 等待用户确认
- ❌ 执行修改 → 直接结束检查（错误做法）

**🚨 重要强调：纯检查步骤不更新修改记录**
**如果检查发现代码提交已经符合规范，无需任何修改，则：**
- ❌ **禁止添加检查记录**：不要添加"AI代码检查步骤7：代码提交检查和优化"
- ❌ **禁止更新时间戳**：不要修改@lastModified字段
- ❌ **禁止递增版本号**：不要修改@version字段
- ✅ **仅提供检查报告**：说明检查结果，确认符合规范

**不能跳过重新检查环节！**

### 🔥 合并文档生成强制要求
**每次完成代码提交后，必须在docs/merge-requests/目录中生成独立的合并md文档！**

- ✅ 完成提交 → 生成独立合并文档 → 在PR中引用文档路径
- ❌ 完成提交 → 直接创建PR（缺少独立文档）

**独立合并文档是统一管理合并操作的重要依据，不能省略！**

## 📋 执行前必须询问的信息

**在执行推送操作前，AI必须询问用户：**

1. **目标远程仓库名称**
   - 问题：请问要推送到哪个远程仓库？
   - 示例回答：origin / whale-town-end / upstream / 其他

2. **确认分支名称**
   - 问题：确认要推送的分支名称是：feature/code-standard-[模块名称]-[日期] 吗？
   - 等待用户确认或提供正确的分支名称

**只有获得用户明确回答后，才能执行推送操作！**