docs(api): replace mismatch outline with tags for 5139

关联 wx/HL#5139

changelogs-v2/2026-07/79_车务派单详情补全产品行程节点与出行人-修改接口-前端待处理-管理后台.md

@@ -24,6 +24,7 @@ generated: "2026-07-22T10:35:00+08:00"
 派单弹窗 Step1 不能再只展示人数、日期和每日一句简介。`GET /admin/fleet/board/orders/{orderId}` 现一次返回：
 
 - `productName`：订单产品名（原字段，前端本次必须展示）。
+- `tags[]`：订单在 `order_tag` 中真实挂载的标签名称与颜色；无标签返回 `[]`。
 - `itinerary.days[].nodes[]`：每日真实行程节点，含开始时间、时段、时长、名称和简介。
 - `travelers[]`：出行人脱敏基本信息，不含生日和任何明文字段。
 - `transport`：抵达、返程及分批大交通信息（原字段，前端本次必须完整展示时间和班次，不能只显示站点）。
@@ -44,6 +45,10 @@ GET /admin/fleet/board/orders/{orderId}
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
+| `tags` | Array | 真实订单标签；无标签返回 `[]` |
+| `tags[].tagId` | String | 标签雪花 ID，必须按字符串处理 |
+| `tags[].name` | String/null | 标签名称 |
+| `tags[].color` | String/null | 标签颜色，如 `#52C41A` |
 | `itinerary.days[].nodes` | Array | 当日节点，按 `sortOrder` 升序；无节点返回 `[]` |
 | `itinerary.days[].nodes[].nodeId` | String | 节点雪花 ID，必须按字符串处理 |
 | `itinerary.days[].nodes[].nodeType` | String/null | 节点类型，如 `SCENIC`、`RESTAURANT`、`ACTIVITY`、`SERVICE`、`CUSTOM` |
