重构(半自动履约): 收敛状态同步并拆分任务服务

This commit is contained in:
yml
2026-11-18 14:35:15 +08:00
parent aa3743f39f
commit f76b9c452d
29 changed files with 3362 additions and 2570 deletions
@@ -3,14 +3,14 @@ type: 权威架构与实施计划
description: 订单、内部 SKU、履约路由、履约执行、商品、成本与财务的唯一权威口径及重构计划。
tags: [订单, 内部SKU, 履约, 商品, 成本, 财务, 迁移]
status: authoritative
version: 2.24
updated_at: 2026-11-15
version: 2.25
updated_at: 2026-11-18
---
# 统一订单、履约与财务模型
> 状态:**唯一权威文档**。
> 最后校准:2026-11-15。
> 最后校准:2026-11-18。
> 生产基线:迁移 `166`。
> 开发基线:迁移 `167`(仅本地,尚未部署生产)。
>
@@ -371,7 +371,18 @@ manual fulfillment
- 客服完成半自动任务必须与 `confirmManualFulfillment` 在同一数据库事务中提交:
成本快照、钱包扣减、履约状态和 `semi_auto_tasks` 完成状态必须全部成功或全部回滚;
事务提交后才执行报表刷新、Connector 会话撤销等旁路动作。
- 后台“任务 → 半自动履约”列表读取前必须执行幂等任务回填,不能依赖客户先打开 `/c/<订单号>`。
- 半自动履约状态采用与斗鱼领取一致的同步原则:客户操作、Connector 回调和后台操作都是状态快照输入,
统一由一个状态收敛服务在任务行锁内写入正式字段并追加事件;多个入口不得各自拼接或覆盖状态。
- 外部 Connector 通过签名 Webhook `POST /api/integration/platform-fulfillment/semi-auto/task-state`
提交登录与绑定快照,事件 ID 使用 `integration_inbox` 幂等;Connector 只提交平台观察到的事实,
不得直接声明业务履约完成。执行状态由登录、绑定和人工确认规则推导。
- 后台“任务 → 半自动履约”由 SSE 失效通知驱动读取,不得对列表或详情做固定秒级轮询。
后台列表首次读取可执行最近 30 天、最多 500 条、15 秒节流的有界兜底回填,
不得在每次列表查询时扫描全库历史订单。
- 客户页在登录或绑定等专用状态同步阶段只允许一个活动同步循环,不得同时轮询整单、登录和绑定。
非专用阶段使用低频整单同步;所有写操作完成后以服务端最新快照为准,不做客户端乐观状态拼接。
- 半自动任务每 15 分钟执行一次限量兜底对账,只处理活跃且有 Connector 会话的任务;
可通过 `SEMI_AUTO_RECONCILE_SECONDS` 调整,最低 60 秒。对账失败只更新最近错误,不覆盖人工完成或取消状态。
- 开发环境的半自动集成测试单必须通过正式 `upsertOrderFromSource` 入库,并继续经过 SKU 映射、
`sku_channel_routes`、渠道判定和 Carrier 补偿;不得直接写 `orders`、`order_items` 或
`fulfillments` 伪造成功。允许显式选择内置 Mock Connector,但不得用 Connector Mock 代替订单链路测试。