docs(changelog): #8423 派车提交生成快照时免费日缺豁免原因返回 605801、司机手机号不合规返回 605802

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-28 12:12:06 +08:00
@@ -0,0 +1,305 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8423"
+title: "派车提交生成快照时：免费日缺豁免原因返回 605801、司机手机号不合规返回 605802（原为 code=500 系统繁忙）"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-28"
+status_note: "PR #8465 合并 dev-v3（ad8ad806a）；hl-fleet-service dev-v3 @ fe023b0ed 部署（任务 2a0e56b9，双实例健康）。TEST 网关实测：手机号 12345678901 的司机单条派车 → 605802、零新增行；三天只计费前两天不带豁免原因 → 605801、零新增行；改前同形状均为 code=500。失败后同 requestId 60 秒内重提返回 100502（幂等键在提交阶段失败时不释放，与改前相同），过窗后重提 200。前端待定：收到两码弹 msg，重提换新 requestId"
+updated_at: "2026-09-28"
+base: "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&lt;LocalDate&gt; | 否 | 须属于本次服务日期 | 不传 = 全部计费；空数组 = 全部免费；**部分日期 = 部分免费** |
+| vehicleFeeWaiverReason | Body | String | 条件必填 | ≤256 | 免费豁免原因；写侧只在全部免费时强制，**部分免费不填时派齐后返回 605801** |
+| 其余字段 | Body | - | - | - | 与现有契约一致，本次不变 |
+
+#### 出参 `Result<AssignmentWriteRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | AssignmentWriteRespVO | 结构不变；命中 605801 / 605802 时 `data=null` |
+
+#### 请求示例
+
+```json
+{
+  "requirementId": "2104392568269848577",
+  "vehicleId": "2089686344644116482",
+  "driverId": "2104416188249616385",
+  "startDate": "2026-10-27",
+  "endDate": "2026-10-29",
+  "chargeableServiceDates": ["2026-10-27", "2026-10-28"],
+  "requestId": "hl8423-45f4a54f755849d4ae6e656b"
+}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "msg": "成功", "data": { "id": "2104416597403942914", "assignmentStatus": "assigned" } }
+```
+
+#### 空数据 / 降级响应
+
+无空数据形态；失败时 `data=null`，见错误响应。
+
+#### 错误响应
+
+```json
+{ "code": 605801, "msg": "服务日 2026-10-29 为免费日，必须填写免费豁免原因", "data": null }
+```
+
+```json
+{ "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&lt;LocalDate&gt; | 否 | - | 不传 = 沿用原计费日 |
+| vehicleFeeWaiverReason | Body | String | 条件必填 | ≤256 | **部分免费不填时可能返回 605801** |
+| reason | Body | String | ✅ | ≤256 | 改派原因 |
+| requestId | Body | String | ✅ | ≤64 | 幂等键 |
+| 其余字段 | Body | - | - | - | 与现有契约一致，本次不变 |
+
+#### 出参 `Result<ChangeAssignmentRespVO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| data | ChangeAssignmentRespVO | 结构不变；命中 605801 / 605802 时 `data=null` |
+
+#### 请求示例
+
+```json
+{
+  "effectiveDate": "2026-10-28",
+  "serviceDates": ["2026-10-28"],
+  "newDriverId": "2104416188249616385",
+  "reason": "原司机临时请假，换司机",
+  "requestId": "hl8423-0b7e61f2c9d84a53b1e6f470"
+}
+```
+
+#### 响应示例
+
+```json
+{ "code": 200, "msg": "成功", "data": { "assignmentId": "2104416597403942914", "assignmentStatus": "assigned" } }
+```
+
+#### 空数据 / 降级响应
+
+无空数据形态；失败时 `data=null`，见错误响应。
+
+#### 错误响应
+
+```json
+{ "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](https://git.1814.love/wx/HL/issues/8423)
+- 关联 PR: [wx/HL#8465](https://git.1814.love/wx/HL/pulls/8465)
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8423](https://git.1814.love/wx/HL/issues/8423)
+- **PR**: [#8465](https://git.1814.love/wx/HL/pulls/8465)
+- **Merge commit**: [ad8ad806a](https://git.1814.love/wx/HL/commit/ad8ad806a)
+
+### 联系人
+
+- **后端负责人**: @lc