195 lines
7.4 KiB
Markdown
195 lines
7.4 KiB
Markdown
# 后台页面设计说明（配送模块｜平台对接第三方轨迹）
|
||
|
||
本文定位：
|
||
- 定义“后台应该有什么样的页面”与每个页面的最小展示/操作/权限要求。
|
||
- 本文服务于平台系统的一部分：订单详情页物流区块 + 客服/履约/对接运维排障。
|
||
|
||
口径说明：本目录文档作为实现与验收唯一口径；如页面形态与本文不一致，以本文更新为准。
|
||
|
||
关联文档：
|
||
- `配送模块需求文档.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 开关默认关闭，且仅在测试环境允许启用
|