# 后台页面设计说明（配送模块｜平台对接第三方轨迹）

本文定位：
- 定义“后台应该有什么样的页面”与每个页面的最小展示/操作/权限要求。
- 本文服务于平台系统的一部分：订单详情页物流区块 + 客服/履约/对接运维排障。

口径说明：本目录文档作为实现与验收唯一口径；如页面形态与本文不一致，以本文更新为准。

关联文档：
- `配送模块需求文档.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 开关默认关闭，且仅在测试环境允许启用