wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-07/25_5245_行程短链预览与同槽位改派解析-修改接口-管理后台.md
wx da2707f63b
所有检测均成功
changelog-filename-gate / validate (pull_request) Successful in 1s
详情
docs: correct frontend slot acceptance for #5245
2026-07-25 19:40:47 +08:00

12 KiB
原始文件 Blame 文件历史

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
schema ticket title consumer change_type backend_status gateway_status frontend_status frontend_owner frontend_ref target_release verified_at status_note updated_at base
hl-changelog/v2 5245 行程短链预览与同槽位改派解析 admin 修改接口 deployed verified claimed hl-ui-codex 后端已部署并完成网关验证；用户验收发现排车页缺少新增车辆槽位入口，前端已退回 claimed 继续修复。 2026-07-25 dev-v3

车务：行程短链预览与同槽位改派解析

服务: hl-fleet-service

工单: wx/HL#5245

后端 PR: wx/HL#5249、 wx/HL#5250

影响范围: 车务管理 → 派车弹窗通知预览、车辆/司机批量选择、派单详情

关键变化

  • 通知模板预览中的 itinerary.url 会为当前派车组即时创建或复用稳定短链， 例如 https://hr.example.com/s/Dabc1234，不再把完整 HMAC token URL 或“派车后生成”占位文案放进预览正文。
  • 既有短链和完整 token 长链在原派车组失效后，只允许解析到同一订单、同一 assignmentSlotId 的唯一当前有效派车组；跨订单、跨槽位、无有效派单或同槽位存在多个 active 派车组时继续返回 605308。
  • 批量派单和详情多司机字段是既有契约，本次明确前端消费口径：一次提交 items[]，详情展示 activeAssignments[]，不得只处理兼容代表字段 currentAssignment。
  • 排车页必须提供“+ 添加车辆槽位”入口。新增槽位不是替换“车辆槽位 1”，而是追加一个可独立 选择车辆和司机的草稿槽位；多个槽位统一映射为批量派单 items[]。

变更接口

方法 路径 本次口径
POST /admin/fleet/message-templates/<templateId>/render 请求新增可选 assignmentGroupId；有效派车组即时创建/复用稳定短链；旧前端未传时仅在订单、车辆、司机唯一定位一个 active 组时兼容
GET /app/h5/s/<code> 继续生成短时 token 并重定向；同槽位改派后的解析由行程接口完成
GET /app/h5/itinerary/<token> 原组失效后仅回退同订单、同稳定槽位的唯一 active 派车组
POST /admin/fleet/assignments/batch 既有：按 items[] 一次提交多个车辆/司机槽位
GET /admin/fleet/board/orders/<orderId> 既有：按 activeAssignments[] 返回全部当前有效派车组

1. 通知模板预览

POST /admin/fleet/message-templates/<templateId>/render

请求新增可选字段 assignmentGroupId，响应结构不变。前端在预览包含 itinerary.url 或 itinerary.code 的模板时，应传入当前派车组 ID；后端仅为兼容旧前端， 在 orderId + vehicleId + driverId 唯一定位一个 active 派车组时允许省略：

字段 类型 必填 说明
orderId string 是 订单雪花 ID
vehicleId string 是 当前派车组车辆雪花 ID
driverId string 是 当前派车组司机雪花 ID
assignmentGroupId string 行程预览时强烈建议 派车组雪花 ID；取自批量派单响应，多车多司机场景必须按槽位传入

派车组有效时，预览会即时创建或复用该组短链：

code: 200
data:
  renderedBody: "请查看行程：https://hr.example.com/s/Dabc1234"
  variablesUsed:
    - "itinerary.url"

未传 assignmentGroupId 且订单、车辆、司机无法唯一定位 active 派车组，或显式派车组无效时， itinerary.url 使用“行程链接暂不可用，请联系车务确认”，itinerary.code 为空字符串。 短链配置、注册或数据库失败时接口直接返回错误，不静默降级为占位文案；任何场景都不会回退或 暴露完整 HMAC URL。同一派车组通过显式 ID 或兼容定位重复预览、发送、重试时复用同一短链。

