502 lines
30 KiB
Markdown
502 lines
30 KiB
Markdown
# 调度App H5行驶证拍摄取景引导框 — 需求文档
|
||
---
|
||
|
||
## 需求文档摘要
|
||
**一句话概括**：在调度App H5车辆管理页（`vehicleAdd.vue`）的行驶证上传流程中，拦截现有 `van-uploader` 的点击事件，先进入自定义拍摄引导页（WebRTC取景+浅色背景+灰色边框引导框+蓝色角标+Hero提示卡+取景要点卡+预览确认），拍摄确认后将照片传回现有的压缩→上传→OCR流程，实现拍摄环节的引导增强。
|
||
|
||
**核心要点**：
|
||
|
||
| 维度 | 内容 |
|
||
| --- | --- |
|
||
| **背景** | 调度App H5车辆管理页行驶证上传使用 `van-uploader` 直接调起系统选择器，无拍摄规范提示，导致卡套反光、证件歪斜、文字模糊等问题频发 |
|
||
| **目标** | 拦截行驶证槽位点击，进入拍摄引导页（浅色背景+相机预览+引导框+Hero提示卡+取景要点卡），拍摄后预览确认，确认后回到现有压缩→上传→OCR流程 |
|
||
| **现有流程** | `van-uploader` 点击 → 系统选择器 → `after-read` 回调 → `compressFileItem` 压缩 → `uploadImage` 上传 → `ocrHandler` OCR识别 |
|
||
| **改造方案** | 行驶证槽位点击 → **拍摄引导页（新增）** → 预览确认（新增）→ `compressFileItem` 压缩 → `uploadImage` 上传 → `ocrHandler` OCR识别 |
|
||
| **界面改动** | 新增拍摄引导页组件 + 预览确认页组件；改造 `vehicleAdd.vue` 中行驶证三个槽位的点击逻辑 |
|
||
| **数据规则** | 无新增字段；引导框样式与文案为前端静态资源；后端接口完全不变 |
|
||
| **原型** | [调度App-H5行驶证拍摄取景引导原型.html](https://sinoassist.yuque.com/attachments/yuque/0/2026/html/34748803/1785205633529-2dd10b98-a855-4a6b-b2a1-894fc14e3ca3.html) |
|
||
|
||
|
||
**技术要点**：
|
||
|
||
+ 后端：无需变更，复用现有 `POST /order/uploadImage` 和 `POST /agg-api/tencent-ocr/unifiedOCR`
|
||
+ 前端：`supplier-dispatch-h5` 项目 `vehicleAdd.vue` 改造 + 新增拍摄引导组件
|
||
+ 数据库：无需变更
|
||
|
||
---
|
||
|
||
## 一、基本信息
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| **需求名称** | 调度App H5行驶证拍摄取景引导框 |
|
||
| **提出人** | |
|
||
| **产品负责人** | 宋志领 |
|
||
| **所属模块** | 调度App H5 - 车辆管理（`vehicleAdd.vue`）- 行驶证上传 |
|
||
| **需求类型** | 优化 |
|
||
| **目标版本** | |
|
||
| **紧急程度** | 中 |
|
||
|
||
|
||
## 二、需求背景
|
||
### 2.1 现有流程
|
||
调度App H5车辆管理页面（`https://crm1.sino-assist.com/h5/supplier/dispatch/vehicleManage`）中，用户在录入或修改车辆信息时，需要上传行驶证主页、副页、车辆照片页。
|
||
|
||
当前上传流程基于 Vant `van-uploader` 组件实现：
|
||
|
||
```plain
|
||
用户点击 van-uploader 上传槽位
|
||
│
|
||
▼
|
||
系统调起相册/相机选择器（accept="image/*"）
|
||
│
|
||
▼
|
||
after-read 回调触发（vehicleLicenseFrontHandler / vehicleLicenseBackHandler / vehicleLicenseCarHandler）
|
||
│
|
||
▼
|
||
compressFileItem() 前端压缩（目标 < 5MB，JPEG 格式）
|
||
│
|
||
▼
|
||
uploadImage() 上传 → POST /order/uploadImage（multipart/form-data）
|
||
│
|
||
▼
|
||
ocrHandler() OCR 识别 → POST /agg-api/tencent-ocr/unifiedOCR
|
||
│
|
||
▼
|
||
回填识别结果到表单字段（车牌号、车架号、所有人等）
|
||
```
|
||
|
||
**现有代码位置**：
|
||
|
||
| 文件 | 关键方法/组件 |
|
||
| --- | --- |
|
||
| `supplier-dispatch-h5/src/views/index/vehicleAdd.vue` | `van-uploader` 组件（行驶证三个槽位） |
|
||
| `supplier-dispatch-h5/src/views/index/vehicleAdd.vue` | `vehicleLicenseFrontHandler()` — 行驶证主页上传 |
|
||
| `supplier-dispatch-h5/src/views/index/vehicleAdd.vue` | `vehicleLicenseBackHandler()` — 行驶证副页上传 |
|
||
| `supplier-dispatch-h5/src/views/index/vehicleAdd.vue` | `vehicleLicenseCarHandler()` — 行驶证车辆照片上传 |
|
||
| `supplier-dispatch-h5/src/views/index/vehicleAdd.vue` | `compressFileItem()` — 图片压缩 |
|
||
| `supplier-dispatch-h5/src/api/mine.js` | `uploadImage()` — 上传接口 |
|
||
| `supplier-dispatch-h5/src/api/mine.js` | `ocrHandler()` — OCR 识别接口 |
|
||
|
||
|
||
### 2.2 问题分析
|
||
当前流程中，用户点击上传槽位后直接调起系统相册/相机选择器，**没有任何拍摄规范提示**。实际采集到的照片普遍存在以下问题：
|
||
|
||
1. **卡套/保护膜未取出**：证件装在透明卡套或覆膜中拍摄，塑料/玻璃表面反光，遮盖号牌、车架号等关键字段，导致OCR无法识别。
|
||
2. **摆放不规整**：歪斜、弯曲、四角缺角、未对准画面中央，导致自动识别定位失败或字段错位。
|
||
3. **反光与阴影**：在强光或灯光直射下拍摄，出现高光斑、阴影遮挡文字，造成文字模糊。
|
||
|
||
上述问题直接造成行驶证OCR识别失败、审核驳回率升高，服务商需反复重传，拉长车辆录入周期。
|
||
|
||
### 2.3 改造方向
|
||
参考业界成熟的证件拍摄方案（如银行卡、身份证识别），在拍摄预览界面上叠加半透明取景引导框，配合文字提示，能从源头规范用户拍摄行为，显著提升照片合格率。
|
||
|
||
**改造原则**：仅改造拍摄环节（系统选择器 → 自定义拍摄引导页），后续的压缩→上传→OCR流程完全保持不变。
|
||
|
||
---
|
||
|
||
## 三、需求目标
|
||
1. 用户点击行驶证任一上传槽位时，**不再直接调起系统选择器**，而是进入自定义拍摄引导页。
|
||
2. 拍摄引导页在相机预览画面上**自动叠加半透明取景引导框**，框的形状和比例匹配行驶证实际尺寸。
|
||
3. 引导框区域显示明确的文字提示：「请将行驶证从卡套内取出后拍摄，避免反光」「请将证件对准框内，确保边缘完整、文字清晰」。
|
||
4. 引导框**适配不同手机屏幕尺寸**，在主流移动端设备上显示正常。
|
||
5. 用户点击拍摄后，引导框消失，进入**照片预览确认步骤**，支持重拍或确认使用。
|
||
6. 用户确认使用后，照片**传回现有的 **`compressFileItem`** → **`uploadImage`** → **`ocrHandler`** 流程**，后续逻辑完全不变。
|
||
7. 车头照、保单等非行驶证槽位**保持现有 **`van-uploader`** 直接调起选择器的逻辑**，不受影响。
|
||
|
||
---
|
||
|
||
## 四、功能说明
|
||
### 功能点 1：拦截行驶证槽位点击，进入拍摄引导页
|
||
**功能概述**：
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| **功能名称** | 行驶证槽位点击拦截 |
|
||
| **涉及页面** | `vehicleAdd.vue` — 行驶证主页、副页、车辆照片页的 `van-uploader` 组件 |
|
||
| **触发条件** | 用户在车辆管理页点击行驶证任一上传槽位（首次上传或重新上传）时触发 |
|
||
| **处理逻辑** | 拦截 `van-uploader` 的默认点击行为（调起系统选择器），改为打开拍摄引导页组件 |
|
||
| **输出结果** | 进入拍摄引导页，展示相机预览 + 引导框 |
|
||
|
||
|
||
**改造前后对比**：
|
||
|
||
| 步骤 | 改造前（现有流程） | 改造后 |
|
||
| --- | --- | --- |
|
||
| 1 | 点击 `van-uploader` 槽位 | 点击 `van-uploader` 槽位 |
|
||
| 2 | 系统调起相册/相机选择器 | **拦截点击 → 进入拍摄引导页（新增）** |
|
||
| 3 | 选择/拍摄照片 | 相机预览 + 引导框 + 文字提示 |
|
||
| 4 | `after-read` 回调 | 点击拍摄 → **预览确认页（新增）** |
|
||
| 5 | `compressFileItem` 压缩 | 确认使用 → **构造 file 对象，触发 **`after-read`** 回调** |
|
||
| 6 | `uploadImage` 上传 | `compressFileItem` 压缩（**不变**） |
|
||
| 7 | `ocrHandler` OCR 识别 | `uploadImage` 上传（**不变**） |
|
||
| 8 | 回填表单 | `ocrHandler` OCR 识别（**不变**）→ 回填表单 |
|
||
|
||
|
||
**关键改造点**：拍摄引导页确认使用后，需将 Canvas 捕获的图片 Blob 构造为 `van-uploader` 的 `after-read` 回调所期望的 `{ file: File, content: dataURL }` 格式，从而无缝衔接现有的压缩→上传→OCR流程。
|
||
|
||
---
|
||
|
||
### 功能点 2：拍摄引导页 — 相机预览 + 引导框
|
||
**功能概述**：
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| **功能名称** | 拍摄取景引导框 |
|
||
| **涉及页面** | 新增拍摄引导页组件 |
|
||
| **触发条件** | 从行驶证槽位点击进入 |
|
||
| **处理逻辑** | 使用 WebRTC `getUserMedia` 获取摄像头视频流，在 `video` 元素上全屏展示；叠加浅色背景层（`#F5F5F5`）+ 中央镂空引导框（灰色实线边框 `#C2C8D2` + 蓝色 L 形角标 `#354D93` + 入场渐显动画）+ 顶部 Hero 提示卡（白底+蓝色图标）+ 取景要点图标卡（do/don't）+ 底部白色拍摄栏 |
|
||
| **输出结果** | 用户在规范引导下完成拍摄 |
|
||
|
||
|
||
**界面设计**（拍摄引导页示意）：
|
||
|
||
```plain
|
||
┌─────────────────────────────────────────┐
|
||
│ ← 拍摄行驶证主页 │ ← 顶部导航栏（深蓝 #2C395F）
|
||
├─────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌───────────────────────────────────┐ │ ← Hero 提示卡（白底+蓝色图标）
|
||
│ │ [📁] 请将行驶证从卡套内取出后拍摄 │ │
|
||
│ │ 避免反光，确保文字清晰 │ │
|
||
│ └───────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌───────────────────────────────────┐ │
|
||
│ │└── ──┘ │ │ ← 蓝色 L 形角标（#354D93）
|
||
│ │ 中华人民共和国机动车行驶证 │ │ ← 证件标题轮廓（半透明蓝色）
|
||
│ │ │ │
|
||
│ │ │ │ ← 页面其余区域空白
|
||
│ │ │ │
|
||
│ │ ▢ 印章 │ │ ← 印章位置轮廓（红色方形）
|
||
│ │└── ──┘ │ │
|
||
│ └───────────────────────────────────┘ │ ← 灰色实线边框（#C2C8D2）
|
||
│ │
|
||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ ← 取景要点图标卡（白底）
|
||
│ │ [✓] │ │ [✓] │ │ [✗] │ │
|
||
│ │ 边缘完整 │ │ 文字清晰 │ │ 避免反光 │ │
|
||
│ └─────────┘ └─────────┘ └─────────┘ │
|
||
│ │
|
||
├─────────────────────────────────────────┤
|
||
│ ┌──────────┐ │
|
||
│ │ ◉ 拍摄 │ │ ← 拍摄按钮（蓝色 #354D93）
|
||
│ └──────────┘ │ ← 底部白色拍摄栏
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
> 说明：全屏相机预览（`video` 元素）作为底层背景，整体页面背景为浅色（`#F5F5F5`），营造明亮的拍摄环境。屏幕中央为镂空透明区域（匹配行驶证宽高比约 1.43:1），镂空区域外围为浅色背景（区别于镂空区域的相机预览画面）。镂空区域外圈增加灰色实线边框（`#C2C8D2`，3px，带入场渐显动画），四角显示蓝色 L 形角标（`#354D93`，带入场渐显动画），辅助用户对齐证件边缘。**引导框上方设置 Hero 提示卡**（白底圆角卡片+蓝色图标+主标题"请将行驶证从卡套内取出后拍摄"+副标题"避免反光，确保文字清晰"），**引导框下方设置取景要点图标卡**（3 个白底小卡片，分别用 ✓/✗ 图标标注"边缘完整""文字清晰""避免反光"）。**引导框内叠加极简证件模板轮廓**（半透明蓝色，透明度约 20%-35%）：主页仅展示顶部一行标题"中华人民共和国机动车行驶证"和左下角红色方形印章，其余区域空白；副页仅展示右下角条形码图案（长度与真实条形码一致）及数字编号，其余区域空白。底部为白色拍摄栏，居中放置蓝色圆形拍摄按钮。
|
||
>
|
||
|
||
**操作按钮**：
|
||
|
||
| 按钮 | 触发条件 | 操作结果 |
|
||
| --- | --- | --- |
|
||
| 拍摄 | 点击 | 通过 Canvas 捕获当前 `video` 帧，生成图片 Blob，进入预览确认页 |
|
||
| 返回（左上角） | 点击 | 关闭相机流，退出拍摄引导页，返回车辆管理页，不上传照片 |
|
||
| 点击背景区（非引导框内） | 点击 | 无响应，保持拍摄引导页（防止误触） |
|
||
|
||
|
||
---
|
||
|
||
### 功能点 3：三页差异化引导
|
||
**功能概述**：
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| **功能名称** | 分页面差异化引导 |
|
||
| **涉及页面** | 行驶证主页、副页、车辆照片页拍摄引导页 |
|
||
| **触发条件** | 按用户点击的具体槽位进入对应拍摄引导页 |
|
||
| **处理逻辑** | 三页共用相同的引导框比例和通用提示文案；差异体现在页面标题和**引导框内的证件模板轮廓** |
|
||
| **输出结果** | 用户明确知道当前拍摄的是行驶证的哪一页，并能按模板轮廓对齐证件内容 |
|
||
|
||
|
||
**各页引导差异**：
|
||
|
||
| 页面 | 对应槽位 | 对应 Handler | 页面标题 | 模板轮廓内容 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 行驶证主页 | `vehicleLicenseFrontList` | `vehicleLicenseFrontHandler` | 拍摄行驶证主页 | 仅展示：顶部一行标题"中华人民共和国机动车行驶证" + 左下红色方形印章 |
|
||
| 行驶证副页 | `vehicleLicenseBackList` | `vehicleLicenseBackHandler` | 拍摄行驶证副页 | 仅展示：右下角条形码图案（长度与真实条形码一致）+ 条形码数字编号 |
|
||
| 行驶证车辆照片 | `vehicleLicenseCarPhotoList` | `vehicleLicenseCarHandler` | 拍摄行驶证车辆照片 | "车辆照片"标题 + 车辆SVG轮廓（车身/车窗/车轮），引导居中拍摄 |
|
||
|
||
|
||
> **说明**：引导框内的证件模板轮廓为半透明叠层（透明度约 20%-35%），仅作视觉对齐辅助，不遮挡相机预览画面。模板轮廓使用 CSS/SVG 静态实现，不依赖后端数据。三种模板通过 `renderLicenseTemplate(type)` 函数根据槽位类型动态切换。
|
||
>
|
||
|
||
---
|
||
|
||
### 功能点 4：照片预览确认
|
||
**功能概述**：
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| **功能名称** | 照片预览确认 |
|
||
| **涉及页面** | 拍摄完成后进入的预览确认页 |
|
||
| **触发条件** | 用户在拍摄引导页点击"拍摄"按钮后触发 |
|
||
| **处理逻辑** | 展示刚拍摄的照片，提供"重拍"和"确认使用"两个操作 |
|
||
| **输出结果** | 确认使用 → 照片传回 `van-uploader` 的 `after-read` 回调，走现有压缩→上传→OCR流程；重拍则返回拍摄引导页 |
|
||
|
||
|
||
**界面设计**（预览确认页示意）：
|
||
|
||
```plain
|
||
┌─────────────────────────────────────────┐
|
||
│ ← 返回 │
|
||
├─────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ 刚拍摄的照片预览 │ │
|
||
│ │ （全宽自适应展示） │ │
|
||
│ │ │ │
|
||
│ └─────────────────────────────┘ │
|
||
│ │
|
||
│ │
|
||
│ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 重拍 │ │ 确认使用 │ │
|
||
│ └──────────┘ └──────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
**操作按钮**：
|
||
|
||
| 按钮 | 触发条件 | 操作结果 |
|
||
| --- | --- | --- |
|
||
| 重拍 | 点击 | 返回拍摄引导页，重新进入相机预览 |
|
||
| 确认使用 | 点击 | 将照片 Blob 构造为 `{ file: File, content: dataURL }` 格式，调用对应槽位的 `after-read` Handler（如 `vehicleLicenseFrontHandler`），进入现有压缩→上传→OCR流程 |
|
||
| 返回 | 点击 | 关闭相机流，返回车辆管理页，不保存照片 |
|
||
|
||
|
||
**数据衔接说明**：
|
||
|
||
确认使用后，需构造以下对象传给现有的 Handler 方法：
|
||
|
||
```plain
|
||
{
|
||
file: new File([blob], `vehicle_license_${type}_${Date.now()}.jpg`, { type: 'image/jpeg' }),
|
||
content: dataURL // base64 格式，供 van-uploader 预览使用
|
||
}
|
||
```
|
||
|
||
传入后，现有的 `compressFileItem()` → `uploadImage()` → `ocrHandler()` 链路完全不变。
|
||
|
||
---
|
||
|
||
## 五、业务规则
|
||
### 规则 1：触发范围
|
||
引导框仅对 `vehicleAdd.vue` 中标题含"行驶证"的三个 `van-uploader` 槽位生效（主页、副页、车辆照片）；**车头照**（`vehicleFrontPhotoList`）、**保单**（`insurancePictureFiles`）等其他槽位不进入拍摄引导页，保持现有 `van-uploader` 直接调起选择器的交互。
|
||
|
||
### 规则 2：引导框比例
|
||
引导框的宽高比固定为行驶证实物比例（约 1.43:1，横向），在不同屏幕尺寸下按屏幕宽度自适应缩放（宽度约为屏幕宽度的 80%），左右留白均匀，确保用户无需过度调整手机位置即可将证件放入框内。
|
||
|
||
### 规则 3：后续流程不变
|
||
引导框仅做"拍摄环节的视觉辅助"，**不改变原上传与OCR识别流程**。用户确认使用后，照片传入现有的 `compressFileItem` → `uploadImage` → `ocrHandler` 链路，识别失败仍按现有方式提示重传。
|
||
|
||
### 规则 4：屏幕适配
|
||
引导框在竖屏模式下以横向矩形展示（行驶证为横向证件）。若用户将手机横置，引导框应自适应旋转为纵向矩形以匹配证件方向。优先保证竖屏体验，横屏为可选适配。
|
||
|
||
### 规则 5：降级策略
|
||
若设备不支持 WebRTC `getUserMedia`（部分低版本 Android WebView 或非 HTTPS 环境），**降级为现有的 **`van-uploader`** 直接调起系统选择器**，不阻断用户上传流程。降级时引导框不展示，用户走原有流程。
|
||
|
||
---
|
||
|
||
## 六、边界与异常场景
|
||
| 场景编号 | 场景描述 | 预期处理 |
|
||
| --- | --- | --- |
|
||
| 1 | 用户未对准引导框就点击拍摄 | 系统不拦截，正常拍摄并进入预览；用户在预览页可点击"重拍"重新对准 |
|
||
| 2 | 相机权限未授权 | 拍摄引导页加载前检测权限；未授权时提示"请允许使用相机权限"，并提供"从相册选择"降级入口 |
|
||
| 3 | 弱光/暗光环境拍摄 | 引导框正常展示；若设备支持，可自动开启屏幕补光（或提示用户到光线充足处拍摄） |
|
||
| 4 | 用户旋转手机（横竖屏切换） | 引导框自适应旋转，保持与行驶证方向一致；拍摄按钮和提示文字跟随屏幕方向调整位置 |
|
||
| 5 | 小屏幕手机（如 iPhone SE） | 引导框按比例缩小，提示文字自动换行，确保所有元素在可视区域内完整展示 |
|
||
| 6 | 大屏幕手机（如 iPhone Pro Max） | 引导框按比例放大，不超过屏幕安全区域，保持舒适的单手操作距离 |
|
||
| 7 | 设备不支持 getUserMedia | 自动降级为 `van-uploader` 直接调起系统选择器，不展示引导框 |
|
||
| 8 | iOS 微信内置浏览器权限受限 | 检测到微信环境且 getUserMedia 不可用时，降级为系统选择器 |
|
||
| 9 | 拍摄后未进入预览（相机被中断） | 检测到相机关闭/中断事件，自动返回车辆管理页，不上传照片 |
|
||
| 10 | 非行驶证槽位（如车头照）点击 | 不进入拍摄引导页，维持现有 `van-uploader` 直接调起选择器的交互 |
|
||
| 11 | 修改车辆时重新上传行驶证 | 同样进入拍摄引导页，拍摄确认后替换原照片，走现有压缩→上传→OCR流程 |
|
||
|
||
|
||
---
|
||
|
||
## 七、影响范围
|
||
### 前端
|
||
| 文件 | 变更类型 | 变更内容 |
|
||
| --- | --- | --- |
|
||
| `supplier-dispatch-h5/src/views/index/vehicleAdd.vue` | **改造** | 行驶证三个 `van-uploader` 槽位（`vehicleLicenseFrontList`/`vehicleLicenseBackList`/`vehicleLicenseCarPhotoList`）增加点击拦截逻辑：点击时打开拍摄引导页组件，而非直接调起系统选择器；拍摄确认后将照片传回现有的 `vehicleLicenseFrontHandler`/`vehicleLicenseBackHandler`/`vehicleLicenseCarHandler` |
|
||
| `supplier-dispatch-h5/src/views/index/vehicleAdd.vue` | **改造** | 车头照（`vehicleFrontPhotoList`）、保单（`insurancePictureFiles`）槽位**不变**，保持现有 `van-uploader` 直接调起选择器的逻辑 |
|
||
| `supplier-dispatch-h5/src/components/CameraGuide.vue` | **新增** | 拍摄引导页组件：WebRTC 相机预览 + 浅色背景层（`#F5F5F5`）+ 镂空引导框 + 灰色实线边框（`#C2C8D2`，入场渐显动画） + 四角蓝色 L 形角标（`#354D93`，入场渐显动画） + Hero 提示卡（白底+蓝色图标） + 取景要点图标卡（do/don't） + **证件模板轮廓叠层**（主页/副页/车辆照片三种模板动态切换） + 底部白色拍摄栏（蓝色圆形拍摄按钮） |
|
||
| `supplier-dispatch-h5/src/components/CameraGuide.vue` | **新增** | 预览确认页：照片展示 + 重拍按钮 + 确认使用按钮 |
|
||
| `supplier-dispatch-h5/src/api/mine.js` | **不变** | `uploadImage()` 和 `ocrHandler()` 完全复用 |
|
||
| `supplier-dispatch-h5/src/utils/` | **不变** | `compressFileItem()` 等工具方法完全复用 |
|
||
|
||
|
||
### 后端
|
||
| 文件 | 变更内容 |
|
||
| --- | --- |
|
||
| 无 | 无需变更，复用现有 `POST /order/uploadImage` 和 `POST /agg-api/tencent-ocr/unifiedOCR` |
|
||
|
||
|
||
### 数据库
|
||
| 表名 | 变更内容 |
|
||
| --- | --- |
|
||
| 无 | 无需变更 |
|
||
|
||
|
||
---
|
||
|
||
## 八、验收标准
|
||
### 8.1 拍摄引导页展示
|
||
- [ ] 点击行驶证主页/副页/车辆照片任一上传槽位，进入拍摄引导页（非直接调起系统选择器）
|
||
- [ ] 拍摄引导页展示全屏相机预览背景（`video` 元素实时画面）
|
||
- [ ] 屏幕中央显示镂空引导框，框的宽高比约 1.43:1（横向）
|
||
- [ ] 引导框外围为浅色背景（`#F5F5F5`），与镂空区域的相机预览画面形成对比
|
||
- [ ] 引导框外圈显示灰色实线边框（`#C2C8D2`，3px，带入场渐显动画）
|
||
- [ ] 引导框四角显示蓝色 L 形定位角标（`#354D93`，带入场渐显动画）
|
||
- [ ] 引导框上方显示 Hero 提示卡（白底圆角卡片+蓝色图标），主标题"请将行驶证从卡套内取出后拍摄"，副标题"避免反光，确保文字清晰"
|
||
- [ ] 引导框下方显示取景要点图标卡（3 个白底小卡片）：边缘完整（✓ 蓝色）、文字清晰（✓ 蓝色）、避免反光（✗ 红色）
|
||
- [ ] 页面底部显示白色拍摄栏，居中放置蓝色圆形拍摄按钮（`#354D93`），按钮样式醒目、易于点击
|
||
- [ ] 页面标题根据槽位类型显示对应文字（"拍摄行驶证主页"/"拍摄行驶证副页"/"拍摄行驶证车辆照片"）
|
||
- [ ] 引导框内显示证件模板轮廓（半透明，不遮挡相机预览）
|
||
- [ ] 主页模板包含：顶部一行标题"中华人民共和国机动车行驶证" + 左下红色方形印章，其余区域空白
|
||
- [ ] 副页模板包含：右下角条形码图案（长度与真实条形码一致）+ 条形码数字编号，其余区域空白
|
||
- [ ] 车辆照片模板包含：车辆SVG轮廓（车身/车窗/车轮）
|
||
- [ ] 切换不同槽位时，模板轮廓自动切换为对应内容
|
||
|
||
### 8.2 预览确认页展示
|
||
- [ ] 点击"拍摄"后进入预览确认页，展示刚拍摄的照片
|
||
- [ ] 预览页提供"重拍"按钮，点击后返回拍摄引导页
|
||
- [ ] 预览页提供"确认使用"按钮，点击后照片传入现有的 `after-read` Handler
|
||
- [ ] 预览页左上角提供"返回"按钮，点击后放弃当前照片，返回车辆管理页
|
||
|
||
### 8.3 现有流程衔接
|
||
- [ ] 确认使用后，照片经 `compressFileItem()` 压缩（目标 < 5MB）
|
||
- [ ] 压缩后经 `uploadImage()` 上传到服务器（`POST /order/uploadImage`）
|
||
- [ ] 上传后经 `ocrHandler()` 进行 OCR 识别（`POST /agg-api/tencent-ocr/unifiedOCR`）
|
||
- [ ] OCR 识别结果正确回填到表单字段（车牌号、车架号、所有人等）
|
||
- [ ] 上传槽位显示拍摄的照片缩略图
|
||
|
||
### 8.4 非行驶证槽位不受影响
|
||
- [ ] 点击车头照上传槽位，保持现有 `van-uploader` 直接调起系统选择器的逻辑
|
||
- [ ] 点击保单上传槽位，保持现有 `van-uploader` 直接调起系统选择器的逻辑
|
||
- [ ] 车头照上传后的 `ocrCarFrontHandler()` OCR 识别正常
|
||
|
||
### 8.5 屏幕适配
|
||
- [ ] 在 iPhone 各型号（SE/标准版/Plus/Pro Max）上引导框比例正确、文字完整显示
|
||
- [ ] 在 Android 主流机型（华为/小米/OPPO/vivo 等）上引导框比例正确、文字完整显示
|
||
- [ ] 竖屏模式下引导框为横向矩形，横屏模式下自适应为纵向矩形
|
||
|
||
### 8.6 降级场景
|
||
- [ ] 设备不支持 `getUserMedia` 时，降级为 `van-uploader` 直接调起系统选择器
|
||
- [ ] 降级后压缩→上传→OCR流程正常
|
||
- [ ] iOS 微信内置浏览器权限受限时，降级为系统选择器
|
||
|
||
---
|
||
|
||
## 九、非功能要求
|
||
+ **性能**：拍摄引导页从点击槽位到展示引导框的耗时 < 500ms；拍摄按钮响应 < 200ms；Canvas 捕获帧 < 100ms。
|
||
+ **兼容性**：支持 iOS Safari 12+、Android Chrome 80+、微信/企业微信内置浏览器；需兼容 WebView 环境。
|
||
+ **适配性**：支持屏幕宽度 320px - 430px 的主流手机；引导框和文字在不同尺寸下自适应，不出现截断或重叠。
|
||
+ **安全性**：引导内容为纯前端静态展示，不涉及用户照片上传前的任何数据采集与存储；相机流在页面关闭时立即释放。
|
||
+ **降级方案**：若设备不支持 WebRTC/getUserMedia，降级为现有的 `van-uploader` 直接调起系统选择器，不阻断用户上传流程。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 流程图
|
||
### 改造后完整流程
|
||
```plain
|
||
用户在 vehicleAdd.vue 点击上传槽位
|
||
│
|
||
▼
|
||
┌─────────────────────┐
|
||
│ 是否为行驶证三个 │
|
||
│ 槽位之一？ │
|
||
│ (主页/副页/车辆照片)│
|
||
└─────────────────────┘
|
||
│ │
|
||
否 是
|
||
│ ▼
|
||
│ ┌─────────────────────┐
|
||
│ │ 检测设备是否支持 │
|
||
│ │ getUserMedia？ │
|
||
│ └─────────────────────┘
|
||
│ │ │
|
||
│ 否 是
|
||
│ │ │
|
||
│ ▼ ▼
|
||
│ 降级： 进入拍摄引导页
|
||
│ van-uploader （WebRTC相机预览 +
|
||
│ 直接调起 浅色背景 + 引导框 +
|
||
│ 系统选择器 Hero卡 + 要点卡 + 角标）
|
||
│ │ │
|
||
│ │ ┌──────┼──────┐
|
||
│ │ ▼ ▼ ▼
|
||
│ │ 返回 拍摄 点击
|
||
│ │ 车辆 按钮 背景
|
||
│ │ 管理页 │ （无响应）
|
||
│ │ ▼
|
||
│ │ ┌──────────────┐
|
||
│ │ │ 照片预览确认 │
|
||
│ │ │ 页面 │
|
||
│ │ └──────────────┘
|
||
│ │ │
|
||
│ │ ┌─────┼─────┐
|
||
│ │ ▼ ▼ ▼
|
||
│ │ 重拍 确认 返回
|
||
│ │ │ 使用 车辆
|
||
│ │ │ │ 管理页
|
||
│ │ │ ▼
|
||
│ │ │ 构造 { file, content }
|
||
│ │ │ 传入 after-read Handler
|
||
│ │ │ │
|
||
▼ ▼ ▼ ▼
|
||
┌─────────────────────────┐
|
||
│ 现有流程（完全不变） │
|
||
│ compressFileItem() 压缩 │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ uploadImage() 上传 │
|
||
│ POST /order/uploadImage │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ocrHandler() OCR识别 │
|
||
│ POST /agg-api/ │
|
||
│ tencent-ocr/unifiedOCR │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 回填表单字段 │
|
||
│ (车牌号/车架号/所有人等) │
|
||
└─────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 影响范围说明
|
||
| 维度 | 影响说明 |
|
||
| --- | --- |
|
||
| **功能** | 仅新增行驶证拍摄前的取景引导层，不改变车辆管理页其他功能和OCR识别流程 |
|
||
| **数据** | 无新增业务数据；不修改现有上传接口的入参和出参 |
|
||
| **接口** | 无接口变更，复用现有 `POST /order/uploadImage` 和 `POST /agg-api/tencent-ocr/unifiedOCR` |
|
||
| **配置** | 无变更 |
|
||
| **用户习惯** | 用户上传行驶证时多了一步引导页+预览确认，但流程轻量，拍摄确认后无缝衔接现有压缩→上传→OCR流程，整体体验提升 |
|
||
|
||
|
||
|
||
|
||
## 测试关注点
|
||
| 测试类型 | 关注点 |
|
||
| --- | --- |
|
||
| **功能测试** | 三页槽位均正确进入拍摄引导页；引导框比例正确；提示文字完整显示；拍摄后进入预览确认；确认后正确回填到 `van-uploader` 并触发现有 Handler |
|
||
| **流程衔接测试** | 确认使用后 `compressFileItem` 压缩正常；`uploadImage` 上传成功；`ocrHandler` OCR 识别结果正确回填表单；行驶证主页 OCR 回填车牌号/车架号/所有人等；行驶证副页 OCR 回填档案编号/核载人数等 |
|
||
| **兼容测试** | iPhone SE/标准版/Plus/Pro Max；华为/小米/OPPO/vivo 主流机型；微信/企业微信内置浏览器；Safari/Chrome |
|
||
| **回归测试** | 车头照等非行驶证槽位保持原有直接调选择器逻辑；车辆管理页其他功能不受影响；OCR 识别与审核流程正常；修改车辆时重新上传行驶证正常 |
|
||
| **降级测试** | 不支持 `getUserMedia` 的设备降级为 `van-uploader` 系统选择器；降级后压缩→上传→OCR 流程正常 |
|
||
| **适配测试** | 竖屏/横屏切换；320px 窄屏与 430px 宽屏的显示效果；文字不截断、按钮可点击 |
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|