API Changelog Bot 5ec7ea3277 docs(changelog): 司机H5真实拍照上传OSS免登录通道已补齐(PR#3823)+缺口收口

新增 POST /app/h5/driver-onboard/upload 免登录中转上传端点,补齐上一条标记的
唯一前瞻缺口;后端中转方案,前端不碰OSS SDK,POST文件拿url回填即可。测试服9443实测两例通过。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-15 15:17:43 +08:00

3.3 KiB

原始文件 Blame 文件历史

【新增接口·司机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. 调用示例

# 上传一张证件照，拿回 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 即可；若想按类型分目录可自定义。

3.3 KiB 原始文件 Blame 文件历史 Unescape Escape