wx/hl-api-changelog

派生 0

文件

T

wx 98ca7cc7d4

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

详情

changelog(9209): 单团排车项上限 4000->500（修改接口/管理后台）

2026-10-23 12:45:01 +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	9209	单团排车项上限由 4000 收紧到 500：超过 500 项在提交阶段即被拒，文案改为「请减少配车项后重新提交」	admin	chewu5(GIT)	修改接口	deployed	verified	not_required					已合并 dev-v3（PR #9218，squash 5f1d456c4），已部署测试服（deploy-backend hl-fleet-service --branch dev-v3，11:47:04）：deploy-status 显示 dev-v3 / 5f1d456c4 / 0/N / ok；双实例 8087、8187 health 均 200，部署日志 Started 之后 ERROR 0。契约变化只有一处上限：POST /admin/fleet/assignments/batch 的 dailyPlan 由最多 4000 项收紧到 500 项（@Size(max=500)），501 项起返回 400 + 可执行文案；入参字段名/类型、出参结构、其余错误码均未变。确认侧上限 500 与 #9193 的计数守卫原样保留，常量统一到 FleetLimits.MAX_DISPATCH_ITEMS_PER_GROUP。hl-ui 不改也不会错；若前端曾按 4000 做本地上限，建议同步到 500，免得用户填到 501~4000 项才在提交时被拒。	2026-10-23	dev-v3

hl-fleet-service: 单团排车项上限由 4000 收紧到 500

服务: hl-fleet-service（管理后台） PR: #9218（已合入 dev-v3，合并提交 5f1d456c4） Issue: #9209 日期: 2026-10-23 影响范围: 管理后台「车务最终实派方案」批量提交（dailyPlan 项数上限）

⚠️ 关键变化

🟢 POST /admin/fleet/assignments/batch 的 dailyPlan 上限：4000 项 → 500 项。

🟢 超过上限的拒绝文案改为可执行提示：

单次逐日派车配置不能超过500项，请减少配车项后重新提交

🔴 请求体字段名/类型、响应结构、错误码集合都没变；500 项整仍然成功提交，501 项起才被拒。

一、背景

确认侧（POST /admin/fleet/group-dispatch/batches/{groupBatchId}/confirm）自 #9179 起单团只允许 500 行存活配车行，而提交侧 batchCreate 的 dailyPlan 一直允许 4000 项（该数值来自 #5292，无容量依据）。两者不一致的结果是：501～4000 项的团能建得成、却永远确认不了——25 天 × 21 车的常规团就是 525 项，直接命中。

wx 2026-10-23 拍板：500 够用，提交侧收紧到 500。本单同时把「500」这个数字收敛到唯一出处 FleetLimits.MAX_DISPATCH_ITEMS_PER_GROUP：提交侧的 Bean Validation 注解与确认侧的行数守卫引用同一个常量，避免将来改一处漏一处。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	车务最终实派方案原子提交	POST	`/admin/fleet/assignments/batch`	入参上限收紧 + 文案	`dailyPlan` 最多 500 项（原 4000）；其余字段与出参不变

三、接口详情

1. 车务最终实派方案原子提交 `POST /admin/fleet/assignments/batch`

VO: BatchCreateAssignmentReqVO / Result<BatchAssignmentWriteRespVO>

使用场景

管理后台在团期 / 订单的车务配车页点「提交最终方案」时调用：一次提交该需求在完整日期窗内的逐日配车清单（服务日期 × 车辆 × 司机），服务端原子落库并回写订单。

入参

字段	位置	类型	必填	约束	说明
orderId	Body	Long	✅	-	订单 ID
requirementId	Body	Long	✅	-	当前生效用车需求 ID
kind	Body	String	否	TRAVEL / TRANSFER	需求类别，不传按 TRAVEL
startDate / endDate	Body	Date	✅	-	用车起止日期
requestId	Body	String	✅	≤ 64 字符	批次级幂等标识
dailyPlan	Body	Array	✅	≤ 500 项（原 4000）	按行程日的完整配车列表，逐项为服务日期×车辆×司机；同一服务日允许多条
其余字段	Body	-	否	-	与改动前一致（headcount / pickupAt / dropoffAt / sendItinerarySms 等）

出参 `Result<BatchAssignmentWriteRespVO>`

结构与字段名均未变：

字段	类型	说明
assignments	Array	本次提交落库的配车行列表
finalPlanPublished	Boolean	最终方案是否已发布
finalPlanNotPublishedReason	String	未发布时的第一个原因；发布时为 null
pickupDropoffGate	Object	接送机第③步门禁信息
failedFleetItemIndex	Integer	失败的配车项下标（仅失败时）
dailyDifferences	Array	整批 diff 明细（按日）
fleetItemIndex	Integer	当前处理到的配车项下标
assignment	Object	单行写入结果（`AssignmentWriteRespVO`）

请求示例

{
  "orderId": "2112275846201069569",
  "requirementId": "2112275846201070000",
  "startDate": "2026-10-25",
  "endDate": "2026-10-30",
  "requestId": "batch-20261023-0001",
  "dailyPlan": [
    { "serviceDate": "2026-10-25", "vehicleId": "2112275846201088001", "driverId": "2112275846201099001" }
  ]
}

