# Git 提交规范 (Git Commit Convention)

为保障铁路培训综合管理系统（RailwaySystem）项目提交历史的清晰、规范与可审计性，项目组统一制定并执行本中文提交规范。

## 1. 核心原则
- **全中文描述**：提交信息（Commit Subject）统一使用简体中文，禁止使用全英文 Commit Subject。
- **允许技术术语**：在中文描述中允许保留业界通用技术名词（如 `GitLab`、`CI/CD`、`DMS`、`RBAC`、`API`、`Kingbase`、`Redis`、`Spring`、`P0`、`V2`、`E2E`、`Wave` 等），但其承载的自然语言表达必须为中文。
- **原子性与真实性**：一个 Commit 应专注于解决一个明确的业务或技术目标，不得虚构功能或改变实际技术事实。

---

## 2. 格式规范

```text
<中文类型><可选中文范围>：<中文说明>
```
> **注意**：类型/范围与说明之间必须使用中文全角冒号 `：` 分隔。

### 2.1 类型映射 (Type)
| 中文类型 | 对应英文 Conventional Type | 说明 |
| :--- | :--- | :--- |
| **新增** | feat | 新增功能、业务能力、模型或界面组件 |
| **修复** | fix | 缺陷修复、Bug 解决、异常排查 |
| **文档** | docs | 文档更新、接口契约修订、验收报告归档 |
| **测试** | test | 自动化测试、E2E 验收用例、测试数据包补充 |
| **合并** | merge | 分支合并、基线同步 |
| **维护** | chore | 依赖升级、忽略文件维护、资产清理 |
| **持续集成** | ci | 流水线配置、容器环境、部署脚本与运行时检查 |
| **重构** | refactor | 既不增加新功能也不修复 Bug 的代码结构调整 |

### 2.2 常见业务与技术范围 (Scope)
- **培训**：开班计划、课程、教师、学员、课次排课、考勤与报到
- **住宿**：宿舍房间、学员住宿分配
- **权限**：三角色（管理员/教师/学员）RBAC、身份绑定、自服务安全控制
- **门禁**：DMS 外部设备接入、临时凭证、通行策略、适配器集成
- **部署**：生产/试用环境脚本、Nginx、反向代理、环境配置
- **流水线**：GitLab CI/CD 自动构建、测试门禁、冒烟测试
- **接口**：API 契约制定与对齐
- **数据库**：Kingbase、Redis、迁移脚本与日志
- **界面**：前端组件、路由、UI 规范对齐
- **需求**：甲方范围确认、需求基线对齐
- **验收**：综合验收证据、浏览器测试、测试场景

---

## 3. 示例参考

- **新增培训**：实现课次排课P0能力
- **修复权限**：修复教师身份越权与访问控制漏洞
- **测试验收**：补充教师端与学员端浏览器验收证据
- **文档需求**：对齐一期范围与甲方待确认事项
- **持续集成**：优化共享试用环境自动部署与健康检查
- **合并发布**：部署一期共享试用候选版本
- **维护仓库**：整理交付资产与忽略生产数据库备份文件

---

## 4. 历史分支说明
自 2026-09-17 实施全中文规范治理后，`feat/cicd-pipeline` 历史提交已按此规范全量重写。历史验收报告中记录的旧 SHA 统称为 `PRE_HISTORY_NORMALIZATION_SHA`，保持客观历史真实性。
今后开发禁止再引入英文 Conventional Commit 前缀或全英文 Commit 描述。