---
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: "pending"
frontend_owner: "mmg"
frontend_ref: "pending"
target_release: "v2.1"
verified_at: "2026-08-12"
updated_at: "2026-08-12"
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` 连续两次调用均成功（兼容路径，测试服网关已验证）。