4.4 KiB
4.4 KiB
状态映射表（第三方/Mock -> 平台统一状态）
本表用于将第三方（或 Mock Server）产生的 event_code/event_text 映射为平台统一 status_code，以保证前端时间线与告警规则可复用。
关联文档：
接口规范.md：统一事件模型与接入模式前端字段清单.md：时间线字段契约（status_history/status_code）
平台统一状态（建议，尽量少且稳定）：
- ORDER_PLACED：已下单（平台侧订单状态；通常不是第三方快递事件）
- SHIPPED：已发货（已绑定运单/待揽收）
- IN_TRANSIT：运输中（含“中转中/发往下一站/分拨/到达节点/在途”等）
- OUT_FOR_DELIVERY：派送中
- READY_FOR_PICKUP：待取件（到驿站/自提柜等，等待收件人取件）
- DELIVERED：已签收（含本人签收/代收点签收）
- EXCEPTION：异常（地址不详、拒收、破损、丢件、派送失败等）
- RETURNED：退回/退件
说明：
ORDER_PLACED通常来自平台订单系统（下单成功），不一定存在tracking_no；在“统一时间线展示”场景下可作为平台生成事件出现在物流时间线里。- 第三方事件原文（
event_text）尽量保留；平台只用status_code做标签/筛选/告警。
第三方/Mock 事件码（建议） -> 平台统一状态（示例映射）
- ORDERED / CREATED -> SHIPPED（若该事件表示“快递单已创建/已出库”，而非平台下单）
- PICKED / COLLECTED -> IN_TRANSIT（已揽收后进入物流网络）
- ARRIVED_HUB / ARRIVAL -> IN_TRANSIT（中转/到达节点统一视为运输中）
- DEPARTED_HUB / TRANSIT / IN_TRANSIT -> IN_TRANSIT
- ARRIVED_DEST_CITY -> IN_TRANSIT
- OUT_FOR_DELIVERY -> OUT_FOR_DELIVERY
- AT_PICKUP_POINT / READY_FOR_PICKUP / DELIVERED_TO_PICKUP -> READY_FOR_PICKUP
- SIGNED / DELIVERED -> DELIVERED
- FAILED_DELIVERY / REJECTED / ADDRESS_INVALID / DAMAGED / LOST -> EXCEPTION
- RETURNED / RETURNING -> RETURNED
平台生成事件（用于统一时间线，可选） -> 平台统一状态
- ORDER_PLACED -> ORDER_PLACED
- MERCHANT_CONFIRMED_SHIPMENT / SHIPPED -> SHIPPED
示例（用于 UI 文案）
- IN_TRANSIT：运输中
- OUT_FOR_DELIVERY：快件正在派送中
- SIGNED：客户已签收（可带 POD 图片）
注意事项
- 平台入库请保留原始
event_text与raw_payload，前端默认展示event_text，状态标签使用status_code。 - Mock Server 应支持故障注入（重复/乱序/延迟/验签失败），平台状态映射必须在幂等入库后执行。
为尽量保证事件状态保持一致（基础要求）：
event_code/event_text视为第三方“事实记录”，尽量不改写；统一口径（标签、颜色、筛选）交由status_code承担。- 映射必须确定性：同一承运方、同一
event_code在同一套映射规则下应得到同一status_code。
备选方案：映射版本化（mapping_version）（可选增强）
为什么要做：
- 防止“状态漂移”：映射规则一旦调整，历史订单的已入库事件如果重新计算
status_code，可能出现“昨天运输中，今天变异常/又变回运输中”，引发用户与客服争议。 - 提升可审计性：当出现纠纷或对账问题时，需要能回答“当时按哪一版规则映射出来的”。
- 降低排障成本：多承运方/多渠道（直连+聚合）并存时，版本信息能快速定位是“第三方事件变了”还是“平台映射变了”。
什么时候启用：
- 状态映射会随运营/产品频繁调整，且希望历史展示稳定、可解释。
- 客服/售后对轨迹状态一致性有明确 SLA 或合规/审计要求。
怎么落地（从轻到重）：
- 轻量做法（推荐起步）：将映射表作为配置/代码资产管理，使用 Git tag/发布号作为
mapping_version，并在发布记录中保留变更原因与生效时间。 - 加强做法：在事件入库时把
mapping_version一并存入事件记录（或运单聚合记录），对外查询接口可返回该版本用于排查。 - 变更策略建议：
- 小改动优先“仅影响未来事件”（不回刷历史）。
- 如必须修正历史映射，采用回放/回填任务，并对已对外展示的结果做备注或审计记录，避免静默改写。
代价与取舍：
- 会引入配置治理与发布流程的管理成本；若当前映射很稳定、承运方少、无强审计诉求，可以先不启用该方案。