# 新人团队协作 SOP

这份说明适用于 DoDo、sumu、shanshi、wangshu、chenxi、renshen 等使用 Codex 参与本项目的成员。团队按照已经确定的业务分工自行协作；开发者只需要把自己的任务目标、现场和验收结果告诉 Codex，仓库检查、技术范围、分支、命令、测试和 PR 由 Codex 完成。

## 一条必须遵守的规则

任务不能只留在个人电脑里。Codex 完成开工检查后，必须立即推送任务分支并创建 `WIP:` PR，先让其他开发者和 Codex 看见任务范围，再开始大量写代码。

没有推送的本机代码，其他人的 Codex 无法发现。等功能写完才推送，是重复页面、重复接口和重复数据库逻辑的主要来源。

## 开始一项任务

开发者把下面这段交给自己的 Codex：

```text
项目：CaiWuXiTong。
任务：<已经分工给我的功能或修复>。
现场：<报错、截图、现有页面或业务说明>。
验收：<最终页面、接口或业务结果>。

请先核对仓库、Git 身份、最新 main 和全部远程任务分支，搜索现有页面、路由、Controller、Repository、表/视图、source_key、scope、权限名、菜单键和共享组件。自行列出精确预计修改路径，并把公共契约分为“将写入”和“仅复用、不修改”两类，然后运行 scripts/codex-task-preflight.ps1。

发现预计修改路径重叠，或双方都会写入同一公共契约时立即停止，只报告具体重叠项，不能继续写代码或另造一套实现。只调用既有共享路由、Controller、组件或 Repository 而不修改它们，不是冲突；在 WIP PR 中列为“仅复用”并通过预检后可以继续。预检通过后，从最新 main 创建本人独立任务分支，立即推送并创建 WIP PR，填写任务范围，再开始修改。
```

Codex 必须先核对：

```bash
git rev-parse --show-toplevel
git status --short --branch
git remote get-url origin
git config user.name
git fetch --prune origin
```

检查结果必须满足：

- 当前项目是 `CaiWuXiTong`；
- `origin` 指向 `WuYongJie/CaiWuXiTong`；
- Git 身份和分支用户名属于当前实际开发者；
- 没有无法解释的受控文件改动；
- 当前任务没有复用已合并旧分支；
- 已列出具体预计路径、将写入的公共契约和仅复用的公共契约，不能只写“财务页面”“数据库接口”等宽泛范围；预计路径也不能只写 `app`、`tests` 等根目录。

## Codex 开工碰撞检查

由 Codex 执行，开发者不手工输入命令：

```powershell
.\scripts\codex-task-preflight.ps1 `
  -Task '<任务名称>' `
  -Developer '<实际开发者用户名>' `
  -PlannedPath @('config/business_navigation.php', 'tests/Feature/Business/OrderDataNavigationTest.php') `
  -Contract @('order-data/after-sales-expense-details', 'order-data/product-promotion-expense-details') `
  -ReuseContract @('business.pages.show')