2. 同稳定槽位改派后的旧链接

短链先通过 /app/h5/s/<code> 重定向到短时 token；短链与直接保存的完整 token 最终都进入 /app/h5/itinerary/<token>，因此使用同一组回退规则：

token 原派单与当前派单 结果
原派车组仍有 holding / assigned 服务日 使用原派车组当前 active 视图
原组失效，同 orderId + 同 assignmentSlotId 恰有一个 active 组 使用当前改派组
仅有其他订单或其他槽位的 active 组 605308
同槽位无 active 组 605308
同槽位存在多个 active 组 605308，失败封闭

本次不改变 token 签名、有效期、短链 code 结构或错误码。

3. 前端多车辆/多司机消费

批量派单

POST /admin/fleet/assignments/batch

每个已选车辆槽位生成一个 items[] 元素，所有槽位一次提交：

orderId: "2080000000000000001"
requirementId: "2080000000000000002"
startDate: "2026-07-29"
endDate: "2026-07-31"
holdMode: 1
requestId: "assign-2080000000000000001-v1"
items:
  - fleetItemIndex: 0
    vehicleId: "2080000000000000101"
    driverId: "2080000000000000201"
  - fleetItemIndex: 1
    vehicleId: "2080000000000000102"
    driverId: "2080000000000000202"
  • fleetItemIndex 从 0 开始，对应需求展开后的稳定车辆槽位。
  • vehicleId、driverId 必填；雪花 ID 全程按字符串处理。
  • protocolPrice、messageTemplateId、customBody、confirmCrossResident 是单槽位可选字段。
  • 前端维护可编辑槽位列表。初始槽位来自当前有效派车组或订单用车需求；点击 “+ 添加车辆槽位”后追加一个空白草稿槽位，不得覆盖或复用既有槽位。
  • 每个草稿槽位独立选择一辆车和一名司机；未提交的新槽位允许删除，已有 holding / assigned 槽位不得被“删除草稿”操作静默撤销。
  • 进入下一步前校验所有可提交槽位均已选择车辆和司机，并为每个槽位生成唯一 fleetItemIndex。页面可见槽位数必须等于本次提交的 items[] 数量。
  • 不得为每辆车循环调用单条 POST /admin/fleet/assignments 代替批量接口。
  • 批量响应按 data.assignments[].assignment.assignmentGroupId 返回各槽位派车组 ID； 前端逐项调用模板预览时传入对应 assignmentGroupId，不得只预览代表项。

派单详情

GET /admin/fleet/board/orders/<orderId>

按 data.activeAssignments[] 渲染每个有效派车组，至少消费：

字段 用途
assignmentGroupId 派车组稳定展示 key
assignmentSlotId 同一需求车辆槽位的稳定身份
fleetItemIndex 槽位顺序
vehicleId / vehiclePlate / vehicleModel 车辆展示
driverId / driverName / driverPhone 司机展示；电话已脱敏
assignmentStatus / assignmentStatusLabel 当前有效状态
lifecycleStageCode 生命周期阶段

currentAssignment 仅为兼容代表项，不能用来判断订单只有一辆车或只展示一名司机。 activeAssignments 无数据时使用空列表空态，不复制代表项凑数。

前端展示矩阵

