64 lines
3.6 KiB
Markdown
64 lines
3.6 KiB
Markdown
# 前端字段清单（订单详情页物流时间线｜安卓 & 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`：平台统一状态码（PENDING/IN_TRANSIT/ARRIVED_HUB/OUT_FOR_DELIVERY/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 应带鉴权或短期有效，前端需支持预览与下载。
|
||
|
||
5. 安卓端适配要点
|
||
- 缓存：将最近一次 `status_history` 缓存在本地（仅该用户的订单范围），离线可展示并提示“数据可能不是最新”。
|
||
- 图片：POD/证据图片支持大图预览与失败重试；弱网下优先加载文本节点。
|
||
- 刷新：进入页面自动拉取；下拉刷新；显示 `last_synced_at`。
|
||
|
||
6. Web 端适配要点
|
||
- 调试信息：`raw_payload` 默认折叠，仅客服/运维可展开查看。
|
||
- 筛选搜索：按 `status_code`、时间范围、承运方 `carrier` 过滤；支持按 `tracking_no` 搜索。
|
||
- 安全：避免在前端日志中打印 `raw_payload` 与敏感字段。
|
||
|
||
7. 兼容性
|
||
- 前端组件可接收 `raw_payload`（仅供客服/运维查看）并折叠显示。
|
||
- 时间线组件需支持展开单条事件详情、证据大图预览与来源标注（承运方/聚合方）。
|
||
|
||
---
|
||
（以上为前端字段与契约建议，实际字段名可与后端协商最终确认）
|