优化(直播履约): 改为订单快照事件驱动
This commit is contained in:
+37
-3
@@ -3,7 +3,7 @@ type: 权威架构与实施计划
|
||||
description: 订单、内部 SKU、履约路由、履约执行、商品、成本与财务的唯一权威口径及重构计划。
|
||||
tags: [订单, 内部SKU, 履约, 商品, 成本, 财务, 迁移]
|
||||
status: authoritative
|
||||
version: 2.27
|
||||
version: 2.29
|
||||
updated_at: 2026-11-18
|
||||
---
|
||||
|
||||
@@ -12,7 +12,7 @@ updated_at: 2026-11-18
|
||||
> 状态:**唯一权威文档**。
|
||||
> 最后校准:2026-11-18。
|
||||
> 生产基线:迁移 `166`。
|
||||
> 开发基线:迁移 `170`(仅本地,尚未部署生产)。
|
||||
> 开发基线:迁移 `172`(仅本地,尚未部署生产)。
|
||||
>
|
||||
> 从本文件生效起,订单、内部 SKU、履约渠道、履约载体、标准商品、成本和财务相关实现,
|
||||
> 只能以本文件为业务口径。其他旧分析只作为历史资料,不再具备设计或验收效力。
|
||||
@@ -285,6 +285,9 @@ terminal 已退款、退款申请、平台取消或商业订单已关闭
|
||||
|
||||
- 自动补载体扫描只允许读取 `v_fulfillment_queue.actionable_for_carrier = TRUE`。
|
||||
- `configuration`、`operator_review`、`terminal` 不得进入自动补载体 cursor,也不得阻塞新订单。
|
||||
- 新订单的主推进路径必须按当前 `orderItemIds` 定向执行“渠道判定 → 载体补建 → 再判定”,
|
||||
不得从全局水位重新扫描;全局 cursor 和定时任务只用于漏事件兜底。
|
||||
- 渠道、载体和自动发布发生变化后必须主动推送后台订单 SSE;定时任务不再作为页面感知状态变化的主路径。
|
||||
- 后台履约待办必须读取同一 `v_fulfillment_queue`,四个页签分别展示对应桶。
|
||||
- 售后/终止桶不得重新指定履约渠道;配置桶只补配置,人工处理桶只由运营确认重试或复核。
|
||||
- 补载体每日扫描采用“最近窗口新单优先 + 历史 actionable cursor”两段式;新单不能排在
|
||||
@@ -359,6 +362,9 @@ manual fulfillment
|
||||
④ 已绑定且 `can_rebind = false` 时不得生成换绑二维码,必须展示冷却剩余天数;
|
||||
⑤ 绑定二维码是 10 分钟短期会话状态,不单独落库;Connector 重启后以账号级 CK 恢复会话并重新查询
|
||||
`game_role`,已绑定事实照常确认,未绑定事实回到重新生成二维码。
|
||||
- 斗鱼客户领取页只允许通过订单级 SSE 接收“需要重读”的瞬态信号,不得固定秒级轮询绑定状态。
|
||||
SSE 不携带订单、角色或 CK 快照;页面收到信号或断线重连后,重新读取 `/api/v1/douyu-fulfillment/<订单号>`
|
||||
的权威快照。live-hub 快照字段没有实际变化时不得重复广播,避免读接口与 SSE 自激循环。
|
||||
- 半自动任务通过 `connector_mode` 显式记录 Connector 来源:
|
||||
`embedded` 为 order_site 内置真实实现并作为默认值,`external` 为显式配置的远程真实实现,
|
||||
`mock` 为 order_site 内置开发 Mock 且仅在非生产环境可用。开发 Mock 造单时默认选择 `embedded`,
|
||||
@@ -395,11 +401,35 @@ manual fulfillment
|
||||
- 外部 Connector 通过签名 Webhook `POST /api/integration/platform-fulfillment/semi-auto/task-state`
|
||||
提交登录与绑定快照,事件 ID 使用 `integration_inbox` 幂等;Connector 只提交平台观察到的事实,
|
||||
不得直接声明业务履约完成。执行状态由登录、绑定和人工确认规则推导。
|
||||
- order_site 与 live-hub 的通信职责必须区分:
|
||||
① order_site → live-hub 的正常路径走事务 `integration_outbox`,事件必须携带目标订单项的有界
|
||||
业务快照和稳定去重指纹,由 worker 投递签名
|
||||
`POST /api/integration/platform-fulfillment/events/order-sync`;live-hub 正常建单不得再依赖
|
||||
回查 order_site 的待履约表,也不得使用“最近 500 条”作为正确性窗口;
|
||||
② 旧版事件只允许按明确订单项 ID 定向兼容查询,不得回退成全量窗口扫描;
|
||||
③ live-hub → order_site 的状态同步由 live-hub Outbox 投递签名 Webhook
|
||||
`POST /api/v1/integration/platform-fulfillment/binding-state`,半自动 Connector 使用
|
||||
`/semi-auto/task-state`;接收端统一通过 `integration_inbox` 幂等。状态载荷必须携带
|
||||
live-hub 单调 `stateVersion`,order_site 拒绝旧版本覆盖新版本;
|
||||
④ 客户明确操作允许调用 `customer-sessions/ensure|binding/start|status|confirm` 同步 RPC,
|
||||
使用 `X-Integration-Key`,失败直接反馈客户,不伪装成 Outbox 已受理;
|
||||
⑤ SSE 只属于浏览器 ↔ order_site,不是 order_site ↔ live-hub 的跨服务消息通道。
|
||||
- live-hub 新任务使用 `next_allocate_at` 作为选号到期时间,任务创建或映射就绪后立即唤醒选号
|
||||
worker;首次选号不得等待固定 45 秒。失败后再写下一次重试时间,批量大小只能限制吞吐,
|
||||
不能成为数据正确性上限。
|
||||
- 斗鱼客户页 `GET /api/v1/douyu-fulfillment/<订单号>` 和 live-hub 后台任务详情 GET 必须是纯读:
|
||||
不得在读取接口中同步准备账号、调用平台或触发全量订单同步。未准备完成时返回 `preparing`
|
||||
或现有安全投影,后续由事务事件更新并通过 SSE 通知页面重读。
|
||||
- live-hub 的低频对账只允许补齐状态 Outbox 和异常任务,不得重新承担正常订单发现;
|
||||
正常订单发现完全由 order_site 事务 Outbox 驱动。
|
||||
- 后台“任务 → 半自动履约”由 SSE 失效通知驱动读取,不得对列表或详情做固定秒级轮询。
|
||||
后台列表首次读取可执行最近 30 天、最多 500 条、15 秒节流的有界兜底回填,
|
||||
不得在每次列表查询时扫描全库历史订单。
|
||||
- 客户页在登录或绑定等专用状态同步阶段只允许一个活动同步循环,不得同时轮询整单、登录和绑定。
|
||||
非专用阶段使用低频整单同步;所有写操作完成后以服务端最新快照为准,不做客户端乐观状态拼接。
|
||||
- “履约渠道 → 管道状态”由后台 SSE 失效刷新,不得固定 30 秒轮询。管道状态只用于观测和手动补跑;
|
||||
新订单是否及时推进取决于入库事件、定向履约推进、事务 Outbox 和即时选号唤醒,
|
||||
不取决于该页面是否打开。
|
||||
- 半自动任务每 15 分钟执行一次限量兜底对账,只处理活跃且有 Connector 会话的任务;
|
||||
可通过 `SEMI_AUTO_RECONCILE_SECONDS` 调整,最低 60 秒。对账失败只更新最近错误,不覆盖人工完成或取消状态。
|
||||
- 开发环境的半自动集成测试单必须通过正式 `upsertOrderFromSource` 入库,并继续经过 SKU 映射、
|
||||
@@ -1117,7 +1147,7 @@ docs/archive/
|
||||
|
||||
## 十三、当前下一步
|
||||
|
||||
截至 2026-11-18,生产基线为 `166`,集成分支开发基线为 `170`。迁移 `152` 保护订单来源快照,
|
||||
截至 2026-11-18,生产基线为 `166`,集成分支开发基线为 `172`。迁移 `152` 保护订单来源快照,
|
||||
迁移 `158–160` 收口寄卖登记人同步、寄卖平台与自动匹配设置;
|
||||
迁移 `161` 一次建立人工渠道半自动任务、内置 Connector 默认值、账号级 Cookie JSON 凭证、
|
||||
任务凭证引用和最终约束;迁移 `162` 建立履约待办四桶只读投影、补载体专用索引和新单优先扫描口径。
|
||||
@@ -1137,6 +1167,10 @@ docs/archive/
|
||||
「登录 → 填写资料 → 绑定角色」,资料未填全不得生成绑定二维码。
|
||||
迁移 `170` 增加半自动全链路报文日志,客户页、管理端和外部 Connector 共用同一追踪口径;
|
||||
角色比对仍以区服、角色名、角色 ID 三项完全一致作为「提交平台绑定」的唯一放行条件。
|
||||
迁移 `171` 建立斗鱼客户领取、live-hub 事务 Outbox/Inbox 和绑定状态安全投影。
|
||||
迁移 `172` 将 order_site → live-hub 订单事件升级为订单项快照契约,增加配置停用/订单关闭收敛、
|
||||
稳定去重指纹和 `live_state_version`;live-hub 同步增加 `next_allocate_at`、即时选号唤醒与
|
||||
`state_version`,删除正常链路上的 500 条回查窗口。
|
||||
迁移中保留的 `semi_auto.credential.export` 权限仅作兼容记录,
|
||||
不再作为 CK 导出门禁。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user