wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
737e20824a2e6f5e7646c21b1a42a72efb83d91d
hl-api-changelog/changelogs-v2/2026-09/30_8579_接送机配置补发条件放宽-修改接口-管理后台.md
T
lc 69c0b76bb9
changelog-filename-gate / validate (push) Failing after 2s
详情
docs(changelog): #8579 接送机配置补发条件放宽 
Refs wx/HL#8579
2026-09-30 16:21:51 +08:00

10 KiB
原始文件 Blame 文件历史

schema, ticket, title, consumer, author, 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 author change_type backend_status gateway_status frontend_status frontend_owner frontend_ref target_release verified_at status_note updated_at base
hl-changelog/v2 8579 接送机配置接口补发条件放宽：门禁已满足且订单有接送机声明时重存也会补发最终方案，NO_GATE_TRANSITION 出现频率下降 admin lc(GIT) 修改接口 deployed verified not_required PR #8595 已合并 dev-v3（0f19f383f），hl-fleet-service 已部署 TEST（8e00cc98b）并经 Gateway 实测。响应结构未变，前端无需改代码。 2026-09-30 dev-v3

hl-fleet-service: 接送机配置接口补发条件放宽

存放目录: changelogs-v2/2026-09/ 服务: hl-fleet-service (端口 8089) PR: #8595 Issue: #8579 日期: 2026-09-30 影响范围: 车务四步向导第③步「接送机配置」保存后的最终方案补发

⚠️ 关键变化

  • 以前：只有「本次保存前门禁不满足、保存后满足」才补发最终方案；门禁本来就满足时再保存一次，一律回 NO_GATE_TRANSITION、不补发。
  • 现在：保存后门禁满足，并且（保存前不满足，或订单大交通有接送机声明）就尝试补发。门禁本来就满足、订单有接送机声明时重存，也会补发。
  • 补发仍要过全部守卫：换版后留下旧定稿（STALE_FINALIZED_PLAN）、方案代际不一致、没派满，照样不发，并如实回原因。换版后的订单仍须车务重新确认执行，本次没有绕开这道守卫。
  • 前端无需改代码：请求体、响应结构、错误码都没变；只是 finalPlanPublished=true 出现得更多、NO_GATE_TRANSITION 出现得更少。

二、变更接口清单

# 接口 方法 路径 变更类型 说明
1 接送机配置（按派车行整批幂等覆盖） PUT /admin/fleet/assignments/pickup-dropoff-config 补发时机放宽 请求、响应结构不变

三、接口详情

1. 接送机配置 PUT /admin/fleet/assignments/pickup-dropoff-config

VO: PickupDropoffConfigReqVO → PickupDropoffConfigRespVO

使用场景

车务四步向导第③步保存接送机勾选。排车（POST /admin/fleet/assignments/batch）时大交通要求接/送机的日期还没配车，最终方案被压住（batch 回 GATE_UNSATISFIED）；在本接口配齐后，服务端当场补发。

入参（未变）

字段 位置 类型 必填 约束 说明
orderId Body Long ✅ - 订单 ID
requirementId Body Long ✅ - 当前生效用车需求 ID
kind Body String - TRAVEL（默认）/ TRANSFER 需求类别
requestId Body String ✅ 非空 幂等请求标识
items[] Body Array ✅ 只列参与接送的行 两个标志都为 false 的行不要放进来（否则 400）；未列入的行服务端置 0
items[].assignmentId Body Long ✅ 当前需求下生效派车行 派车行 ID
items[].pickupParticipant Body Boolean ✅ - 当天是否参与接机
items[].dropoffParticipant Body Boolean ✅ - 当天是否参与送机

出参 Result<PickupDropoffConfigRespVO>（结构未变）

字段 类型 说明
finalPlanPublished Boolean 本次是否补发了最终方案
finalPlanNotPublishedReason String 未补发原因，补发时为 null；取值见六.5
requirementReopened Boolean 是否把已完成订单拉回处理中（未变）
reopenBlockedReason String 本该拉回却没拉回的原因（未变）
pickupDropoffGate Object 写入后的门禁状态：arrivalRequiredDates / departureRequiredDates / missingPickupDates / missingDropoffDates / declared / satisfied

请求示例

{
  "orderId": "2105196047255126017",
  "requirementId": "2105197351138410497",
  "kind": "TRAVEL",
  "requestId": "pd-2105196047255126017-20260930-02",
  "items": [
    { "assignmentId": "2105197584132046850", "pickupParticipant": true, "dropoffParticipant": false },
    { "assignmentId": "2105197584157212674", "pickupParticipant": false, "dropoffParticipant": true }
  ]
}

响应示例（配齐即补发）

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "finalPlanPublished": true,
    "finalPlanNotPublishedReason": null,
    "requirementReopened": false,
    "reopenBlockedReason": null,
    "pickupDropoffGate": {
      "arrivalRequiredDates": ["2026-10-12"],
      "departureRequiredDates": ["2026-10-14"],
      "missingPickupDates": [],
      "missingDropoffDates": [],
      "declared": true,
      "satisfied": true
    }
  }
}

响应示例（换版后配齐，仍被陈旧定稿拦下）

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "finalPlanPublished": false,
    "finalPlanNotPublishedReason": "STALE_FINALIZED_PLAN",
    "requirementReopened": false,
    "reopenBlockedReason": null,
    "pickupDropoffGate": { "declared": true, "satisfied": true, "missingPickupDates": [], "missingDropoffDates": [] }
  }
}

