docs: add mobile redesign spec for WebView transport plans.

Capture the approved HTML demo as the UI authority for rewriting /#/m/pl/* without changing ticket or shell architecture. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-15 01:40:45 +08:00
1 parent fe9d30105d
commit 43f5ae8603
@@ -0,0 +1,173 @@
+# 小程序 WebView 运输计划 · 移动端交互重设计 — 设计文档
+
+> **日期**: 2026-09-15  
+> **状态**: 待实现（Demo 已验收）  
+> **前置架构**: `docs/superpowers/specs/2026-09-14-mp-webview-transport-plan-design.md`（壳页、ticket、权限、路由骨架已落地）  
+> **权威 Demo**: `bak/mobile-ui/shanxia-mp-pl-plan-mobile-redesign-demo.html`  
+> **视觉规范**: `docs/miniprogram-ui-spec-sanqiang.md`（三墙 Token；WebView 内 H5 使用 `#0a9f6d` 链，不套 Fresh Mint）
+
+## 1. 目标
+
+现网 `/#/m/pl/plan*` 已能跑通业务，但多为桌面弹窗/`variant=page` 硬套窄屏，信息过密、选择器不适配手指。
+
+本期在 **不改后端业务规则、不改小程序壳与 ticket** 的前提下，按已验收 Demo **重写移动端 UI/交互**，使列表 → 详情 → 表单（含安排）→ 打印 → 三方人车 全链路达到与 Web 管理端同等能力、手机可用。
+
+成功标准：
+
+1. 主路径可在真机 WebView 走通（新增/暂存/创建/安排/调整、复制、等通知、作废、打印预览存图、三方人车）。
+2. 交互与信息架构以 Demo 为准；业务校验与按钮显隐与桌面 `PlPlanFormDialog` / 列表操作一致。
+3. 只发 `web-admin` 静态资源即可更新体验，不必提审小程序。
+
+## 2. 已确认决策
+
+| # | 项 | 决策 |
+|---|-----|------|
+| D1 | 交付路径 | **方案 1**：先 HTML SPA Demo 验收，再按 Demo 重写 `/#/m/pl/*`（已完成 Demo） |
+| D2 | 范围 | 全链路：列表、详情、表单、安排、打印、三方人车快速创建 |
+| D3 | 表单布局 | **长页滚动 + 分区锚点**（基础 / 运输 / 装货 / 送货 / 备注） |
+| D4 | 选择器 / 确认 | **Bottom Sheet**（车辆、人员、客户、产品、承运商、合同、地址库、更多操作、危险确认） |
+| D5 | 安排 vs 编辑 | 与 Web 相同：同一表单，`openForArrange` / 安排模式；底栏按钮随模式变化，不做第二套安排页 |
+| D6 | 架构边界 | 沿用 2026-09-14 文档：小程序通用 WebView 壳 + ticket；本期 **只改 H5 UI** |
+| D7 | 列表筛选 | 对齐 Web `PL_PLAN_LIST_TABS`（含「全部」在草稿中之后）；日期快捷 + **自定义区间**；京东式双下拉，非一排 Chip 硬挤 |
+| D8 | 列表新增入口 | 右下角 **Speed Dial**（新增计划 / 三方人车快速创建），不要底栏双主按钮 |
+| D9 | 详情底栏 | 「⋯ 更多」+ 最多 **2** 个主操作（优先编辑、安排/调整）；复制/等通知/打印/作废进更多 |
+| D10 | 危化证 | 详情按产品展示证书槽位（易制毒：购买证+运输证；易制爆：合法证明）；上传/齐备确认仍在「危化品证上传」页，不塞进计划表单 |
+| D11 | 运费 | 详情只读展示；**编辑态不在本期**（Web 主编辑在归档弹窗，非计划表单） |
+| D12 | 打印 | WebView 内预览 + 引导长按/存图；送(提)货单须先选送货客户 |
+| D13 | 非本期 | 列设置、导出、强制改状态；独立危化证上传移动端重做（可后续单独立项） |
+
+## 3. 非目标
+
+- 不改运输计划后端状态机、租户隔离、数据权限、合同可安排量等业务规则。
+- 不改小程序 `mp-webview` 壳、ticket/exchange、菜单 perms（除非发现缺口再开小变更）。
+- 不下线现场原生「运输计划单」或公开司机/现场链接。
+- 不把桌面 `el-dialog` 作为 WebView 主交互形态保留。
+- 本期不做运费编辑、不做危化证上传页移动端重设计。
+
+## 4. 与前置文档关系
+
+| 文档 | 关系 |
+|------|------|
+| `2026-09-14-mp-webview-transport-plan-design.md` | **架构仍有效**：ticket、壳、权限、路由前缀 `/#/m/pl/plan*` |
+| 本文 | **替换**该文档 §7 的 UI 形态说明；权威 Demo 改为 `shanxia-mp-pl-plan-mobile-redesign-demo.html` |
+| 现网 `web-admin/src/views/m/pl/plan/*` | 实现基线，按本文与 Demo **重写页面结构与样式**，优先复用 API / composable / 表单子逻辑 |
+
+## 5. 信息架构
+
+```text
+列表 /m/pl/plan
+  ├─ Speed Dial → 新增 /m/pl/plan/new
+  ├─ Speed Dial → 三方人车 /m/pl/plan/paste
+  ├─ 卡片 → 详情 /m/pl/plan/:id
+  └─ 卡片 复制 / 安排 → 表单（copy / arrange）
+
+详情
+  ├─ 主操作 → 编辑 / 安排（同表单不同 mode）
+  ├─ 更多 → 复制 / 等通知·取消等通知 / 打印 / 作废
+  └─ 车辆「查看」→ Bottom Sheet 只读详情
+
+表单（new | edit | arrange | copy）
+  └─ 锚点分区；选择器均为 Sheet；底栏对齐 Web 显隐规则
+
+打印 /m/pl/plan/:id/print
+三方人车 /m/pl/plan/paste
+```
+
+路由可继续沿用现有 `/#/m/pl/plan*` 路径；**安排不必独立路由**（与 Web 一致用表单 mode）。若现有 `/arrange` 路由已存在，可保留为打开同一表单组件的入口，避免双实现。
+
+## 6. 分屏规格（对齐 Demo）
+
+### 6.1 列表
+
+- Header：返回工作台、标题「运输计划」、搜索（计划编号/供方/需方/产品/车牌号）。
+- 筛选条：日期下拉（今天/明天/本周/本月/自定义）+ 状态下拉（对齐 `PL_PLAN_LIST_TABS` 顺序）。
+- 卡片：编号、类型·日期、状态 Tag、**供方→需方**、跟进人、车牌、人员、产品摘要。
+- 卡片操作：更多（等通知/作废等）· 复制 · 安排/调整（权限与状态同 Web）。
+- 分页：加载更多。
+- Speed Dial：主色「新增计划」+「三方人车快速创建」。
+
+### 6.2 详情
+
+分区顺序对齐 Web `PlPlanViewTabs`：
+
+1. 基础信息  
+2. 运输信息（已安排：司机链接、**多现场链接**、车辆摘要+查看、司机/现场回传摘要）  
+3. 装送货（装货明细；送货 **多段 Tab**；产品行含型号规格/单位/包装/计划·实际量/送货方式等；数量平衡）  
+4. 危化品证书（按产品 + 槽位附件/未上传 + 齐备状态）  
+5. 运费信息（只读字段集与 Web 一致）  
+6. 备注  
+
+底栏：见 D9。
+
+### 6.3 表单
+
+- 锚点：基础 / 运输 / 装货 / 送货 / 备注。  
+- 运输：车辆库、三方人车入口、司机/押运、承运商、车辆摘要。  
+- 装/送：客户、合同、时间、联系、地址（**地址库 Sheet**）、注意事项、地磅、产品行（含型号规格/品牌/别名/可安排量/数量/单位/包装；送货另有送货方式）；送货多段 + 同步装货产品 + 数量平衡。  
+- 底栏（对齐 `PlPlanFormDialog`）：  
+  - 新增/复制：取消 / 暂存 / 创建 / 创建并安排运输  
+  - 编辑（待安排/草稿）：取消 / 暂存 / 保存 / 保存并安排  
+  - 已安排再安排：取消 / 调整运输  
+- 安排前危化证未齐备：沿用 Web 拦截文案，引导「危化品证上传」（本期可不做该页移动端，可用 toast/外链说明）。
+
+### 6.4 打印
+
+- 单据类型 Chip 与 Web 一致（入库/送提货/分装及空白单）。  
+- 送(提)货单：必选送货客户后再预览。  
+- 主操作：返回详情、保存预览（模拟/实现为引导存图）。
+
+### 6.5 三方人车
+
+字段对齐 `PlPasteRecognizeDialog`（`vehicle-bundle`）：原文识别、承运商、主挂车、核载、驾驶员三要素、押运员三要素、冲突处理（复用/覆盖/取消）、确认生成。承运商用 Sheet。
+
+## 7. 组件与样式约定
+
+| 单元 | 约定 |
+|------|------|
+| Token | 三墙：`--brand #0a9f6d` 等；禁止 WebView 页用 `#10b981` 作主色 |
+| Sheet | 遮罩无 backdrop blur；点遮罩关闭；列表类 Sheet 顶部模糊搜索 |
+| 底栏 | 贴底 flex，预留 `safe-area-inset-bottom`；勿用悬浮留白断层 |
+| 状态 Tag | 语义色与 Web/小程序一致（待安排警告、已安排成功、等通知等待、草稿中性） |
+| 复用 | 优先复用 `planApi`、`usePlFreightCalc`（详情只读）、危化槽位工具 `getRequiredCertSlots`、装送货 stop form utils；UI 层按移动端重写，避免再包一层 `el-dialog` |
+
+## 8. 实现落点（供后续计划拆任务）
+
+| 层 | 路径 |
+|----|------|
+| Demo（已完成） | `bak/mobile-ui/shanxia-mp-pl-plan-mobile-redesign-demo.html` |
+| H5 页面 | `web-admin/src/views/m/pl/plan/{index,detail,form,print,paste}.vue` |
+| 壳 / 守卫 | 原则上不动 `MpWebviewShell`、ticket；仅当样式冲突时做最小调整 |
+| 共享逻辑 | 现有 `@/api/pl`、`@/composables/usePl*`、`@/utils/pl-*`、表单子组件按需抽「无 dialog」用法 |
+| 样式 | 页内 SCSS 或 `web-admin/src/styles` 下 mp-webview 专用片段，对齐三墙 Token |
+
+建议实现顺序：
+
+1. 列表（筛选 + 卡片 + Speed Dial + 加载更多）  
+2. 详情（分区 + 危化证槽位 + 底栏更多）  
+3. 表单（锚点 + Sheet 选择器 + 底栏模式）  
+4. 打印 / 三方人车  
+5. 真机 WebView 冒烟与权限回归  
+
+## 9. 错误与边界
+
+| 情况 | 行为 |
+|------|------|
+| 无 `pl:plan:*` | 页内无权限空态（沿用现网） |
+| 安排时危化证未齐 | 拦截提示，不进入成功安排 |
+| Sheet 无匹配 | 「无匹配结果」空态 |
+| 打印未选送货客户 | Toast，不生成预览 |
+| 网络/401 | 沿用 2026-09-14 文档（清 token → 小程序登录） |
+
+## 10. 测试要点
+
+- Demo 对照：列表双下拉、Speed Dial、详情多送货段与危化槽位、表单锚点与四按钮新增、打印选客户、三方人车全字段。  
+- 与桌面同账号：列表数据范围、按钮显隐（草稿/待安排/已安排/等通知）、创建/安排/调整结果一致。  
+- 窄屏 375：底栏不遮挡、Sheet 可滚、锚点可跳。  
+- 仅发 H5 静态资源后小程序内可见变更。  
+- 现场「运输计划单」原生页不受影响。
+
+## 11. 风险
+
+- 桌面表单逻辑重，移动端易漏字段或漏校验：以 Demo 字段清单 + `PlPlanFormDialog` 提交 payload 为核对表。  
+- 现网 `/m/pl/*` 已上线，重写时建议按屏替换并保留 API 层，避免中断 ticket 壳。  
+- WebView 文件预览弱于桌面：危化附件以「已上传文件名 + 可点预览/打开」为最低交付，不强求与桌面上传组件像素一致。