hl-api-changelog/changelogs-v2/2026-09/28_8423_派车快照校验两处改业务码605801与605802-修改接口-管理后台.md

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	8423	派车提交生成快照时：免费日缺豁免原因返回 605801、司机手机号不合规返回 605802（原为 code=500 系统繁忙）	admin	lc(GIT)	修改接口	deployed	verified	pending				2026-09-28	PR #8465 合并 dev-v3（ad8ad806a）；hl-fleet-service dev-v3 @ fe023b0ed 部署（任务 2a0e56b9，双实例健康）。TEST 网关实测：手机号 12345678901 的司机单条派车 → 605802、零新增行；三天只计费前两天不带豁免原因 → 605801、零新增行；改前同形状均为 code=500。失败后同 requestId 60 秒内重提返回 100502（幂等键在提交阶段失败时不释放，与改前相同），过窗后重提 200。前端待定：收到两码弹 msg，重提换新 requestId	2026-09-28	dev-v3

fleet 派车: 快照校验两处失败改返回业务码 605801 / 605802

存放目录: 二期(v3) → changelogs-v2/2026-09/

服务: hl-fleet-service (端口 8087) PR: #8465 Issue: #8423 日期: 2026-09-28 影响范围: 管理后台派车 / 改派等提交后需求派齐、生成派车快照的写接口的错误返回

---

⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）

• 本次变了什么：派车提交让需求派齐时后端会生成派车快照，快照校验里有两种失败是调度员自己能修的，现在返回业务码：605801（某免费服务日没填免费豁免原因）、605802（司机档案手机号不是 1[3-9] 开头的 11 位手机号）。
• 以前：这两种情况一律返回 code=500「系统繁忙，请稍后重试或联系客服」，调度员不知道要改什么。
• 现在：返回 HTTP 200 + code=605801/605802，msg 点明哪一天 / 哪位司机、该怎么改；整次提交仍全部回滚（与以前相同）。其余快照校验失败属系统缺陷，仍返回 code=500 + traceId，前端按通用错误处理。

---

一、背景（选填）

快照校验在事务提交前执行，同样的输入改前改后都失败，只是失败信息从「系统繁忙」变成可行动的提示；请求、响应结构一字不改。

维度	605801	605802
触发	部分日期免费（chargeableServiceDates 非空且不是全部日期）且不带 vehicleFeeWaiverReason，本次提交让需求派齐	所派司机档案手机号能存进档案（11 位数字）但不是 1[3-9] 开头，如 12345678901，本次提交让需求派齐
调度员怎么修	补填免费豁免原因后重新提交	先改司机档案手机号，再对该司机已派车次重新派车

除下文详述的两个接口外，以下端点在提交时同样可能生成快照，也可能返回这两个码（请求 / 响应结构均不变）：

方法 + 路径	说明
POST /admin/fleet/assignments/batch	逐日派车方案
PUT /admin/fleet/assignments/pickup-dropoff-config	接送机门禁由不满足变为满足时
POST /admin/fleet/assignments/requirements/{requirementId}/confirm	需求确认
POST /admin/fleet/assignments/{assignmentId}/confirm	派单确认
POST /admin/fleet/assignments/{assignmentId}/restore-cancel	撤销取消
POST /admin/fleet/group-dispatch/batches/{groupBatchId}/share-groups	团期共用车确认（经改派链路触发）
POST /admin/fleet/assignments/requirements/{requirementId}/no-vehicle	声明不用车：只会出现 code=500，不会出现这两个码

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	单条派车	POST	/admin/fleet/assignments	新增错误码	605801 / 605802
2	改派	POST	/admin/fleet/assignments/{assignmentId}/change	新增错误码	605801 / 605802

---

三、接口详情

1. 单条派车 POST /admin/fleet/assignments

VO: CreateAssignmentReqVO → AssignmentWriteRespVO

使用场景

调度板给用车需求派车、提交单条派车时调用。本次提交让需求派齐时后端生成派车快照，快照校验失败按下文返回。

入参

