Merge pull request 'docs(api): 明确 5139 司机筛选按原型平铺' (#17) from docs/5139-driver-filter-prototype into main

changelogs-v2/2026-07/80_5139_车务派单候选筛选分页与任意车辆选择-修改接口-前端待处理-管理后台.md

@@ -52,7 +52,7 @@ generated: "2026-07-22T13:25:00+08:00"
 | `requiredVehicleType` | String/null | 否 | 订单需求车型大类 key，只影响匹配标记，不限制选择 |
 | `vehiclePage` / `vehiclePageSize` | Integer | 是 | 车辆独立分页，页大小 1～100 |
 | `driverPage` / `driverPageSize` | Integer | 是 | 司机独立分页，页大小 1～100 |
-| `driverAvailability` | String | 否 | `ALL` / `AVAILABLE`，默认 `ALL` |
+| `driverAvailability` | String | 否 | `ALL` / `AVAILABLE`，接口默认 `ALL`；管理后台按原型首屏显式传 `AVAILABLE` |
 | `driverSort` | String | 否 | `SMART` / `RATING` / `YEARS` / `RECENT_ORDER`，默认 `SMART` |
 
 雪花 ID 一律按字符串保存和提交，禁止 `Number()`、`parseInt()`。
@@ -138,6 +138,15 @@ generated: "2026-07-22T13:25:00+08:00"
 
 `hasRating=false` 时显示“暂无评价”，不要展示星标和 `0.0/5.0`；不得再用固定 `5.0` 兜底。单量为司机历史累计，不按赛季清零。
 
+### 原型一致性：司机筛选控件
+
+司机筛选必须按原型平铺展示，不能用两个下拉框折叠选项。平铺按钮让车务一眼看到当前范围和全部排序方式，并可单击切换：
+
+- 范围：`仅空闲`（`AVAILABLE`，首屏默认选中）、`全部`（`ALL`）。
+- 排序：`智能推荐`（`SMART`，首屏默认选中）、`评分`（`RATING`）、`驾龄`（`YEARS`）、`最近接单`（`RECENT_ORDER`）。
+- 切换范围或排序时只把 `driverPage` 重置为 1，不重置车辆筛选、车辆页码或已选车辆。
+- “全部司机/智能排序”两个 `NSelect` 不视为原型等价实现；验收以按钮全部可见、选中态明确为准。
+
 ## 最终派单规则
 
 - 车型或座位不匹配：候选项仍可选，预检返回 warning，最终派单不阻断。
@@ -151,6 +160,7 @@ generated: "2026-07-22T13:25:00+08:00"
 - [ ] 车辆行展示车型、常驻司机、协议参考价；需求车型或座位不匹配只醒目标记，不禁选。
 - [ ] 支持再次点击已选车辆取消选择，并传 `selectedVehicleId: null`。
 - [ ] 支持先选司机，并展示/置顶 `selectedDriverResidentVehicle`。
+- [ ] 司机范围与排序按原型平铺为 2+4 个按钮，默认“仅空闲 + 智能推荐”，不得折叠成两个下拉框。
 - [ ] 司机无评价显示“暂无评价”，不伪造 `5.0` 或 `0.0`；完成单量读取 `completedOrderCount`。
 - [ ] 雪花 ID 全程按字符串处理。
 

changelogs-v2/2026-07/81_5141_车务派单司机保险保障状态-修改接口-前端待处理-管理后台.md

@@ -0,0 +1,69 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5141"
+title: "车务派单司机保险类型与行程保障状态"
+consumer: "admin"
+backend: "verified"
+gateway: "verified"
+frontend: "pending"
+base: "dev-v3"
+generated: "2026-07-22T14:07:00+08:00"
+---
+
+# 【修改接口·前端待处理·管理后台】车务派单司机保险类型与行程保障状态
+
+## 目标前端
+
+- 端类型：管理后台（Web）
+- 目标仓库：`mmg/hl-ui`
+- 仓库地址：<https://git.1814.love:8443/mmg/hl-ui.git>
+- 联调/验收环境：<http://192.168.100.160:9527>
+- 小程序：无需处理
+
+## 变更接口
+
+`POST /admin/fleet/assignments/candidates` 的 `data.drivers.records[]` 新增司机保险字段。数据直接来自司机档案，并按本次请求的 `startDate/endDate` 判断全年保险是否完整覆盖行程。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `insuranceType` | String | `annual` 全年保险、`perTrip` 按行程投保、`none` 无保险 |
+| `insuranceTypeLabel` | String | `全年保险`、`按行程投保`、`无保险` |
+| `insuranceAnnualStart` | Date/null | 全年保险起始日；非 `annual` 为空 |
+| `insuranceAnnualEnd` | Date/null | 全年保险到期日；非 `annual` 为空 |
+| `insuranceCoverageStatus` | String | 本次行程保障状态，枚举见下表 |
+| `insuranceCoverageMessage` | String | 后端生成的中文提示，可直接展示 |
+| `insuranceCovered` | Boolean | 仅全年保险完整覆盖本次服务日期时为 `true` |
+
+## 保障状态
+
+| `insuranceCoverageStatus` | `insuranceCoverageMessage` | 含义 |
+| --- | --- | --- |
+| `ANNUAL_COVERED` | 全年保险已覆盖 | 年保起止日完整覆盖本次行程 |
+| `ANNUAL_NOT_COVERED` | 全年保险不覆盖本行程 | 年保缺日期、未生效、已过期或仅覆盖部分行程 |
+| `PER_TRIP_REQUIRED` | 待按行程投保 | 司机配置为按行程投保，候选阶段尚不代表已经出单 |
+| `UNINSURED` | 无保险 | 司机档案明确为无保险 |
+| `UNKNOWN` | 保险状态未知 | 存量异常值兜底，不能当作已保障 |
+
+## 前端展示规则
+
+- 在司机卡片姓名或驾龄附近展示保险徽标，文案优先使用 `insuranceCoverageMessage`。
+- `ANNUAL_COVERED` 可用绿色；`PER_TRIP_REQUIRED` 用橙色；`ANNUAL_NOT_COVERED/UNINSURED/UNKNOWN` 用红色或醒目警示色。
+- 全年保险可在悬浮提示或次级文案展示 `insuranceAnnualStart ~ insuranceAnnualEnd`。
+- 保险状态只用于车务判断和提示，不影响司机候选的 `available`，不得因为未投保或待按行程投保禁用司机。
+- 不要只根据 `insuranceType=annual` 显示“已保障”，必须以 `insuranceCoverageStatus` 或 `insuranceCovered` 为准。
+
+## 前端处理清单
+
+- [ ] 司机候选卡片展示保险保障徽标。
+- [ ] 区分全年已覆盖、全年未覆盖、待按行程投保、无保险及未知状态。
+- [ ] 年保可查看保障起止日，且不把过期或部分覆盖年保展示为已保障。
+- [ ] 保险状态不改变司机可选性，候选禁用仍只依据 `available === false`。
+
+## 验证证据
+
+- 后端 PR [wx/HL#5143](https://git.1814.love:8443/wx/HL/pulls/5143) 已合并到 `dev-v3`。
+- 派单候选与司机域定向测试共 148 项通过。
+- fleet `spotless:check` 与 `mvn -pl hl-fleet-service -am verify` 通过。
+- 测试网关真实返回 21 名司机，覆盖全年已覆盖、全年未覆盖、待按行程投保和无保险四类结果；响应与测试库司机保险档案逐条一致，19 名警示状态司机仍可选择。
+
+> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。