whale-town-end/docs/ai-reading/step7-code-commit.md

步骤7：代码提交

🎯 检查目标

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

📋 执行前置条件

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

🔍 Git变更检查与校验

1. 检查Git状态和变更内容

# 查看当前工作区状态
git status

# 查看具体变更内容
git diff

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

2. 文件修改记录校验

重要：检查每个修改文件的头部信息是否与实际修改内容一致

校验内容包括：

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

校验方法：

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

3. 修改记录不一致的处理

如果发现文件头部的修改记录与实际修改内容不符：

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

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

🌿 分支管理规范

分支命名规范

根据修改类型创建对应的分支：

# 代码规范优化分支
feature/code-standard-optimization-[日期]
# 示例：feature/code-standard-optimization-20240112

# Bug修复分支  
fix/[具体问题描述]
# 示例：fix/room-concurrency-issue

# 功能新增分支
feature/[功能名称]
# 示例：feature/user-authentication

# 重构分支
refactor/[模块名称]
# 示例：refactor/room-management

# 性能优化分支
perf/[优化内容]
# 示例：perf/database-query-optimization

# 文档更新分支
docs/[文档类型]
# 示例：docs/api-documentation

创建和切换分支

# 确保在主分支上
git checkout main
# 或者
git checkout develop

# 拉取最新代码
git pull origin main

# 创建并切换到新分支
git checkout -b feature/code-standard-optimization-20240112

📝 提交信息规范

提交类型映射

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

修改内容	提交类型	示例
命名规范调整、注释优化、代码清理	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缓存配置

提交信息格式

<类型>：<简短描述>

[可选的详细描述]

[可选的关联信息]

提交信息示例

单一类型修改

# 代码规范优化
git commit -m "style：统一命名规范和注释格式

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

# Bug修复
git commit -m "fix：修复用户注册时的邮箱验证问题

- 修复邮箱格式验证逻辑错误
- 添加重复邮箱检查机制
- 优化错误提示信息"

# 功能新增
git commit -m "feat：实现用户权限管理系统

- 添加角色和权限定义
- 实现权限验证中间件
- 支持动态权限分配"

多文件相关修改

git commit -m "refactor：重构用户管理模块架构

涉及文件：
- src/business/user-mgmt/user.service.ts
- src/business/user-mgmt/user.controller.ts  
- src/core/db/users/users.repository.ts

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

🔄 提交执行流程

1. 分阶段提交（推荐）

将不同类型的修改分别提交，保持提交历史清晰：

# 第一步：提交代码规范优化
git add src/business/auth/
git commit -m "style：优化auth模块代码规范

- 统一命名规范和注释格式
- 清理未使用的导入
- 调整代码结构和缩进"

# 第二步：提交功能改进（如果有）
git add src/business/user-mgmt/
git commit -m "feat：添加用户状态管理功能

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

# 第三步：提交测试相关（如果有）
git add test/
git commit -m "test：完善用户管理模块测试覆盖

- 添加缺失的单元测试
- 补充集成测试用例
- 提升测试覆盖率到95%以上"

# 第四步：提交文档更新（如果有）
git add docs/ src/**/README.md
git commit -m "docs：更新用户管理模块文档

- 完善API接口文档
- 更新功能模块README
- 添加使用示例和注意事项"

2. 使用交互式暂存（精确控制）

# 交互式选择要提交的代码块
git add -p src/business/auth/login.service.ts

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

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

3. 提交前最终检查

# 检查暂存区内容
git diff --cached

# 确认提交信息准确性
git commit --dry-run

# 执行提交
git commit -m "提交信息"

📄 合并文档生成

合并请求文档模板

完成所有提交后，生成合并文档：

# 代码规范优化合并请求

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

## 🔍 主要变更内容

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

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

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

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

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

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

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

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

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

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

🔧 执行步骤总结

完整执行流程

1. Git变更检查

   • 执行 git status 和 git diff 查看变更
   • 确认所有修改文件都在预期范围内

2. 修改记录校验

   • 逐个检查修改文件的头部注释
   • 确认修改记录与实际变更内容一致
   • 如有不一致，立即修正

3. 创建功能分支

   • 根据修改类型创建合适的分支
   • 使用规范的分支命名格式

4. 分类提交代码

   • 按修改类型分别提交（style、feat、fix、docs等）
   • 使用规范的提交信息格式
   • 每次提交保持原子性（一次提交只做一件事）

5. 生成合并文档

   • 创建详细的合并请求文档
   • 说明变更内容、影响范围、测试情况
   • 提供审查要点和部署说明

6. 推送和创建PR

   • 推送分支到远程仓库
   • 创建Pull Request并关联合并文档

⚠️ 重要注意事项

提交原则

• 原子性：每次提交只包含一个逻辑改动
• 完整性：每次提交的代码都应该能正常运行
• 描述性：提交信息要清晰描述改动内容和原因
• 一致性：文件修改记录必须与实际修改内容一致

质量保证

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

协作规范

• 遵循项目的分支管理策略
• 提供清晰的合并请求说明
• 及时响应代码审查意见
• 保持提交历史的清晰和可追溯性

🔥 重要提醒

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

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

不能跳过重新检查环节！