```

脚本会：

1. 拉取最新远程引用；
2. 检查当前仓库、远程地址、Git 身份和工作区；
3. 检查所有尚未包含于 `main` 的远程任务分支；
4. 比较预计路径是否重叠；
5. 在远程 diff 中检查将写入的路由、Repository、表/视图、`scope` 等公共契约；仅复用契约只输出提示，不单独阻断；
6. 搜索 `main` 是否已经存在同名功能；
7. 给出“可以开始”或“停止并协调”的明确结果。

脚本返回阻断时，Codex 不得修改代码。阻断只表示存在实际写入重叠：相同预计修改路径，或双方都会修改同一公共契约。相关开发者根据报告中的分支、文件和公共契约自行确认保留哪套实现，确认后重新运行预检。若只复用既有共享能力，则在 WIP PR 写明“不修改”即可继续。

## 立即建立远程可见任务

预检通过后，Codex 从最新 `main` 创建新分支：

```bash
git switch main
git pull --ff-only origin main
git switch -c feature/用户名-任务名
git push -u origin feature/用户名-任务名
```

修复使用 `fix/用户名-问题名`，紧急修复使用 `hotfix/用户名-问题名`。一个分支只做一个任务，已合并分支不得复用。

随后在 Gitea 立即创建 PR：

- 标题：`WIP: <任务名称>`；
- 目标分支：`main`；
- 描述：完整填写 `.gitea/PULL_REQUEST_TEMPLATE.md` 中的“开工范围”；
- 尚未完成的测试明确写“待完成”，不能伪造结果。

WIP PR 用于公开任务占用，不代表功能已经完成，也不能被合并。

## 开发过程

1. 页面先复用现有共享组件和业务 Repository；
2. Controller 和页面不得直接连接数据库；
3. 新上游查询必须同时具备 Repository、稳定 `scope`、缓存调用、刷新器映射和测试；
4. 公共路由、权限、侧边栏、数据库配置、共享组件和部署脚本有改动时，必须在 WIP PR 中列为“将写入”；只调用、不修改的共享能力列为“仅复用”。实施中若要从“仅复用”改为“将写入”，必须先停止、更新 WIP PR 并重新运行预检；
5. 多个 Codex/Subagent 可以并行做只读排查、测试和审查，但不能同时写同一批文件；
6. 每次准备扩大修改范围时，先更新 WIP PR，再用新增路径和契约重新运行预检；
7. 修改后由 Codex 检查 `git status`、`git diff`，不得提交 `.env`、密码、Token、真实财务数据、日志或构建产物。

## 申请合并

Codex 在合并前必须进入一次独立自审，不得直接沿用开发阶段的完成结论：

1. 再次 `git fetch --prune origin`；
2. 使用实际修改路径和公共契约重新运行预检；
3. 对比最新 `main`，确认没有新的重叠任务；
4. 完成目标页面/接口、错误输入和受影响旧功能的最小验证；
5. 更新 PR 中的实际文件、公共契约、测试证据和风险；
6. 重新读取原始需求和验收标准，逐文件审核 `origin/main...任务分支` 的完整 diff；
7. 确认没有越界修改、重复实现、敏感内容、未处理冲突和未验证结果；
8. 自审通过后将标题从 `WIP:` 改成正式标题。

开发者把下面这段交给自己的 Codex：

```text
请进入独立的合并前自审，不要直接沿用开发阶段的完成结论。重新 fetch、读取原始需求和验收标准，并以 origin/main...当前任务分支的完整 diff 为准逐文件审核。检查工作区、WIP 状态、修改边界、公共契约、远程支线重叠、敏感内容、测试证据和目标 main。条件全部满足后，使用 Squash merge 合并到 main，核对远程 main 已包含目标改动，再验证实际页面或接口并删除已合并任务分支。禁止强推；如有冲突、测试失败、自审不通过或涉及尚未授权的生产迁移/数据操作，立即停止并报告。
```

日常 PR 自审、合并、主线验证、普通代码部署与验收和分支清理由任务开发者的 Codex 完成，不需要另一位开发者或项目负责人参与，也无需另行取得普通部署授权。开发者不手工执行 Git 合并命令，也不能绕过 PR；用户明确要求暂不上线时遵循其范围。本任务上游接入、共享镜像迁移、首次全量、回补和校准由 Codex 自主完成备份、执行与验收，无需负责人重复授权或代操作；其他生产迁移、数据修复、删除或覆盖配置继续按 `AGENTS.md` 执行。

## PR 落后或发生冲突

开发者把下面这段交给 Codex：

```text
当前任务分支的 PR 落后 main 或发生冲突。请先 fetch，并只读分析最新 main、当前分支和其他活跃远程分支的差异。禁止 force push 和 rebase。请列出冲突文件、双方业务逻辑、推荐保留方案和测试范围。普通代码冲突由相关分支提交人及其 Codex 处理；没有完成协调前不得修改、推送或合并。
```

不能用删除对方代码、恢复旧版本、复制另一项目实现或扩大公共权限的方式消除冲突。

## 任务完成

- PR 合并后删除本地和远程任务分支；
- 下一项任务重新从最新 `main` 开始；
- WIP PR、远程分支和实际代码是团队 Codex 判断任务占用的依据；
- 产品方向或重大业务规则无法由现有需求判断时，再提交清晰的选项、影响和证据进行确认。