zsp-project/docs/Git提交规范.md

Git 提交规范文档

本文档规范项目中的 Git 提交信息格式，便于团队协作与版本追溯。

---

一、提交信息格式

采用 Conventional Commits 规范，格式如下：

<类型>[可选范围]: <简短描述>

[可选的详细说明]

[可选的脚注]

1.1 类型（type）

类型	说明
feat	新功能
fix	缺陷修复
docs	文档变更（README、说明等）
style	代码格式（空格、缩进等，不影响逻辑）
refactor	重构（ neither feat nor fix）
perf	性能优化
test	测试相关
chore	构建、工具、依赖等

1.2 可选范围（scope）

标明影响模块，便于检索，例如：

• contract - 合同管理
• finance - 财务管理
• delivery - 提货管理
• inventory - 库存
• invoice - 发票
• api - 后端 API
• frontend - 前端
• backend - 后端

---

二、提交示例

2.1 新功能

feat(contract): 新增合同批量上传功能
feat(finance): 结算管理支持导出 Excel

2.2 修复

fix(api): 修复合同查询接口分页参数错误
fix(frontend): 修复发票列表筛选不生效

2.3 文档

docs: 补充财务管理模块待确认问题
docs(api): 更新合同管理 API 文档

2.4 重构与优化

refactor(invoice): 抽取发票上传公共逻辑
perf(contract): 优化合同列表查询性能

2.5 其他

style: 统一前端代码缩进
chore: 升级 Go 依赖版本
test(finance): 补充结算单单元测试

---

三、书写建议

1. 标题：简洁明了，控制在 50 字符内；使用中文，动词开头。
2. 一条提交做一件事：功能、修复、格式尽量分开提交。
3. 说明可省略：简单变更可不写正文，复杂逻辑建议补充说明。
4. 关联需求/问题：如有 Jira/飞书等，可在脚注中写 Refs: #123。

---

四、反例（应避免）

不良示例	问题说明
update	类型不明确，描述含糊
修改了一些东西	没有说明修改了什么
fix bug	未说明修复的是哪个 bug
WIP	未完成工作不宜直接合并

---

五、工作流简要

• main：生产分支，稳定版本
• dev：开发主分支
• feature/xxx：功能开发分支
• fix/xxx：缺陷修复分支

提交前请先在 dev 或对应 feature 分支上开发，完成后再合并到目标分支。