字段	位置	类型	必填	约束	说明
requestId	Body	String	✅	≤64	幂等键；返回 605801/605802 后该键不释放，60 秒内沿用同一个 requestId 重提返回 100502，修正后重提请换新 requestId
vehicleId	Body	Long	✅	-	车辆 ID
driverId	Body	Long	✅	-	司机 ID；该司机档案手机号是 605802 的判断来源
startDate / endDate	Body	LocalDate	✅	yyyy-MM-dd	派车日期段
chargeableServiceDates	Body	List<LocalDate>	否	须属于本次服务日期	不传 = 全部计费；空数组 = 全部免费；部分日期 = 部分免费
vehicleFeeWaiverReason	Body	String	条件必填	≤256	免费豁免原因；写侧只在全部免费时强制，部分免费不填时派齐后返回 605801
其余字段	Body	-	-	-	与现有契约一致，本次不变

出参 Result<AssignmentWriteRespVO>

字段	类型	说明
data	AssignmentWriteRespVO	结构不变；命中 605801 / 605802 时 data=null

请求示例

{
  "requirementId": "2104392568269848577",
  "vehicleId": "2089686344644116482",
  "driverId": "2104416188249616385",
  "startDate": "2026-10-27",
  "endDate": "2026-10-29",
  "chargeableServiceDates": ["2026-10-27", "2026-10-28"],
  "requestId": "hl8423-45f4a54f755849d4ae6e656b"
}

响应示例

{ "code": 200, "msg": "成功", "data": { "id": "2104416597403942914", "assignmentStatus": "assigned" } }

空数据 / 降级响应

无空数据形态；失败时 data=null，见错误响应。

错误响应

{ "code": 605801, "msg": "服务日 2026-10-29 为免费日，必须填写免费豁免原因", "data": null }

{ "code": 605802, "msg": "司机「苏和巴特尔」的手机号不符合派车快照要求，请先修正司机档案，再对该司机已派车次重新派车", "data": null }

业务边界

• 只在本次提交让需求派齐、生成快照时才会出现这两个码；没派齐不生成快照，不会出现。
• 两个码都是整次提交回滚：不新增派车行、快照版本不前进；与改前 code=500 时相同。
• 幂等：这两个码在事务提交阶段产生，幂等键不释放（与改前 500 时相同）；60 秒内沿用同一个 requestId 重提返回 100502「派单创建处理中，请勿重复提交」，过 60 秒或换新 requestId 可正常提交。
• 其余快照校验失败仍返回 code=500「系统繁忙，请稍后重试或联系客服」+ traceId，属系统缺陷。
• 605899（快照不变量）会出现在 Swagger 全局错误码清单里，但只写在服务端日志，接口不会返回，前端无需适配。

2. 改派 POST /admin/fleet/assignments/{assignmentId}/change

VO: ChangeAssignmentReqVO → ChangeAssignmentRespVO

使用场景

改派车辆 / 司机或改车费时调用。改派后需求派齐会重新生成派车快照，快照校验失败按下文返回。

入参

字段	位置	类型	必填	约束	说明
assignmentId	Path	Long	✅	-	当前车辆槽位任一派单 ID
effectiveDate	Body	LocalDate	✅	yyyy-MM-dd	生效日期
newDriverId	Body	Long	否	与 newVehicleId 至少一个	新司机档案手机号是 605802 的判断来源
chargeableServiceDates	Body	List<LocalDate>	否	-	不传 = 沿用原计费日
vehicleFeeWaiverReason	Body	String	条件必填	≤256	部分免费不填时可能返回 605801
reason	Body	String	✅	≤256	改派原因
requestId	Body	String	✅	≤64	幂等键
其余字段	Body	-	-	-	与现有契约一致，本次不变

出参 Result<ChangeAssignmentRespVO>

字段	类型	说明
data	ChangeAssignmentRespVO	结构不变；命中 605801 / 605802 时 data=null

请求示例

{
  "effectiveDate": "2026-10-28",
  "serviceDates": ["2026-10-28"],
  "newDriverId": "2104416188249616385",
  "reason": "原司机临时请假，换司机",
  "requestId": "hl8423-0b7e61f2c9d84a53b1e6f470"
}

响应示例

{ "code": 200, "msg": "成功", "data": { "assignmentId": "2104416597403942914", "assignmentStatus": "assigned" } }

空数据 / 降级响应

无空数据形态；失败时 data=null，见错误响应。

错误响应

