7.4 KiB
7.4 KiB
后台页面设计说明（配送模块｜平台对接第三方轨迹）
本文定位：
- 定义“后台应该有什么样的页面”与每个页面的最小展示/操作/权限要求。
- 本文服务于平台系统的一部分：订单详情页物流区块 + 客服/履约/对接运维排障。
口径说明：本目录文档作为实现与验收唯一口径；如页面形态与本文不一致，以本文更新为准。
关联文档：
配送模块需求文档.md：范围/目标/验收与总体定位接口规范.md：Webhook/控制面接口与入库建议前端字段清单.md：订单详情页物流区块字段契约（安卓/Web）状态映射表.md：event_code/event_text -> status_code 映射与一致性治理缺口与待补充清单.md：需补齐的验收/场景/权限矩阵等
1. 角色与权限（页面设计前提）
角色建议：
- 普通用户（消费者端）：仅查看自己订单物流（不在本后台范围内）
- 商家（商户后台）：发货与查看订单物流（不看 raw_payload）
- 客服：查看订单物流、辅助处理异常（有限查看 raw_payload，需审计）
- 履约/运营：看指标、看异常趋势、做配置（按权限）
- 对接运维：看 webhook 日志、验签结果、配置密钥与回调、排障（可看 raw_payload，需审计）
强约束：
raw_payload、完整手机号/地址、签收凭证（POD）属于敏感信息：默认折叠、按角色授权、访问需审计。
1.1 页面拆分原则 & 权限控制原则（避免跑偏）
结论：页面是否拆分不只由“权限”决定；更主要由“工作流/信息密度/风险”决定，权限用于控制同一页面内的可见字段与可操作按钮。
页面拆分建议（什么时候需要单独页面/专区）：
- 工作流不同：商家做发货/运单绑定；客服做工单/异常处理；运维做对接配置/排障。
- 信息密度不同：面向商家的页面应短而清晰；面向运维的页面需要更细的日志与诊断信息。
- 风险不同：密钥/证书、回调配置、
raw_payload查看等高敏能力建议放在“对接运维专区”或独立页面，降低误操作与暴露面。
权限控制建议（同一页面内怎么按角色展示）：
- 字段级：例如
raw_payload、完整手机号/地址、POD 仅授权角色可见；默认折叠。 - 操作级：例如“触发回查/补采”“修改接入配置/密钥”“启用 Mock 开关”等仅运维可操作。
- 审计级：对敏感字段访问与关键配置变更必须记录审计。
推荐做法：
- 信息架构先按人群拆两条导航线（商家后台 vs 平台后台）。
- 在每个页面内部再做字段/按钮的权限控制（同页不同角色看到的内容不同）。
2. 信息架构（IA）与导航建议
建议将后台拆成两条导航线：
A. 商家后台（商户侧）
- 订单
- 订单列表
- 订单详情（含物流区块 + 发货/运单绑定）
- 设置（可选）
- 默认承运方/发货偏好
B. 平台后台（客服/运维侧）
- 订单
- 订单查询
- 订单详情（含物流区块）
- 物流对接
- 运单/轨迹查询（排障）
- Webhook 接收日志
- 接入配置中心（承运方/聚合配置）
- 监控与告警
- 状态映射治理（可选增强）
3. 商家后台页面（最小集）
3.1 订单列表页（商家）
目的：商家快速定位需要发货/查看物流的订单。
最小展示：
order_no、下单时间、收件人（脱敏）、订单状态、发货状态- 物流摘要（若已发货）：
carrier、tracking_no、当前status_code
最小操作：
- 查看订单详情
- 发货（跳转/弹窗进入“承运方选择 + 运单号绑定”）
3.2 订单详情页（商家，含物流区块）
目的：完成发货动作，并查看物流时间线。
物流区块展示（以 前端字段清单.md 为准）：
carrier、tracking_no、status、status_history、last_synced_at
操作：
- 发货：选择承运方 + 录入/回填
tracking_no - 刷新物流：调用平台统一查询（不直连第三方）
禁止/限制：
- 不展示
raw_payload - 收件信息按平台规则脱敏
4. 平台后台页面（客服/履约/对接运维）
4.1 订单查询页（平台）
目的：客服/履约按订单维度查找并进入详情处理。
筛选：
order_no、tracking_no、carrier、status_code、时间范围
展示：
- 订单摘要 + 物流摘要（当前状态、最后同步时间）
4.2 订单详情页（平台，含物流区块加强版）
目的：在订单上下文内查看完整物流与异常。
展示：
- 物流区块：同商家侧字段 + 事件来源标注（mock/承运方/聚合）
- 异常标记：长时间无更新、签收失败、退回等（按规则）
- POD（可选）：签收凭证预览（按权限）
操作：
- 刷新/回查（可选增强）：触发平台轮询补偿或第三方回查
- 备注/工单关联（可选）：记录客服处理信息
4.3 运单/轨迹查询页（平台排障核心）
目的：脱离订单也能按运单快速排障。
筛选：
tracking_no、carrier、status_code、时间范围、来源（mock/承运方/聚合）
展示：
- 事件时间线（入库后统一模型）
- 幂等/乱序结果提示（例如：去重命中次数、最新事件时间）
操作：
- 复制对接诊断信息（不含敏感字段）
4.4 Webhook 接收日志页（平台对接运维）
目的：定位“回调未到/验签失败/重复推送/入库失败”。
筛选：
- 时间范围、
carrier、tracking_no、验签结果、HTTP 状态、处理结果
展示：
- 请求摘要：
X-Client-Id、X-Timestamp、签名校验结果 - 处理摘要：解析成功/失败原因、幂等键、入库结果
- 原始回文：
raw_payload折叠展示（仅授权角色可见，且记录访问审计）
4.5 接入配置中心（平台对接运维）
目的：管理承运方/聚合接入与回调配置。
配置项：
- 承运方列表与状态（启用/停用）
- 验签密钥/证书、公网 IP 白名单（如需要）
- Webhook 目标地址与环境（测试/预发/生产）
- 轮询补偿策略：频率、阈值（多久无更新触发）、熔断
- 测试环境 Mock 开关（默认关闭，需显式开启）
4.6 监控与告警页（平台履约/运维）
目的：按承运方/接口维度观察质量。
指标建议：
- webhook 接收成功率、验签失败率、平均同步延迟
- 超过阈值未更新的运单数
- 第三方接口错误率/超时率（轮询补偿场景）
4.7 状态映射治理页（可选增强）
目的：让 event_code -> status_code 可治理、可追溯。
展示：
- 当前映射表、变更记录、（可选）映射版本
5. MVP（最小可上线范围）
商家后台：
- 订单列表 + 订单详情（含发货与物流区块）
平台后台：
- 运单/轨迹查询
- Webhook 接收日志（含验签/去重/入库结果）
- 接入配置中心（至少支持配置承运方/密钥/回调目标）
- 监控与告警（至少有基础指标与列表）
6. 验收要点（页面层）
- 订单详情页物流区块字段与展示规则符合
前端字段清单.md - 平台后台能从运单号定位到：事件时间线 + webhook 接收记录 + 验签结果 + 入库结果
raw_payload默认不可见/折叠，且按权限展示并有审计- Mock 开关默认关闭，且仅在测试环境允许启用