17 KiB
17 KiB
配送模块需求文档（模拟三通一达后台 / Mock 承运方 Server）
本文定位：定义 Mock 承运方 Server 的目标、范围、流程、故障注入与验收标准；接口与字段细节以 接口规范.md、前端字段清单.md 为准。
口径说明：本目录文档作为联调、验收与实现的唯一口径；如与口头沟通或临时讨论结论不一致，以本文档及其关联文档（接口/字段/映射）为准，并通过文档更新同步。
关联文档：
README.md：阅读入口与联调路径接口规范.md：Webhook 推送规范 + Mock 控制面 API状态映射表.md：event_code/event_text -> 平台 status_code前端字段清单.md：安卓/Web 时间线字段契约
1. 背景
当前配送链路依赖第三方承运方（常见为“三通一达”等快递公司或聚合平台）。在真实承运方接口尚未签约/联调完成前，需要一个可控的模拟承运方后台服务（Mock Server），用于开发与测试平台侧的：Webhook 接收、验签、幂等入库、时间线展示、异常处理与监控告警。
系统定位与边界：
- 本模块属于平台系统的一部分，最终呈现在“订单详情页”的物流区块，并同时服务客服/履约/对接排障。
- 平台端需要查看订单的履约详情（至少包括：
order_no、tracking_no、carrier、物流时间线status_history、异常与处理记录）。 - 但本需求不覆盖商品明细、支付、营销等订单业务域的展示与流程；这里聚焦“物流轨迹对接、入库与展示”。
多端归属与页面边界（统一口径）：
- 本需求产出的“物流能力”不是一个独立的骑手/配送员端 App，而是作为同一套物流模块能力，分别嵌入到三个端（按权限展示不同颗粒度）：
- 消费者端（C 端）：订单详情的物流时间线/物流详情（只读为主，展示
event_text+status_code，不展示raw_payload）。 - 商家端（B 端）：发货与运单绑定（选择承运方、录入/回填
tracking_no）+ 查看物流（不包含对接配置与敏感调试信息）。 - 管理端（平台后台：客服/履约/对接运维）：订单/运单查询、Webhook 接收日志、接入配置、（可选）监控告警与审计能力。
- 消费者端（C 端）：订单详情的物流时间线/物流详情（只读为主，展示
- 三端展示字段口径以统一事件模型与前端字段契约为准（见
接口规范.md、前端字段清单.md），避免出现“不同端展示不一致/状态口径不一致”。 - 若未来要做“自营配送/同城骑手端”（接单、导航、到店取货、送达签收等），需单独立项与另写需求文档，不在本需求范围内。
2. 目标
- 适用阶段：主要用于真实第三方承运方未签约/未联调/不可控时的替代数据源；即便后续已接入真实承运方，也保留用于回归测试、故障注入与排障复现（生产环境默认关闭）。
- 提供一个可配置的 Mock 承运方服务，模拟多承运方（圆通/韵达/中通/申通）轨迹事件与签收凭证。
- 支持将轨迹事件按既定规范推送到平台 Webhook（模拟承运方 -> 平台）。
- 支持主动查询轨迹（平台轮询场景）与“预置场景脚本”快速生成整条物流生命周期。
- 支持故障注入：延迟、重复推送、乱序、签名错误、时间戳偏移、缺字段等，用于验证平台鲁棒性。
2.1 配送合作模式（不同解决方案）
说明：以下方案是“商城履约/配送合作关系”的产品与工程取舍；无论选哪一种，只要前端要展示稳定一致的物流时间线，平台都建议建设统一的轨迹模型与查询接口（见 接口规范.md 与数据库 Schema）。本 Mock 体系用于在第三方未就绪或不可控时，替代外部系统快速联调与做故障注入回归。
方案 A：平台统一配送（平台与第三方合作 / 统采统接）
适用：希望提供强一致的履约体验、统一客服口径、统一监控与统计；平台愿意承担对接与运维成本。
平台职责：
- 统一签约/选择承运方或聚合平台；提供平台侧发货能力（下单、订阅/回调、轨迹查询与回单能力按合同）。
- 平台统一事件模型入库（幂等去重、乱序处理、状态不回退），对客户端输出统一
status_history。
商家职责：
- 在平台内选择配送方案并发货；不需要自行对接承运方轨迹接口（或仅提供必要发货信息）。
优点：体验一致，平台可观测性强；扩展新承运方主要改 Adapter，不影响前端契约。 风险/成本：平台对接与运维成本高；履约兜底责任更集中在平台侧。
与 Mock 的关系：
- Mock 用于第三方未联通阶段的替代数据源与故障注入；生产环境默认关闭。
方案 B：商家自选配送（商家自找承运方 / 平台只做订单）
适用：平台招商、品类/区域差异大、平台希望给商家“选择承运方”的灵活性。
重要说明（商家只是平台商户的常见情况）：
- 默认不要求商家自建系统或自行对接第三方 API。
- “商家自选”指商家在平台提供的承运方/聚合平台范围内进行选择，第三方对接、验签、幂等、入库与前端展示由平台统一承担。
平台职责（建议至少做到“统一展示底座”）：
- 提供统一轨迹查询接口给前端；平台内部仍建议使用统一事件模型入库。
- 平台负责与第三方承运方/聚合平台对接：订阅/回调（Webhook）或轨迹查询（轮询补偿）、验签、防重放、幂等去重、乱序处理与统一入库。
- 平台提供“发货与运单绑定”的入口（承运方选择、运单号录入/回填/打单），把差异收敛在平台 Adapter/映射规则，避免前端直接适配多家第三方。
商家职责：
- 在平台选择承运方并完成发货动作：提供/回填
tracking_no与必要的订单关联信息（如order_no）。 - 若商家坚持使用“商家与第三方的独立合同/账号”，可向平台提交第三方对接所需材料，由平台统一配置与代接入（不要求商家自建回调服务）。
优点：平台轻、商家灵活。 风险/成本：体验碎片化风险大；如果不强制回传规范，平台客服/前端会被迫处理多样差异，长期维护成本更高。
商家自选配送需要提供的内容（接入清单）
基础信息（发货侧最小闭环）：
carrier：承运方标识（可为直连承运方或聚合平台，如 YUNDA/YTO/ZTO/STO/KDN 等）。tracking_no：运单号生成与回传方式（商家生成/第三方返回/平台生成）。- 订单关联信息：
order_no（或平台侧可解析的业务单号），用于把轨迹绑定到订单详情页。
轨迹数据接入方式（平台统一接入，推荐第一种）：
- 第三方 -> 平台 Webhook 推送（推荐）：
- 平台与第三方完成订阅/回调配置；第三方直接回调平台 Webhook。
- 平台统一完成：验签、防重放、字段映射、状态映射、幂等去重、乱序入库。
- 平台 -> 第三方 轮询拉取（可选补偿）：
- 平台按承运方策略轮询“长时间无更新”的运单，补齐轨迹。
- 适用于第三方不稳定、回调丢失或仅提供查询能力的场景，但平台运维成本更高。
（高级模式，可选，适用于有自建系统的大商家）
- 商家系统 -> 平台：商家按平台统一事件模型回传轨迹事件；平台仍执行幂等/乱序入库与审计。
对接材料（按商家选择的接入方式提供）：
- 若商家仅在“平台已接入承运方范围内自选”，通常无需商家提供第三方接口材料。
- 若商家使用“独立合同/账号”并要求平台代接入，则需要商家提供或协助申请：
- 鉴权信息：
appKey/appSecret、token、证书、公网 IP 白名单等（因第三方而异）。 - 回调能力：是否支持订阅 + Webhook（以及重试策略、签名算法、回调白名单）。
- 能力说明：是否提供
event_id、是否提供 POD/签收凭证、是否需要手机号后四位参与查询等。
- 鉴权信息：
映射配置（用于消除差异化，平台侧必须落库为配置或代码映射）：
- 事件码/文案 -> 平台
status_code的映射（至少覆盖：揽收/在途/派送中/签收/异常/退回）。 - 幂等去重策略：优先
event_id；缺失时使用组合键（见接口规范.md的入库层建议）。
差异化来源与平台收敛策略
差异化来源（商家自选必然存在）：
- 鉴权差异：Token/HMAC/证书/IP 白名单等。
- 字段差异：时间格式、地点粒度、是否有
event_id、异常字段命名等。 - 状态差异：同一状态不同叫法/码值，甚至“派送/签收/退回”的边界不同。
- 交互差异：仅查询（轮询）/订阅回调（Webhook）/两者并存；重试与乱序程度不同。
平台收敛策略（避免差异扩散到前端与数据库）：
- 前端只消费平台统一查询接口与统一字段（见
前端字段清单.md），不得直接依赖第三方字段。 - 平台统一入库模型与幂等/乱序规则（见
接口规范.md），第三方差异仅在 Adapter/配置映射层处理。 - 分级能力与降级：
- 达标（可回传轨迹或可稳定拉取 + 通过验收）-> 展示完整时间线 + 可做告警统计。
- 不达标（仅能提供运单号或字段缺失严重）-> 降级为“仅展示运单号/跳转外部查询”，不承诺完整时间线。
验收建议（商家自配准入）：
- 必测：重复推送、乱序、延迟、验签失败、缺字段（对应本 Mock 的故障注入项）。
- 通过后才允许全量展示/告警统计；未通过仅允许降级展示。
与 Mock 的关系：
- Mock 可作为“平台对接与回归”的验收工具：在第三方未就绪或不可控时，先用 Mock 场景验证幂等/乱序/缺字段容错等；接入真实第三方后也可用于故障注入回归。
方案 C：混合模式（平台默认合作 + 允许商家自配）【推荐】
适用：既要平台可控的默认体验，又要给大商家/特殊品类保留弹性。
规则建议：
- 默认：商家走平台合作承运方（覆盖大多数订单，保证体验一致）。
- 例外：允许商家自配，但必须满足平台回传规范（至少事件时间/文案/状态映射可得）；否则只提供降级展示能力。
- 前端：永远只消费平台统一查询接口，不直接依赖第三方字段。
落地建议（最小闭环）：
- 平台统一事件表与查询 API 先上线；Mock 先跑通联调与回归。
- Phase 1：接 1 家聚合或 1 家主力承运方（平台统一配送）。
- Phase 2：开放商家自配（按准入与验收清单接入）。
3. 范围
3.1 包含
- Mock Server 对外提供控制面 API：创建/查询运单、追加事件、运行场景、触发推送、配置回调目标。
- Mock Server 向平台推送 Webhook：按统一事件模型、支持 HMAC 验签头。
- 事件与场景数据本地持久化（最小可用可内存；建议支持文件落盘，便于复现）。
3.2 不包含
- 真实承运方业务能力（计费、真实网点、真实 POD 获取）
- 配送员实时定位与地图
- 平台侧业务实现（本需求仅定义 Mock Server 的接口与行为）
4. 目标用户
- 平台后端开发：联调 Webhook、验签、幂等与入库。
- 平台前端开发：使用固定运单/事件数据验证时间线展示。
- QA 测试：用故障注入覆盖异常链路与回归。
- 运维/对接：用于排查“回调未到/重复到/乱序到”等问题。
4.1 使用端（主要投放端）
- 安卓端（App）：订单详情页展示物流时间线、签收凭证预览、异常上报。
- Web 端（H5/PC 管理后台或用户 Web）：同样展示物流时间线，提供更完整的原始事件/审计信息（按权限）。
4.2 平台后台展示建议（客服/履约/对接运维最小集）
说明：本节定义“平台侧管理后台”在物流模块上建议具备的最小展示与排障能力（不等同于完整订单后台）。
- 订单详情页（物流区块）
- 基础信息：
order_no、carrier、tracking_no、当前status_code、last_synced_at - 物流时间线：
status_history（按event_time排序，展示event_text，标签使用status_code） - 异常提示：长时间无更新、签收失败、退回等（按
status_code与规则触发）
- 运单/轨迹查询页（排障入口）
- 支持按
tracking_no/order_no/carrier/status_code查询 - 展示最近 N 条事件与来源（mock/承运方/聚合），便于快速定位
- 对接日志与审计（运维/对接用）
- Webhook 接收日志：验签结果、去重命中、入库结果/错误原因（按权限）
- 原始回文：
raw_payload折叠展示（仅客服/运维可见，记录访问审计）
- 配置中心（对接运维用）
- 承运方/聚合平台配置、Webhook 目标与密钥/证书、轮询补偿开关与频率
- 测试环境 Mock 开关（默认关闭，需显式开启）
（可选增强）一致性回查/纠偏入口：按需触发第三方回查，补采缺失事件并保留审计记录。
4.3 商家后台展示建议（商户侧最小集）
说明：商家只是平台商户时，建议仅提供“发货与运单绑定 + 物流查看”的最小能力。
- 发货：选择承运方、录入/回填
tracking_no、发货确认 - 订单详情（物流区块）：查看时间线与当前状态（不展示
raw_payload）
端侧差异化要求：
- 安卓端需支持弱网/后台切换恢复后的快速刷新；证据图片需支持点击预览/下载。
- Web 端需支持表格/筛选/搜索（便于客服排障）；对调试信息（raw_payload）默认折叠。
5. 核心概念
- 承运方（carrier）：YUNDA / YTO / ZTO / STO（可扩展）
- 运单（tracking_no）：可由 Mock Server 生成或由调用方指定
- 事件（event）：包含 event_id、event_time、event_code、event_text、node_name、location、evidence_urls 等
- 场景（scenario）：一组按时间顺序生成的事件脚本（如“标准签收”“拒收退回”“地址异常”）
6. 关键流程
- 配置推送目标：设置平台 Webhook URL、
client_id、secret。 - 创建运单：选择 carrier，生成/指定 tracking_no。
- 运行场景：Mock Server 生成一系列关键节点事件并入库。
- 触发推送：Mock Server 按顺序（或按乱序/延迟策略）将事件推送到平台。
- 平台侧验证：校验验签、去重、入库、前端展示与告警。
7. 功能需求
7.1 控制面 API（Mock Server）
- 配置：设置 webhook 目标、密钥、默认承运方。
- 运单：创建/查询/列表。
- 事件：追加/查询/清空；支持批量追加。
- 场景：运行预置脚本（标准流程/异常流程）。
- 推送：立即推送指定运单的全部/增量事件；支持模拟重试与重复。
7.2 Webhook 推送（Mock -> 平台）
- 请求头包含
X-Client-Id、X-Timestamp、X-Signature。 - body 结构遵循统一事件模型（见
接口规范.md）。 - 幂等：对同一事件可重复推送，平台需以
event_id去重。
7.3 故障注入（必须）
delay_ms：推送延迟duplicate：重复推送次数out_of_order：乱序推送bad_signature：签名错误timestamp_skew_seconds：时间戳偏移drop_fields：缺字段（用于校验平台必填校验与容错）
8. 非功能需求
- 易用性：一条命令启动；提供最少的配置即可发送事件。
- 可复现：场景运行应可导出/导入（或提供固定随机种子）。
- 可观测：每次推送记录 request/response 摘要与 request_id。
- 安全：仅用于内网/测试环境；支持简单 Token 或 IP 白名单（可选）。
端侧体验要求（安卓/Web）：
- 刷新策略：页面进入时拉取一次平台侧轨迹；用户可手动“刷新物流”；显示
last_synced_at。 - 离线降级：无网络时展示上次缓存的时间线并提示“网络不可用”。
- 权限与隐私：手机号脱敏；
raw_payload仅客服/运维可见并记录审计；不展示配送员精确地址/定位。
9. 验收标准
- 能创建运单并运行“标准签收”场景，向平台推送至少 6 个关键节点（揽收/到达中转/在途/到达目的地/派送中/签收）。
- 能注入重复与乱序事件，平台侧仍能正确去重并按时间线展示。
- 能注入验签失败事件，平台侧能拒绝并记录告警。
10. 文档与交付物
接口规范.md：Mock Server 控制面 API + Webhook 推送规范状态映射表.md：事件码/原文到平台统一状态映射建议前端字段清单.md：前端展示字段契约（供时间线组件使用）- 数据库 Schema：
mall_sql/schemas/express_tracking_mock_platform.sql（平台统一轨迹入库 + Mock 承运方持久化表）
11. 待补充项（备忘与下一步）
为保证联调、验收与后续接真实承运方不走弯路，建议按优先级补齐：
缺口与待补充清单.md