forked from datawhale/whale-town-end
docs：添加AI代码检查执行指南文档
- 添加完整的7步代码检查流程指导 - 包含命名规范、注释标准、代码质量等检查标准 - 提供游戏服务器特殊要求和最佳实践 - 支持NestJS双模式架构和WebSocket实时通信检查 涉及文件： - docs/ai-reading/README.md - 总体执行指南 - docs/ai-reading/step1-naming-convention.md - 命名规范检查 - docs/ai-reading/step2-comment-standard.md - 注释规范检查 - docs/ai-reading/step3-code-quality.md - 代码质量检查 - docs/ai-reading/step4-architecture-layer.md - 架构分层检查 - docs/ai-reading/step5-test-coverage.md - 测试覆盖检查 - docs/ai-reading/step6-documentation.md - 功能文档生成 - docs/ai-reading/step7-code-commit.md - 代码提交规范
This commit is contained in:
moyin
368
docs/ai-reading/step7-code-commit.md
Normal file
368
docs/ai-reading/step7-code-commit.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# 步骤7：代码提交
|
||||
|
||||
## 🎯 检查目标
|
||||
完成代码修改后的规范化提交流程，确保代码变更记录清晰、分支管理规范、提交信息符合项目标准。
|
||||
|
||||
## 📋 执行前置条件
|
||||
- 已完成前6个步骤的代码检查和修改
|
||||
- 所有修改的文件已更新修改记录和版本信息
|
||||
- 代码能够正常运行且通过测试
|
||||
|
||||
## 🔍 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: 代码规范优化 - 清理未使用导入和优化注释 (修改者: 张三)
|
||||
*/
|
||||
```
|
||||
|
||||
## 🌿 分支管理规范
|
||||
|
||||
### 分支命名规范
|
||||
根据修改类型创建对应的分支：
|
||||
|
||||
```bash
|
||||
# 代码规范优化分支
|
||||
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
|
||||
```
|
||||
|
||||
### 创建和切换分支
|
||||
```bash
|
||||
# 确保在主分支上
|
||||
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缓存配置` |
|
||||
|
||||
### 提交信息格式
|
||||
```bash
|
||||
<类型>：<简短描述>
|
||||
|
||||
[可选的详细描述]
|
||||
|
||||
[可选的关联信息]
|
||||
```
|
||||
|
||||
### 提交信息示例
|
||||
|
||||
#### 单一类型修改
|
||||
```bash
|
||||
# 代码规范优化
|
||||
git commit -m "style：统一命名规范和注释格式
|
||||
|
||||
- 调整文件和变量命名符合项目规范
|
||||
- 优化注释格式和内容完整性
|
||||
- 清理代码格式和缩进问题"
|
||||
|
||||
# Bug修复
|
||||
git commit -m "fix：修复用户注册时的邮箱验证问题
|
||||
|
||||
- 修复邮箱格式验证逻辑错误
|
||||
- 添加重复邮箱检查机制
|
||||
- 优化错误提示信息"
|
||||
|
||||
# 功能新增
|
||||
git commit -m "feat：实现用户权限管理系统
|
||||
|
||||
- 添加角色和权限定义
|
||||
- 实现权限验证中间件
|
||||
- 支持动态权限分配"
|
||||
```
|
||||
|
||||
#### 多文件相关修改
|
||||
```bash
|
||||
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. 分阶段提交（推荐）
|
||||
将不同类型的修改分别提交，保持提交历史清晰：
|
||||
|
||||
```bash
|
||||
# 第一步：提交代码规范优化
|
||||
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. 使用交互式暂存（精确控制）
|
||||
```bash
|
||||
# 交互式选择要提交的代码块
|
||||
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. 提交前最终检查
|
||||
```bash
|
||||
# 检查暂存区内容
|
||||
git diff --cached
|
||||
|
||||
# 确认提交信息准确性
|
||||
git commit --dry-run
|
||||
|
||||
# 执行提交
|
||||
git commit -m "提交信息"
|
||||
```
|
||||
|
||||
## 📄 合并文档生成
|
||||
|
||||
### 合并请求文档模板
|
||||
完成所有提交后，生成合并文档：
|
||||
|
||||
```markdown
|
||||
# 代码规范优化合并请求
|
||||
|
||||
## 📋 变更概述
|
||||
本次合并请求包含对 [具体模块/功能] 的代码规范优化和质量提升。
|
||||
|
||||
## 🔍 主要变更内容
|
||||
|
||||
### 代码规范优化
|
||||
- **命名规范**：调整文件、类、方法命名符合项目规范
|
||||
- **注释规范**：完善注释内容，统一注释格式
|
||||
- **代码清理**：移除未使用的导入、变量和死代码
|
||||
- **格式统一**：统一代码缩进、换行和空格使用
|
||||
|
||||
### 功能改进（如适用）
|
||||
- **新增功能**：[具体描述新增的功能]
|
||||
- **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 → 提供验证报告 → 等待用户确认
|
||||
- ❌ 执行修改 → 直接结束检查（错误做法）
|
||||
|
||||
**不能跳过重新检查环节！**
|
||||
Reference in New Issue
Block a user