# 【新增接口·司机H5】真实拍照/证件照免登录上传 OSS 通道已补齐（PR #3823）

> 端：hl-ui（司机自助录入 H5，fleet 二期）+ 后端 hl-fleet-service | PR #3823（已合 dev-v3）| 测试服网关 9443 实测（2026-06-15）
> 关联上一条 `15_司机H5录入免登录已就绪PR3803-待补真实拍照上传OSS免登录通道-司机H5.md` 标记的「唯一前瞻缺口」——本条**正式补齐**，前端可以接「拍照上传」了。

## ⚠️ 关键说明（一句话）

新增免登录端点 `POST /app/h5/driver-onboard/upload`：司机**无需任何账号**，凭录入 token 即可把真实拍照/证件照传到 OSS 拿回**公开 URL**，再回填到提交入参的 `idCardFrontUrl / licenseFrontUrl / portraitUrl / regFrontUrl` 等字段。之前对齐的两条走法（STS 前端直传 vs 后端中转）后端**选了"后端中转"**——前端不用碰 OSS SDK、不用拿临时密钥，只管把文件 POST 给这个端点、拿返回的 `url` 即可。

## 1. 接口契约

| 项 | 内容 |
|---|---|
| 方法/路径 | `POST /app/h5/driver-onboard/upload` |
| 鉴权 | **免登录**（网关 `/app/h5/**` 白名单 + token 自校验），无需任何 JWT |
| Content-Type | `multipart/form-data` |
| 入参 `token` | 必填，录入链接 token（form 字段） |
| 入参 `file` | 必填，图片文件，**仅图片类型 ≤10MB** |
| 入参 `groupKey` | 选填，OSS 分组前缀，**默认 `fleet-driver`**（如需头像单独目录可传 `fleet-portrait` 等） |
| 返回 | `{ "url": "OSS 公开访问 URL" }` |
| 限流 | 30 次 / 60 秒（公开端点防刷，口径同 OCR） |

**错误码**：

| code | 含义 |
|---|---|
| 100001 | 文件为空 / 非图片 / 超 10MB |
| 600300 | token 无效 |
| 600301 | token 已过期 |
| 600302 | token 已使用 |
| 600304 | 链接已作废 |

## 2. 调用示例

```bash
# 上传一张证件照，拿回 OSS 公开 URL
curl -k -X POST "https://web.test.1814.love:9443/app/h5/driver-onboard/upload" \
  -F "token=<录入链接token>" \
  -F "file=@id_card_front.jpg" \
  -F "groupKey=fleet-driver"
# → {"code":200,"message":"成功","data":{"url":"https://oss.../fleet-driver/2026/06/xxx.jpg"},"success":true}
```

前端典型流程：拍照/选图 → 调本端点拿 `url` → 把 `url` 填进对应字段（`idCardFrontUrl` 等）→ 最后一并提交 `submit/new` 或 `submit/renew`。多图（车辆外观/内饰 `exteriorUrls/interiorUrls`）逐张上传、各自拿 `url` 收进数组。

## 3. 实测（测试服 9443，2026-06-15）

| 场景 | 入参 | 实测返回 |
|---|---|---|
| 合法图片 + 无效 token | image/png + 伪 token | `code:600300`「邀请链接无效」✓（路由通 + 免登录无 401 + 文件校验过 + token 校验生效） |
| 非图片文件 | text/plain | `code:100001`「参数非法: 仅支持上传图片文件」✓（文件守门先于 token） |

真实 OSS 落盘走的是 user-service 文件服务现成直传链路（与车/司机批量导入内联图同一通道，已生产验证）。

## 4. 前端动作

- 排到「拍照上传」那步时，把图片 POST 到本端点，用返回的 `url` 回填字段即可。
- **不要**再接需登录的 `/mp/file/upload` 或 `/admin/file/upload`（司机端无账号用不了）。
- `groupKey` 一般不用传，默认 `fleet-driver` 即可；若想按类型分目录可自定义。