CargoMesh
面向集装箱物流的确定性交易编译器与耐久执行运行时。
我负责定义该参考系统的交易模型、执行边界、验证状态和验收策略。
- 角色
- 系统架构师与独立构建者
- 证明能力
- 这个案例证明了契约优先的平台设计、确定性领域建模、耐久工作流决策和失败关闭式验证能力。
- 技术
- Python · Temporal · DCSA contracts · Playwright
背景
集装箱物流软件位于不断变化的标准、承运人接口、浏览器回退、人工审批和难以撤销的业务动作之间。真正的问题并不是在系统之间搬运 JSON，而是在执行路径、证据来源和外部界面都可能变化时，仍然保留一笔交易的身份与意图。
CargoMesh 是一个公开参考系统，用来探索这个边界。它把固定版本的 DCSA 契约编译成确定性 Transaction IR，冻结执行计划，通过耐久工作流运行已批准动作，并在分配验证状态前记录独立来源的证据。
问题
请求成功并不等于商业结果已经得到证明。承运人接口可能在接受动作后超时，门户可能发生漂移，重试可能重复订舱，证据也可能延迟或与执行回执冲突。如果把每次适配器完成都写成成功，就会掩盖系统本来要控制的风险。
因此，设计把执行状态与验证状态分开。EXECUTED_UNVERIFIED 表示动作已经完成，但缺少足够独立证据；VERIFIED 必须有匹配证据；冲突进入 NEEDS_REVIEW；缺失、过期或不足的证据进入 HALTED。这种更窄、更诚实的状态语言比乐观的绿色勾选更有用，因为它明确说明已经知道什么、仍不确定什么，以及自动化何时必须停止。
这个案例证明什么
- 契约优先建模可以让重放和兼容性判断保持确定性。
- 耐久工作流状态可以跨进程保存审批、重试、取消和补偿。
- 独立证据可以阻止执行回执被包装成没有依据的结果声明。
关键约束
决定实现形态的约束
- 外部物流标准会变化，但已接受的交易必须能够按照当时使用的精确契约版本重现。
- 重试和补偿可能产生真实副作用，执行状态不能只依赖一次请求内的内存。
- 适配器返回成功并不足以证明预期业务结果已经发生。
核心决策
选择、替代方案与代价
先编译，再执行
- 背景
- 直接传递外部数据会让重放、迁移和策略判断依赖不断变化的模式。
- 选择
- 固定源契约，并将其编译为严格、不可变、带规范化 JSON 与摘要的 Transaction IR。
- 放弃方案
- 把外部 JSON 直接交给适配器; 在每个集成中维护非正式字段映射
- 代价
- 编译器增加了前期模式工作，但兼容性变化和执行身份因此变得明确。
复用耐久工作流运行时
- 背景
- 审批等待、重试、取消和反向补偿会跨越单次进程请求。
- 选择
- 使用 Temporal 进行耐久编排，并把适配器副作用放在明确的 Activity 边界中。
- 放弃方案
- 自建队列与状态机; 在 API 请求处理器内重试
- 代价
- Temporal 带来运行依赖，但避免重新发明更难检查的工作流引擎。
架构与失败行为
责任、输入、输出与失败行为
- 01
固定契约
冻结已接受的 DCSA 源与兼容边界。
- 输入
- 版本化标准文件
- 输出
- 已校验的本地契约源
- 失败
- 摘要或兼容性不一致时在编译前失败。
- 02
交易编译器
把业务意图规范化为确定性 Transaction IR。
- 输入
- 固定契约载荷与租户上下文
- 输出
- 规范 IR、诊断与摘要
- 失败
- 未知字段或无效谓词被明确拒绝。
- 03
执行计划
冻结依赖、审批、重试和补偿规则。
- 输入
- Transaction IR 与策略
- 输出
- 不可变有序计划
- 失败
- 策略拒绝或无法解析时停止提交。
- 04
耐久运行时
以可查询状态执行已批准的适配器操作。
- 输入
- 计划、信号与适配器绑定
- 输出
- 回执与执行状态
- 失败
- 可重试故障有上限；副作用不明确时停止并等待验证。
- 05
独立验证
用独立采集的证据核对预期结果。
- 输入
- 不可变回执与有界观察
- 输出
- VERIFIED、NEEDS_REVIEW 或 HALTED
- 失败
- 缺失、过期或冲突证据绝不会变成 VERIFIED。
失败模式
失败如何被发现、限制和升级
| 触发 | 发现与响应 | 副作用与人工边界 | 状态 |
|---|---|---|---|
| 同一个幂等键被用于不同业务意图。 | 租户范围内的摘要比较发现冲突。 拒绝第二次提交，不启动新工作。 | 冲突重放不会调用适配器。 调用方必须确认哪个意图有效。 | 已验证 |
| 门户页面与预期界面签名不一致。 | 来源、标题、标签和提示检查生成漂移签名。 停止浏览器路径，不猜测选择器。 | 配方只读、摘要固定，并在每次调用中隔离。 必须审核适配器更新后才能重试。 | 已验证 |
| 外部超时后执行结果不明确。 | 运行时记录未知副作用状态，而不是假定失败。 重试或取消前先采集独立证据。 | 有副作用的工作不会自动切换到另一条路径。 冲突证据进入 NEEDS_REVIEW。 | 已设计 |
| 后续步骤失败后，补偿动作也失败。 | 耐久计划记录反向动作失败与当前状态。 带着可查询明细停止，而不是声称回滚完成。 | 执行前已经冻结补偿顺序。 由操作人员复核未解决的外部状态。 | 已设计 |
项目证据
证据及其验证范围
架构
CargoMesh 把固定版本的物流契约编译为带版本和摘要的业务交易表示。
参考实现仅覆盖文档中已接受的交易演示。CargoMesh README——已实现范围执行路径使用 Temporal 建模审批、重试、补偿、取消与可查询状态，而不是自建工作流引擎。
本地参考运行时；真实外部生产服务不在仓库范围内。CargoMesh README——耐久运行时验证
系统区分已执行未验证、已验证、需要复核与已停止，而不是把执行当作结果证明。
确定性参考报告与独立来源的证据。CargoMesh README——验证边界披露
仓库明确区分合成适配器、本地控制边界与真实承运人、身份、支付和云集成。
公开仓库披露。CargoMesh README——实现披露真实状态
已经实现、没有声称和仍需完成
- 运行状态
- 参考系统
- 数据
- 确定性夹具与明确标记的合成交易演示。
- 外部集成
- 合成 API/浏览器适配器；真实承运人、身份、支付和云端集成不在仓库内。
- 收入声明
- 不声称真实客户流量或商业收入。
- 源码
- 公开源码
- 生产前工作
- 仍需真实适配器认证、托管身份与密钥、部署加固和独立运营审查。
集成范围: 已验收演示使用合成 API/浏览器适配器和刻意缩小的合成订舱切片；真实承运商、身份、支付与云集成不在公开实现范围内。
复盘与下一优先级
有效的选择
把执行与验证分开，让系统最重要的判断变得准确：动作可以完成，但结果尚未被证明。
会改变什么
如果重做，我会更早建立最小可验收纵向切片，只在新板块确实改变失败边界时扩展。
下一优先级
- 使用现有契约与漂移测试认证一个真实只读适配器。
- 在托管预发布边界运行耐久工作流，并外置密钥。
- 任何有副作用的生产集成前增加独立运营审查。
现在不做：在一个真实集成证明认证与支持模型前，不值得先构建大规模适配器市场。