{ "code": 605802, "msg": "司机「苏和巴特尔」的手机号不符合派车快照要求，请先修正司机档案，再对该司机已派车次重新派车", "data": null }

业务边界

• 与单条派车相同：只在改派后需求派齐、生成快照时出现；整次改派回滚；修正后重提请换新 requestId。
• 605801 的日期、605802 的司机姓名都来自快照内的派车行。

---

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

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

✅ 正确 / ❌ 错误 payload 对照

场景	payload
✅ 部分免费并填原因	{ "chargeableServiceDates": ["2026-10-27","2026-10-28"], "vehicleFeeWaiverReason": "客人第三天自驾" }
✅ 全部计费	不传 chargeableServiceDates
❌ 部分免费不填原因（派齐时）	{ "chargeableServiceDates": ["2026-10-27","2026-10-28"] } → 605801
❌ 司机档案手机号 12345678901（派齐时）	任意派车 payload → 605802

切换状态时的必要动作

收到 605801 / 605802 直接把 msg 展示给调度员即可；修正后重提请生成新的 requestId（沿用原值 60 秒内会返回 100502）。605802 需要先改司机档案，再对该司机已派车次重新派车。

---

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

情形	fleet_assignment	快照版本
返回 605801 / 605802	不新增、不修改（整事务回滚）	不前进
修正后重提成功	按原逻辑落派车行	前进一版

---

六、边界行为

• 未登录 → 401（网关拦截）
• 没派齐 → 不生成快照，不会出现这两个码
• 其余快照校验失败 → code=500 + traceId（不外露内部区分码）
• 改前已派的历史数据不迁移；只有新的提交才会走到

---

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

字段级对比

字段	改前	改后
请求 / 响应字段	-	不变

行为级对比

行为	改前	改后
部分免费不填豁免原因且本次派齐	code=500 系统繁忙	code=605801，msg 点明免费日
司机档案手机号 11 位但不是 1[3-9] 开头且本次派齐	code=500 系统繁忙	code=605802，msg 点明司机
其余快照校验失败	code=500	code=500（不变）

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

• 是否破坏向后兼容: 否（只把两种 500 换成业务码，结构不变）
• 前端是否必须同步上线: 否；未识别的业务码若已按通用方式弹 msg，无需改动
• 前端 workaround 清理点: 无

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

• 仅影响: 上文列出的派车类写接口在派齐生成快照时的错误返回
• 零影响:
  • 请求 / 响应字段结构
  • 未派齐的提交
  • 看板、列表、详情等读接口
  • 声明不用车（只可能 code=500）

---

八、测试环境已验证

部署：hl-fleet-service dev-v3 @ fe023b0ed（含合并提交 ad8ad806a），Deploy Panel 任务 2a0e56b9，两实例健康。经 Gateway 用测试车务账号实测（订单 2104392497767854082 需求 2104392521323065345、订单 2104392536896454658 需求 2104392568269848577，坦克300 蒙P301A）：

POST /admin/fleet/assignments  部署前（旧代码）手机号 12345678901 的司机派三天        → code=500 系统繁忙，派车行 0→0 ✓（改前对照）
POST /admin/fleet/assignments  部署后同形状（司机「苏和巴特尔」）                    → HTTP 200 code=605802，data=null，派车行 0→0，快照版本 0→0 ✓
PUT  /admin/fleet/drivers/{id} 手机号改为合规号码                                    → code=200 ✓
POST /admin/fleet/assignments  同 requestId 失败后 8.6s 重提                         → code=100502 派单创建处理中，请勿重复提交，派车行 0→0 ✓
POST /admin/fleet/assignments  同 requestId 失败后 73.3s 重提                        → code=200，派车行 3 行，快照版本 0→1 ✓
POST /admin/fleet/assignments  部署前三天只计费前两天、不带豁免原因                  → code=500 系统繁忙，派车行 0→0 ✓（改前对照）
POST /admin/fleet/assignments  部署后同形状                                          → HTTP 200 code=605801「服务日 2026-10-29 为免费日，必须填写免费豁免原因」，派车行 0→0 ✓

---

十、相关文档

• 关联 Issue: wx/HL#8423
• 关联 PR: wx/HL#8465

关联 / 联系人

链接

• Issue: #8423
• PR: #8465
• Merge commit: ad8ad806a

联系人

• 后端负责人: @lc