From ab46a8c9993250f167ba2b978cf92916d1d62884 Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Fri, 21 Aug 2026 11:12:35 +0800 Subject: [PATCH] docs: add driver transport history design and HTML demo Capture the approved design for same-main-plate public driver history (list by pickup/delivery day, today shortcuts, cross-plan feedback). Co-authored-by: Cursor --- docs/demo-driver-transport-history.html | 657 ++++++++++++++++++ ...8-21-pl-driver-transport-history-design.md | 176 +++++ 2 files changed, 833 insertions(+) create mode 100644 docs/demo-driver-transport-history.html create mode 100644 docs/superpowers/specs/2026-08-21-pl-driver-transport-history-design.md diff --git a/docs/demo-driver-transport-history.html b/docs/demo-driver-transport-history.html new file mode 100644 index 000000000..f0a306a32 --- /dev/null +++ b/docs/demo-driver-transport-history.html @@ -0,0 +1,657 @@ + + + + + + 司机链接 · 运输记录 Demo + + + +
+
+

司机链接 ·「运输记录」交互 Demo

+

+ 列表默认今天。筛选为:单日日期框 +「今天 / 明天 / 后天」快捷按钮。 + 命中:取货日或送货日等于所选日。按主车车牌聚合。 +

+
+ + + + +
+
+ +
+ +
+
可交互 Demo(点底部按钮 / 点记录)
+
+ +
+ +
+
+
计划编号YS20260821001
+
计划日期2026-08-21
+
车牌苏A·D12345
+
司机张师傅
+
+
+
取货信息
+
取货地址南京市江宁区××仓库
+
取货时间2026-08-21 09:00
+
+
+
产品回传数量
+
+
硫酸
+
计划 28 吨 · 实际待填
+
+
+
+ +
+ + +
+ + + +
+ + +
+ + + +
+ + +
+ +
+
+
+ + + +
+
+ +
+
当前:今天 2026-08-21 · 取货或送货命中
+
+ +
+
+
+
+
+ + +
+
对照:任意状态底部都有「运输记录」
+
+ + + +
+
+
+ +
+ Demo 说明(已确认部分):
+ 1)「运输记录」按主车车牌号聚合历史与后续安排。
+ 2)任意状态底部仅保留「运输记录」;不再提供「返回列表」。
+ 3)筛选:单日日期框 +「今天/明天/后天」快捷;默认今天。
+ 4)命中:取货日或送货日任一等于所选日。 +
+
+ + + + diff --git a/docs/superpowers/specs/2026-08-21-pl-driver-transport-history-design.md b/docs/superpowers/specs/2026-08-21-pl-driver-transport-history-design.md new file mode 100644 index 000000000..b33867bab --- /dev/null +++ b/docs/superpowers/specs/2026-08-21-pl-driver-transport-history-design.md @@ -0,0 +1,176 @@ +# 司机链接 · 运输记录(同主车车牌)设计 + +**日期:** 2026-08-21 +**状态:** 待实现 +**Demo:** `docs/demo-driver-transport-history.html` +**推荐方案:** 入口 token 鉴权 + 按主车车牌列历史 + 详情跳转目标单自有 token(方案 1) + +## 1. 背景与目标 + +当前司机免登录页(`/#/public/pl/transport/:token`)仅绑定**单次运输单**。现场希望同一辆车(主车号)能查看历史与后续安排的计划,并在进行中计划间互通填写回执。 + +**目标:** + +- 每个司机详情页(含归档/作废空状态)底部提供「运输记录」入口。 +- 列表按**主车车牌号**(`license_plate`,不含挂车号)聚合同租户记录。 +- 默认展示**今天**命中的记录;提供「今天 / 明天 / 后天」快捷 + 单日日期选择。 +- 点击记录进入对应司机详情;进行中可填写/保存;归档/作废与现状一致(仅空状态文案)。 +- 不单独提供「返回列表」——统一用「运输记录」进出列表。 + +## 2. 已确认需求 + +| 项 | 结论 | +|---|---| +| 聚合维度 | 主车车牌号(`license_plate` / 主车号),不含 `trailer_no` | +| 互通操作 | 持有任一有效司机链接,可打开并**填写/保存**同车牌其他进行中计划回执 | +| 日期命中 | `DATE(pickup_time) = 所选日` **OR** `DATE(delivery_time) = 所选日` | +| 筛选 UI | 单日日期框 + 今天/明天/后天;**默认今天**(不再提供「全部记录」默认态) | +| 底部按钮 | 仅「运输记录」;取消原设想的「返回列表」 | +| 归档/作废 | 详情仍只显示「运输计划已归档完成」/「运输计划已作废」;底部仍有「运输记录」 | + +## 3. 非目标 + +- 不引入车辆级长期 token,不改造安排运输时的 token 签发模型(除列表返回既有 `driver_access_token`)。 +- 不改现场链接(入库/出库公共页)行为。 +- 不做管理端(web-admin 登录态)运输记录页;本能力仅司机免登录 H5。 +- 不按挂车号、司机人员 ID 聚合。 + +## 4. 架构(方案 1) + +```text +司机详情 token_A + │ + ├─「运输记录」→ /public/pl/transport/{token_A}/history?date=今天 + │ │ + │ └─ GET /api/public/pl/transport/{token_A}/history?date= + │ → 解析 token_A → tenant + license_plate + │ → 同车牌计划列表(含各单 driverAccessToken) + │ + └─ 点击记录 B → /#/public/pl/transport/{token_B} + → 现有 GET/POST feedback(token_B) +``` + +**安全边界:** 持有有效司机链接即视为可操作该主车车牌下同租户运输回执。列表会返回同车牌其他单的 `driverAccessToken`;与「同车牌互通填写」产品结论一致。调整运输轮换旧 token 后,旧链接与其 history 入口一并失效(与现状一致)。 + +## 5. 后端设计 + +### 5.1 新增接口 + +`GET /api/public/pl/transport/{token}/history?date=YYYY-MM-DD` + +- **鉴权:** 与现有公共司机 API 相同,按 `PlTransport.driver_access_token` 查找;无效 → 404。 +- **`date`:** 必填;非法格式 → 400。 +- **解析:** 入口运输单 → `tenant_no`、主车 `license_plate`(trim)。车牌为空 → 返回空列表 `records: []`(不报错,避免脏数据阻断入口)。 +- **查询条件(同时满足):** + - `tenant_no` = 入口单租户 + - 计划 / 运输未删除(`del_flag = 0`) + - 计划已安排运输(如 `PlPlan.transport_status = 'arranged'`,且关联有效 `PlTransport`) + - 运输单(或计划快照)主车车牌 = 入口主车车牌(建议以 `PlTransport.license_plate` 为准,空则回退 `PlPlan.license_plate`) + - `DATE(plan.pickup_time) = date OR DATE(plan.delivery_time) = date` + (两端皆空则不命中) +- **排序:** `pickup_time DESC`,空值靠后;再按 `plan_date` / `create_time` DESC。 +- **入口计划已归档/作废:** 仍允许调用本接口(详情页底部按钮始终可用)。 + +### 5.2 响应字段(camelCase) + +列表包装建议: + +```json +{ + "licensePlate": "苏AD12345", + "date": "2026-08-21", + "records": [ + { + "planId": "...", + "planNo": "YS...", + "transportId": "...", + "driverAccessToken": "...", + "driverUrl": "https://.../#/public/pl/transport/...", + "licensePlate": "苏AD12345", + "pickupTime": "2026-08-21T09:00:00", + "deliveryTime": "2026-08-21T18:00:00", + "pickupAddress": "...", + "destinationAddress": "...", + "planVoided": false, + "planArchived": false + } + ] +} +``` + +- `planVoided` / `planArchived`:复用现有 `_resolve_driver_link_flags` 语义(计划作废/运输取消 → voided;计划归档 → archived)。 +- `statusLabel` 可由前端根据上述 flag 计算:已作废 > 已归档 > 进行中;也可后端直接返回,二选一,实现时保持单一来源。 + +### 5.3 不变接口 + +- `GET /api/public/pl/transport/{token}` +- `POST /api/public/pl/transport/{token}/feedback` +- `POST /api/public/pl/transport/{token}/attachments` + +互通填写**不**扩展「入口 token + targetId」双参;一律跳转目标单自有 token。 + +### 5.4 实现落点(建议) + +- 路由:`backend/app/api/pl/public_transport.py` +- Schema:`backend/app/schemas/pl/transport.py`(新增 History 读模型) +- 车牌规范化:trim;比较前可统一去除内部空格(若存量有空格差异,实现时与列表筛车牌逻辑对齐) + +## 6. 前端设计 + +### 6.1 路由 + +| 路径 | 说明 | +|---|---| +| `/public/pl/transport/:token` | 现有司机详情(改底部栏) | +| `/public/pl/transport/:token/history` | 新增运输记录列表;`token` 为**进入列表时**所用司机 token | + +静态路由注册于 `web-admin/src/router/routes/staticRoutes.ts`。 + +### 6.2 详情页 + +文件:`web-admin/src/views/public/pl/transport/index.vue` + +- 底部固定「运输记录」:`router.push({ name/path: history, params: { token } })`。 +- **可编辑:** 「运输记录」+「保存回执」并排。 +- **`planVoided` / `planArchived`:** 仅空状态 +「运输记录」。 +- **链接无效 error:** 不展示「运输记录」(无有效 token 可查)。 + +### 6.3 列表页(新) + +- Shell:`PublicMobileShell`;风格对齐现有公共运输页(绿顶栏、卡片、圆角底栏)。 +- 筛选:快捷「今天」「明天」「后天」+ ``(或 Vant 等价);进入默认今天并立即请求。 +- 卡片:计划号、状态 Tag、取货/送货日、线路(取货地址 → 送货地址摘要)。 +- 点击:`router.push(/public/pl/transport/${item.driverAccessToken})`。 +- 顶栏返回:回到 `/public/pl/transport/${列表路由上的 token}`(即进入列表时的那一单)。 + +### 6.4 API 封装 + +`web-admin/src/api/pl/public-transport.ts` 增加: + +`getHistory(token: string, date: string)` → `GET /public/pl/transport/${token}/history?date=` + +## 7. 错误与边界 + +| 场景 | 行为 | +|---|---| +| token 无效/已轮换 | 404;详情与 history 均不可用 | +| 车牌为空 | history 返回空列表 | +| 所选日无命中 | 空状态「暂无运输记录」 | +| 取送货时间皆空 | 该行永不被任何 date 命中 | +| 同主车不同挂车 | 仍聚合(只比主车号) | +| 跨租户同车牌 | 不聚合(强制入口 `tenant_no`) | + +## 8. 测试要点 + +1. 默认今天;快捷明天/后天;手选其他日;命中取货日或送货日任一等于所选日。 +2. 同主车多计划:从 A 链进列表再进 B,可保存 B 回执。 +3. 归档/作废详情:空状态 +「运输记录」可进列表。 +4. 调整运输轮换 token 后旧链接 404。 +5. 主车不同不出现;仅挂车不同仍出现。 +6. 入口单已归档仍可打开 history。 + +## 9. 参考 + +- 现有公共 API:`backend/app/api/pl/public_transport.py` +- 现有详情页:`web-admin/src/views/public/pl/transport/index.vue` +- 交互 Demo:`docs/demo-driver-transport-history.html`