响应示例

{ "code": 200, "message": "成功", "data": { "finalPlanPublished": true, "finalPlanNotPublishedReason": null }, "success": true }

空数据 / 降级响应

dailyPlan 为空或缺失不属于降级场景：@NotNull 直接拒绝，返回 400「逐日派车计划不能为空」。

错误响应

超过 500 项时（HTTP 200 + 业务码，网关统一语义）：

{ "code": 400, "message": "单次逐日派车配置不能超过500项，请减少配车项后重新提交", "data": null, "success": false }

其余错误码（605062 服务日期越窗、605912 派车快照缺车型等）语义与文案均未变。

业务边界

dailyPlan 恰好 500 项：成功，与改动前一样走完整提交流程。
dailyPlan 501 项起：@Size 拒绝，零写入，不产生配车行、不触发订单回写。
确认侧上限仍是 500 行存活配车行（#9179 / #9193），且 #9193 的「先计数拒绝、不读明细」守卫原样保留；提交侧与确认侧现在共用同一常量。
本单不动读取路径、不动表结构、不订正存量数据。

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

场景	调用
✅ 单团 ≤ 500 项	正常提交
❌ 501～4000 项	会被 400 拒绝；应按提示减少配车项后重新提交，不要重试同一请求
❌ 把 400 当成可重试的并发错误	不是并发错误，重试不会改变项数

前端若做提交前校验，上限请用 500；已经按 4000 做本地上限的页面在 501～4000 项时会拿到上述 400 与文案（功能不会错，只是提示出现在提交时刻）。

五、数据库行为

无表结构变更、无 Flyway、无数据订正。仅提交侧入参校验收紧。

六、边界行为

边界严格按 > 500：500 成功、501 拒绝，两侧都有单元用例（BatchCreateAssignmentReqVOTest#validate_dailyPlanAtLimit_passes / #validate_dailyPlanOverLimit_violatesSize）。
校验发生在 Controller 入参绑定阶段（@Valid），早于任何业务写入与锁获取。
确认侧文案：「拆团」措辞已清理，现为「请减少配车项后重试」（该动作没有接口，不该出现在提示里）。

六.6、修改前后对比

行为级对比

场景	改前	改后
dailyPlan = 500 项	成功	成功（不变）
dailyPlan = 501 项	成功提交（随后永远确认不了）	400 拒绝，零写入
dailyPlan = 1000 / 4000 项	成功提交（死团）	400 拒绝
确认侧 > 500 存活行	602010（#9193：先计数拒绝）	不变

字段级对比

无字段变化：字段名、类型、必填性、枚举、错误码数值均未改；只有 dailyPlan 的 @Size(max) 由 4000 变为 500，以及超限文案改为可执行提示。

六.7、影响评估

是否破坏向后兼容: 是「收紧」而非「破坏」——合法调用（≤ 500 项）行为与出参完全不变；原本能提交的 501～4000 项现在被提前拒绝，而这批数据原本也无法确认（确认侧上限 500）。
前端是否必须同步上线: 否。前端不做任何改动也能正常提交 ≤ 500 项；若前端自己按 4000 做本地上限，建议同步到 500（只是把提示提前到用户编辑时）。
前端 workaround 清理点: 若有页面按 4000 做客户端条数校验，把常量改为 500。
存量数据: 测试服 > 500 行的团 0 个，无需订正；生产如有存量死团，应另单处置（本单不做数据订正）。

七、不影响范围

其它 hl-fleet-service 接口：PickupDropoffConfigReqVO 的 4000 上限属接送机配置，写的是另一张表、不参与 fleet_group_dispatch，本单未改。
确认侧守卫逻辑（#9193）零改动。
hl-mini / about-h5 不消费 /admin/fleet/**。

八、测试环境已验证

项	读数
部署	`deploy-backend hl-fleet-service --branch dev-v3` 11:47:04；deploy-status：dev-v3 / 5f1d456c4 / 0/N / ok
双实例	8087、8187 `is UP`，`/actuator/health` 均 200
部署日志	两实例 `Started` 之后 `ERROR` 计数均 0
定向测试	`BatchCreateAssignmentReqVOTest` 13 / `AssignmentControllerTest` 49 / `GroupDispatchConfirmTest` 32 / `FleetRedLineArchTest` 31+2，SUM tests=127 failures=0 errors=0 skipped=0
编译	清 classes 后重新编译：Compiling 1195 main + 532 test，EXIT=0
存量数据只读核对	测试服 `fleet_group_dispatch` 存活行：>500 行的团 0 个（最多 7 行，4 团共 23 行）⇒ 无死团需要处置

十、相关文档

docs/fleet-workbench/1-2接口文档.md（提交接口的 dailyPlan 上限说明如与本条不一致，以本条为准）
上游单：#9179（确认侧 500 行上限）、#9193（先计数再拒绝）、#5292（4000 的来源，已判定无依据）

关联 / 联系人

后端：车务5（本单实现与验证）
工单：wx/HL#9209；PR：wx/HL#9218

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