hl-api-changelog/changelogs-v2/2026-08/12_5933_生成H5录入token幂等键requestId-修改接口-管理后台.md

author, schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, updated_at, status_note, base

author	schema	ticket	title	consumer	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	updated_at	status_note	base
wx(GIT)	hl-changelog/v2	5933	生成 H5 录入 token 支持 requestId 幂等键（防双击）	admin	修改接口	deployed	verified	pending	mmg	pending	v2.1	2026-08-12	2026-08-12	后端已于 2026-08-12 合并 PR #5940 并部署测试服验证：同 requestId 首次成功、30s 内第二次返回 100502、不同 requestId 成功；旧客户端不传 requestId 连续两次均成功。API-SPEC §13.6 同步补声明 contractVersion/segmentDays/serviceDates/segmentRoute。	dev-v3

生成 H5 录入 token 支持 requestId 幂等键（#5933）

服务：hl-fleet-service

Backend Issue：#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 连续两次调用均成功（兼容路径，测试服网关已验证）。