65 lines
3.3 KiB
Markdown
65 lines
3.3 KiB
Markdown
# 状态映射表（Mock 承运方 Server -> 平台统一状态）
|
||
|
||
本表用于将 Mock Server 产生的 `event_code/event_text` 映射为平台统一 `status_code`，以保证前端时间线与告警规则可复用。
|
||
|
||
关联文档：
|
||
- `接口规范.md`：统一事件模型与接入模式
|
||
- `前端字段清单.md`：时间线字段契约（status_history/status_code）
|
||
|
||
平台统一状态（建议）：
|
||
- PENDING：待揽收
|
||
- IN_TRANSIT：运输中
|
||
- ARRIVED_HUB：到达中转/分拨中心
|
||
- OUT_FOR_DELIVERY：派送中
|
||
- DELIVERED：已签收
|
||
- EXCEPTION：异常
|
||
- RETURNED：退回
|
||
|
||
Mock 事件码（建议） -> 平台统一状态
|
||
- CREATED / ORDERED -> PENDING
|
||
- PICKED / COLLECTED -> IN_TRANSIT
|
||
- ARRIVED_HUB -> ARRIVED_HUB
|
||
- DEPARTED_HUB / IN_TRANSIT -> IN_TRANSIT
|
||
- ARRIVED_DEST_CITY -> IN_TRANSIT
|
||
- OUT_FOR_DELIVERY -> OUT_FOR_DELIVERY
|
||
- SIGNED / DELIVERED -> DELIVERED
|
||
- REJECTED -> EXCEPTION
|
||
- ADDRESS_INVALID -> EXCEPTION
|
||
- DAMAGED -> EXCEPTION
|
||
- LOST -> EXCEPTION
|
||
- RETURNED / RETURNING -> RETURNED
|
||
|
||
示例（用于 UI 文案）
|
||
- ARRIVED_HUB：到达北京分拨中心
|
||
- 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` 一并存入事件记录（或运单聚合记录），对外查询接口可返回该版本用于排查。
|
||
- 变更策略建议：
|
||
- 小改动优先“仅影响未来事件”（不回刷历史）。
|
||
- 如必须修正历史映射，采用回放/回填任务，并对已对外展示的结果做备注或审计记录，避免静默改写。
|
||
|
||
代价与取舍：
|
||
- 会引入配置治理与发布流程的管理成本；若当前映射很稳定、承运方少、无强审计诉求，可以先不启用该方案。
|