# RecognizeDriverLicenseController 测试报告

## 测试环境

| 项 | 值 |
|---|---|
| 测试时间 | 2026-06-06 01:51:54 |
| 服务地址 | `http://localhost:8888` |
| 接口路径 | `POST /driver/license/recognize` |
| Content-Type | `application/json` |
| 鉴权 | macOS 本地环境跳过 Tencent 鉴权（LogAop 非 Linux 不拦截） |

## 汇总

- 总用例：**19**
- 通过：**19**
- 失败：**0**
- 通过率：**100%**

## 用例明细

| 编号 | 场景 | 类型 | HTTP | code | 结果 | 说明 |
|---|---|---|---|---|---|---|
| TC01 | 缺少 imageUrlOrBase64 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC02 | imageUrlOrBase64 空字符串 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC03 | imageUrlOrBase64 仅空白 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC04 | side 非法值 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC05 | www 缺少协议头 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC06 | ftp 协议 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC07 | Unix 本地路径 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC08 | Windows 本地路径 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC09 | 非 Base64 普通文本 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC10 | data 前缀缺少 base64 段 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC11 | Base64 过短 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC12 | Base64 填充位非法 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC13 | http 协议少斜杠 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC14 | 双斜杠缺协议 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC15 | file 协议 | 入参校验 | 200 | 200 | ✅ 通过 | 入参校验拦截成功，返回 R.ok + 提示 |
| TC16 | 有效 HTTPS 公网图片（正页） | 平台识别 | 200 | 200 | ✅ 通过 | 平台链路返回提示：平台业务拒绝 |
| TC17 | 有效 1x1 PNG Base64 | 平台识别 | 200 | 200 | ✅ 通过 | 平台链路返回提示：影像不合规 |
| TC18 | side=back 公网图片 | 平台识别 | 200 | 200 | ✅ 通过 | 平台链路返回提示：平台业务拒绝 |
| TC19 | side=front 别名 | 平台识别 | 200 | 200 | ✅ 通过 | 平台链路返回提示：并发限流 |

## 详细记录

### TC01 缺少 imageUrlOrBase64

- **类型**：入参校验
- **期望**：影像源缺失
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·影像源缺失】imageUrlOrBase64 未提供或仅包含空白字符｜定位信息：入参长度=0，side=face｜处置指引：请传 HTTP/HTTPS 图片链接，或 jpg/jpeg/png/bmp 的 Base64 字符串
```

**响应 data（摘要）：**

```json
{}
```

### TC02 imageUrlOrBase64 空字符串

- **类型**：入参校验
- **期望**：影像源缺失
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·影像源缺失】imageUrlOrBase64 未提供或仅包含空白字符｜定位信息：入参长度=0，side=face｜处置指引：请传 HTTP/HTTPS 图片链接，或 jpg/jpeg/png/bmp 的 Base64 字符串
```

**响应 data（摘要）：**

```json
{}
```

### TC03 imageUrlOrBase64 仅空白

- **类型**：入参校验
- **期望**：影像源缺失
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "   ",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·影像源缺失】imageUrlOrBase64 未提供或仅包含空白字符｜定位信息：入参长度=0，side=face｜处置指引：请传 HTTP/HTTPS 图片链接，或 jpg/jpeg/png/bmp 的 Base64 字符串
```

**响应 data（摘要）：**

```json
{}
```

### TC04 side 非法值

- **类型**：入参校验
- **期望**：页面标识无效
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "https://example.com/a.jpg",
  "side": "invalid"
}
```

**响应 msg：**

```
【驾驶证识别·页面标识无效】参数 side 的取值无法映射到驾驶证正页或副页识别模式｜定位信息：当前 side=invalid，合法取值=face|front|back｜处置指引：正页（含纸质正页、电子驾驶证正页）请传 face 或 front；副页（含实习记录等）请传 back
```

**响应 data（摘要）：**

```json
{}
```

### TC05 www 缺少协议头

