cangku/仓库提交与合并规范.md

# 仓库提交与合并规范（多用户与 AI 开发必读）

本规范适用于所有开发者及其使用的 AI 编程工具。目标是保留他人的提交和业务行为，让每次修改都可审核、可追溯、可回退。开始修改前必须阅读本文件与根目录 `AGENTS.md`；需要更新生产服务器时还必须阅读 `服务器部署规范.md`。

公开仓库允许所有人 Fork、修改并提交 Pull Request（PR）；直接写入本仓库仍需要协作者权限。每名开发者使用自己的账号和凭据，禁止多人共用管理员账号或把账号、密码、令牌写入代码、文档、提交信息及 PR。

## 1. 必须遵守的规则

1. **一个任务一个分支、一个独立工作目录。** 默认分支名为 `codex/<开发者>-<任务>-<唯一编号>`。不同 AI 会话不得同时修改同一工作目录，也不得共用任务分支。
2. **通过 PR 合并到 `main`。** 禁止直接向 `main` 推送；由有合并权限的维护者在审核及验证通过后合并。
3. **禁止强制推送。** 不得使用 `--force`、`-f`、`--force-with-lease`、带 `+` 的推送 refspec 或 `--mirror` 绕过拒绝。不得删除他人分支、重建仓库或替换历史来解决冲突。
4. **保留他人工作。** 未确认归属的修改、未跟踪文件、提交和业务逻辑都不能删除或覆盖。禁止为得到“干净目录”执行 `git reset --hard`、`git clean -fd/-fdx` 或全量恢复文件。
5. **先同步，再验证，再推送。** 推送成功、没有文本冲突、测试通过，都不能单独证明没有覆盖他人的业务行为；必须审核最终差异。
6. **不能把冲突处理交给一条批量命令。** 禁止对整批冲突使用 `ours` / `theirs`，或把旧版本目录复制到新版本上。意图不明时停止该部分合并，交由相关开发者或维护者确认。
7. **已推送的提交不得改写。** 共享分支和已发布的任务分支不要 rebase、amend 或 squash 后重新推送；用新的修正提交及 merge 保留历史。维护者在 PR 页面使用平台的 squash 合并功能不属于强推，但必须满足审核要求。
8. **不夹带任务之外的改动。** 不顺手重构、恢复已删除功能、修改权限或部署配置；确有依赖变更时，在 PR 中说明必要性。

普通 Git 推送会拒绝非快进更新，但无法防止“基于最新提交，却把文件内容改回旧实现”的正常提交。因此，防止覆盖既需要保留历史，也需要检查代码含义和回归行为。

## 2. 开工前：确认仓库、基线与隔离目录

先检查当前位置、远端、分支及现有修改，不要直接执行复制来的修改命令：

```bash
pwd
git remote -v
git branch --show-current
git status --short
git fetch origin
git log -5 --oneline origin/main
git rev-parse origin/main
```

记录 `origin/main` 的完整 SHA，作为本任务起始基线。确认远端确实是本项目；Fork 开发者还需核对上游仓库。浏览已有 PR，确认有没有人正在改同一模块。

如果当前目录有他人的修改，不要暂存、提交、stash、清理或覆盖它们。新建独立克隆，或在仓库内创建独立 worktree。下面的分支名和目录名仅是示例，执行前必须换成自己的唯一名称；若已经存在，换名而不是删除：

```bash
git worktree add -b codex/alice-login-001 ../cangku-alice-login-001 origin/main
cd ../cangku-alice-login-001
git status --short
```

只有已经确认由自己独占且干净的工作目录，才可直接使用 `git switch -c <任务分支> origin/main`。开始编辑前再次确认实际所在目录和分支。多个独立克隆通常更便于隔离；worktree 仍共享 Git 对象和部分仓库配置，不得随意修改全局或共享配置。

## 3. 修改与提交：仅纳入自己的任务

- 修改前阅读最新代码、调用方及相关测试，不凭历史对话或旧文件恢复整个模块。
- 共享接口、权限、数据库迁移、依赖锁文件、路由和配置是容易互相影响的区域；涉及它们时，在 PR 中标明影响范围，必要时先协调接口约定。
- 保留锁文件中其他开发者的依赖，用项目规定的包管理器生成自己的变更；不要以“重新生成”为由丢弃他人的依赖。
- 数据库迁移使用不重复的名称，兼容已有数据，不能修改已经执行的历史迁移来代替新增迁移。
- 不提交 `.env`、私钥、令牌、真实业务数据、数据库备份、`node_modules` 或无关构建产物。示例配置只使用占位值。

### 3.1 数据表、索引与映射负载要求

开发者及 AI 新建或修改数据表、第三方数据映射、查询接口、报表或同步任务时，必须把数据库负载作为功能验收条件，不得等到上线后再补索引或限流。

