From 9af37c3f5659a267cc6f793f6ef55220036af59b Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Sun, 2 Aug 2026 10:13:12 +0800 Subject: [PATCH] docs: add vehicle/personnel photo field design and UI demo Capture the approved photo_urls approach (list thumbnail A, optional upload) for pl_vehicle and pl_personnel before implementation. Co-authored-by: Cursor --- .gitignore | 1 + ...-mint-pl-vehicle-personnel-photo-demo.html | 759 ++++++++++++++++++ ...08-02-pl-vehicle-personnel-photo-design.md | 200 +++++ 3 files changed, 960 insertions(+) create mode 100644 docs/fresh-mint-pl-vehicle-personnel-photo-demo.html create mode 100644 docs/superpowers/specs/2026-08-02-pl-vehicle-personnel-photo-design.md diff --git a/.gitignore b/.gitignore index 6e4883e98..29f9af310 100644 --- a/.gitignore +++ b/.gitignore @@ -84,3 +84,4 @@ exports/ # uni-app 编译产物 miniprogram/unpackage/ +.superpowers/ diff --git a/docs/fresh-mint-pl-vehicle-personnel-photo-demo.html b/docs/fresh-mint-pl-vehicle-personnel-photo-demo.html new file mode 100644 index 000000000..fb60372de --- /dev/null +++ b/docs/fresh-mint-pl-vehicle-personnel-photo-demo.html @@ -0,0 +1,759 @@ + + + + + + Fresh Mint · 车辆/驾押人员照片字段 Demo + + + + + + +
+
+

Fresh Mint · 车辆 / 驾押人员照片字段

+

+ 覆盖四个列表页：三方车辆、山峡自有车辆、三方驾押人员、山峡驾押人员。 + 车辆与人员各增加一个照片字段，默认只存 1 张图片（MinIO URL）。 + 请点击下方方案卡片选择偏好，便于后续落地实现。 +

+ +
+ +
+
+

1. 覆盖范围 两表四页

+

