需求分析

pages/mall/delivery/doc/需求文档/后台页面设计说明.md

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