1. **按真实访问路径设计索引。** 根据 `WHERE`、`JOIN`、`ORDER BY`、分页、去重和幂等键设计单列或联合索引，明确联合索引列顺序和最左匹配规则。索引列的类型、长度、字符集和排序规则必须与关联列一致。不要添加没有查询依据的重复索引，也不能以索引过多换取“可能更快”。
2. **映射关系必须稳定且可幂等。** 第三方主键、业务编码与系统主键应使用明确的标准化字段和唯一约束，需要多字段定位时建立与匹配顺序一致的联合唯一索引。禁止每次请求通过模糊匹配、字符串函数或全表扫描重建映射。
3. **提交前验证执行计划。** 在隔离的测试环境使用 `EXPLAIN`；数据库支持且确认语句安全时可使用 `EXPLAIN ANALYZE`。检查实际命中索引、预估/实际扫描行数、回表、排序和临时表情况。不得在生产库上执行高负载的 `EXPLAIN ANALYZE` 或压测。
4. **查询必须有界。** 使用限制列的字段选择和有上限的分页，大数据量优先使用基于稳定索引键的游标分页。避免 `SELECT *`、N+1 查询、无上限 `IN`、前置通配符模糊查询、对索引列包裹函数，以及没有范围条件的更新或删除。
5. **同步任务必须分批、增量和可恢复。** 通过时间水位、版本号或稳定主键做增量读取，用唯一约束与 upsert 保证幂等；设置可控的批量、并发数、查询超时、重试退避和单实例锁。禁止每次启动全量扫描、无限并发、紧循环轮询或重复后台任务。
6. **保护第三方云数据库。** 业务云库查询必须只取必要列和必要范围，并在系统库持久化必要的结果或增量水位，避免页面请求反复扫描远程大表。未获明确授权不得在第三方库执行 DDL、建索引或写入。
7. **迁移必须考虑锁表和回退。** 针对大表新增索引、变更列类型或回填数据前，评估表规模、锁等待、磁盘增长和业务窗口；采用可分步的兼容迁移，并说明回退时是否会丢数据。
8. **PR 必须附上数据库证据。** 说明表规模假设、索引定义及对应查询、执行计划摘要、扫描行数或耗时对比、同步批量/并发/超时参数、迁移与回退方式。无法获得有代表性数据时要标明限制，不得虚构性能结论。

只有功能结果正确且负载证据可接受，数据表和查询变更才算完成。无法证明索引有效、可能对中央系统库或业务云库造成高负载时，保持 PR 待审核，不得部署。

提交前逐项检查，并显式暂存文件；文件中混有不同任务时使用 `git add -p` 选择自己的改动。不要盲目使用 `git add .` 或 `git add -A`：

```bash
git status --short
git diff --stat
git diff
git add <本任务文件路径>
git diff --cached --check
git diff --cached
git commit -m "docs: 说明本次变更目的"
```

尖括号内容是需要替换的占位符，不要原样执行。提交信息说明修改目的，每个提交保持逻辑完整。使用自己的真实开发身份，不冒用其他开发者身份。

## 4. 推送前：同步远端并处理并行修改

先把自己的工作整理为提交，确认没有未知的未提交修改，再执行同步。以下命令应当在自己的任务分支中执行：

```bash
git fetch origin
git branch --show-current
git status --short
git log --left-right --oneline HEAD...origin/main
git merge origin/main
```

如果远端已经有同名任务分支，还必须检查 `HEAD...origin/<任务分支>`。远端出现本地没有的提交时，先查明来源，再用 `git merge origin/<任务分支>` 合入；不允许用本地版本覆盖它。不要把新分支第一次推送时不存在的远端引用当成错误而强推。

发生冲突时：

1. 使用 `git status` 和 `git diff --name-only --diff-filter=U` 定位冲突。
2. 阅读共同基线、双方提交及调用关系，弄清楚双方改动要实现的行为。
3. 逐处整合并保留双方有效意图，同时检查相关文件中未产生文本冲突的逻辑兼容性。
4. 意图或取舍不明确时，停止处理相关冲突并请负责人确认；不得自动选择“自己的版本”。
5. 解决后显式暂存已解决的文件，确认没有未解决冲突，检查暂存差异，再完成 merge 提交。
6. 对合并后的结果重新验证，并在 PR 中说明冲突位置及处理理由。

同步完成后审核整个任务相对最新主分支的差异：

```bash
git diff --check origin/main...HEAD
git diff --stat origin/main...HEAD
git diff origin/main...HEAD
git status --short
```

完成下节验证后才可推送：

```bash
git push -u origin HEAD
```

若推送被拒绝，重新 fetch、查看新增提交、合并、审核及验证。**拒绝不是强推授权。** 不通过修改 push 配置或反复重试危险命令绕过保护。

Fork 开发者约定 `origin` 为自己的 Fork、`upstream` 为本项目：从 `upstream/main` 创建任务分支，同步时合并 `upstream/main`，并检查自己 `origin/<任务分支>` 的更新；推送至自己的 Fork 后向本项目 `main` 发起 PR。不要将自己的 Fork 主分支误认成项目最新主分支。

## 5. 验证要求

按改动范围执行仓库现有检查：

```bash
npm --prefix backend run check
npm --prefix frontend run check
```