- **类型**：入参校验
- **期望**：链接缺少协议头
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "www.example.com/a.jpg",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·链接缺少协议头】链接以 www. 开头但缺少协议头，无法识别为 HTTP(S) 地址｜定位信息：入参前缀=www.example.com/a.jpg，side=face｜处置指引：若以链接传图，请补全为 https:// 或 http:// 开头
```

**响应 data（摘要）：**

```json
{}
```

### TC06 ftp 协议

- **类型**：入参校验
- **期望**：链接协议无效
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "ftp://example.com/a.jpg",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·链接协议无效】检测到 ftp:// 协议，本接口仅支持 HTTP/HTTPS 图片链接｜定位信息：入参前缀=ftp://example.com/a.jpg，side=face｜处置指引：图片链接须以 http:// 或 https:// 开头，且可被公网访问
```

**响应 data（摘要）：**

```json
{}
```

### TC07 Unix 本地路径

- **类型**：入参校验
- **期望**：影像格式无效
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "/tmp/driver.jpg",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·影像格式无效】检测到以 / 开头的本地绝对路径，无法作为网络图片链接使用｜定位信息：入参前缀=/tmp/driver.jpg，side=face｜处置指引：请改为 HTTP/HTTPS 图片链接，或将图片转为 Base64 后传入
```

**响应 data（摘要）：**

```json
{}
```

### TC08 Windows 本地路径

- **类型**：入参校验
- **期望**：影像格式无效
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "C:\\images\\driver.jpg",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·影像格式无效】检测到 Windows 本地路径（如 C:\...），无法作为网络图片链接使用｜定位信息：入参前缀=C:\images\driver.jpg，side=face｜处置指引：请改为 HTTP/HTTPS 图片链接，或将图片转为 Base64 后传入
```

**响应 data（摘要）：**

```json
{}
```

### TC09 非 Base64 普通文本

- **类型**：入参校验
- **期望**：Base64 字符非法
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "not-a-valid-image-input",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·Base64 字符非法】内容包含非 Base64 合法字符（仅允许 A-Z、a-z、0-9、+、/、=）｜定位信息：非法片段示例=not-a-va，side=face｜处置指引：请检查是否误传了普通文本、JSON 字段名或文件路径；链接须以 http:// 或 https:// 开头
```

**响应 data（摘要）：**

```json
{}
```

### TC10 data 前缀缺少 base64 段

- **类型**：入参校验
- **期望**：Base64 前缀无效
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "data:image/jpeg;xxx,abc",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·Base64 前缀无效】data: 前缀格式不正确，缺少 base64, 段｜定位信息：入参前缀=data:image/jpeg;xxx,abc，side=face｜处置指引：请使用 data:image/jpeg;base64,{数据} 格式，或直接传纯 Base64 字符串
```

**响应 data（摘要）：**

```json
{}
```

### TC11 Base64 过短

- **类型**：入参校验
- **期望**：Base64 内容过短
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "abc",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·Base64 内容过短】剥离前缀后 Base64 仅 3 字符，不足以构成有效图片｜定位信息：原始入参长度=3 字符，side=face｜处置指引：请确认图片已完整编码，未截断
```

**响应 data（摘要）：**

```json
{}
```

### TC12 Base64 填充位非法

- **类型**：入参校验
- **期望**：Base64 字符非法
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "abcd====",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·Base64 字符非法】内容包含非 Base64 合法字符（仅允许 A-Z、a-z、0-9、+、/、=）｜定位信息：非法片段示例=abcd====，side=face｜处置指引：请检查是否误传了普通文本、JSON 字段名或文件路径；链接须以 http:// 或 https:// 开头
```

**响应 data（摘要）：**

```json
{}
```

### TC13 http 协议少斜杠

- **类型**：入参校验
- **期望**：链接缺少协议头
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "http:/example.com/a.jpg",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·链接缺少协议头】链接协议写法错误，应为 http:// 而非 http:/｜定位信息：入参前缀=http:/example.com/a.jpg，side=face｜处置指引：若以链接传图，请补全为 https:// 或 http:// 开头
```

**响应 data（摘要）：**

```json
{}
```

### TC14 双斜杠缺协议

- **类型**：入参校验
- **期望**：链接缺少协议头
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "//example.com/a.jpg",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·链接缺少协议头】链接以 // 开头但缺少协议头（如 https:），无法识别为完整 URL｜定位信息：入参前缀=//example.com/a.jpg，side=face｜处置指引：若以链接传图，请补全为 https:// 或 http:// 开头
```

