优化
This commit is contained in:
@@ -0,0 +1,60 @@
|
||||
# Order↔Firstleg 在线依赖解环设计
|
||||
|
||||
## 结论
|
||||
|
||||
当前不能在不改变已确认产品成功时点的前提下直接实施解环，业务代码保持不变。在线图仍包含
|
||||
`Order→Firstleg` 与 `Firstleg→Order`，所以非平凡强连通分量仍是 `Firstleg↔Order`。
|
||||
|
||||
建议的最小退出方向是 **退出全部 `Firstleg→Order` REQUEST 边**。该方向只有
|
||||
`OrderCargoClient` 和 `OrderFulfillmentSplitClient` 两个客户端；Order 继续拥有订单、货物、父子订单和
|
||||
拆分台账，Firstleg 继续拥有入库、测量、分柜装柜、PDA 拣货和库位结算。完成后只保留
|
||||
`Order→Firstleg` 在线查询/门禁边以及双方后台边，在线 SCC 才会实际消失。
|
||||
|
||||
## 当前可执行调用
|
||||
|
||||
| 方向/客户端 | Controller→Service→Client→被调用入口 | 时点与调用者期望 | 失败传播 | 幂等性 |
|
||||
|---|---|---|---|---|
|
||||
| Order→Firstleg `FirstlegPricingClient` | `MerchantFirstLegOrderController`、`PlatformFirstLegOrderController` 的创建/编辑/提交 → `OrderApplicationService` → `OrderPricingChannelGuard` → `/internal/firstleg/v1/pricing/channels/validate` | 保存或提交前实时确认渠道有效；提交还必须取得入仓码前缀 | 业务错误原码上传；连接、空响应或不完整数据映射依赖不可用/冲突，订单不提交 | 纯读取 `SAFE_READ` |
|
||||
| Order→Firstleg `FirstlegUnifiedOrderClient` | `PlatformUnifiedOrderController`、`MerchantUnifiedOrderController` 列表/详情 → `UnifiedOrderQueryService` → Firstleg unified query/summaries/detail | 一个响应内组合 Order 主数据与 Firstleg 实时履约、测量、装柜和时间线 | 远端异常、失败码、空数据均失败关闭，不返回伪造履约摘要 | 纯读取 `SAFE_READ` |
|
||||
| Order→Firstleg `FirstlegInboundClient` | `MerchantFirstLegOrderController.page` → `MerchantInboundOrderListService` → references/prepareBatch；已提交订单编辑提交后 → `OrderApplicationService.prepareDraftInbound` → prepare；审核 Outbox → `OrderInboundOutboxPublisher` → create | 列表需要入库引用；草稿/待审编辑尝试同步预入库；审核成功已与 Firstleg 建单解耦 | references 失败关闭；prepare/prepareBatch 当前捕获异常并允许列表缺少入库引用，是现有失败传播缺口；审核 Outbox 持久化重试 | `tenantId+orderId` 业务键；Firstleg 对订单唯一且入仓码一致时幂等 |
|
||||
| Firstleg→Order `OrderCargoClient` | 箱号 Controller/Order 审核后台建单 → `InboundCartonLabelService`；测量 Controller/OpenAPI → `InboundMeasurementService`/`InboundMeasurementOpenApiService`；智能装柜 Controller → `SmartLoadingService` → Order cargo/snapshot endpoints | 首次箱号、测量明细、申报回填和装柜清单均要求当前订单货物事实 | 服务不可用、空数据、归属不一致均阻断当前操作；没有默认货物或空列表成功 | 纯读取 `SAFE_READ`；同时存在 REQUEST 和审核 Outbox 回调产生的 BACKGROUND 上下文 |
|
||||
| Firstleg→Order `OrderFulfillmentSplitClient` | `PlatformLoadingPdaController.complete` → `LoadingPickService.complete @Transactional` → `PdaPickSettlementService.settle` → `/internal/order/v1/fulfillment-splits` → `OrderFulfillmentSplitService.split @Transactional` | PDA 完成请求必须先取得 Order 真实余量子单 ID/单号，再在同一 Firstleg 事务写分片、测量、库位、审计并推进装柜完成 | Order 不可用或响应数量/柜次/父子关系不一致时整个 Firstleg 完成事务回滚；不得返回完成成功 | Firstleg 使用 `idempotencyKey=pda-task-{taskId}`、`operationId=PDA-SPLIT-{taskId}-{inboundId}`；Order 保存请求哈希并以唯一键重放 |
|
||||
|
||||
## 事实所有权
|
||||
|
||||
- Order：订单交易状态、订单货物及允许编辑的字段、父子订单 ID/单号、履约拆分台账和订单版本。
|
||||
- Firstleg：入库单、测量事实、分柜/装柜计划、PDA 拣货数量、库位结算、装柜证据和 `LOADING→LOADED` 门禁。
|
||||
- 允许复制的仅是带来源版本和哈希的 Order 快照；Firstleg 不得成为订单货物或父子订单的第二写入方。
|
||||
- 统一订单查询是组合读模型，不把 Firstleg 履约状态写回 Order 交易状态。
|
||||
|
||||
## 推荐退出方案
|
||||
|
||||
### 1. 先退出货物在线读取
|
||||
|
||||
复用 Order 已有 Outbox 和 Firstleg 已有订单入库接收入口，将完整货物快照、订单版本和规范化哈希随草稿准备、待审编辑和审核事件可靠投递；Firstleg 以
|
||||
`tenantId+orderId+orderVersion` 单调 Inbox/快照落库。箱号、测量和智能装柜只读本地快照，缺失、版本冲突或哈希冲突均失败关闭。
|
||||
|
||||
不能只在审核时复制一次：当前契约允许 `LOADED` 前按权限和状态修改业务资料。必须先冻结货物在哪个节点停止修改，或要求每次允许的 Order 编辑都可靠发布版本事件，并明确 Firstleg 在投影落后期间阻断哪些操作。
|
||||
|
||||
### 2. 再将履约拆分改为可靠后台命令
|
||||
|
||||
Firstleg 在本地持久化稳定 operation/idempotency key、数量行、柜次和请求哈希；后台 Relay 调用现有 Order 幂等拆分接口并保存完整响应。Order 现有拆分台账和唯一键可承担 Inbox/业务幂等，不需要新服务或 MQ。
|
||||
|
||||
Firstleg 只有在后台结果为 `READY` 且父子关系、数量和柜次全部校验通过后，才能消费余量子订单 ID并执行本地结算。失败进入可诊断重试/DEAD，禁止默认成功。远端成功、本地未完成时只允许向前恢复，不得自动删除 Order 子订单。
|
||||
|
||||
这一方案会引入技术态 `PENDING/READY/FAILED`，但不能擅自增加产品主状态。若在 PDA 首次点击完成时只创建任务并返回待处理，成功时点发生变化；若提前创建 Order 子单，则子单可能在装柜硬门禁完成前可见，同样改变现有语义。
|
||||
|
||||
## 必须由产品冻结的决策
|
||||
|
||||
1. **货物冻结点**：Order 货物在审核通过、首次生成箱号、确认测量还是确认预装后不可再改；若仍允许修改，哪些 Firstleg 操作必须等待最新 `orderVersion` 投影。
|
||||
2. **PDA 完成成功时点**：必须继续在一次请求中同时完成 Order 子单与 Firstleg 结算，还是允许首次请求返回“处理中”，后台完成后才成为 `LOADED`。同时确认后台已创建 Order 子单但 Firstleg 最终失败时采用持续向前修复，不提供在线冲正。
|
||||
|
||||
上述任一决策未冻结前，不实施业务解环。
|
||||
|
||||
## 最小实施与验证边界（决策冻结后）
|
||||
|
||||
- Order：扩充版本化货物快照 Outbox；保留 `OrderFulfillmentSplitService` 事实所有权和现有幂等唯一键。
|
||||
- Firstleg：货物快照 Inbox/表、拆分命令 Outbox/Relay/诊断查询；替换两个在线 Client 的业务调用点。
|
||||
- SQL：仅更新当前模块基线与统一增量，不引入 Flyway/Liquibase，不执行 SQL。
|
||||
- 合同：证明生产请求路径不再引用两个客户端、`Firstleg→Order` 只剩 BACKGROUND，REQUEST SCC 中不再出现两者同一分量。
|
||||
- 测试：Order/Firstleg 全量直接测试、重复/异哈希事件、租约恢复、远端成功本地失败重放、DEAD 人工重试、PDA 未 READY 失败关闭，以及同步依赖合同。
|
||||
@@ -26,7 +26,7 @@
|
||||
| IAM | Event Bridge | 1 | 安全事件中继，`BACKGROUND` |
|
||||
| Order | Firstleg | 3 | 计价/统一订单查询为 `REQUEST`，入库协作为 Outbox `BACKGROUND` |
|
||||
| Order | IAM / File / Warehouse | 各 1 | 资格、图片、仓库守卫，`REQUEST` |
|
||||
| Firstleg | Order | 2 | 货物查询与分拆回写，`REQUEST` |
|
||||
| Firstleg | Order | 2 | 货物查询同时存在 `REQUEST/BACKGROUND`；PDA 履约分拆为 `REQUEST` |
|
||||
| Firstleg | IAM / Finance / Integration / Event Bridge / Print | 各 1 | IAM、Integration、Print 为 `REQUEST`；Finance 与 Event Bridge 为 `BACKGROUND` 中继 |
|
||||
| Firstleg | File | 7 | 测量、装柜、凭证、报关、拖车等，`REQUEST` |
|
||||
| Firstleg | Warehouse | 4 | 主数据、供应商、库位/托盘，`REQUEST` |
|
||||
@@ -79,9 +79,9 @@
|
||||
|
||||
后台图包含 Outbox/Inbox、导出 Worker 和定时任务，当前强连通分量为：
|
||||
|
||||
`Event Bridge ↔ Firstleg ↔ Finance ↔ Lastleg`
|
||||
`Event Bridge ↔ Firstleg ↔ Finance ↔ Lastleg ↔ Order`
|
||||
|
||||
File 的五个导出 Provider、Order→Firstleg 入库 Outbox、IAM 默认尺寸可靠任务、IAM 安全 Outbox、Firstleg/Lastleg 跨区 Outbox、Firstleg→Finance 费用 Outbox及 Event Bridge 三个消费者均只在后台图中计算。Event Bridge→Lastleg Security 与 Event Bridge→Lastleg 业务事件在服务图上收敛为同一条后台服务边，不形成新的在线业务边或独立安全节点。
|
||||
File 的五个导出 Provider、Order→Firstleg 入库 Outbox、该入库消费者为生成箱号而回读 Order 货物的后台回调、IAM 默认尺寸可靠任务、IAM 安全 Outbox、Firstleg/Lastleg 跨区 Outbox、Firstleg→Finance 费用 Outbox及 Event Bridge 三个消费者均只在后台图中计算。Event Bridge→Lastleg Security 与 Event Bridge→Lastleg 业务事件在服务图上收敛为同一条后台服务边，不形成新的在线业务边或独立安全节点。
|
||||
|
||||
### 全图
|
||||
|
||||
@@ -108,6 +108,10 @@ File 的五个导出 Provider、Order→Firstleg 入库 Outbox、IAM 默认尺
|
||||
|
||||
`IAM → Firstleg` 的 `CustomerDimensionRuleClient` 默认尺寸初始化已经从 REQUEST WRITE 改为可靠后台编排。IAM 与客户主档同事务持久化稳定 `initializationKey` 的任务，显式维护 `PENDING/READY/FAILED`，由租约调度重试并提供诊断查询和人工重试；审批通过与下单资格在未 READY 时失败关闭。此边现在仅属于 BACKGROUND，在线五服务强连通分量实际拆为 Auth↔IAM 与 Order↔Firstleg 两个子环，未触碰财务、Event Bridge 或四期业务状态机。
|
||||
|
||||
### Order↔Firstleg 第二阶段结论
|
||||
|
||||
具体入口、所有权与可执行退出方案见 `docs/Order-Firstleg在线依赖解环设计.md`。当前 `COMPLETE_LOADING` 在 Firstleg 本地事务中同步取得 Order 余量子单后才完成结算，且 Order 货物在 `LOADED` 前仍允许修改；成功时点和货物冻结点尚未冻结，因此本阶段不改业务代码。REQUEST SCC 仍为 `Firstleg↔Order`，合同明确阻止仅改变分类却未退出生产调用的伪解环。
|
||||
|
||||
## 退出顺序
|
||||
|
||||
1. **冻结与分层。** 先用清单合同阻止未评审新边；为每个客户端补齐 `REQUEST/BACKGROUND/INFRASTRUCTURE/EXTERNAL`、读写语义、幂等键和失败映射。这个阶段不改变业务状态。
|
||||
|
||||
Reference in New Issue
Block a user