文件

T

changelog-filename-gate / validate (push) Failing after 1s

详情

docs(changelog): 16 份前端判 not_required(#8621/#8603/#8559/#8577/#8593/#8576/#8536/#8528/#8571/#8561/#8597/#8491旧列表/#8533/#8508/#8515/#8613)

2026-09-30 10:30:14 +08:00

11 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	8528	团期配车重排新增资源态硬校验，响应回填被 clearAll 忽略的行程日	admin	wx(GIT)	修改接口	deployed	verified	not_required					PR #8553 合并 dev-v3（7b702f5c3f）；hl-fleet-service dev-v3 分支部署测试网关 @ e2982739e8（含 7b702f5c3f）并实测：排入 rest 司机返 605038、排入 DISABLED 车辆返 605037（均一行未落库）；正常 ACTIVE 车辆 7 天全排返 addedCount=7；clearAll=true 场景返 ignoredDemandDays 回填生效。	2026-09-30	dev-v3

团期配车重排：新增资源态硬校验，响应回填被 clearAll 忽略的行程日

存放目录: changelogs-v2/2026-09/ 服务: hl-fleet-service (端口 8087) PR: #8553 Issue: #8528 #8529 日期: 2026-09-29 影响范围: 管理后台团期配车页「整团逐日配车提交」

⚠️ 关键变化

团期配车重排提交时，本次新增或就地改动的配车行，其车辆与司机的当前状态（是否维保/停用/休假/待激活/黑名单/非在册赛季）现在会被硬校验，不可派即整批提交回滚（工单 #8528）。
响应新增字段 ignoredDemandDays：clearAll=true 时把未被写入的行程日回填给前端（工单 #8529）。此前 clearAll=true 提交后无法区分「清完并按新计划重排」与「只清空」，两者响应里 addedCount 都是 0。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	整团逐日配车提交	POST	`/admin/fleet/group-dispatch/batches/{groupBatchId}/reconfigure`	新增错误码 + 新增响应字段	605037/605038 新增；605006/605013 文案带占位符；响应新增 `ignoredDemandDays`

三、接口详情

1. 整团逐日配车提交 `POST /admin/fleet/group-dispatch/batches/{groupBatchId}/reconfigure`

VO: GroupDispatchReconfigureReqVO → GroupDispatchReconfigureRespVO

使用场景

车务在团期配车页提交/重排整团逐日配车计划：服务端按乘车分组与现状差量比对，多删少补，旧记录软删留痕。本次改动新增两类内容：①提交时对新增/就地改的配车行做车辆与司机的当前可派性硬校验；②clearAll=true 时把未写入的行程日回填进响应。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	-	团期主订单 ID
requirementId	Body	Long	✅	-	正式团级用车需求 ID；与基线不一致抛 602005
requirementVersion	Body	Integer	✅	-	需求版本；落后于基线当前版本抛 602005
clearAll	Body	Boolean	否	默认 false	true=整团清零，`demands` 仅当待清日用，不写入任何配车行
survivorPolicy	Body	String	条件必填	`KEEP_LEGAL`/`REASSIGN`/`RELEASE`	仅 `clearAll=true` 且该团存在 active 共用关系时必填，缺失抛 602110
demands	Body	List<GroupDispatchDayDemandReqVO>	条件必填	-	`clearAll=false` 时必填且非空；每项含 `tripDate` + `assignments`（车辆/司机/分组），本次不变
reconfigureWindowToken	Body	String	条件必填	-	团期过资源准备阶段后必填，本次不变

出参 `Result<GroupDispatchReconfigureRespVO>`

字段	类型	说明
ignoredDemandDays	List<LocalDate>	新增（#8529）：因 `clearAll=true` 未被写入的行程日清单，格式 `yyyy-MM-dd`；`clearAll=false` 时恒为空列表，不会是 null
addedCount / removedCount / keptCount / updatedCount / aliveCount	Integer	结构不变
coverage	GroupDispatchCoverageRespVO	结构不变，含 `wholeBatchSatisfied`（全团行程日整体覆盖是否成立）等字段
其余字段	-	结构不变，与既有契约一致（本次不变）

请求示例

正常提交（7 天全排 ACTIVE 车辆场景，节选一天）：

{
  "requirementId": "5501",
  "requirementVersion": 3,
  "clearAll": false,
  "demands": [
    { "tripDate": "2026-09-12", "assignments": [ { "groupId": "BUS", "vehicleId": "1001", "driverId": "2001" } ] }
  ]
}

clearAll 场景：

{
  "requirementId": "5501",
  "requirementVersion": 3,
  "clearAll": true,
  "survivorPolicy": "RELEASE",
  "demands": [
    { "tripDate": "2026-11-10", "assignments": [] }
  ]
}

响应示例

7 天全排成功：

{ "code": 200, "message": "成功", "data": { "addedCount": 7, "coverage": { "wholeBatchSatisfied": true } }, "success": true }

clearAll 场景（行程日被回填进 ignoredDemandDays）：

{ "code": 200, "message": "成功", "data": { "addedCount": 0, "ignoredDemandDays": ["2026-11-10"] }, "success": true }

空数据 / 降级响应

无空数据形态；命中资源态硬校验或既有校验失败时 data=null，见错误响应。

错误响应

{ "code": 605038, "message": "司机处于休假或待激活状态，不能派车：苏和巴特尔", "data": null, "success": false }

{ "code": 605037, "message": "车辆处于维保或停用状态，不能派车：蒙C02E02", "data": null, "success": false }

业务边界

605037/605038/605006/605013 四个码新增的占位符文案同样出现在逐户派单写路径（POST /admin/fleet/assignments 及改派端点），二者共用同一个资源态校验组件；前端若对这 4 个码有硬编码文案匹配，两条路径都要一起改。
资源态校验是整批拒绝：任意一天新增/就地改的车辆或司机不可派，会回滚本次整团提交，不是部分成功。
本次未改动的存量配车行不重判——车辆/司机事后状态变化不会把整团重配卡死，只挡本次新增/就地改的行。
车辆/司机已被删除时，占位符退回请求里携带的主键（ID=车辆ID / ID=司机ID），不是报 500。
ignoredDemandDays 在 clearAll=false 时恒为空列表（不是 null），前端可无条件取其长度判断有无回填项。

四、契约约束与正确调用方式（接口类必写）

本节只写后端接受/拒绝 payload 的规则，不写 UI 渲染建议。

✅ 正确 / ❌ 错误 payload 对照

场景	payload
✅ 排入正常 ACTIVE 车辆/司机	正常提交，返回 `code=200`
❌ 排入 DISABLED/维保车辆	任意排车项使用该车辆 → `605037`
❌ 排入休假/待激活司机	任意排车项使用该司机 → `605038`

切换状态时的必要动作

收到 605037/605038/605006/605013 直接把 message 展示给车务，引导其在该排车项上更换车辆或司机后重新提交；本端点无独立幂等键字段，防重仅靠既有 10 秒窗口，修正后正常重提即可。

五、数据库行为（涉及写操作时必写）

本次未新增表、未新增列。资源态硬校验发生在写入前（校验车辆/司机当前状态），校验不通过时整批回滚、不产生任何 fleet_group_dispatch 写入；ignoredDemandDays 是内存计算结果、不落库。

六、边界行为

未登录 → 401（网关拦截）
车辆/司机已被删除 → 错误码占位符退回请求里携带的主键（ID=车辆ID/ID=司机ID），不是 500
本次未改动的存量配车行不参与资源态重判
clearAll=false 时 ignoredDemandDays 恒为空列表，不是 null

六.5、枚举 / 数据字典（接口出现枚举时必写）

本次未新增或变更任何枚举取值；survivorPolicy（KEEP_LEGAL/REASSIGN/RELEASE）沿用既有契约，未变化。

六.6、修改前后对比（修改/删除类接口必写，新增跳过）

字段级对比

字段	改前	改后
`data.ignoredDemandDays`	不存在	新增，`clearAll=true` 时回填未被写入的行程日
605006 `message`	`司机已黑名单，不能派车`	`司机已黑名单，不能派车：{司机姓名}`（缺姓名退回 `ID=司机ID`）
605013 `message`	`司机非在册赛季不可派单`	`司机非在册赛季不可派单：{司机姓名}`（缺姓名退回 `ID=司机ID`）

行为级对比

行为	改前	改后
排入维保/停用车辆	无该项硬校验，可能带着不可派车辆落库	605037 拒绝，整批回滚
排入休假/待激活司机	无该项硬校验，可能带着不可派司机落库	605038 拒绝，整批回滚
`clearAll=true` 提交	响应无法区分「清完重排」与「只清空」	`ignoredDemandDays` 回填未写入日期

六.7、影响评估（修改/删除类必写）

是否破坏向后兼容: 否——605037/605038 是新增错误码，605006/605013 只在文案末尾追加占位符文本（前端如做精确字符串匹配需要更新）；ignoredDemandDays 是新增字段，旧前端忽略它不受影响。
前端是否必须同步上线: 否——新增字段/错误码是可选适配，未处理时行为退化为"看不到具体车牌/司机名，只看到通用错误码提示"，不影响提交本身的成败判定。
前端 workaround 清理点: 若此前靠 addedCount===0 猜测「clearAll 是否清空后又重排」，可以换成直接读 ignoredDemandDays。

七、不影响范围（显式声明, 帮前端/QA 缩小排查面）

仅影响: 管理后台团期配车页「整团逐日配车提交」（POST reconfigure）
零影响:
- 确认整团配车端点（POST confirm）本次未改动响应结构（其资源态硬校验为工单 #8528 同批改动，但不在本 changelog 覆盖范围内）
- 团期配车四个读口（总览/就绪/共用关系/共用候选，见另一份 changelog）
- 既有错误码（600003-600011、602005-602012 等）语义与格式不变

八、测试环境已验证

服务：hl-fleet-service，dev-v3 分支部署测试网关 @ e2982739e8（含 #8528/#8529 所在提交 7b702f5c3f），测试网关 https://api.test.1814.love：

✓ 排入 driverStatus=rest 的司机 → code=605038, message="司机处于休假或待激活状态，不能派车：苏和巴特尔"，一行未落库
✓ 排入 DISABLED 车辆（车牌 蒙C02E02）→ code=605037, message="车辆处于维保或停用状态，不能派车：蒙C02E02"，一行未落库
✓ 正常 ACTIVE 车辆 7 天全排 → code=200, addedCount=7, coverage.wholeBatchSatisfied=true（回归未破坏）
✓ clearAll=true 场景 → code=200, data.addedCount=0, data.ignoredDemandDays=["2026-11-10"]

十、相关文档

关联 Issue: wx/HL#8528、wx/HL#8529
关联 PR: wx/HL#8553

关联 / 联系人

链接

Issue: #8528、#8529
PR: #8553
Merge commit: 7b702f5c3f

联系人

后端负责人: @wx

11 KiB 原始文件 Blame 文件历史 Unescape Escape