From c74fed135390a5bc6d56acba21ffbe8c1c51c260 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Tue, 28 Jul 2026 09:49:40 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BA=A4=E6=8E=A5=E6=9C=80=E7=BB=88?=
 =?UTF-8?q?=E4=B8=8D=E7=94=A8=E8=BD=A6=E7=A8=B3=E5=AE=9A=E6=A7=BD=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81=E4=BF=AE=E5=A4=8D=20(#5307)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...用车稳定槽看板状态与筛选-修改接口-管理后台.md | 84 +++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 changelogs-v2/2026-07/28_5307_最终不用车稳定槽看板状态与筛选-修改接口-管理后台.md

diff --git a/changelogs-v2/2026-07/28_5307_最终不用车稳定槽看板状态与筛选-修改接口-管理后台.md b/changelogs-v2/2026-07/28_5307_最终不用车稳定槽看板状态与筛选-修改接口-管理后台.md
new file mode 100644
index 0000000..f98b0af
--- /dev/null
+++ b/changelogs-v2/2026-07/28_5307_最终不用车稳定槽看板状态与筛选-修改接口-管理后台.md
@@ -0,0 +1,84 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5307"
+title: "最终不用车稳定槽看板状态与筛选"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端 PR #5309 已合并并部署测试环境；既有字段的稳定槽聚合与状态筛选语义已修正，前端无需新增字段或改造"
+updated_at: "2026-07-28"
+base: "dev-v3"
+---
+
+# Fleet：最终不用车稳定槽看板状态与筛选
+
+> **服务**：`hl-fleet-service`
+> **Issue**：#5307
+> **影响页面**：管理后台车务看板、配车矩阵、未派窗口及当天清单
+> **兼容性**：接口路径、方法、请求参数和响应字段均不变化；仅修正既有状态、代表资源、统计和筛选语义
+
+## 问题与目标
+
+逐日最终方案允许同一稳定车辆槽位部分日期实际用车、其他日期明确不用车。此前最终不用车切片仍以基础状态 `unassigned` 持久化，会覆盖同槽真实已派切片，导致看板误显示待派、代表车辆/司机为空，并使状态筛选和矩阵统计出现幽灵待派。
+
+本次统一识别 `dispatchPlanFinalized=1,dailyVehicleUsed=0` 的最终不用车事实。该事实不占车辆/司机、不投保、不计费，也不能重新开放普通派车动作。
+
+## 变更接口
+
+### 车务看板 `/admin/fleet/board/orders`
+
+- 同一稳定槽存在实际用车日和最终不用车日时，槽位状态、代表车辆和代表司机来自真实用车切片；稳定槽日期范围仍覆盖全部当前有效服务日。
+- 全日期均最终不用车时，仅在看板只读聚合中归入“最终方案已完成”的既有 `assigned` 分面；数据库业务状态仍保持 `unassigned`，不会伪造派车、取消或完结事件。
+- 全日期最终不用车记录固定关闭 `canAssign`、`canRejectRequirement`、`availableActionCodes` 和紧急徽章，不开放重复派车或需求驳回。
+- `assignmentProgress` 按权威稳定槽守恒：混合槽和全最终不用车槽不再计入 `unassignedSlots`。
+- `status/statuses` 先取得基础态候选超集，输出前再按最终稳定槽状态复筛；`assigned` 与 `unassigned` 互斥筛选不再返回同一需求。
+- 大候选游标扫描会在 5,000 安全上限前排除普通待派，只保留可能聚合为最终方案完成的 final-unused 候选。
+
+### 配车矩阵 `/admin/fleet/matrix/*`
+
+- 最终不用车切片不进入车辆甘特条、顶部待派统计、月份统计、未派窗口、当天待派清单、并行派车或衔接计算。
+- 混合槽仍展示所有真实用车车辆段及实际司机，不由无车切片覆盖。
+- 全日期最终不用车不会产生幽灵待派；详情接口原有 `dailyVehiclePlan[].planState=NOT_USED` 事实保持不变。
+- 普通未最终化 `unassigned`、`holding/assigned/completed`、人工加急五键统计、Long ID 字符串和手机号脱敏均保持原语义。
+
+## 前端处理
+
+无需新增字段或修改请求。继续直接消费后端现有：
+
+- `assignmentStatus`、`assignmentStatusLabel`
+- `canAssign`、`canRejectRequirement`、`availableActionCodes`
+- `assignmentProgress.finalizedByFleet`
+- `assignmentSlots[]`
+- 矩阵 `statusCounts` 与 `effectiveStatusCounts`
+- 详情 `dailyVehiclePlan[].planState`
+
+不要根据基础 `unassigned`、车辆为空或司机为空自行覆盖后端返回的稳定槽状态和操作权限。
+
+## 不影响范围
+
+- 不修改派单五态数据库状态机。
+- 不修改逐日方案写入、车辆/司机占用、费用、保险、对账或完成回调。
+- 不新增 Feign、数据库查询或逐订单 N+1。
+- 不修改 `hl-ui`；本次为既有字段语义纠正，前端状态为 `not_required`。
+
+## 验证证据
+
+- 后端 PR [wx/HL#5309](https://git.1814.love:8443/wx/HL/pulls/5309) 已 squash 合并至 `dev-v3`，合并提交 `ca23f64fc`。
+- `hl-fleet-service` 已滚动部署测试环境，8087/8187 双实例健康。
+- 定向核心：395 tests，0 failures，0 errors；Reviewer 上限回归 `BoardOrderServiceTest` 59 tests 通过。
+- Fleet reactor verify：2487 tests，0 failures，0 errors，1 skipped；Spotless 629 Java files clean。
+- 独立 Reviewer 首轮发现 assigned 候选超集可能提前触发 5,000 上限；修复并补充“5,000 普通待派 + 1 最终不用车”游标测试后，终审无 P0–P2。
+- 真实测试网关只读验证：矩阵精确状态筛选仅返回请求状态、五键统计守恒；看板 assigned/unassigned 返回状态与筛选一致且需求集合互斥；已完成最终方案未进入 unassigned；Long ID 仍为字符串、手机号保持脱敏，全程无业务写入。
+- 测试环境 API 未暴露内部 final-unused 标记且当前样本未确认存在合法混合槽，因此未伪报真实网关正例；混合槽和全 final-unused 正例由 Service 定向测试覆盖。
+- 网关证据：`D:/work2/HL-v3/.tmp/5307-gateway.json`，SHA-256 `699363c3a06b0d40205ea477c2a0a67daadc2e1718d08ba1102733e66cf2d505`。
+- OpenAPI 与 Spring Cloud Contract：`not_required`，因为 Controller、DTO/VO/BO、Feign、shared Java、枚举及错误码形状均未变化。
+
+当前状态：后端已部署、网关已验证，前端无需改造。
+
+关联：#5307、#5292、#5301。
-- 
2.43.0