246 行
11 KiB
Markdown
246 行
11 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8528"
|
||
title: "团期配车重排新增资源态硬校验，响应回填被 clearAll 忽略的行程日"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "not_required"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "PR #8553 合并 dev-v3（7b702f5c3f）；hl-fleet-service dev-v3 分支部署测试网关 @ e2982739e8（含 7b702f5c3f）并实测：排入 rest 司机返 605038、排入 DISABLED 车辆返 605037（均一行未落库）；正常 ACTIVE 车辆 7 天全排返 addedCount=7；clearAll=true 场景返 ignoredDemandDays 回填生效。"
|
||
updated_at: "2026-09-30"
|
||
base: "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 车辆场景，节选一天）：
|
||
|
||
```json
|
||
{
|
||
"requirementId": "5501",
|
||
"requirementVersion": 3,
|
||
"clearAll": false,
|
||
"demands": [
|
||
{ "tripDate": "2026-09-12", "assignments": [ { "groupId": "BUS", "vehicleId": "1001", "driverId": "2001" } ] }
|
||
]
|
||
}
|
||
```
|
||
|
||
clearAll 场景：
|
||
|
||
```json
|
||
{
|
||
"requirementId": "5501",
|
||
"requirementVersion": 3,
|
||
"clearAll": true,
|
||
"survivorPolicy": "RELEASE",
|
||
"demands": [
|
||
{ "tripDate": "2026-11-10", "assignments": [] }
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
7 天全排成功：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "addedCount": 7, "coverage": { "wholeBatchSatisfied": true } }, "success": true }
|
||
```
|
||
|
||
clearAll 场景（行程日被回填进 `ignoredDemandDays`）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "addedCount": 0, "ignoredDemandDays": ["2026-11-10"] }, "success": true }
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无空数据形态；命中资源态硬校验或既有校验失败时 `data=null`，见错误响应。
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{ "code": 605038, "message": "司机处于休假或待激活状态，不能派车：苏和巴特尔", "data": null, "success": false }
|
||
```
|
||
|
||
```json
|
||
{ "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](https://git.1814.love/wx/HL/issues/8528)、[wx/HL#8529](https://git.1814.love/wx/HL/issues/8529)
|
||
- 关联 PR: [wx/HL#8553](https://git.1814.love/wx/HL/pulls/8553)
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#8528](https://git.1814.love/wx/HL/issues/8528)、[#8529](https://git.1814.love/wx/HL/issues/8529)
|
||
- **PR**: [#8553](https://git.1814.love/wx/HL/pulls/8553)
|
||
- **Merge commit**: [7b702f5c3f](https://git.1814.love/wx/HL/commit/7b702f5c3f)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|