weichenandCursor
7647215513
Move the reviewed durable-event, HTTP envelope, and PI typed-result designs off the docs/ prefix so Track E can start from latest dev. Co-authored-by: Cursor <cursoragent@cursor.com>
6.5 KiB
title, status, created, updated, severity
| title | status | created | updated | severity |
|---|---|---|---|---|
| 模块解耦 Phase 2 方案审阅 | done | 2026-09-15 | 2026-09-15 | high |
模块解耦 Phase 2 方案审阅
结论
模块化单体、消费者端口、组合根和持久事件的方向成立，但原 Phase 2 方案不能直接进入实施。它把事件可靠性、结构整理和两个外部协议绑成一个完成目标，并基于数项不成立的代码事实设计切换门。修订版已把 Track E（持久事件）、Track S（结构解耦）、Track P（外部协议）拆开，Track E 必须先完成生产者与历史数据门，再启动 dispatcher。
高优先级发现
A1. PG delivery 尚未形成生产闭环
internal/events/pg.go 的 ClaimIDs 只做 SELECT + FOR UPDATE SKIP LOCKED，没有在同一事务写 lease owner/token/until；也没有 PG ack/fail/retry/dead-letter 的完整生产实现。internal/events/dispatcher_test.go 验证的是 MemoryBus。原方案把这些能力写成“已有”，会低估 D1 的 migration、状态机和故障测试范围。
整改：D1 增加 additive migration、原子 lease、heartbeat、fenced side-effect/ack、retry/dead/quarantine、不可变 attempt 表和独立 cmd/events 进程。
A2. “恰好一次投递”不可由当前算法保证
副作用成功后、ack 前崩溃会导致重放。Fencing 若只拦 ack，也拦不住租约过期的旧 worker 提交副作用。
整改：契约改为 at-least-once delivery + exactly-one visible outcome。Token 进入 consumer command 和最终提交点；数据库副作用与 inbox/token 校验同事务，projection 使用 expected version、digest 和单调 marker。
A3. 原 shadow 定义会双写，且按天零差异可空跑通过
旧方案同时写闭包和消费者结果，却又称“不产生可见变化”；两者矛盾。三天 dev 流量也可能没有低频文档事件或失败分支。
整改：闭包是 shadow 期间唯一真实写者。消费者只计算 normalized intended outcome 并写 reconciliation。停走门同时要求预登记样本、分支覆盖、最短时间和零未解释 diff；生产入口未证明出事件前不开始计时。
A4. 文档事件源与作用域尚不可信
部分生产 HTTP 路径临时构造 docflow.Commands，没有稳定注入 EventSink/UoW。Environment:"dev"、ProjectID:0 和 FAV stage project 0 会使跨环境/项目 delivery 失真。
整改：E0A 先由组合根注入唯一命令对象；领域变化、envelope、delivery 同一 UoW；缺 project/env fail closed；旧数据先 inventory。
A5. AggregateVersion 不能直接当无缺口事件序号
当前只在部分领域转换发事件。历史文档首次事件可能从较高版本开始；按缺号等待会永久阻塞。
整改：D11 在独立 event sequence 与 consumer checkpoint/bootstrap 中二选一，审计现有 aggregate/version 唯一约束并迁移。未决前禁止开启 gap blocking。
A6. docgov/docrevision 不是双向 import
生产方向为 docgov → docrevision，用途集中在 canonical Markdown 与 SHA helper。原方案“提升无行为类型到 vocabulary”不能承载 canonicalization 行为。
整改：D6 改为提取内聚 doccontent 行为模块和 golden vectors；D6 可独立执行，不依赖 bizdev/stageflow。
A7. event allowlist 已存在
module-boundaries.yaml 已有 event_producers/event_consumers。问题是映射稀疏，且运行时注册没有与静态清单做 parity 检查。
整改：D10 提升到 E0A，补 payload schema/version、enabled state 与 registry parity；FAV 标记 disabled。
A8. FAV、HTTP、PI 不应阻塞核心
FAV 分支未完成独立审计。ADR 已把 HTTP 错误信封和 PI result protocol 定义为独立工作。把三者放入 Track E DoD 会延迟最有价值的刷新恢复闭环。
整改：Track E 只激活 notify、workflow advance、projection。FAV 只预留 disabled 契约；D8/D9 分别另建 remediation。
A9. Replay、后台权限与日志脱敏不足
延迟事件不能沿用历史用户权限；当前 replay 校验不足以支持生产 apply。Raw payload/error 进入 dead-letter 或 reconciliation 会泄露正文、路径或凭证。
整改：每 consumer 独立 service principal，处理时重读资源和当前权限。Replay 采用 capability + 精确范围 + dry-run digest/apply exact digest + 审计；多项目/批量 apply 两人批准。日志只存 ID/digest/typed code/sanitized summary。
A10. 滚动切换缺少集群级权威写者
删除新版本 hook 不会阻止旧实例继续执行。若 dispatcher 同时 live，滚动部署会双写。
整改：off|shadow|live 使用带 revision 的集群级状态；先部署兼容代码、drain 全部旧实例、记录 backlog 水位，再原子切换。回滚先暂停 claim并核对 receipt/backlog。
A11. Locator 门禁原文过宽
全局禁止 *pgxpool.Pool/pgx.Tx 会拦截组合根注入与登记表属主的合法 UoW unwrap。
整改：只禁止领域/用例 API 暴露、返回、转发 pool/tx；明确允许 app/cmd 构造注入和登记属主 unwrap。
范围修订
| 轨道 | 内容 | 关闭条件 |
|---|---|---|
| Track E | D1/D2/D3/D10/D11 | PG + browser + restart + auth/replay 证据完成后独立关闭 |
| Track S | D4/D5/D6/D7a/D7b | 各单元独立 go/no-go 与报告 |
| Track P | HTTP error、PI typed result | 各自独立 remediation，不阻塞 Track E/S |
关联整改
审阅方法与证据
- 代码证据：
internal/events/pg.go、bus.go、dispatcher_test.go、replay.go、internal/app/docflow/commands.go、internal/docgov/lease.go、internal/bizdev/service.go。 - Schema：
deploy/postgres/goose/00035_2026-09-14-durable-event-delivery.sql。 - 边界：
.doc/system-design/module-boundaries.yaml。 - 上位决策：模块化单体 ADR 与 Phase 1 U6。
- 审阅视角：一致性、可行性、范围、安全、产品价值、对抗失败预演；外部 reviewer 的有效结论仅用于交叉验证，不替代仓库证据。
开放问题
以下问题必须由 E0A 的代码/数据审计回答，不能在计划阶段猜测：
- projection consumer 的最终 owner 与 no-replace 提交接口。
- event sequence 或 checkpoint/bootstrap 的选择及迁移成本。
- 每类事件前 7 天基线流量、shadow 样本 N 和 worker 连接预算。
- 现存错误 scope/schema delivery 的数量和 repair/quarantine/expire 分类。