- 后端改动运行后端检查；前端改动运行前端检查；跨端接口或共享行为改动需要两侧检查。
- 功能修复补充能检出原问题的测试；影响页面交互时验证实际操作路径；涉及接口、权限或数据迁移时验证受影响场景及已有行为。
- 仅文档变更可检查内容、链接、示例命令和 `git diff --check`，说明未运行应用测试的原因。
- 使用隔离的测试环境和数据，不为了检查连接生产数据库或执行生产迁移。
- 记录实际命令、结果和被验证的提交 SHA。失败要如实报告；无法运行的检查标记“未运行/受阻”，不能写成“通过”。
- 同步或冲突解决改变了待合并内容后，重新运行受影响的验证。旧提交上的成功结果不能证明新提交正确。

## 6. PR 与安全合并

每个 PR 只对应一个明确任务，目标为 `main`，描述至少包含：

```markdown
## 目的与范围
- 解决的问题：
- 修改的模块/文件：
- 是否使用 AI 及负责开发者：

## 同步与兼容性
- 起始基线 SHA：
- 最近同步的 main SHA：
- 待审核任务分支 SHA：
- 并行 PR、共享接口、迁移/配置影响：
- 冲突及处理理由（无冲突也应说明）：
- 如何确认保留了其他开发者的已有行为：

## 验证
- 实际执行的命令及结果：
- 未运行或失败的检查及原因：
- 人工验证路径（如适用）：

## 风险与回退
- 已知风险：
- 回退方式和数据兼容性：
```

合并要求：

1. 至少一名非提交者的维护者或开发者审核最终差异；AI 自我复查可以辅助，但不代替独立审核。提交 AI 不得用另一个会话或共享账号冒充独立审核者。
2. 审核需关注是否撤销他人逻辑、丢失配置/依赖、改变接口与权限、破坏已上线功能，不能只看有无冲突或测试绿灯。
3. 审核和检查必须对应最终待合并提交；后续新提交或冲突解决后需要重新确认，不能沿用失效的批准。
4. 合并前再次确认最新 `main` 已被纳入任务分支，并验证组合后的行为。其他 PR 先合并导致主分支前进时，更新本 PR、重新检查并确认审核后再合并。
5. 由维护者通过仓库 PR 合并功能依次处理；同时有多个待合并 PR 时串行合并。有合并队列时使用针对最新组合提交的检查，避免两份旧验证同时放行。
6. 未解决冲突、必需检查失败、尚未审核或同步状态不清楚时不得合并。缺少独立审核者时保持 PR 待审核，不自行批准。
7. 合并后核对主分支结果。删除任务分支前确认已合并且无人继续使用，不删除其他开发者的分支。

## 7. 发现误合并或代码被覆盖

先保留当前状态、记录相关提交 SHA 和影响，暂停自己受影响的后续提交，交由维护者定位问题。使用新的修复 PR 或 `git revert` 生成撤销提交，让历史可追溯。撤销 merge 提交需要维护者先确认正确的主父提交，不要盲目套用 `-m` 参数。

禁止将 `main` reset 回旧版本再强推。代码回退不会自动恢复数据库和外部状态；涉及迁移或数据变更时，需要单独验证兼容性与恢复方案。部署只能使用已合并、已验证的明确提交，并遵守实际部署授权；提交或合并代码本身不代表获准操作生产服务器。

## 8. AI 交付前检查清单

- [ ] 已阅读本规范；当前仓库、目录、账号、任务分支和基线正确。
- [ ] 没有覆盖、清理、暂存或提交他人的未提交修改。
- [ ] 提交仅包含本任务内容，没有秘密信息、真实业务数据或无关产物。
- [ ] 涉及数据表、索引、映射、查询或同步时，已验证执行计划、数据量边界和负载控制，并在 PR 记录真实证据。
- [ ] 已同步最新主分支及远端任务分支，未强推、未改写已发布历史。
- [ ] 已逐项审核最终差异；冲突处理保留双方有效行为，疑点已确认。
- [ ] 已完成受影响的验证，记录准确结果和提交 SHA。
- [ ] PR 已说明范围、兼容性、验证、风险和回退方法。
- [ ] 已明确报告当前状态：本地提交 / 已推送 / PR 待审核 / 已合并；没有把推送成功说成合并或部署成功。

## 9. 文档要求与服务端强制保护的区别

本文件规定协作流程，`AGENTS.md` 提供 AI 读取入口；它们不是权限控制，不能保证每个 AI 工具自动读取或遵守。使用不自动读取这些文件的工具时，开发者必须主动提供规则。

仓库管理员应在服务端落实以下保护，并以实际设置为准：保护 `main`、禁止直接及强制推送和删除、要求 PR 与独立审核、使过期审核失效、绑定真实运行的必需检查、限制合并权限、按个人发放最小权限凭据。没有真正运行的检查不能仅凭同名状态作为合并依据。

**添加本文件不等于上述保护已经启用。** 此文档变更不修改仓库权限、分支保护、CI 或生产部署；如需启用服务端限制，应由管理员单独配置并验证。