**响应 data（摘要）：**

```json
{}
```

### TC15 file 协议

- **类型**：入参校验
- **期望**：链接协议无效
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 入参校验拦截成功，返回 R.ok + 提示

**请求体：**

```json
{
  "imageUrlOrBase64": "file:///tmp/a.jpg",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·链接协议无效】检测到 file:// 本地文件协议，不支持直接读取本地文件｜定位信息：入参前缀=file:///tmp/a.jpg，side=face｜处置指引：图片链接须以 http:// 或 https:// 开头，且可被公网访问
```

**响应 data（摘要）：**

```json
{}
```

### TC16 有效 HTTPS 公网图片（正页）

- **类型**：平台识别
- **期望**：进入平台识别链路
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 平台链路返回提示：平台业务拒绝

**请求体：**

```json
{
  "imageUrlOrBase64": "https://www.opsky.com.cn/upload/20211224/KXfgvm2MFRAXKbPu5LK.png",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·平台业务拒绝】平台返回了未在本地维护的错误码，需结合错误描述人工判读｜定位信息：错误码=282103，错误描述=recognize error, failed to match the template，目标页面=正页(front/face)｜处置指引：请依据错误描述调整入参或影像后重试；持续失败请附带 traceId 联系技术支持
```

**响应 data（摘要）：**

```json
{}
```

### TC17 有效 1x1 PNG Base64

- **类型**：平台识别
- **期望**：进入平台识别链路
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 平台链路返回提示：影像不合规

**请求体：**

```json
{
  "imageUrlOrBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
  "side": "face"
}
```

**响应 msg：**

```
【驾驶证识别·影像不合规】像素尺寸或编码后体积不满足规范（边长 15~4096px，编码后≤4M）｜定位信息：错误码=216202，错误描述=image size error，目标页面=正页(front/face)｜处置指引：请压缩或裁剪图片，保证最长边≤4096px、最短边≥15px，且 urlencode 后≤4M
```

**响应 data（摘要）：**

```json
{}
```

### TC18 side=back 公网图片

- **类型**：平台识别
- **期望**：进入平台识别链路
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 平台链路返回提示：平台业务拒绝

**请求体：**

```json
{
  "imageUrlOrBase64": "https://www.opsky.com.cn/upload/20211224/KXfgvm2MFRAXKbPu5LK.png",
  "side": "back"
}
```

**响应 msg：**

```
【驾驶证识别·平台业务拒绝】平台返回了未在本地维护的错误码，需结合错误描述人工判读｜定位信息：错误码=282103，错误描述=recognize error, failed to match the template，目标页面=副页(back)｜处置指引：请依据错误描述调整入参或影像后重试；持续失败请附带 traceId 联系技术支持
```

**响应 data（摘要）：**

```json
{}
```

### TC19 side=front 别名

- **类型**：平台识别
- **期望**：进入平台识别链路
- **HTTP 状态码**：200
- **业务 code**：`200`
- **结果**：通过 — 平台链路返回提示：并发限流

**请求体：**

```json
{
  "imageUrlOrBase64": "https://www.opsky.com.cn/upload/20211224/KXfgvm2MFRAXKbPu5LK.png",
  "side": "front"
}
```

**响应 msg：**

```
【驾驶证识别·并发限流】单位时间请求过于密集，已触发平台 QPS 限流，请拉长调用间隔后重试｜定位信息：错误码=18，错误描述=Open api qps request limit reached，目标页面=正页(front/face)｜处置指引：请在客户端增加限流/退避策略，避免瞬时并发过高
```

**响应 data（摘要）：**

```json
{}
```

## 结论

1. **入参校验类用例（TC01–TC15）**：均返回 HTTP 200 + 业务 code 200，错误说明写入 `msg`，`data` 为空对象，符合「校验失败也返回 ok」的约定。
2. **平台识别类用例（TC16–TC19）**：使用公网 PNG / 1x1 Base64 触发百度识别链路；测试图非驾驶证，字段为空或带平台提示属正常。
3. **建议**：补充真实驾驶证正/副页样本，验证字段映射完整性。
