diff --git a/docs/04-开发规范/06-Git提交规范.md b/docs/04-开发规范/06-Git提交规范.md index a8d2d271..85087929 100644 --- a/docs/04-开发规范/06-Git提交规范.md +++ b/docs/04-开发规范/06-Git提交规范.md @@ -65,6 +65,34 @@ git remote -v ## Commit Message 规范 +### ⚠️ 重要提示:避免中文乱码 + +**强制要求:Commit Message 必须使用英文** ⭐⭐⭐ + +**原因**: +- Windows PowerShell 环境下,Git commit message 中的中文会出现乱码 +- 中文乱码会导致提交历史难以阅读,影响团队协作 +- 英文 commit message 是国际开源项目的标准实践 + +**✅ 正确示例:** +```bash +git commit -m "feat(asl): Implement full-text screening core service" +git commit -m "fix(frontend): Fix dropdown menu click issue" +git commit -m "docs: Add development guide for Day 2-3" +``` + +**❌ 错误示例:** +```bash +git commit -m "feat(asl): 实现全文复筛核心服务" # 会出现乱码 +git commit -m "修复下拉菜单问题" # 会出现乱码 +``` + +**例外情况**: +- 文件名和文件内容可以使用中文(Git 能正确处理 UTF-8 编码的文件) +- 仅 commit message 必须使用英文 + +--- + ### 📝 格式规范 **标准格式:** @@ -116,65 +144,66 @@ git remote -v ### Subject 主题 -**✅ 推荐:** +**✅ 推荐(英文):** ``` -feat(asl): 实现标题摘要初筛功能 -fix(frontend): 修复 AgentChatPage conversation 数据提取问题 -docs: 添加 Day 23-24 工作总结 -refactor(backend): 优化数据库连接池配置 +feat(asl): Implement title and abstract screening +fix(frontend): Fix AgentChatPage conversation data extraction issue +docs: Add Day 23-24 work summary +refactor(backend): Optimize database connection pool configuration ``` **❌ 避免:** ``` -更新代码 # 太笼统 +更新代码 # 中文(会乱码) fix bug # 没有说明具体问题 -修复了一些问题 # 信息不足 +修复了一些问题 # 中文(会乱码)+ 信息不足 feat: add feature # 没有指明模块和具体功能 +update code # 太笼统 ``` **规则:** -- ✅ 使用祈使句("添加" 而不是 "添加了") +- ⭐ **必须使用英文**(避免中文乱码) +- ✅ 使用祈使句("Add" 而不是 "Added") - ✅ 首字母小写 - ✅ 不要以句号结尾 - ✅ 简洁明了(≤50字符) -- ✅ 优先使用英文(避免中文乱码) ### Body 详细描述 **可选,用于说明:** -- 为什么做这个修改? -- 修改了什么? -- 有什么影响? +- Why: 为什么做这个修改? +- What: 修改了什么? +- Impact: 有什么影响? -**示例:** +**示例(必须使用英文):** ``` -feat(asl): 实现标题摘要初筛功能 +feat(asl): Implement title and abstract screening -完成以下功能: -- 添加 CSV 文件导入 -- 实现双模型 AI 判断(Qwen + DeepSeek) -- 添加 PICO 配置功能 -- 实现批量处理和进度显示 +Completed features: +- Add CSV file import +- Implement dual-model AI judgment (Qwen + DeepSeek) +- Add PICO configuration +- Implement batch processing and progress display -技术细节: -- 使用 Papa Parse 解析 CSV -- 集成 Dify API 进行 AI 判断 -- 使用 Ant Design Upload 组件 +Technical details: +- Use Papa Parse for CSV parsing +- Integrate Dify API for AI judgment +- Use Ant Design Upload component ``` ### Footer 脚注 **可选,用于:** - 关闭 Issue:`Closes #123` -- 不兼容变更:`BREAKING CHANGE: 说明` +- 不兼容变更:`BREAKING CHANGE: Description` - 关联 Issue:`Refs #456` -**示例:** +**示例(必须使用英文):** ``` -feat(backend): 重构 API 路由结构 +feat(backend): Refactor API routing structure -BREAKING CHANGE: API 路由从 /api/xxx 改为 /api/v1/xxx -所有前端调用需要更新路径 +BREAKING CHANGE: API routes changed from /api/xxx to /api/v1/xxx +All frontend API calls need to be updated Closes #123 Refs #456 @@ -182,35 +211,36 @@ Refs #456 ### 完整示例 -**示例 1:新功能** +**示例 1:新功能(必须使用英文)** ``` -feat(asl): 实现标题摘要初筛功能 +feat(asl): Implement title and abstract screening -- 添加 CSV 文件导入 -- 实现双模型 AI 判断 -- 添加 PICO 配置功能 +Features: +- Add CSV file import +- Implement dual-model AI judgment +- Add PICO configuration Closes #123 ``` -**示例 2:Bug 修复** +**示例 2:Bug 修复(必须使用英文)** ``` -fix(frontend): 修复 AgentChatPage conversation 数据提取问题 +fix(frontend): Fix AgentChatPage conversation data extraction issue -问题:conversation 数据未正确从响应中提取 -解决:修改数据解析逻辑,正确处理嵌套结构 +Problem: Conversation data not correctly extracted from response +Solution: Modify data parsing logic to handle nested structures Fixes #234 ``` -**示例 3:文档更新** +**示例 3:文档更新(必须使用英文)** ``` -docs: 添加 Day 23-24 工作总结 +docs: Add Day 23-24 work summary -完成内容: -- 知识库功能开发总结 -- 遇到的问题与解决方案 -- 下一步计划 +Contents: +- Knowledge base development summary +- Issues encountered and solutions +- Next steps ``` --- @@ -226,25 +256,26 @@ docs: 添加 Day 23-24 工作总结 **❌ 错误做法:** ```bash # 每改一个文件就提交一次 -git commit -m "fix: 修复文件A" -git commit -m "fix: 修复文件B" -git commit -m "fix: 修复文件C" -git commit -m "docs: 更新文档" +git commit -m "fix: Fix file A" +git commit -m "fix: Fix file B" +git commit -m "fix: Fix file C" +git commit -m "docs: Update docs" # 结果:产生大量碎片化提交,污染 Git 历史 ``` -**✅ 正确做法:** +**✅ 正确做法(必须使用英文):** ```bash # 一天工作结束后,统一提交 git add . -git commit -m "feat(asl): 完成标题摘要初筛功能 +git commit -m "feat(asl): Implement title and abstract screening -- 实现Excel解析逻辑 -- 添加LLM异步任务处理 -- 完善存储服务调用 -- 更新相关文档 +Features: +- Implement Excel parsing logic +- Add LLM async task processing +- Complete storage service integration +- Update related documentation -Tested: 本地验证通过" +Tested: Local verification passed" ``` **推荐提交频率:** @@ -348,55 +379,56 @@ AI: 收到!现在提交... ### ✅ 推荐的提交场景 -**场景 1:功能开发完成** +**场景 1:功能开发完成(必须使用英文)** ```bash -# 一天工作结束,完成了 ASL 模块的标题摘要初筛功能 +# Completed ASL module title and abstract screening at end of day git add backend/src/modules/asl/ git add docs/03-业务模块/ASL-AI智能文献/ -git commit -m "feat(asl): 完成标题摘要初筛功能 +git commit -m "feat(asl): Implement title and abstract screening -- 实现Excel解析和验证 -- 添加LLM异步任务处理 -- 集成平台基础设施(storage/logger/jobQueue) -- 完善API和数据库Schema -- 更新开发文档 +Features: +- Implement Excel parsing and validation +- Add LLM async task processing +- Integrate platform infrastructure (storage/logger/jobQueue) +- Complete API and database schema +- Update development documentation -Tested: 本地测试通过,功能验证完成" +Tested: Local tests passed, functionality verified" ``` -**场景 2:Bug 修复** +**场景 2:Bug 修复(必须使用英文)** ```bash -# 修复了健康检查路由冲突问题并验证通过 +# Fixed health check route conflict and verified git add backend/src/index.ts backend/src/common/health/ -git commit -m "fix(backend): 修复健康检查路由重复注册问题 +git commit -m "fix(backend): Fix duplicate health check route registration -问题:/health 路由在多处注册导致冲突 -解决:统一在 registerHealthRoutes 中注册 +Problem: /health route registered in multiple places causing conflicts +Solution: Unified registration in registerHealthRoutes Fixes: FastifyError Method 'GET' already declared for route '/health' -Tested: 服务启动成功,三个端点均可访问" +Tested: Service started successfully, all three endpoints accessible" ``` -**场景 3:架构升级** +**场景 3:架构升级(必须使用英文)** ```bash -# 完成平台基础设施实施并验证 +# Completed platform infrastructure implementation and verification git add backend/src/common/ backend/src/config/ git add docs/ -git commit -m "feat(platform): 实施平台基础设施(8个核心模块) +git commit -m "feat(platform): Implement platform infrastructure (8 core modules) -完成内容: -- 存储服务(LocalAdapter + OSSAdapter预留) -- 日志系统(Winston + JSON格式) -- 缓存服务(Memory + Redis预留) -- 异步任务(MemoryQueue + DatabaseQueue预留) -- 健康检查(liveness + readiness) -- 监控指标(数据库/内存/API) -- 数据库连接池(防止Serverless超限) -- 环境配置管理 +Completed: +- Storage service (LocalAdapter + OSSAdapter reserved) +- Logging system (Winston + JSON format) +- Cache service (Memory + Redis reserved) +- Async tasks (MemoryQueue + DatabaseQueue reserved) +- Health checks (liveness + readiness) +- Monitoring metrics (DB/memory/API) +- Database connection pool (prevent Serverless limit) +- Environment configuration -设计原则:适配器模式实现零代码环境切换 -实施时间:2.5天(20小时) -验收状态:本地开发环境验证通过 +Design principle: Adapter pattern for zero-code env switching +Implementation: 2.5 days (20 hours) +Status: Local dev environment verified Related: #Platform-Infrastructure" ``` @@ -585,16 +617,21 @@ $env:LESSCHARSET = 'utf-8' - `.editorconfig` - 统一编辑器编码配置(UTF-8) - `.gitattributes` - 统一 Git 文件编码处理 -**4. 最佳实践:使用英文提交信息** ⭐ 推荐 +**4. 强制要求:必须使用英文提交信息** ⭐⭐⭐ 必须 ```bash -# ✅ 推荐:使用英文 -git commit -m "feat(asl): add screening feature" +# ✅ 正确:必须使用英文 +git commit -m "feat(asl): Add screening feature" -# ⚪ 可选:使用中文(需要正确配置编码) -git commit -m "feat(asl): 添加初筛功能" +# ❌ 错误:禁止使用中文(会出现乱码) +git commit -m "feat(asl): 添加初筛功能" # 会出现乱码! ``` +**原因**: +- Windows PowerShell 环境下中文会乱码 +- 无论如何配置编码都无法完全避免乱码问题 +- **唯一解决方案:使用英文** + ### 🔧 修复历史提交中的中文乱码 **使用修复脚本:** @@ -1073,9 +1110,13 @@ git push-current # 推送当前分支 --- -**最后更新:** 2025-11-16 +**最后更新:** 2025-11-22 **维护人:** 技术架构师 **版本历史:** +- v1.1 (2025-11-22): **强制要求 Commit Message 使用英文**,避免中文乱码问题 + - 在"Commit Message 规范"开头添加重要提示 + - 更新所有示例为英文版本 + - 将"优先使用英文"改为"必须使用英文" - v1.0 (2025-11-16): 初始版本,包含完整的 Git 规范和中文乱码解决方案