底层两张表各加一字段；四个页面共用同一套上传控件（AttachmentUploadField，limit=1，accept=image/*）。

+
+
+
+
三方车辆
+
表 pl_vehicle
字段建议 photo_urls
+
+
+
山峡自有车辆
+
同表 pl_vehicle
车辆照片
+
+
+
三方驾押人员
+
表 pl_personnel
字段建议 photo_urls
+
+
+
山峡驾押人员
+
同表 pl_personnel
人员照片
+
+
+
+ 存储约定：与现有附件一致，库字段存逗号分隔 URL；前端 limit=1，实际默认只保留一张。上传 folder 建议： + pl/vehicle-photo / pl/personnel-photo。 +
+
+ +
+
+

2. 列表展示形态 请点选

+

照片列放在主标识列（车牌号 / 姓名）附近。请选择更偏好的列表展示方式。

+
+
+
+
+
+

方案 A · 方形缩略图（推荐）

+

48×48，object-fit: cover，无图显示「未上传」

+
+
+
+
+
+

三方车辆

+
+ ＋ 新增车辆 + 编辑 +
+ + + + + + + + + + + + + + + + + + + + + + + +
照片车牌号状态承运商
+ 车辆照片 + 皖H12345 / 皖H12346可用承运商1
未上传皖P09872 / 皖S90921可用隆鑫运输
+
+
+
+ +
+
+
+

方案 B · 附件卡片紧凑态

+

对齐证书附件列样式，略扁的预览卡

+
+
+
+
+
+

山峡驾押人员

+
+ ＋ 新增人员 + 编辑 +
+ + + + + + + + + + + + + + + + + + + + + + + +
照片姓名类型状态
+ 人员照片 + 王驾驶驾驶员在职
—李押运押运员在职
+
+
+
+
+
+ +
+
+

3. 新增 / 编辑弹窗

+

沿用协议附件卡片化布局：上传触发卡片 140×96，虚线边框；limit=1，仅图片；与业务字段同表单。

+
+
+
+
新增自有车辆
+
+
+
+ +
请输入车牌号
+
+
+ +
请输入挂车号
+
+
+ +
请选择承运商
+
+
+ +
如 32
+
+
+ +
+
+
+
+ 上传附件 +
+ + +
+
仅支持图片，最多 1 张；上传后立即保存到对象存储。
+
+
+
+
+ ✕ 取消 + ✓ 确定 +
+
+
+ +
+
+
+
+

照片非必填（推荐）

+

可先建档后补图，与当前证书附件策略一致

+
+
+
+
+
+
+
+

照片必填

+

新增/编辑提交时校验必须有 1 张图

+
+
+
+
+
+
+ +
+
+

4. 查看弹窗中的照片

+

只读预览：左侧大图，右侧基础信息；无图时显示占位。

+
+
+
+ 人员照片 +
+
姓名
王驾驶
+
手机号
13089012212
+
人员类型
驾驶员
+
归属
山峡驾押人员
+
状态
在职
+
+
+
+
+ +
+
+ 当前选择：列表 方案 A · 方形缩略图 · 校验 非必填 +
+
文件：docs/fresh-mint-pl-vehicle-personnel-photo-demo.html
+
+
+ + + + diff --git a/docs/superpowers/specs/2026-08-02-pl-vehicle-personnel-photo-design.md b/docs/superpowers/specs/2026-08-02-pl-vehicle-personnel-photo-design.md new file mode 100644 index 000000000..1e789e7bc --- /dev/null +++ b/docs/superpowers/specs/2026-08-02-pl-vehicle-personnel-photo-design.md @@ -0,0 +1,200 @@ +# 运输计划 · 车辆/驾押人员照片字段 — 设计文档 + +> **日期**: 2026-08-02 +> **状态**: 待审阅 +> **Demo**: `docs/fresh-mint-pl-vehicle-personnel-photo-demo.html` +> **页面**: +> - 三方车辆 `web-admin` `/#/pl/vehicle` → `src/views/pl/vehicle/index.vue` +> - 山峡自有车辆 `/#/pl/self-vehicle` → `src/views/pl/self-vehicle/index.vue` +> - 三方/山峡驾押人员 `/#/pl/personnel*` → `src/views/pl/personnel/index.vue`（归属模式共用） + +## 目标 + +为车辆档案与驾押人员档案各增加一个**照片**字段，默认只存 **1 张**图片（MinIO URL），用于列表识别与档案查看。 + +覆盖范围： + +1. 三方车辆、山峡自有车辆（同一张表 `pl_vehicle`） +2. 三方驾押人员、山峡驾押人员（同一张表 `pl_personnel`） + +## 已确认业务规则 + +| 规则 | 决策 | +|------|------| +| 存储形态 | 路径 2：`photo_urls`（逗号分隔 URL），前端 `limit=1` | +| 列表展示 | 方案 A：48×48 方形缩略图；无图显示「未上传」 | +| 是否必填 | **非必填**（可先建档后补图） | +| 文件类型 | 仅图片（`accept="image/*"`） | +| 数量 | 默认 1 张；前端硬限制 1；后端不强制必填 | +| 上传组件 | 复用 `AttachmentUploadField`（卡片化布局） | +| 上传目录 | 车辆 `pl/vehicle-photo`；人员 `pl/personnel-photo` | + +## 非目标（本期不做） + +- 多图相册、主图/附图切换 +- 照片 OCR / 人脸比对 +- 强制历史数据补图 +- MinIO 孤儿文件清理 +- 小程序端同步改造（除非后续单独需求） + +--- + +## 方案选型 + +**采用路径 2：`photo_urls` 字段 + 前端 limit=1** + +| 对比项 | `photo_url` 单 URL | `photo_urls`（采用） | 挂到证书附件 | +|--------|-------------------|----------------------|--------------| +| 与附件组件一致性 | 弱 | 强 | 职责混淆 | +| 扩展多图 | 需改字段 | 仅调 limit | 不合适 | +| 语义 | 更直观 | 字段名带 s | — | + +--- + +## 数据模型变更 + +### `pl_vehicle` 新增列 + +放在 `vehicle_status` 与 `tenant_no` 之间： + +```sql +ALTER TABLE `pl_vehicle` + ADD COLUMN `photo_urls` varchar(2000) DEFAULT NULL COMMENT '车辆照片URL，逗号分隔（默认1张）' AFTER `vehicle_status`; +``` + +### `pl_personnel` 新增列 + +放在 `status` 与 `tenant_no` 之间： + +```sql +ALTER TABLE `pl_personnel` + ADD COLUMN `photo_urls` varchar(2000) DEFAULT NULL COMMENT '人员照片URL，逗号分隔（默认1张）' AFTER `status`; +``` + +同步更新： + +- `docs/sql/shanxia2.0.sql` +- 迁移脚本：`backend/scripts/migrate_20260802_pl_vehicle_personnel_photo_urls.sql` +- ORM：`backend/app/models/pl_models.py` 中 `PlVehicle` / `PlPersonnel` + +--- + +## 后端设计 + +### Schema（`backend/app/schemas/pl/base_data.py`） + +| Schema | 变更 | +|--------|------| +| `VehicleBase` | 增加可选 `photo_urls: Optional[str]`，alias `photoUrls`，`max_length=2000` | +| `VehicleUpdate` | 同上（optional） | +| `PersonnelBase` | 同上 | +| `PersonnelUpdate` | 同上 | + +`VehicleRead` / `PersonnelRead` 经 Base 或显式字段带出 `photoUrls`；`model_validate(vehicle)` 即可自动映射 ORM 列。 + +### API（`backend/app/api/pl/base_data.py`） + +| 接口 | 变更 | +|------|------| +| `POST /transport/vehicle` | `PlVehicle(..., photo_urls=payload.photo_urls)` | +| `PUT /transport/vehicle/{id}` | `model_dump(exclude_unset=True)` 已含 `photo_urls` 时 setattr | +| `GET` list/detail vehicle | Read 自动带 `photoUrls` | +| `POST /transport/personnel` | 写入 `photo_urls` | +| `PUT /transport/personnel/{id}` | 同上 | +| `GET` list/detail personnel | Read 自动带 `photoUrls` | + +**校验** + +- 不校验非空（非必填） +- 不在后端截断多 URL；前端保证最多 1 张。若未来需要，可在 service 层取第一段 URL（本期不做） + +**字段一致性** + +Create/Update Body 与前端 `formData` / Payload 均包含 `photoUrls`，与 Read 对齐；实现后可跑 `python scripts/check_field_consistency.py`（若该检查已覆盖 PL 实体）。 + +--- + +## 前端设计 + +### 类型（`web-admin/src/api/pl/index.ts`） + +`Vehicle` / `VehiclePayload` / `Personnel` / `PersonnelPayload` 增加： + +```ts +photoUrls?: string +``` + +### 列表（方案 A） + +四页（车辆两页 + 人员一页双模式）在主标识列附近增加「照片」列： + +- 有 URL：`` 48×48，`object-fit: cover`，圆角 8px；取 `photoUrls` 逗号分隔的第一段 +- 无 URL：占位「未上传」 +- 列表缩略图**仅展示**，不单独开预览；预览在查看弹窗（`AttachmentUploadField` disabled）完成 +- 列定义加入 `listColumnDefs`，**默认可见**，支持列设置隐藏 +- 列持久化 key 如有版本号需升版（避免旧缓存无新列） + +### 新增 / 编辑弹窗 + +在表单合适位置（建议业务基础字段之后、证书区块之前）增加： + +```vue + + + /> + +``` + +- 非必填，无 form rules +- 提交前：`photoUploadRef.hasUploading?.()` 为 true 时 `ElMessage.warning('附件上传中，请稍候')` +- 重置/打开弹窗时同步 `photoUrls` + +### 查看弹窗（`SystemViewDialog`） + +- 在详情字段中增加照片只读展示（可用 `AttachmentUploadField` `disabled` + `limit=1`，或 hero 区缩略图） +- 无图时展示「—」或「未上传」 + +### UI 规范对齐 + +- Fresh Mint；附件卡片 140×96、虚线边框 `#a7f3d0`（组件已实现） +- 弹窗 `label-position="top"`、`dialog-form-layout` +- 列表缩略图风格见 Demo + +--- + +## 错误处理与边界 + +| 场景 | 行为 | +|------|------| +| 未上传照片保存 | 允许，`photo_urls` 为 null/空 | +| 上传中点确定 | 前端拦截提示 | +| 上传失败 | 组件内提示，不写入 form | +| 删除照片后保存 | `photoUrls` 置空字符串或 undefined，后端写 null/空 | +| 旧数据无列值 | 列表显示「未上传」，功能正常 | + +--- + +## 测试要点 + +1. 迁移后四页列表出现「照片」列，默认可见 +2. 车辆/人员新增上传 1 张图 → 列表缩略图可见 → 查看弹窗可见 +3. 编辑替换/删除照片后列表与详情同步 +4. 不上传可成功保存 +5. `limit=1` 无法选第二张 +6. 三方与自有车辆、三方与山峡人员行为一致 +7. 字段一致性检查通过（若适用） + +--- + +## 实施顺序建议 + +1. DB 迁移 + ORM + Schema +2. API create/update 透传 +3. 前端类型 + 车辆两页 +4. 前端人员页 +5. 自测上述要点 + `graphify` / `./scripts/update-graph.sh`（改代码后）