From 5ec7ea3277fe48a23c5ae4b7f354a1118cc84314 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 15 Jun 2026 15:17:43 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=8F=B8=E6=9C=BAH5?= =?UTF-8?q?=E7=9C=9F=E5=AE=9E=E6=8B=8D=E7=85=A7=E4=B8=8A=E4=BC=A0OSS?= =?UTF-8?q?=E5=85=8D=E7=99=BB=E5=BD=95=E9=80=9A=E9=81=93=E5=B7=B2=E8=A1=A5?= =?UTF-8?q?=E9=BD=90(PR#3823)+=E7=BC=BA=E5=8F=A3=E6=94=B6=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 POST /app/h5/driver-onboard/upload 免登录中转上传端点,补齐上一条标记的 唯一前瞻缺口;后端中转方案,前端不碰OSS SDK,POST文件拿url回填即可。测试服9443实测两例通过。 Co-Authored-By: Claude Opus 4.8 (1M context) --- ...拍照上传OSS免登录通道已补-新增接口-司机H5.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 changelogs-v2/2026-06/15_司机H5真实拍照上传OSS免登录通道已补-新增接口-司机H5.md diff --git a/changelogs-v2/2026-06/15_司机H5真实拍照上传OSS免登录通道已补-新增接口-司机H5.md b/changelogs-v2/2026-06/15_司机H5真实拍照上传OSS免登录通道已补-新增接口-司机H5.md new file mode 100644 index 0000000..1b04c0d --- /dev/null +++ b/changelogs-v2/2026-06/15_司机H5真实拍照上传OSS免登录通道已补-新增接口-司机H5.md @@ -0,0 +1,59 @@ +# 【新增接口·司机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` 即可；若想按类型分目录可自定义。