场景 数据源 页面行为
通知预览传入有效派车组 assignmentGroupId + renderedBody 中的 itinerary.url 即时创建或复用并展示稳定短链
旧前端未传派车组但订单、车辆、司机唯一定位 orderId + vehicleId + driverId 兼容定位并返回同一稳定短链
派车组缺失、无效或定位不唯一 “行程链接暂不可用，请联系车务确认” 展示不可用态，不把文案当可发送链接
已有车辆槽位 activeAssignments[] 或当前排车草稿 按稳定槽位逐项展示；允许重选当前槽位的车辆或司机
新增车辆槽位 前端草稿槽位列表 展示“+ 添加车辆槽位”；每次点击只追加一个空白槽位，不替换已有槽位
新增槽位未选完整 草稿槽位的 vehicleId / driverId 槽位显示未完成警示，禁用“下一步”；不生成可发送通知
删除未提交槽位 前端草稿槽位列表 只删除新增且未提交的草稿槽位，不撤销已有有效派车组
一单多个车辆槽位 items[] 每个槽位各选一辆车和一名司机，一次批量提交；可见槽位数与 items[] 数量守恒
详情有多个 active 派车组 activeAssignments[] 按槽位逐项展示车辆、司机、脱敏电话和状态
详情无 active 派车组 activeAssignments=[] 展示无有效派单空态

前端处理清单

  • 排车页提供“+ 添加车辆槽位”入口，允许连续新增多个草稿槽位，不得只重选“车辆槽位 1”。
  • 每个新增槽位分别选择一辆车和一名司机，并支持删除未提交的草稿槽位。
  • “下一步”前校验所有槽位，按页面槽位顺序生成唯一 fleetItemIndex，可见槽位与 items[] 一一对应。
  • 统一提交 POST /admin/fleet/assignments/batch 的 items[]，保留批次级 requestId。
  • 批量派单响应逐项保存 assignmentGroupId；通知预览传入当前槽位的 orderId、vehicleId、driverId、assignmentGroupId，只把真实短链视为可发送链接。
  • 派单详情按 activeAssignments[] 展示全部车辆/司机，不只读 currentAssignment。
  • 司机电话使用后端脱敏值，雪花 ID 始终按字符串处理。
  • 覆盖无 active、多 active、短链不可用等空态/失败封闭场景。

前端验收反馈

  • 2026-07-25 用户页面验收：排车页仅显示“车辆槽位 1”，只能在该槽位内重选车辆或司机， 无法新增第二个槽位；当前前端提交不满足多车辆、多司机批量派单要求。
  • 状态因此由 implemented 回退为 claimed。前端完成新增槽位、逐槽位选择和批量提交后， 应填写新的 frontend_ref 再迁移为 implemented。

验证证据

  • OpenAPI/oasdiff：not_configured。项目未配置可复现的 Swagger2 → OAS3 导出与 oasdiff 基线； 本次使用源码语义比对、Controller/Service 定向测试与测试网关证据兜底。
  • 消费者契约/Spring Cloud Contract：not_required。本次没有内部 Feign 或共享 Java DTO 变化。
  • 后端定向测试：41 项通过，0 失败、0 错误、0 跳过。
  • Fleet Spotless：606 个 Java 文件检查通过。
  • 完整 reactor verify：3209 项测试，0 失败、0 错误、1 跳过；其中 fleet 2373 项， 0 失败、0 错误、1 跳过。
  • 后端 PR #5249 合并提交：433ef238f09eba2258c996093b1d8cb2309a8e83。
  • 后端 PR #5250 合并提交：d939995bd266f11076eb79ea183e37a968e01afc。
  • 测试部署任务：8eae87b2；hl-fleet-service 的 8187、8087 两实例均健康。
  • 测试网关已验证：显式 assignmentGroupId 与唯一兼容定位返回同一 7 位短码； 重复预览保持稳定，短链 302、H5 JSON 与 HTML 均成功；失效组返回 605308， 篡改签名返回 605306。脱敏证据已回写工单 #5245。

不影响范围

  • 不修改或部署 D:/work2/hl-ui。
  • 除模板预览请求新增可选 assignmentGroupId 外，不删除 API 字段，不改变既有字段类型、 必填性或枚举；模板预览响应结构不变。预览在命中有效派车组时会幂等写入短链记录。
  • 不修改批量派单事务、价格、跨常驻确认、保险或通知冻结规则。
  • 不新增 DDL，不清理、不回填存量数据。

frontend_status: claimed 表示前端已领取但仍需修复“新增车辆槽位”；尚未形成可验收的完整实现。