83 lines
5.0 KiB
Markdown
83 lines
5.0 KiB
Markdown
# 缺口与待补充清单（配送模块｜第三方轨迹对接 + Mock 联调）
|
||
|
||
本文定位：
|
||
- 用“交付物清单”的方式回答：当前这套配送对接文档还缺什么、为什么缺、补了带来什么收益。
|
||
- 不改变现有方案（统一事件模型 + Adapter + 幂等乱序入库 + 前端统一契约），只补齐落地时最容易卡住的材料。
|
||
|
||
关联文档：
|
||
- `README.md`：阅读入口与联调路径
|
||
- `配送模块需求文档.md`：目标/范围/验收口径
|
||
- `接口规范.md`：Webhook + 控制面 API + 入库建议
|
||
- `状态映射表.md`：event_code/event_text -> status_code + 一致性治理（含备选方案）
|
||
- `前端字段清单.md`：安卓/Web 展示契约
|
||
|
||
---
|
||
|
||
## P0（建议本期补齐，影响联调与验收能否顺利推进）
|
||
|
||
1) 联调/验收 Checklist（平台侧 + Mock 侧）
|
||
- 为什么要补：现在“验收标准”是目标描述，但缺少可勾选的操作性检查项，QA/对接会反复口头对齐。
|
||
- 补齐收益：把“验签/幂等/乱序/重复/延迟/缺字段”等要求落到可执行项，减少漏测。
|
||
- 建议产物：一份表格/列表（可以后续直接贴到测试用例/测试报告里）。
|
||
|
||
2) 场景库清单（scenario catalog）+ 每个场景的事件序列期望
|
||
- 为什么要补：当前只提了 `standard_delivered` 等示例名，但没有定义“这个场景到底要生成哪些关键节点、每个节点对应哪些 event_code/status_code、时间间隔怎样”。
|
||
- 补齐收益：前端可稳定对照 UI；后端可稳定断言幂等与排序；QA 可复现回归。
|
||
- 建议产物：
|
||
- 场景列表（标准签收/拒收退回/地址异常/破损/丢失/长时间无更新/签收失败后成功等）
|
||
- 每个场景：事件数、关键事件码、是否包含 POD、是否包含异常、是否需要乱序/重复/延迟注入。
|
||
|
||
3) Webhook 接收契约的“ACK/重试”约定（平台与第三方的边界）
|
||
- 为什么要补：目前只写“成功返回 200”，但缺少“平台什么时候返回 2xx、什么时候 4xx/5xx、第三方是否重试、重试间隔与上限”的共识。
|
||
- 补齐收益：避免线上/联调出现“平台处理慢导致第三方重推爆量”“平台 4xx 被第三方当作可重试”之类问题。
|
||
- 建议产物：在 `接口规范.md` 增补一小节：
|
||
- 验签失败/缺字段/无法解析 -> 4xx（不建议重试）
|
||
- 平台内部暂时不可用 -> 5xx（允许重试）
|
||
- 成功接收但异步入库失败 -> 2xx 还是 5xx 的取舍（建议：接收成功就 2xx，入库失败走内部告警与补偿队列）。
|
||
|
||
4) 承运方接入配置表模板（Carrier Integration Profile）
|
||
- 为什么要补：你已经发现韵达/圆通等第三方细节差异大，缺少一个“把关键信息落盘”的标准表格，后续每接一家都要重新摸索。
|
||
- 补齐收益：缩短接新承运方周期；把差异收敛到 Adapter/配置层；减少口头信息丢失。
|
||
- 建议字段（模板）：
|
||
- `carrier`、接入模式（webhook/polling/both）
|
||
- 鉴权类型与签名算法、参与签名字段、是否含 timestamp/nonce
|
||
- 轨迹查询接口（URL/method/v/字段示例）、回调接口（回调验签字段/重试策略）
|
||
- 是否提供稳定 `event_id`、是否要求手机号后四位
|
||
- 时间格式/时区、地点粒度
|
||
- 状态码枚举来源与映射版本
|
||
|
||
---
|
||
|
||
## P1（建议尽快补齐，影响长期维护与一致性/审计能力）
|
||
|
||
1) 权限矩阵与审计要求（谁能看 raw_payload / POD / 全量地址手机号）
|
||
- 原因：`raw_payload` 可包含敏感字段；Web 客服/运维能力需要最小权限与审计。
|
||
- 产物：角色（普通用户/商家/客服/运维/管理员）× 字段（raw/POD/手机号/地址）的可见性矩阵 + 审计日志要求。
|
||
|
||
2) 错误码与返回体统一（控制面 API）
|
||
- 原因：目前 `接口规范.md` 仅列举了示例错误码，但缺少标准响应结构。
|
||
- 产物：统一响应：`{success, code, message, request_id, data}`；并约定 HTTP 状态码与业务码的对应。
|
||
|
||
3) OpenAPI（可选）
|
||
- 原因：接口多了以后靠 Markdown 容易漂移。
|
||
- 产物：控制面 API + Webhook payload 的 OpenAPI（至少给 Mock 侧）。
|
||
|
||
4) “状态不回退/一致性”策略的明确算法（平台侧）
|
||
- 原因：`接口规范.md` 提了可选规则，但未选型；当出现终态后补到更早事件时，当前状态如何计算需要一口径。
|
||
- 产物：选定一种算法并写清：以 `event_time` 最新为准 / 状态等级只进不退 / 双轨（展示按时间，current_status 不回退）。
|
||
|
||
---
|
||
|
||
## P2（可后补，锦上添花）
|
||
- DB 字典与 ER 图（便于新人理解 schema）
|
||
- 场景导入导出（JSON）格式规范
|
||
- 对接灰度/熔断/降级策略的配置说明
|
||
|
||
---
|
||
|
||
## 建议补充顺序（最省时间）
|
||
1) 先补 P0-1（Checklist）+ P0-2（场景库清单）——直接提升联调效率
|
||
2) 再补 P0-3（ACK/重试约定）——避免重复推送与误判
|
||
3) 再补 P0-4（承运方接入配置表模板）——为后续接真实承运方铺路
|
||
4) 最后补 P1 项——为线上长期治理做准备
|