medical-mall/pages/mall/delivery/doc/需求文档/前端字段清单.md

前端字段清单（订单详情页物流时间线｜安卓 & Web）

说明：本清单用于平台前端展示“物流关键节点时间线”。数据来源为平台后端消费 Mock Server（或未来真实承运方）的事件后形成的统一模型。

本文定位：只定义“平台后端 -> 客户端”的展示字段契约与规则；Mock Server 的接口与字段以 接口规范.md 为准。

关联文档：

• 配送模块需求文档.md：目标/范围/验收与故障注入
• 接口规范.md：统一事件模型、平台接收 Webhook、Mock 控制面 API
• 状态映射表.md：event_code -> status_code 映射建议

适用端：

• 安卓端（App）：重点是用户体验（弱网/图片预览/快速刷新）。
• Web 端（H5/PC）：重点是排障效率（筛选/搜索/原始事件折叠展示）。

1. 订单详情（delivery block）

• order_no：订单号
• tracking_no / waybill_no：运单号（可能为空）
• carrier：承运商标识（YUNDA/YTO/KDN 等）
• status：平台统一状态码（ORDER_PLACED/SHIPPED/IN_TRANSIT/OUT_FOR_DELIVERY/READY_FOR_PICKUP/DELIVERED/EXCEPTION/RETURNED）
• status_history：事件数组，元素结构 {event_id, event_time, event_code, event_text, status_code, node_name, location, description, evidence_urls, source}
• eta：预计到达时间（ISO8601，若承运方或 ETA 服务提供）
• pod：签收凭证数组，元素 {type: photo|signature, url, timestamp, remark}
• receiver_name：收件人姓名（仅客服可查看完整）
• receiver_masked_phone：脱敏手机号（前端展示）
• receiver_address：收货地址（可按需隐藏部分字段）
• last_synced_at：最后同步时间（平台本地）
• source：来源（mock / carrier / aggregator），用于 UI 标注与排障

2. 管理/调试视图字段（可选）

• mock_enabled：是否开启 mock 数据
• mock_carrier：当前模拟承运方
• webhook_last_result：最近一次 webhook 推送结果摘要（仅调试页面）

3. 行为与按钮映射（平台侧）

• 刷新物流 -> GET /api/v1/delivery/express/track（平台查询自身已入库事件；或平台发起轮询）
• 上报异常 -> POST /api/v1/delivery/express/report-exception

（联调阶段可选）平台侧调试按钮（调用 Mock Server 控制面 API）：

• 运行标准场景 -> POST /mock/v1/waybills/{tracking_no}/run-scenario
• 触发推送 -> POST /mock/v1/waybills/{tracking_no}/push

4. 展示规则 & 隐私

• 所有时间使用 ISO8601（含时区）。
• 手机号必须脱敏（如 138****8000），完整手机号仅在客服/运维界面显示并记录访问审计。
• 证据 URL 应带鉴权或短期有效，前端需支持预览与下载。

4.1 同源数据，不同端展示颗粒度

• 同一运单的轨迹事件（event_code/event_text/status_code/node_name/location）必须同源，保证事实与状态口径一致；不同端仅做“展示层过滤/脱敏”，不做口径改写。
• 商家端（B 端）：只需展示大致进度（到达某地/中转/派送/签收/异常）与最新节点摘要；不展示配送员/快递员手机号等个人敏感信息。
• 消费者端（C 端）：可展示更详细的节点文案；若提供“联系配送”能力，建议用按钮/虚拟号/中转号承载，而不是把第三方 event_text 中的手机号原文直接展示或通过消息推送透传。

4.2 event_text 使用建议（避免直接透传敏感信息）

• event_text 属于第三方原文，可能包含手机号、网点内部信息等；建议前端展示使用“清洗后的文案”。
• 最小实现：
  • 商家端优先展示 status_code + node_name/location 组合出的摘要；必要时展示清洗后的 event_text。
  • 消费者端可展示清洗后的 event_text；仅在 OUT_FOR_DELIVERY 等末端节点按需提供脱敏联系方式。
• 口径要求：除末端状态（派送中/待取件/已签收/异常/退回等）外，中转/到达/发往下一站等统一展示为“运输中”，不展示“到达××网点/分拨中心”等中间节点状态文案。

5. 安卓端适配要点

• 缓存：将最近一次 status_history 缓存在本地（仅该用户的订单范围），离线可展示并提示“数据可能不是最新”。
• 图片：POD/证据图片支持大图预览与失败重试；弱网下优先加载文本节点。
• 刷新：进入页面自动拉取；下拉刷新；显示 last_synced_at。

6. Web 端适配要点

• 调试信息：raw_payload 默认折叠，仅客服/运维可展开查看。
• 筛选搜索：按 status_code、时间范围、承运方 carrier 过滤；支持按 tracking_no 搜索。
• 安全：避免在前端日志中打印 raw_payload 与敏感字段。

7. 兼容性

• 前端组件可接收 raw_payload（仅供客服/运维查看）并折叠显示。
• 时间线组件需支持展开单条事件详情、证据大图预览与来源标注（承运方/聚合方）。

---

（以上为前端字段与契约建议，实际字段名可与后端协商最终确认）