空数据 / 降级响应

订单大交通没有接送机声明时 pickupDropoffGate 各日期数组为空、declared=false、satisfied=true；此时重存不补发：

{ "code": 200, "success": true, "data": { "finalPlanPublished": false, "finalPlanNotPublishedReason": "NO_GATE_TRANSITION", "pickupDropoffGate": { "declared": false, "satisfied": true, "missingPickupDates": [], "missingDropoffDates": [] } } }

错误响应

{
  "code": 400,
  "message": "同一行接送机标志不能全为 false；不参与的行不要出现在配置列表中",
  "success": false,
  "data": null
}

业务边界

  • 补发时机：保存后门禁满足，且保存前不满足或订单有接送机声明。订单大交通没有接送机声明时，重存不会补发（回 NO_GATE_TRANSITION），避免每存一次都发一版没有变化的最终方案。
  • 补发仍依次过陈旧定稿、方案代际、满派拓扑、接送机门禁四道判据，只回第一个没通过的原因。
  • 同一需求多次补发，order-v3 的配车记录按最新一版整体替换，不会重复累加。

四、契约约束与正确调用方式

  • finalPlanPublished=false 不是错误，按 finalPlanNotPublishedReason 提示车务下一步：GATE_UNSATISFIED/NO_GATE_TRANSITION 看 pickupDropoffGate.missing*Dates 补配；STALE_FINALIZED_PLAN 提示车务重新确认执行；PLAN_INCOMPLETE 提示补派。
  • 不要按 NO_GATE_TRANSITION 判断「这次保存没生效」：勾选照常落库，它只表示本次没有尝试补发。

五、数据库行为

  • 补发时写 fleet fleet_vehicle_assignment_snapshot_state（修订号 +1）和 fleet_vehicle_assignment_snapshot_outbox，再异步写 order-v3 order_vehicle_assignment（旧行软删、按新一版重建）。
  • 不补发时只更新派车行的接送标志。

六、边界行为

  • 未登录 → 401（网关拦截）
  • items 含两个标志都为 false 的行 → 400「同一行接送机标志不能全为 false」
  • 换版后未经车务重新确认 → 不补发，回 STALE_FINALIZED_PLAN

六.5、枚举 / 数据字典

finalPlanNotPublishedReason（FinalPlanNotPublishedReasons）

取值 含义
STALE_FINALIZED_PLAN 存在按旧需求定稿的陈旧行，需车务重新确认
INVALID_PLAN_GENERATION 方案代际不一致
PLAN_INCOMPLETE 满派拓扑不完整（缺车 / 缺司机 / 在途行越窗等）
CAPACITY_INSUFFICIENT 未定稿方案载客量不足
GATE_UNSATISFIED 大交通要求的接/送机日未配车
NO_GATE_TRANSITION 口径变化：本次没有尝试补发——保存后门禁仍不满足，或门禁满足但订单没有接送机声明且保存前已满足
PICKUP_DROPOFF_GATE_DISABLED 接送机门禁开关关闭

六.6、修改前后对比

行为级对比

场景 修改前 修改后
保存前缺配、保存后配齐 补发 补发（不变）
门禁本已满足、订单有接送机声明，再保存 NO_GATE_TRANSITION，不补发 尝试补发（过全部守卫）
门禁本已满足、订单无接送机声明，再保存 NO_GATE_TRANSITION NO_GATE_TRANSITION（不变）
保存后仍缺配 NO_GATE_TRANSITION NO_GATE_TRANSITION（不变）
换版后配齐 NO_GATE_TRANSITION 或 STALE_FINALIZED_PLAN STALE_FINALIZED_PLAN

六.7、影响评估

  • 是否破坏向后兼容: 否
  • 前端是否必须同步上线: 否
  • 前端 workaround 清理点: 无

七、不影响范围

  • 仅影响: PUT /admin/fleet/assignments/pickup-dropoff-config 的补发时机
  • 零影响: 请求体与响应结构；POST /admin/fleet/assignments/batch；确认执行接口（缺失日期字段的删除见 #8603 changelog）

八、测试环境已验证

2026-09-30 TEST（hl-fleet-service @ 8e00cc98b）经 Gateway 实测，夹具订单验收后已行前取消：

场景 结果
batch 排满三天、首日接机末日送机未配 finalPlanPublished=false + GATE_UNSATISFIED，缺 2026-10-12 / 2026-10-14
只配接机 NO_GATE_TRANSITION，门禁仍缺 2026-10-14
配齐接机 + 送机 finalPlanPublished=true，outbox 1 行，order-v3 配车记录 3 行
换版后配齐 finalPlanPublished=false + STALE_FINALIZED_PLAN，门禁 satisfied=true，无快照发出

九、相关历史 PR

  • #8429：统一 batch / 接送机配置 / 确认三处的最终方案发布判据，引入 finalPlanNotPublishedReason。
  • #8603（PR #8608）：确认执行响应删除恒为空的缺失日期字段，缺失日期改由 605914/605915 错误消息承载。

十、相关文档

关联 / 联系人

链接

联系人

  • 后端：@lc
在新工单中引用 查看 Git Blame 复制永久链接