playableads-platform/docs/GIT_GUIDELINES.md

Git 提交规范指南

一、核心原则（前置要求）

1. 操作触发与执行约束

• 触发条件：必须在人为明确指定本文档，且确认目标远程仓库及分支后，方可执行 git add/commit/push 等涉及代码变更的操作。
• 禁止场景：
  • 禁止在非人为交互场景下自动读取或执行本规范。
  • 若未被人为指定阅读，AI 需立即停止继续读取本文档。
• 重复确认机制：
  • 禁止在非人为确认情况下执行任何 git add/commit/push 操作。
  • 每次完成 git add/commit/push 后，后续任何 Git 操作均需重新经过人为确认方可执行。
  • 每次执行 git add/commit/push 前，必须罗列出要提交的文件分类及对应的 commit 内容，经确认后再执行。

2. 提交信息要求

• 清晰可追溯：准确描述“做了什么”和“为什么做”，避免模糊表述（如“修改代码”“更新文件”）。
• 粒度最小化：单次提交仅包含一个完整功能/修复/文档更新，禁止混合多类无关变更（如同时开发功能+修复bug需拆分提交）。
• 关联上下文：涉及需求或Bug时，需在提交信息中关联编号（如 Fixes: #123，#123 为Bug编号）。
• 禁止的commit内容：
  • 禁止提交包含敏感信息（如密码、密钥、个人隐私数据）的代码变更。
  • 禁止提交包含二进制文件（如图片、音频、视频等）的变更。
  • 禁止提交包含自动生成的代码（如编译输出、临时文件）的变更。
  • 禁止commit内容过于笼统，比如“修改了一些代码”、“更新了文档”、“同步工作区改动”等。

二、提交格式

基础结构

<类型>(范围): <简短描述>
[可选：详细说明]
[可选：关联信息]

• 类型：标识提交的功能类别（必填）。
• 范围：标识修改涉及的模块/文件类型（必填）。
• 简短描述：简洁概括变更内容（必填，中文，≤50字）。
• 详细说明：复杂变更可换行补充细节（可选,中文）。
• 关联信息：关联需求ID、Bug号等（可选，格式如 Ref: #123 或 Fixes: #456）。

三、类型与范围定义

1. 提交类型

类型	标识	适用场景
新增功能	feat	新增代码功能（接口、模块、逻辑）；新增配置项、资源文件（音频、图片等）。
功能修复	fix	修复代码bug、逻辑错误；修复配置错误、资源路径问题。
文档更新	docs	修改注释、使用手册、API文档；补充README、配置说明。
代码优化	refactor	重构代码（不新增功能/修复bug，仅优化结构、命名、性能）。
样式调整	style	代码格式调整（缩进、空格、注释格式）；不影响代码逻辑。
测试相关	test	新增/修改测试用例、测试脚本。
构建/配置	chore	调整依赖、构建脚本、环境配置（如修改requirements.txt、Dockerfile）。

2. 范围定义

• 业务代码：internal、controllers、services等（业务逻辑、数据处理、业务功能模块）。
• 框架代码：pkg、middlewares、constants_text等（核心框架、原生功能模块、公共工具类）。
• 配置文件：config、env、backup等（系统配置、环境变量）。
• 资源文件：docs、.trae、.env等（非代码文件，如音频、图片、字体等）。
• 无范围：全局变更（如根目录文档、全局配置）。

四、操作规范（需人为确认后执行）

1. 暂存（add）流程

1. 文件分类：按“类型+范围”对修改文件进行分类（如“feat(修改目标)”类文件、“fix(原始代码)”类文件）。
2. 列出文件：明确列出每类需暂存的文件路径（如：main/修改目标/device.js、src/utils/tool.py）。
3. 执行暂存：按分类执行 git add <文件路径>，禁止使用 git add . 批量暂存。
4. 确认内容：执行 git diff --cached 检查暂存内容，无误后等待人为确认。

2. 提交（commit）流程

1. 生成信息：根据文件分类和修改内容，按规范格式生成commit中文信息（包含类型、范围、描述等）。
2. 展示信息：清晰展示完整的commit信息（使用中文描述，含详细说明和关联信息）。
3. 执行提交：经人为确认后，执行 git commit -m "<commit信息>"。
4. 限制说明：使用中文写commit信息

3. 推送（push）流程

1. 环境说明：列出当前本地分支（如：修改目标_ws）及可用远程仓库（如：mjgitlab/origin）。
2. 确认目标：询问并确认推送的远程仓库及分支（如：mjgitlab/修改目标_ws）。
3. 执行推送：仅在人为确认后执行 git push <远程仓库> <分支>。
4. 放弃推送：若未确认目标或存在冲突风险，放弃推送并提示原因。

五、示例

1. 新增功能（带关联需求）

• 文件分类：feat(修改目标)
  
• 涉及文件：main/修改目标/wakeup.js、main/修改目标/config/wakeup.json
  

• Commit信息：

  feat(修改目标): 新增设备语音唤醒功能
  详细说明：
  - 支持自定义唤醒词（最长8个字符）
  - 新增唤醒成功回调接口
  Ref: #102（关联需求ID）
  

2. 修复Bug（带问题描述）

• 文件分类：fix(原始代码)
  
• 涉及文件：src/device/heartbeat.py
  

• Commit信息：

  fix(原始代码): 修复设备心跳包发送超时问题
  问题：设备联网后30秒内未发送心跳，导致被误判为离线
  修复：调整心跳包发送间隔为10秒
  Fixes: #567（关联Bug ID）
  

3. 文档更新

• 文件分类：docs(修改目标)
  
• 涉及文件：docs/修改目标/tts_api.md
  

• Commit信息：

  docs(修改目标): 补充TTS推送接口错误码说明
  新增错误码400（参数无效）、500（服务异常）的处理建议
  

4. 代码优化

• 文件分类：refactor(原始代码)
  
• 涉及文件：src/device/connection.py
  

• Commit信息：

  refactor(原始代码): 拆分设备连接逻辑为独立函数
  提高代码复用性，便于后续维护
  

六、规范维护

• 本规范存放于项目根目录 GIT_COMMIT_GUIDELINES.md，团队成员需共同遵守。
• 可通过Git钩子（如pre-commit）自动校验提交信息格式，不符合时拦截提交。
• 定期同步规范执行问题，根据实际场景补充新类型/范围（如新增perf标识性能优化）。