统一状态码，优化对应逻辑
This commit is contained in:
not-like-juvenile
@@ -72,7 +72,8 @@
|
||||
- 平台提供“发货与运单绑定”的入口（承运方选择、运单号录入/回填/打单），把差异收敛在平台 Adapter/映射规则，避免前端直接适配多家第三方。
|
||||
|
||||
商家职责：
|
||||
- 在平台选择承运方并完成发货动作：提供/回填 `tracking_no` 与必要的订单关联信息（如 `order_no`）。
|
||||
- 商家在平台的订单列表/订单详情页点击“发货/绑定运单”，选择承运方并录入/回填 `tracking_no`；`order_no` 由平台订单上下文自动带入，不要求商家手工输入订单号。
|
||||
- `ORDER_PLACED`（已下单）阶段允许 `tracking_no` 为空（前端展示“暂无运单号”）；完成发货绑定后进入 `SHIPPED`，此时必须具备 `carrier + tracking_no`。
|
||||
- 若商家坚持使用“商家与第三方的独立合同/账号”，可向平台提交第三方对接所需材料，由平台统一配置与代接入（不要求商家自建回调服务）。
|
||||
|
||||
可选增强：商家在平台内“自助对接第三方”（无需商家开发）
|
||||
@@ -99,7 +100,7 @@
|
||||
- Phase 2：先接入 1 家聚合平台做统一下单/面单/轨迹（降低多家直连成本）。
|
||||
- Phase 3：再开放 BYO Account（商家自带账号）自助配置（安全与运维成本最高）。
|
||||
|
||||
优点：平台轻、商家灵活。
|
||||
优点：相对方案 A 平台责任更轻、商家更灵活。
|
||||
风险/成本：体验碎片化风险大；如果不强制回传规范，平台客服/前端会被迫处理多样差异，长期维护成本更高。
|
||||
|
||||
#### 商家自选配送需要提供的内容（接入清单）
|
||||
@@ -107,12 +108,12 @@
|
||||
基础信息（发货侧最小闭环）：
|
||||
- `carrier`：承运方标识（可为直连承运方或聚合平台，如 YUNDA/YTO/ZTO/STO/KDN 等）。
|
||||
- `tracking_no`：运单号生成与回传方式（商家生成/第三方返回/平台生成）。
|
||||
- 订单关联信息：`order_no`（或平台侧可解析的业务单号），用于把轨迹绑定到订单详情页。
|
||||
- 订单关联信息：`order_no`（或平台侧可解析的业务单号），用于把轨迹绑定到订单详情页；通常由平台在“订单发货/绑定运单”操作中自动带入，不要求商家手工录入。
|
||||
|
||||
运单号（`tracking_no`）获取方式（两种常见落地，二选一或并存）：
|
||||
1) 回填运单号（最小模式，推荐先上线）：
|
||||
- 商家在线下/快递官方系统/聚合平台完成下单与交接，获得运单号。
|
||||
- 商家在平台后台“发货”时选择承运商并回填 `tracking_no`。
|
||||
- 商家在平台后台“发货/绑定运单”时选择承运商并回填 `tracking_no`（订单号无需手填，平台自动关联当前订单）。
|
||||
- 平台不需要调用第三方“下单/面单”接口，只需后续接入轨迹（Webhook/轮询）用于展示。
|
||||
2) 电子面单 / 在线下单（增强模式，体验更好）：
|
||||
- 平台（或平台集成的服务商）需要对接第三方提供的“下单/面单”接口，向第三方提交发货所需信息（收件人/地址/重量/件数等），并获得：运单号 `tracking_no` + 面单文件/面单号等。
|
||||
@@ -143,6 +144,29 @@
|
||||
- 事件码/文案 -> 平台 `status_code` 的映射（至少覆盖：揽收/在途/派送中/签收/异常/退回）。
|
||||
- 幂等去重策略：优先 `event_id`；缺失时使用组合键（见 `接口规范.md` 的入库层建议）。
|
||||
|
||||
#### 平台统一配送状态（`status_code`，必须遵循）
|
||||
|
||||
说明：平台内部与对外输出统一使用同一套 `status_code`，三端（C/B/管理端）按需展示，不得随意改写状态口径。
|
||||
|
||||
状态枚举（当前统一口径）：
|
||||
- `ORDER_PLACED`：已下单（平台侧订单已创建；通常不是第三方快递事件；此阶段允许 `tracking_no` 为空）
|
||||
- `SHIPPED`：已发货（已绑定运单/待揽收）
|
||||
- `IN_TRANSIT`：运输中（所有中转/分拨/到达节点统一归类为运输中）
|
||||
- `OUT_FOR_DELIVERY`：派送中
|
||||
- `READY_FOR_PICKUP`：待取件（驿站/自提柜等）
|
||||
- `DELIVERED`：已签收
|
||||
- `EXCEPTION`：异常
|
||||
- `RETURNED`：退回/退件
|
||||
|
||||
展示规范：
|
||||
- 为保证用户体验，应真实展示第三方回传的物流轨迹文案（如“到达北京分拨中心”、“离开上海网点”等），不做脱敏处理。
|
||||
- 前端时间线展示 `event_text` 原文，状态标签对应 `status_code`。
|
||||
|
||||
说明：本项目不维护“发货前”的配送状态；在未绑定运单阶段属于订单域状态，不纳入物流轨迹状态枚举。
|
||||
|
||||
补充约束（与页面展示相关）：
|
||||
- 当 `tracking_no` 为空时，前端仅展示订单的配送状态为 `ORDER_PLACED` 与“暂无运单号”，不展示可查询的第三方物流时间线；待商家完成“发货/绑定运单”后，再展示轨迹时间线。
|
||||
|
||||
#### 差异化来源与平台收敛策略
|
||||
差异化来源（商家自选必然存在）：
|
||||
- 鉴权差异：Token/HMAC/证书/IP 白名单等。
|
||||
|
||||
Reference in New Issue
Block a user