@@ -106,6 +111,13 @@ GET /admin/fleet/board/orders/{orderId}
   "data": {
     "orderNo": "HL20260721171011648",
     "productName": "草原亲子三日游",
+    "tags": [
+      {
+        "tagId": "9001",
+        "name": "亲子家庭",
+        "color": "#52C41A"
+      }
+    ],
     "itinerary": {
       "theme": "草原亲子三日游",
       "route": null,
@@ -182,6 +194,8 @@ GET /admin/fleet/board/orders/{orderId}
 目标文件：`src/views/fleet/board/components/Step1OrderDetail.vue`。
 
 1. 顶部订单摘要展示产品名，读取 `order.productName || order.product`；产品名为空才显示 `—`。
+   - 当前 `Step1OrderDetail.vue` 中的 `order.bookingType || '企业包车'` 是硬编码占位，不是订单标签，必须删除。
+   - 该位置改为遍历详情响应 `tags[]`，使用 `name` 作为文案、`color` 作为颜色；`tags=[]` 时不显示标签，也不回退“企业包车”。
 2. 在顶部订单摘要下增加“大交通”信息卡，抵达与返程分栏展示 `transportNo + time + station + remark`：
    - 时间使用完整月日和时分，不只展示日期。
    - `arrive`、`depart` 独立判空，只有一段时仍正常展示该段。
@@ -208,6 +222,7 @@ GET /admin/fleet/board/orders/{orderId}
 ## 兼容与降级
 
 - 仅新增响应字段，不修改请求参数，不影响旧调用方。
+- 历史订单无订单标签时 `tags=[]`，禁止使用产品类型、预订类型或固定文案冒充订单标签。
 - 历史行程没有节点时 `nodes=[]`，每日标题和简介仍照常返回。
 - order-v3 聚合上下文失败并回退 fleet 本地快照时，`relatedDetailReady=false`，`travelers=[]`，行程节点不可用；前端显示真实空态。
 - 原独立脱敏接口 `GET /admin/fleet/board/orders/{orderId}/travelers` 保留兼容，但此页面无需再发第二次请求。
@@ -218,6 +233,7 @@ GET /admin/fleet/board/orders/{orderId}
 ## 验收清单
 
 - [ ] 顶部可看到订单产品名。
+- [ ] 顶部只展示 `tags[]` 中的真实订单标签；无标签时不显示，“企业包车”硬编码已删除。
 - [ ] 大交通卡分别展示抵达/返程的班次、完整时间、站点和备注。
 - [ ] 有分批接送时展示每批出行人、班次、时间和站点；无大交通时间时展示真实空态。
 - [ ] 每日安排按节点顺序展示时间、节点名、时长和简介。
@@ -236,9 +252,11 @@ GET /admin/fleet/board/orders/{orderId}
 - `OrderFleetProviderServiceTest`：覆盖节点随当前订单日期对齐且出行人脱敏进入聚合上下文。
 - `BoardOrderServiceTest`：覆盖 shared DTO 到管理端 VO 的节点和出行人映射。
 - `BoardControllerTest`：覆盖 `productName`、节点时间、String ID 与脱敏出行人的 JSON 契约。
+- `OrderFleetProviderServiceTest`、`BoardOrderServiceTest` 与 `BoardControllerTest`：覆盖 `order_tag` 名称/颜色进入详情响应，标签 ID 按字符串序列化。
 - 测试环境网关实测订单 `HL20260721171011648`：HTTP 200，返回 3 个行程日、14 个真实节点和 5 位出行人；5 位出行人均返回 `ageAtDeparture`，且未出现生日、明文姓名、明文证件号或明文手机号。
+- 同一实测订单返回 2 个真实订单标签“自动化测试”“房务需求”，均包含颜色，`tagId` 均为字符串；响应不含 `bookingType`，前端无需也不得使用“企业包车”等硬编码兜底。
 - 同一实测订单已返回抵达大交通的班次、抵达时间和站点；该订单无返程段、无分批接送，接口按真实数据返回空值或空数组。
 - 该订单 14 个节点的 `startTime` 与 `timePeriod` 在订单行程源数据中均为空，接口如实返回 `null`；前端须展示“时间待定”，若要显示具体钟点需先补录订单行程节点时间。
-- 网关证据已由 `hl task` 登记，SHA-256：`37a3c08afb11230d5d93f806e701f8fe5d5c84973fb330d87ad3c478726a4b27`。
+- 网关证据已由 `hl task` 登记，SHA-256：`8ff09cc804fb8d72fde6df3f338125b725c857d2c098b59f6b222f460da844a3`。
 
 > 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。

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

@@ -0,0 +1,183 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5139"
+title: "车务派单候选筛选、分页与任意车辆选择"
+consumer: "admin"
+backend: "verified"
+gateway: "verified"
+frontend: "pending"
+base: "dev-v3"
+generated: "2026-07-22T13:25:00+08:00"
+---
+
+# 【修改接口·前端待处理·管理后台】车务派单候选筛选、分页与任意车辆选择
+
+## 目标前端
+
+- 端类型：管理后台（Web）
+- 目标仓库：`mmg/hl-ui`
+- 仓库地址：<https://git.1814.love:8443/mmg/hl-ui.git>
+- 联调/验收环境：<http://192.168.100.160:9527>
+- 小程序：无需处理
+
+> **服务**: hl-fleet-service  
+> **日期**: 2026-07-22  
+> **工单**: #5139  
+> **影响范围**: 订单派车弹窗的车辆候选、司机候选与最终派单校验
+
+## 关键变化
+
+`POST /admin/fleet/assignments/candidates` 继续同时返回车辆和司机，但两侧必须按各自分页参数渲染。后端新增动态车队/车型筛选、车型需求匹配、协议参考价、车辆常驻司机、司机历史统计，以及“先选司机时回显常驻车”的契约。
+
+车型或座位不符合订单需求时，车辆仍允许选择；只有真实档期冲突或资源不可用才禁止。车辆选中态不是强制单选，前端再次点击已选车辆时可把 `selectedVehicleId` 清为 `null` 后重新查询。
+
+## 变更接口
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| POST | `/admin/fleet/assignments/candidates` | 车辆、司机独立筛选和分页；任一侧可先选 |
+| POST | `/admin/fleet/assignments/precheck` | 车型/座位不匹配只返回 warning |
+| POST | `/admin/fleet/assignments` | `strictSeats` 历史字段不再阻断任意车辆派单 |
+
+## 候选查询入参
+
+在原请求基础上新增或明确以下字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `selectedVehicleId` | String/null | 否 | 当前已选车辆；传 `null` 表示取消车辆选择 |
+| `selectedDriverId` | String/null | 否 | 当前已选司机；可在未选车辆时先传 |
+| `fleetTeamId` | String/null | 否 | 独立车队主数据 ID；空为全部 |
+| `vehicleTypeId` | String/null | 否 | 车型大类 ID；空为全部 |
+| `requiredVehicleType` | String/null | 否 | 订单需求车型大类 key，只影响匹配标记，不限制选择 |
+| `vehiclePage` / `vehiclePageSize` | Integer | 是 | 车辆独立分页，页大小 1～100 |
+| `driverPage` / `driverPageSize` | Integer | 是 | 司机独立分页，页大小 1～100 |
+| `driverAvailability` | String | 否 | `ALL` / `AVAILABLE`，接口默认 `ALL`；管理后台按原型首屏显式传 `AVAILABLE` |
+| `driverSort` | String | 否 | `SMART` / `RATING` / `YEARS` / `RECENT_ORDER`，默认 `SMART` |
+
+雪花 ID 一律按字符串保存和提交，禁止 `Number()`、`parseInt()`。
+
+取消车辆但保留司机的请求示例：
+
+```json
+{
+  "orderId": "2080000000000000001",
+  "requirementId": "2080000000000000101",
+  "fleetItemIndex": 0,
+  "startDate": "2026-07-29",
+  "endDate": "2026-07-31",
+  "headcount": 5,
+  "requiredVehicleType": "suv",
+  "selectedVehicleId": null,
+  "selectedDriverId": "2080000000000000201",
+  "vehiclePage": 1,
+  "vehiclePageSize": 10,
+  "driverPage": 1,
+  "driverPageSize": 10
+}
+```
+
+## 响应结构
+
+### 独立分页
+
+`data.vehicles` 和 `data.drivers` 均返回：
+
+```json
+{
+  "records": [],
+  "list": [],
+  "total": 106,
+  "page": 1,
+  "pageSize": 10
+}
+```
+
+`records` 与 `list` 内容相同，前端统一使用 `records`。切换车辆筛选只重置 `vehiclePage`，切换司机筛选只重置 `driverPage`，不要一次性把所有候选渲染成长列表。
+
+### 动态筛选项
+
+- `fleetTeamFacets[]`: `fleetTeamId/fleetTeamName/fleetType/count`。
+- `vehicleTypeFacets[]`: `vehicleTypeId/vehicleTypeKey/vehicleTypeName/count`。
+- 数量按当前车辆关键词统计；“全部”数量可按 facet 求和或使用 `vehicles.total`。
+- 不再写死“自有车队/合作车队 A/合作车队 B”或固定车型数组。
+
+### 车辆候选新增字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `vehicleTypeId` | String/null | 车型大类 ID |
+| `vehicleTypeKey` / `vehicleTypeName` | String/null | 车型大类编码和名称 |
+| `fleetTeamId/fleetTeamName/fleetType` | String/null | 动态车队信息 |
+| `primaryDriverId/primaryDriverName` | String/null | 常驻司机；为空显示“无常驻” |
+| `protocolPrice` | Decimal/null | 用车开始日价格日历协议参考价；为空显示“未设价” |
+| `passengerCapacity` | Integer | 载客数，已扣除司机座 |
+| `seatsEnough` | Boolean | 座位是否满足人数，仅用于提示 |
+| `requirementMatched` | Boolean | 车型和座位是否均符合需求；`false` 只做醒目标记 |
+| `available` | Boolean | 是否可选的权威值；真实档期冲突时为 `false` |
+| `selected` | Boolean | 是否为当前已选车辆 |
+
+前端禁用判断只使用 `available === false`。禁止用 `requirementMatched === false`、`seatsEnough === false` 或车型不一致禁用车辆；这些情况应显示“需求不匹配/座位不足”提示，但允许车务选中。
+
+需求不匹配必须使用车辆卡片内的显式标签，不能再以黄色外框作为主要提示：
+
+- `requirementMatched === false`：在车辆名称/状态附近显示橙色 `需求不匹配` 标签。
+- `seatsEnough === false`：额外显示红色或橙红色 `座位不足` 标签。
+- 移除需求不匹配专用黄色外框；边框只保留选中态、档期冲突等已有交互语义，避免颜色含义不明。
+- 标签只负责提醒，不改变 `available`、点击选择或最终派单规则。
+
+### 先选司机与取消车辆
+
+- 仅传 `selectedDriverId` 时，`selectedDriverResidentVehicle` 返回该司机常驻车的完整车辆候选；司机无常驻车时为 `null`。
+- 常驻车即使不在当前车队、车型筛选页内，也会通过该独立字段返回，前端可置顶或单独提示。
+- 再次点击已选车辆时，前端清空本地车辆 ID，并以 `selectedVehicleId: null` 查询；保留 `selectedDriverId` 时常驻车提示仍存在。
+- 同时选定跨常驻车组合时，沿用 `selectedRelation.requiresConfirmation` 和候选项 `requiresCrossResidentConfirmation` 的确认流程。
+
+### 司机候选统计
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `completedOrderCount` | Integer | 司机跨赛季历史完单量，按派车组去重 |
+| `lastOrderAt` | Date/null | 最近完单日期 |
+| `rating` | Decimal/null | 真实平均评分；无评价时为 `null` |
+| `hasRating` | Boolean | 是否存在真实评分 |
+| `residentVehicleId/residentVehiclePlate` | String/null | 司机常驻车辆 |
+
+`hasRating=false` 时显示“暂无评价”，不要展示星标和 `0.0/5.0`；不得再用固定 `5.0` 兜底。单量为司机历史累计，不按赛季清零。
+
+### 原型一致性：司机筛选控件
+
+司机筛选必须按原型平铺展示，不能用两个下拉框折叠选项。平铺按钮让车务一眼看到当前范围和全部排序方式，并可单击切换：
+
+- 范围：`仅空闲`（`AVAILABLE`，首屏默认选中）、`全部`（`ALL`）。
+- 排序：`智能推荐`（`SMART`，首屏默认选中）、`评分`（`RATING`）、`驾龄`（`YEARS`）、`最近接单`（`RECENT_ORDER`）。
+- 切换范围或排序时只把 `driverPage` 重置为 1，不重置车辆筛选、车辆页码或已选车辆。
+- “全部司机/智能排序”两个 `NSelect` 不视为原型等价实现；验收以按钮全部可见、选中态明确为准。
+
+## 最终派单规则
+
+- 车型或座位不匹配：候选项仍可选，预检返回 warning，最终派单不阻断。
+- 档期冲突、车辆/司机不可用、黑名单或跨常驻未确认：仍按现有业务守卫阻断。
+- `strictSeats` 为历史兼容字段，可不再提交；即使提交 `true` 也不会把座位不足变成阻断。
+
+## 前端处理清单
+
+- [ ] 车辆和司机列表分别接 `records/total/page/pageSize` 并增加独立分页控件。
+- [ ] 车队和车型筛选使用 `fleetTeamFacets/vehicleTypeFacets` 动态渲染及计数。
+- [ ] 车辆行展示车型、常驻司机、协议参考价；需求不匹配改用卡片内显式标签并移除黄色外框，座位不足追加独立标签，均不禁选。
+- [ ] 支持再次点击已选车辆取消选择，并传 `selectedVehicleId: null`。
+- [ ] 支持先选司机，并展示/置顶 `selectedDriverResidentVehicle`。
+- [ ] 司机范围与排序按原型平铺为 2+4 个按钮，默认“仅空闲 + 智能推荐”，不得折叠成两个下拉框。
+- [ ] 司机无评价显示“暂无评价”，不伪造 `5.0` 或 `0.0`；完成单量读取 `completedOrderCount`。
+- [ ] 雪花 ID 全程按字符串处理。
+
+## 验证证据
+
+- PR [wx/HL#5140](https://git.1814.love:8443/wx/HL/pulls/5140) 已合并到 `dev-v3`。
+- 派单候选、派单服务、司机统计、可靠投影、价格日历和迁移审计定向测试全部通过。
+- `spotless:check` 与 `mvn -pl hl-fleet-service -am verify` 通过。
+- 测试环境 `hl-fleet-service` 8087/8187 双实例滚动部署健康。
+- 测试网关实测 HTTP/业务码 200：车辆和司机独立分页一致，返回 3 个动态车队、4 个车型大类；协议价非空，车型不匹配车辆仍可选；车辆可清空，先选司机可返回常驻车。
+- 测试库只读核验：`V20260722.002` 已成功执行，候选 `completedOrderCount/lastOrderAt` 与 `fleet_driver` 投影一致，无评分司机返回 `rating=null`。
+
+> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。

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

@@ -0,0 +1,114 @@
+---
+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`。
+
+## 编辑司机：无保单时直接线上投保
+
+司机编辑抽屉选择“全年保险”后，如果“关联保游网保单”没有可选数据，不应只展示空下拉。需要在当前抽屉提供“立即投保”入口，复用保险订单页“投保下单 → 司机”的线上真实投保逻辑。
+
+目标文件：
+
+- `src/views/fleet/drivers/components/DriverEditModal.vue`
+- 可复用 `src/views/insurance/orders/index.vue` 中的司机投保表单和 `src/api/fleet/drivers.js` 的 `purchaseDriverInsurance`。
+
+交互要求：
+
+1. 无可关联保单时显示“暂无可关联保单”，并提供“立即投保”按钮。
+2. 点击后填写保险计划、保障开始、保障结束和可选备注；表单行为与保险订单页的司机投保一致。
+3. 用户点击“确认投保”后才发起真实线上投保；仅切换到“全年保险”不得自动出单。
+4. 投保请求必须传 `bindAnnual: true`。受理成功后，后端会自动把新保单绑定为司机档案的全年保险。
+5. 成功后重新加载司机保单列表和司机详情，回显新 `insuranceOrderId`、保单状态及保障起止；`INSURING` 时显示“出单中”，不能要求用户重复投保。
+6. 保留“手工录入线下保单”作为独立兜底路径，文案和操作不得与线上投保混用。
+
+调用示例：
+
+```http
+POST /admin/fleet/drivers/{driverId}/insurance/purchase
+```
+
+```json
+{
+  "planId": "2080000000000000001",
+  "coverageStartDate": "2026-07-23",
+  "coverageEndDate": "2027-07-22",
+  "bindAnnual": true,
+  "remark": "司机全年保险"
+}
+```
+
+`driverId`、`planId` 和响应中的 `insuranceOrderId` 均为雪花 ID，前端必须按字符串透传。保险计划继续使用 `GET /admin/fleet/drivers/insurance/plan-options`。
+
+异常处理沿用保险订单页：全局展示后端错误文案；若返回 `600206`，表示可能已经出单但档案绑定失败，必须关闭投保弹窗并刷新保单列表，提示用户勿重复投保。
+
+追加验收项：
+
+- [ ] 编辑司机选择全年保险且无已有保单时，可在当前抽屉发起线上真实投保。
+- [ ] 请求携带 `bindAnnual: true`，投保受理后司机档案自动回显全年保险，无需先保存再关联。
+- [ ] 出单中、已承保和 `600206` 场景均不会诱导用户重复投保。
+- [ ] 线上投保与手工录入线下保单入口、文案和数据来源清晰分离。
+
+## 验证证据
+
+- 后端 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`。