23 KiB
title, type, date, product_contract_source, execution
| title | type | date | product_contract_source | execution |
|---|---|---|---|---|
| 通用模块平台封装与渐进采用 - Plan | docs | 2026-09-22 | ce-plan-bootstrap | knowledge-work |
通用模块平台封装与渐进采用 - Plan
Goal Capsule
让未来项目在新增功能和处理故障时，能够围绕明确的模块职责、通信契约与数据 owner 独立工作，并通过可重复验证判断问题是否被限制在约定范围内。
采用通用模块契约规范 MCS v0.1，以最小参考实现和故障验收推动平台封装。当前授权仅为现状研究、规范和方案编制；本文后续开发单元是建议工作，不是已启动的实施。
当前项目证据来自解耦现状审查。通用规范独立复用，不依赖本项目的业务对象、路径或运行工具。本项目的既有 ADR/开发标准继续生效。
Product Contract
Problem Frame
模块分目录、共用接口和使用消息总线后，仍可能因共享数据、入口旁路、类型泄漏、慢消费者和不一致的失败语义发生连带问题。全面网络化又会增加超时、重复执行、部署和一致性成本。因此需要“职责与契约强约束 + 分档运行隔离 + 可证明的一致性”，并把横切能力封装复用。
Requirements
边界与复用
- R1. 通用标准必须可用于不同语言和业务，项目现状证据独立存放。
- R2. 每个模块有职责、公开契约、数据 owner、不变量和目标隔离档位。
- R3. 同一业务动作的不同入口保持授权、持久结果与事件语义一致。
- R4. 统一封装覆盖共性通信治理，业务规则留在模块和显式编排中。
一致性与隔离
- R5. 命令、查询、事件、流有不同成功/失败语义；网络未知结果可恢复。
- R6. 数据 owner、事务、幂等、顺序与租约共同保证已声明的不变量。
- R7. 慢任务、错误、过载和进程崩溃在所选隔离档位下有明确影响范围。
- R8. 并发/故障/兼容测试是验收的一部分，不能只靠静态依赖检查。
落地范围
- R9. 先建立小型可验证参考实现，再推广到第二个场景；不先造完整微服务平台。
- R10. 本次只交付待审文档，业务实施、平台仓库创建、外部发布和环境操作留待单独授权。
Acceptance Examples
| ID | 例子 | 验收结果 |
|---|---|---|
| AE1 | 两个入口提交相同授权动作 | 持久状态与事件一致，拒绝边界相同；覆盖 R3 |
| AE2 | 并发重复/响应丢失后重试 | 单一业务效果、结果可查询；覆盖 R5/R6 |
| AE3 | 慢消费者 + 其他消费者持续工作 | 后者仍达到约定延迟预算；覆盖 R7 |
| AE4 | 首条高版本、乱序和过滤订阅 | 按明确契约推进，不误把空洞当丢失；覆盖 R6 |
| AE5 | 新旧契约混跑与失败回退 | 无数据丢失或旧客户端误解释；覆盖 R8 |
| AE6 | 参考实现替换传输适配器 | 业务不变量相同，额外网络失败行为显式呈现；覆盖 R4/R5 |
Scope Boundaries
本次文档范围包括：当前实现审查、通用标准、统一封装设计、验证与推广计划。规范本文不指定云厂商、消息产品或全项目微服务化。
后续工作建议分两条线：
- 通用平台线：模板、契约与参考 SDK/适配器/可靠投递套件，放在未来独立模板或平台仓库。
- 当前项目线：优先修复已核实的契约偏差与旁路，再按原 A–G 计划收敛依赖。以单独任务认领，继续遵守项目 ADR。
跨区高可用、全部语言 SDK、通用可视化流程平台、service mesh、复杂 broker 拓扑均延后到实际需求证明价值。它们不是第一版完成条件。
Planning Contract
Key Technical Decisions
- KTD1. 以契约和数据 owner 划分模块，以资源/信任要求划分进程。 实现 R2/R7；简单业务默认 L1，必须隔离 OOM、非可信插件或重计算选 L2 以上。既不强制每功能一个服务，也不禁止合理拆分。
- KTD2. 统一治理入口采用薄 SDK 与适配器，事件采用持久总线。 实现 R4/R5；Query/同步 Command 可直接访问提供方，经过同样的策略中间件。总线不做所有调用的中心转发服务器，避免放大共享故障点。
- KTD3. 长任务调度归持久业务编排器。 实现 R4/R6；平台提供任务/lease/receipt 原语，流程步骤、补偿和领域规则由用例定义。
- KTD4. 一致性分成本地原子事务与跨域恢复协议。 实现 R6；共库 UoW 和 outbox 是一种部署模式，跨进程使用 outbox/inbox 与 Saga。不能用一个“透明 RPC”承诺两者等价。
- KTD5. 可靠投递默认至少一次，幂等由效果 owner 完成。 实现 R5/R6；借鉴官方 outbox 与幂等 API 原理，具体规则以 MCS-11/13 为准。外部效果的未知结果走查询对账。
- KTD6. 业务版本与消息序列分开。 实现 R6；现状 A1 已显示混用风险，按 MCS-15 显式选择快照、可交换、严格增量三种语义。
- KTD7. 第一版只做一套最小组合。 实现 R9；建议 Go 参考 SDK + 进程内 + HTTP/JSON + PostgreSQL durable delivery。理由是足以验证类型、跨进程失败、事务和恢复，也可复用现有源码经验。该选择只作用于参考实现，规范不要求所有项目使用 Go/PG。
- KTD8. 门禁分层并报告未覆盖项。 实现 R8；静态边界、schema 兼容、真实数据库并发、真实传输故障和运行隔离各自提供证据，不用单个 arch-check 宣称全覆盖。
选择 HTTP/JSON 是第一版的可检查性与通用接入选择，不是性能判断。gRPC/UDS 在强类型多语言或本机进程需求出现后增加；WebSocket 留给双向流；SSE 面向单向 UI 通知。每次增加适配器都跑相同业务契约和该传输特有故障测试。
Alternatives
| 方案 | 收益 | 代价 | 决策 |
|---|---|---|---|
| 所有功能独立 HTTP 服务 | 独立进程/发布机会 | 同步链、运维和事务复杂性高 | 只用于已证明需要独立隔离的模块 |
| 所有调用经过中央 bus 服务 | 集中路由与监控 | 单点、语义弱化、延迟和共享瓶颈 | 不采用为通用默认 |
| 只用进程内接口 | 简洁、高效、本地事务 | 无崩溃/资源隔离 | 作为 L1 档 |
| 显式契约 + 可替换适配器 + 持久事件 | 按风险演进、可验证 | 需要契约治理和一致性测试 | 推荐 |
| 立即部署复杂消息集群 | 扩展能力丰富 | 缺容量证据、增加运营成本 | 达到触发条件后评估 |
消息基础设施第一版可用事务型数据库队列。若多服务解耦、积压量、重放规模或独立吞吐突破数据库预算，再比较 NATS JetStream、RabbitMQ、Kafka 或云队列；选择需按顺序语义、retention、运维能力与真实 benchmark，而非流行度。即使 broker 提供去重，也仍须 MCS-13 的业务收据。
High-Level Technical Design
系统组件和持久交付时序以规范 §3、§6 两张图为准。平台发布时按能力拆包，业务模块只依赖最小集合。
flowchart TB
Contract["U1 契约与设计卡"] --> SDK["U2 调用治理与适配器"]
Contract --> Data["U3 本地事务与幂等"]
SDK --> Event["U4 可靠事件消费"]
Data --> Event
Event --> Schedule["U5 持久调度与隔离"]
Contract --> Gates["U6 自动门禁"]
SDK --> Gates
Event --> Gates
Schedule --> Gates
Gates --> Pilot["U7 第二场景试点"]
Pilot --> Release["U8 发布与推广"]
Output Structure
下面是未来独立参考仓库的建议相对路径，不是本仓库将要新增的业务文件，也不是对已存在文件的声明：
spec/
module.schema.json
operation.schema.json
errors.yaml
compatibility.md
templates/
module-card.md
contract.md
failure-model.md
sdk/go/
contract/
invoke/
transport/inprocess/
transport/http/
persistence/postgres/
delivery/
scheduler/
conformance/
fixtures/
contract_test.go
concurrency_test.go
delivery_test.go
isolation_test.go
examples/
reservation/
projection/
webhook/
ci/
boundary-rules.yaml
runbooks/
recovery.md
release.md
样例使用“资源预留 → 查询投影”展示可恢复工作流，无真实付费或外部通知副作用。外部效果另用可查询、支持幂等的本地 webhook 接收进程验证故障窗口。示例不使用本项目的文档审批等术语。
Assumptions and Deferred Decisions
- 文中的“数据库和所”按“数据库和锁”理解；规范已区分唯一约束、事务、CAS、锁和 lease 的作用。
- 新项目的业务规模、语言和运维环境尚未指定，当前不承诺吞吐、时限和工程工期。
- 参考语言 Go 是建议起点，可在实施立项时替换；稳定 IDL、测试向量和语义仍然保留。
- 未来平台仓库路径/owner、首个试点系统、业务 SLO 和外部副作用种类是实施启动前必填项。不阻塞本次方案交付，但没有这些信息不得称平台已经实施就绪或直接开工。
Implementation Units
所有 U 单元均为后续建议。每单元以独立可验收结果收口，代码与其必要回归测试同批提交，避免先搭完框架再验证。
U1. 契约与模块设计模板
目标/需求：实现 R1/R2/R5。把规范落实为模板与可校验 manifest，先明确人读语义与机器字段的对应关系。
依赖：实施前选择试点与 owner。
文件：spec/module.schema.json、spec/operation.schema.json、spec/errors.yaml、spec/compatibility.md、templates/ 三份模板、conformance/contract_test.go。
做法：模板覆盖 MCS-02/08，manifest 声明能力及 N/A 理由，不生成业务方法大全。契约给出资源预留命令、预留状态查询、预留完成事件三个相互关联样例；事件信封版本与 payload 版本分开。OpenAPI 与事件 schema 来源单一。
测试场景：
- 缺 owner/数据边界/错误语义的 manifest 拒绝。
- 未知 major、字段改类型、枚举扩展按兼容策略发现差异。
- 新增可选字段时旧消费者仍能处理。
- Contract DTO 不引入业务实现/数据库类型。
验收：新开发者仅依据设计卡能判断谁可调用、写什么、失败怎么恢复；schema 工具只能证明的部分在报告中标出。
U2. 统一调用治理与两种适配器
目标/需求：实现 R3/R4/R5，覆盖 AE1/AE6。
依赖：开发依赖 U1，可与 U3 并行；涉及 committed/unknown 持久结果查询的最终验收依赖 U3。
文件：sdk/go/contract/、invoke/、transport/inprocess/、transport/http/；conformance/contract_test.go，新增 conformance/transport_test.go。
做法：显式注入类型化客户端；统一身份、deadline、错误、trace、大小限制和取消。进程内与 HTTP 共享业务契约，HTTP 单独暴露断连/未知结果，不模拟成无失败本地函数。
测试场景：
- 两入口相同输入产生相同业务结果及拒绝边界。
- 下游超时，剩余预算向下传播，不叠加完整超时。
- 超大请求、未知字段策略、伪造租户和错误 envelope 均按契约处理。
- HTTP 提交后响应中断，返回/记录 unknown 并能按 operation 查询。
- 客户端取消后已提交结果不被假称回滚。
验收：替换适配器不修改业务不变量测试；业务入口不依赖整个 Runtime 或公共万能 Store。
U3. 单写者、事务和幂等收据
目标/需求：实现 R6，覆盖 AE2。
依赖：U1；可与 U2 并行开发，集成时统一契约。
文件：sdk/go/persistence/postgres/；examples/reservation/；conformance/concurrency_test.go，新增 conformance/idempotency_test.go。
做法：以唯一约束、expected_version 和同事务结果收据维护预留不变量；UoW 不穿越网络。无副作用的领域计算与提交校验分开。提供单次命令结果收据及按幂等键/operation_id 的授权查询；U5 在其上管理多步骤流程状态。
测试场景：
- 同键并发 100 次，仅一个效果且所有成功重放得到等价结果。
- 同键异摘要冲突；不同键抢同版本只有一个成功。
- 数据变更与结果收据中途失败一起回滚。
- 序列化失败重跑完整事务，但不重放事务外副作用。
- 收据到期、迟到重试与业务唯一号保护符合契约。
验收：真实独立数据库下验证并发与回滚；每种表/资源只有一个 owner，不以进程 mutex 验收。
U4. Outbox、消费者收据与顺序策略
目标/需求：实现 R5/R6/R8，覆盖 AE2/AE4。
依赖：U2/U3。
文件：sdk/go/delivery/、examples/projection/、examples/webhook/；conformance/delivery_test.go，新增 conformance/recovery_test.go。
做法：按 MCS-11/13/14/15 实现持久投递、按订阅者状态、短事务认领、token 校验、失败分类和受控重放。发布与消费入口均验证 schema/来源/租户；去重比较摘要。
测试场景：
- DB commit 后 relay 崩溃，重启仍交付；事务回滚不交付。
- 效果提交后丢 ack，重复投递不重复效果。
- 首条版本 42、42→47、重复/乱序、部分订阅按所选策略工作。
- 同事件 ID 异 payload 被拒绝；错误生产身份/未知 schema 隔离。
- worker 旧 token ack 和旧版本写入均拒绝。
- webhook 已完成但回执丢失，经同键/查询恢复，不能再次执行。
- 重放超出效果收据保留窗口，系统拒绝或走明确恢复流程。
验收：真实独立进程、数据库与传输故障证据齐全；不能以 MemoryBus 通过代替本单元。
U5. 持久调度与资源隔离
目标/需求：实现 R4/R7，覆盖 AE3。
依赖：U4。
文件：sdk/go/scheduler/、sdk/go/delivery/；conformance/isolation_test.go，新增 conformance/scheduler_test.go；runbooks/recovery.md。
做法：为两步预留/投影流程保存 operation/step 状态；有界并发、独立消费者执行槽、公平调度、停止领取与排空。高风险执行器进独立进程。业务补偿由示例模块显式提供。
测试场景：
- 一个消费者阻塞，其他消费者达到试点声明的延迟预算。
- 预取任务尚未执行就租约过期，不导致未受控并发效果。
- 任务运行中进程终止，另一个 worker 接管；旧 worker 恢复后不能写入。
- 重复定时触发、重复取消、补偿失败均有稳定持久状态。
- 过载有背压且 accepted 只用于已可靠保存的工作。
- 停机排空超时后任务可恢复，进程 liveness 与业务进度分别反映。
- 不可信执行器无法读取宿主凭证、访问未授权业务路径或直连未授权数据服务；测试使用合成秘密与隔离数据。
验收：记录故障域、负载和指标；L1 仅证明逻辑隔离，L2 场景必须杀实际子进程验证。
U6. 架构与契约门禁
目标/需求：实现 R2/R8，覆盖 AE5。
依赖：U1；最终验收依赖 U2–U5。
文件：ci/boundary-rules.yaml、spec/compatibility.md、conformance/fixtures/；新增 conformance/boundary_test.go 和 conformance/compatibility_test.go。
做法：依赖方向、内部类型引用、数据 owner、schema diff、消费者兼容与真实故障套件分开报告。语言 AST 负责静态边界，数据库 role 负例验证运行权限；不能仅正则扫描就宣称阻止所有动态 SQL。
测试场景：
- 故意引入内部实现依赖和模块环，门禁失败。
- 越 owner 写表的普通运行身份被数据库拒绝。
- 扩字段、改类型、旧消费者枚举不兼容给出明确结果。
- 例外过期、基线增加、未执行关键测试不能生成全绿报告；经能力核对的 N/A 与适用但未执行的 SKIP 分开。
验收：每项 enforced 有正负例与工具版本；提供静态/运行未覆盖说明。
U7. 第二业务场景与采用验证
目标/需求：实现 R1/R9。
依赖：U6。
文件：在未来试点仓库新增模块设计卡、契约和 conformance 映射；参考仓库新增 examples/second-domain/ 与 conformance/adoption_test.go。确切业务路径待试点确定后补充，当前不假定存在。
做法：选择与资源预留不同的真实场景，记录 SDK 引入的代码量、学习成本、业务接口数量、部署需求与故障定位耗时。优先复用原语，不复制第一个业务模型。
测试场景：
- 第二场景无需 import 第一个示例的实现。
- 同样的重复、取消、失败恢复测试向量能够复用。
- 必须增加的扩展点有两个实际调用场景，避免预先制造万能框架。
验收：证明封装具有跨场景复用价值；否则收缩平台表面并改模板，不能直接全项目推广。
U8. 版本发布与渐进推广
目标/需求：实现 R8/R9。
依赖：U7。
文件：runbooks/release.md、runbooks/recovery.md、spec/compatibility.md；新增 conformance/upgrade_test.go。
做法：按版本发布契约、SDK、适配器和测试向量，声明支持矩阵。迁移一条纵向能力后再推进下一条；采用 expand/contract，不双写两套权威状态。
测试场景：
- 新旧 SDK/服务混跑可处理兼容请求与积压旧事件。
- 业务提交后回退程序版本，状态与事件仍可读取，不删收据制造重放。
- 从备份恢复后，外部不可逆副作用通过对账处理。
- 操作人员可按手册处理 DLQ、unknown operation 和失效租约。
验收：版本支持期、升级/回退与恢复责任明确，完成的试点才进入推广。
Verification Contract
实施验证分五层：纯领域/公开用例、进程内与 HTTP 契约、独立数据库并发、真实进程交付故障、试点用户端到端。每层独立报告，SKIP/未运行不得计 PASS。
| 单元 | 核心证据 | 失败时处理 |
|---|---|---|
| U1/U2 | schema/兼容与同一动作不同入口结果 | 修契约或适配器，不改业务含义掩盖差异 |
| U3 | 并发竞争、事务与收据回滚 | 停止引入更多消费者 |
| U4 | 崩溃/重投/稀疏版本/错误来源 | 保留 delivery 与诊断，不清库重来 |
| U5 | 慢任务、过载、旧 worker 复活、排空 | 降低领取/并发，调整隔离，重测受影响预算 |
| U6 | 人为违规负例与测试缺项拒绝 | 不标 enforced |
| U7/U8 | 第二场景、混跑、恢复与操作手册 | 不扩大推广范围 |
测试记录必须包含源版本、制品、运行拓扑、配置摘要、预期场景、实际执行、失败/重试和证据位置。容量目标由试点 SLO 确定后固化，不能凭方案给出未经测量的“毫秒级”“零影响”。
Current Project Adoption
这部分是当前项目的映射附录，不属于跨项目通用标准。保持既有模块化单体 ADR，后续如拆进程另提 ADR 和授权。
| 顺序 | 目标与现有路径 | 建议新增/扩展验证 | 关联 |
|---|---|---|---|
| CP1 | events/dispatcher.go 对齐首事件 bootstrap；校验所有 producer 的版本语义 | dispatcher_pg_test.go：首条高版本、跳版本、部分订阅；pg_test.go 不再固化矛盾规则 | 审查 A1、MCS-15 |
| CP2 | chat/action_executor.go 汇入 app/docflow.Commands；检查所有批准/提交入口 | chat/action_executor_test.go（新增或扩展）、server HTTP/真实对话批准：状态+事件+下游一致 | A2、MCS-04 |
| CP3 | events 的发布/消费 schema、producer 与 digest 冲突校验 | events/envelope_test.go、pg_test.go、dispatcher_pg_test.go：非法来源/字段/同ID异摘要 | A3/A5 |
| CP4 | events worker 分消费者预算，按容量 claim，补监控 | events/worker_isolation_test.go（计划新增）、真实 PG/多进程慢消费者与 lease 测试 | A4/A5 |
| CP5 | 原 A/B/C/D/G 收敛 server 装配、契约类型、workflow 方向与数据/文件 owner | 对应公开用例特征测试与逐项删除例外的静态证据 | 原 A–G 计划 |
| CP6 | 原 F 收敛前端 client/状态 owner，再按需做 E 文件拆分 | web API 错误/取消测试、受影响真实页面验收 | B4/B5 |
CP1–CP4 先验证事实和修复原契约，不以本方案自动修改生效 ADR；各项都需实施任务。CP5 保留原批次 owner 与 mutex，避免同名领域同时两套重构。文件长度用于定位，不以拆文件作为解耦验收。
项目现有业务与 PG 事务边界尚可受益于 L1 收敛，不建议先做全模块 HTTP 化。优先独立执行器/解析器等高资源或高风险边界时，另补权限、artifact owner、取消和恢复契约。
Risks and Operating Model
| 风险 | 约束/缓解 |
|---|---|
| 总线成为万能业务引擎 | 按 MCS-07 分开路由、投递、编排和领域逻辑 |
| SDK 大版本导致全部模块同时升级 | 最小依赖包、兼容矩阵、协议和实现分版 |
| 共享 DB 成为隐式通信 | owner、运行权限与投影，跨域查询例外有期限 |
| 锁 TTL 被误认为排他完整证明 | MCS-14 要求资源端拒绝旧写，外部 API 另用幂等/对账 |
| 为统一协议消除所有业务差异 | 统一技术语义，业务输入输出分模块定义 |
| 推广早于真实恢复证明 | U7 第二场景后才进入 U8 |
| 通用规范覆盖本项目现行规则 | 规范保持 proposed，采纳必须有适用范围和生效版本 |
| 过度工程影响交付速度 | 第一版限制适配器数量，每个扩展点有实际场景 |
职责建议：模块 owner 负责不变量与契约；平台 owner 负责 SDK、投递和兼容工具；运维负责容量、故障演练与恢复；集成/评审者核对端到端跨模块行为。小团队可兼任，责任不能空缺。
不提供缺乏人员与容量输入的固定工期。排期按 U1 → U2/U3 → U4 → U5/U6 → U7 → U8 的依赖推进，各阶段先验收再扩大范围。
Definition of Done
本次研究交付：现状报告明确源码证据与未验证范围；通用规范脱离本项目仍完整可读；本方案列明统一封装边界、技术选择、工作单元、故障测试与采用顺序；文档链接、状态与审阅记录可核对。
后续平台交付：U1–U8 对应证据齐全、第二场景验证通过、运维恢复和兼容矩阵可执行。模块故障隔离只按已实测档位声明。
当前项目改造交付：按获授权 CP 任务范围分别验收，不能用本次文档交付代替代码、PG、真实产品 Runner 或浏览器证明。
Sources
机制依据和官方链接已放在通用规范相应条款：gRPC deadline/retry、OpenAPI/AsyncAPI、CloudEvents、PostgreSQL 行锁、AWS outbox/幂等 API。它们支持机制选择，不直接证明本项目运行表现。项目落点与证据来自同批现状报告。
可能相关的现有文档包括模块开发标准、module-boundaries.yaml、模块化单体 ADR、checkpoint ADR、09-20 A–G 计划及验证契约。只有后续实施真正改变它们的声明时才更新，不在此次方案中预先把能力记完成。