71 行
3.2 KiB
Markdown
71 行
3.2 KiB
Markdown
---
|
||
author: "wx(GIT)"
|
||
schema: "hl-changelog/v2"
|
||
ticket: "5933"
|
||
title: "生成 H5 录入 token 支持 requestId 幂等键（防双击）"
|
||
consumer: "admin"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "232274b5"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-08-13"
|
||
updated_at: "2026-08-13"
|
||
status_note: "后端已于 2026-08-12 合并 PR #5940 并部署测试服验证：同 requestId 首次成功、30s 内第二次返回 100502、不同 requestId 成功；旧客户端不传 requestId 连续两次均成功。API-SPEC §13.6 同步补声明 contractVersion/segmentDays/serviceDates/segmentRoute。"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 生成 H5 录入 token 支持 requestId 幂等键（#5933）
|
||
|
||
> **服务**：`hl-fleet-service`
|
||
>
|
||
> **Backend Issue**：[#5933](https://git.1814.love:8443/wx/HL/issues/5933)
|
||
|
||
## 变更接口
|
||
|
||
| 接口 | 方法 | 路径 | 变更类型 |
|
||
|---|---|---|---|
|
||
| 生成 H5 录入 token | `POST` | `/admin/fleet/h5/token` | additive 请求字段（可选 requestId） |
|
||
|
||
## 1. 变更内容
|
||
|
||
### 1.1 新增可选入参 `requestId`
|
||
|
||
`POST /admin/fleet/h5/token` 入参新增**可选** `requestId`：
|
||
|
||
| 字段 | JSON 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `requestId` | `String` | 否 | 前端稳定幂等键（1-64 位，仅字母数字与 `._-`，建议 UUID）。同 `requestId` **30s 窗口内**重复请求被拒（`100502 请勿重复提交`），防双击 / 弱网重试重复建链 |
|
||
|
||
**前端适配（推荐）**：生成按钮点击时生成稳定唯一值（如 UUID），**重试沿用同一值**；作废后重新生成属不同业务动作，应换新 `requestId`。不传 `requestId` 完全兼容（后端跳过幂等，行为与旧版一致）。
|
||
|
||
**错误码新增触发场景**：`100502`（同 requestId 30s 内重复提交）。
|
||
|
||
### 1.2 行程单 H5 契约补声明（无接口变更）
|
||
|
||
`GET /app/h5/itinerary/{token}` 出参中的 `contractVersion` / `segmentDays` / `serviceDates[]` / `segmentRoute` 四字段随 #5364 已上线并交接（frontend_status=verified），本次仅补全 API-SPEC §13.6 文档声明，**接口与实现均无变化**，前端无需任何改动。
|
||
|
||
## 2. 兼容性
|
||
|
||
- `requestId` 可选：旧前端不传时行为与旧版完全一致（线上实测验证）。
|
||
- 线上旧版本收到含 `requestId` 的请求体时忽略未知字段、正常生成（实测 200），前后端可异步上线。
|
||
|
||
## 3. 验证证据
|
||
|
||
- 后端 PR：`#5940`，squash merge `0792b27c`。
|
||
- 测试服部署：Deploy Panel 任务 `d0c1a1ef`，`hl-fleet-service` / `dev-v3`，状态 `success`。
|
||
- 自动化：H5 定向测试 88/88、Fleet ArchTest 13/13、spotless 通过。
|
||
- 网关实测：
|
||
- 同 `requestId` 首次调用 → `200/成功`；
|
||
- 同键 30s 内第二次调用 → `100502/生成处理中，请勿重复提交`；
|
||
- 不同 `requestId` → 各自成功；
|
||
- 不传 `requestId` 连续两次 → 均成功。
|
||
|
||
## 4. 验收要点
|
||
|
||
- 同 `requestId` 30s 内第二次调用 → `100502 生成处理中，请勿重复提交`（测试服网关已验证）。
|
||
- 不同 `requestId` 各自成功（测试服网关已验证）。
|
||
- 不传 `requestId` 连续两次调用均成功（兼容路径，测试服网关已验证）。
|