# BRD：`supervisor/deploy_stage.py` 并发部署冲突的诊断化处理 ## 1. 背景与问题定义 graphlemon 的 Deploy Supervisor（`supervisor/`）在自举（self-hosting）场景下，会把针对 graphlemon 自身仓库 的代码变更打包成一次部署（`deployment` 行），由 `supervisor/deploy_stage.stage_deployment()` 负责"拉起候选 实例"这一步：检出新提交到独立 worktree、拷贝生产数据库、在临时端口上启动候选进程。这是蓝绿部署链路 （stage → health-check → cutover → monitor → finalize/rollback）里唯一一个会创建新部署记录的入口，一旦并发 触发两次，会产生两个互相踩踏的候选实例，属于高风险类别（生产事故 / 不可逆的部署状态错乱）。 原始任务描述（来自 `docs/todo/` 及既往 gap-analysis）断言"`stage_deployment()` 只检查上一次成功落地的部署， 完全不检查当前是否已有进行中的部署，因此会静默产生第二个冲突的候选实例"。**经对当前代码逐行核实，这一断言 不成立**，需要在此明确记录并纠偏（SOUL.md 原则 4：不得把猜测当事实，事实与预想冲突时以事实为准）： - `src/schema.py`（`deployment` 表定义）已经存在 `ux_deployment_active` 部分唯一索引（U-034 引入， 2026-08-02，非本次新增）： ```sql CREATE UNIQUE INDEX ux_deployment_active ON deployment((1)) WHERE status NOT IN ('finalized', 'rolled_back', 'blocked_pending_human'); ``` 即数据库层面已经保证"同一时刻最多一条非终态部署记录"，由 SQLite 在 `INSERT` 语句级别原子化生效，不存在 TOCTOU（检查后再写入之间的）竞态窗口。 - `stage_deployment()`（`supervisor/deploy_stage.py:148-176`）把 `INSERT INTO deployment ...` 放在所有具有 真实副作用的操作（`git worktree add`、生产库拷贝、`Popen` 启动候选进程）**之前**执行并立即 `commit()`。 也就是说，如果此时已存在未到终态的部署记录，冲突会在任何副作用发生前就终止函数执行——不会产生"第二个 冲突的候选实例"，这个具体后果本身已经被现有实现规避。 - `supervisor/test_deploy_stage.py::StageDeploymentHappyPathTest.test_only_one_non_terminal_deployment_allowed` （171-180 行）已经用真实 sqlite 断言了"第二次调用会被拒绝"这一行为，不是完全没有测试覆盖。 因此，"完全没有互斥检查"这个业务问题已经不存在。但核实过程中发现了两处真实、边界清楚、仍值得作为独立 bug 修复交付的差距，二者都属于"并发冲突被正确拒绝，但拒绝的方式和覆盖不够可靠/可诊断"这一类问题，而不是 "未被拒绝"： - **G1（诊断信息缺失，可运维性问题）**：冲突发生时，`stage_deployment()` 让底层 `sqlite3.IntegrityError` 原样向上抛出。调用方（当前是测试代码，未来是 Deploy Supervisor 的轮询循环和任何手工触发路径）拿到的是一个 不携带 `deployment_id`、当前占用者状态等诊断信息的通用底层异常，且与同模块 `CheckoutFailedError`、同包 `deploy_cutover.CutoverFailedError`、`deploy_rollback.RollbackFailedError` 这类"具名异常 + 携带诊断字段" 的既有约定不一致。出了并发冲突之后，值班人员/日志只能看到一串 SQLite 内部错误文本，无法直接判断"是谁在 占用、占用到什么状态"，需要额外查库才能定位——这是一个真实的可运维性缺口，而不是功能性缺口。 - **G2（回归测试覆盖不完整，防回归问题）**：`ux_deployment_active` 索引的 `WHERE` 子句显式把 `finalized`/`rolled_back`/`blocked_pending_human` 三个状态列为"允许发起新部署"的终态，但现有测试只间接 覆盖了 `finalized` 这一条路径（`BootstrapPreviousTest.test_prior_finalized_deployment_supplies_previous_fields`）。 `rolled_back`、`blocked_pending_human` 这两个同样被索引显式放行的终态没有对应的回归测试。这意味着如果未来 有人不小心改动了这条 `WHERE` 子句、或者在 `stage_deployment()` 里加了额外的状态判断逻辑，测试套件不会 发现"本该允许发起新部署的终态被误挡住了"这类回归。 以及贯穿全程的门禁： - **G3**：`src/` 与 `supervisor/` 两个独立 `unittest discover` 套件必须保持全绿——修复动作不得引入新的失败 或破坏既有 560+ 测试。 ## 2. 干系人与使用场景 - **Deploy Supervisor 自身的轮询循环**（`supervisor/deploy_supervisor.py`，未来接线 `stage_deployment()` 的调用方）：需要能程序化区分"这次失败是因为已有部署在进行中"和"这次失败是其他真实错误（如 checkout 失败、 磁盘满）"，以便做出不同的后续动作（等待重试 vs. 上报阻塞）。 - **值班人 / 事后排查者**：在自举流程出现异常时，需要从异常信息本身直接读出"是谁占用了这次部署"，而不是 额外去查 `deployment` 表。 - **未来维护 `stage_deployment()` 或 `ux_deployment_active` 索引定义的开发者**（人类或 Coder Agent）：需要 一组明确的回归测试作为"这三个终态必须放行新部署"这一约束的可执行文档，防止未来改动悄悄破坏该约束。 ## 3. 目标（Goals） 1. 当 `stage_deployment()` 因 `ux_deployment_active` 冲突而无法发起新部署时，调用方能拿到一个具名、语义 明确、携带诊断字段（本次被拒绝的 `git_commit_hash`、当前占用中的 `deployment_id` 与 `status`）的异常， 而不是原始的底层数据库异常。 2. 把"`finalized`/`rolled_back`/`blocked_pending_human` 三个终态都允许发起新部署"这一约束，从"隐式依赖 SQL `WHERE` 子句不被改错"变成"由可执行的回归测试显式锁定"。 3. 修复过程不破坏任何既有行为：`CheckoutFailedError` 的既有触发路径与语义、`stage_deployment()` 现有的 返回值结构和调用契约，均保持不变。 4. `src/` 与 `supervisor/` 两个 `unittest discover` 套件全部通过，退出码为 0。 ## 4. 非目标（Non-Goals） - 不重新设计或改变 `ux_deployment_active` 索引本身的终态集合定义（`finalized`/`rolled_back`/ `blocked_pending_human`）——这是 01-M 1.15 既定约束，本次不涉及业务语义变更。 - 不引入应用层的额外锁（文件锁、进程内内存锁、乐观锁重试等）——数据库唯一约束已经是并发正确性的单一事实 来源且已经过原子化验证，重复加锁只会增加不必要的复杂度和新的一致性风险。 - 不改变 `stage_deployment()` 现有的返回值结构（`{deployment_id, status, candidate_port, candidate_pid, candidate_instance_dir}`）。 - 不处理 `health_check_failed`、`rollback_failed` 是否也应该被视为终态、允许发起新部署——这两个状态目前 仍在 `ux_deployment_active` 的"非终态"一侧（即仍会阻止新部署发起），这是否合理需要业务侧判断，属于状态 机语义变更，不在本次 bug 修复范围内（详见第 7 节范围外事项）。 - 不改动 `deploy_supervisor.py` 轮询循环本身如何消费这个异常——本次只交付异常的产生方（`deploy_stage.py`） 和对应测试；调用方是否/如何区分处理该异常留给后续任务。 ## 5. 范围（Scope） 仅涉及两个文件： - `supervisor/deploy_stage.py`：新增一个具名异常类（携带诊断字段），并在触发 `ux_deployment_active` 冲突的那一次 `INSERT` 周围新增 `try/except`，把底层数据库异常转译为该具名异常后抛出。 - `supervisor/test_deploy_stage.py`：收紧现有并发冲突测试的断言（从笼统的 `assertRaises(Exception)` 改为 断言具名异常类型及其诊断字段），并新增 `rolled_back`、`blocked_pending_human` 两条终态放行路径的回归 测试。 不涉及 `src/schema.py`（不改 schema）、不涉及 `deploy_cutover.py`/`deploy_rollback.py`/`deploy_health_check.py` 等同包其他模块、不涉及新增外部依赖。 ## 6. 已知事实 / 设计决策 / 待验证假设 / 阻塞性未知 **已知事实**（均来自对当前代码的直接核实，非猜测）： - `ux_deployment_active` 唯一索引已存在并在 `INSERT` 语句级别原子化生效（`src/schema.py:357-362`）。 - `stage_deployment()` 的 `INSERT`（`supervisor/deploy_stage.py:170-176`）先于所有具有真实副作用的调用 （`_checkout_candidate`/`_copy_prod_db`/`_launch_candidate`，178 行起）执行；冲突发生时不会产生候选 worktree、候选数据库拷贝或候选进程等任何副作用。 - 现有测试 `test_only_one_non_terminal_deployment_allowed`（`supervisor/test_deploy_stage.py:171-180`）用 `self.assertRaises(Exception)` 承接冲突异常，未指定异常类型也未校验诊断字段——这正是 G1 要收紧的具体 测试点。 - 索引 `WHERE` 子句排除（即"允许发起新部署"）的终态集合是 `{'finalized', 'rolled_back', 'blocked_pending_human'}`；`health_check_failed` 与 `rollback_failed` 不在该集合中，即当前设计下仍被 视为"非终态、会继续阻止新部署发起"的状态。 **设计决策**（PL 基于本仓库既有约定作出，非新的产品/业务决策，供 SDD 阶段延续）： - 新异常应沿用模块内 `CheckoutFailedError` 的命名与文档风格：具名、放在模块顶部、docstring 说明触发场景 与语义，与同包 `CutoverFailedError`/`RollbackFailedError` 的既有约定保持一致。 - 转译逻辑必须能区分"因 `ux_deployment_active` 冲突导致的插入失败"与"其他类型的数据库错误"（如 schema 不匹配、连接已关闭等意外情况），不能把所有 `sqlite3.IntegrityError` 一律归类为并发冲突而掩盖其他真实 错误。具体判别手段（例如检查错误信息是否指向 `ux_deployment_active`，或其他等价可靠方式）留给 SDD/实现 阶段选择，唯一的硬约束是"不得误判"。 **待验证假设**：无——本次范围内的全部行为均可通过单元测试直接、确定性地验证，不依赖运行期观测或线上数据。 **阻塞性未知**：无——不需要产品、业务或外部决策即可完成本次修复。 ## 7. 风险与依赖 - **风险等级：低。** 改动范围局限在单一模块新增一个异常类 + 一处 `try/except` 转译逻辑，加上测试文件补充 用例；不触及 schema、不触及部署状态机的语义定义、不改变任何模块对外的调用签名或返回值结构。 - **依赖：无新增外部依赖**，转译逻辑沿用 Python 标准库 `sqlite3` 的异常体系。 - 不涉及权限、鉴权、支付、不可逆数据变更等更高风险类别本身（部署系统虽然高风险，但本次改动不触碰其状态 机语义或副作用触发顺序，只改"冲突发生后异常长什么样"这一件事），无需额外审批门槛。 ## 8. 范围外后续事项（供后续任务参考，不在本次交付范围内） - `health_check_failed`/`rollback_failed` 是否也应该被纳入 `ux_deployment_active` 的终态集合、允许在这两 个状态下发起新部署——需要业务侧判断"健康检查失败/回滚失败之后，是否应该允许立即重新尝试部署"，涉及 01-M/04-P 状态机语义变更，不是本次 bug 修复的范围，留待独立任务讨论。 - `deploy_supervisor.py` 轮询循环如何消费本次新增的具名异常（例如是否需要针对 `ConcurrentDeploymentError` 做专门的等待重试逻辑）——本次只保证异常"存在且可诊断"，调用方的消费策略留给后续任务。