docs(api): publish assignment candidate contract (#5139)

关联 wx/HL#5131

changelogs-v2/2026-07/5131-fleet-team-management.md

@@ -0,0 +1,201 @@
+---
+schema: "hl-changelog/v1"
+ticket: "5131"
+title: "车队独立管理及车队字典下线"
+consumer: "admin"
+backend: "verified"
+gateway: "verified"
+frontend: "pending"
+base: "dev-v3"
+generated: "2026-07-22T10:46:00+08:00"
+---
+
+# 【新增接口·修改接口·前端需联调·管理后台/H5】车队独立管理及车队字典下线
+
+> **服务**: hl-fleet-service + hl-user-service  
+> **日期**: 2026-07-22  
+> **工单**: #5131  
+> **影响范围**: 车队管理、车辆档案、司机 H5、自带车审核、派车候选、矩阵、车队对账
+
+## 关键变化
+
+`fleet_attribution` 不再是车队数据源。后端新增 `fleet_team` 主数据，统一维护：
+
+- `teamName`：车队名称。
+- `teamType`：`SELF_OPERATED` 自有 / `COOPERATIVE` 合作。
+- `leaderName`、`leaderPhone`：负责人及电话；列表电话脱敏，详情返回编辑原值。
+- `settleType`：直接复用资源付款方式 `resource_settle_type`，当前值为 `cash` / `sign` / `company`。
+- `status`：`ACTIVE` / `DISABLED`。
+
+车辆及相关链路以 `fleetTeamId` 为权威关联。旧 `fleet` 稳定编码仅在客户端切换期保留兼容，不得再用于生成选项或写死 `own/coopA/coopB`。
+
+## 变更接口
+
+### 车队管理
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/admin/fleet/teams/page` | 分页；支持 `keyword/teamType/status/settleType` |
+| GET | `/admin/fleet/teams/options` | 有效车队下拉；编辑存量时可传 `includeDisabledId` 回显当前停用车队 |
+| GET | `/admin/fleet/teams/:fleetTeamId` | 详情；负责人电话返回原值供编辑 |
+| POST | `/admin/fleet/teams` | 新增 |
+| PUT | `/admin/fleet/teams/:fleetTeamId` | 编辑 |
+| POST | `/admin/fleet/teams/:fleetTeamId/disable` | 停用；仍有在役车辆返回 `601103` |
+| POST | `/admin/fleet/teams/:fleetTeamId/enable` | 启用 |
+
+保存请求：
+
+```json
+{
+  "teamName": "合作车队一队",
+  "teamType": "COOPERATIVE",
+  "leaderName": "张三",
+  "leaderPhone": "13800138000",
+  "settleType": "sign",
+  "sortOrder": 20,
+  "remark": "旺季合作车队"
+}
+```
+
+下拉响应项：
+
+```json
+{
+  "fleetTeamId": "2080000000000000001",
+  "teamCode": "ft_fsq1ab23cd",
+  "teamName": "合作车队一队",
+  "teamType": "COOPERATIVE",
+  "settleType": "sign",
+  "status": "ACTIVE"
+}
+```
+
+雪花 ID 一律按字符串处理，禁止 `Number()` / `parseInt()`。
+
+## 修改接口
+
+### 车辆档案
+
+- `POST /admin/fleet/vehicles`、`PUT /admin/fleet/vehicles/:id`：新增 `fleetTeamId`，新前端必传。
+- `GET /admin/fleet/vehicles/page`：新增筛选参数 `fleetTeamId`；列表项新增 `fleetTeamId/fleetTeamName/fleetType/settleType`。
+- `GET /admin/fleet/vehicles/:id`：详情新增同上字段。
+- 车辆导入模板把车队列改为“车队名称”，填写独立车队管理中的有效名称；历史表头和稳定编码仍兼容。
+
+### 司机 H5 与审核
+
+- `GET /app/h5/driver-onboard/init`：链接可编辑时新增 `fleetTeamOptions[]`，只包含 `fleetTeamId/teamName/teamType`，不暴露负责人和结算资料；续签会额外包含当前已停用车队用于原值回显。
+- `SubmitVehicleVO`、续签常驻车回显新增 `fleetTeamId`。
+- 待审核详情 `vehicle`、审核通过请求 `ownVehicle` 新增 `fleetTeamId`。
+- H5 和管理端都必须提交 ID；旧 `fleet` 仅兼容已打开的旧页面。
+
+### 派车候选与矩阵
+
+- 派车车辆候选新增 `fleetTeamId/fleetTeamName/fleetType/settleType`。
+- `GET /admin/fleet/board/orders` 已派车辆新增 `currentVehicleFleetTeamId/currentVehicleFleetTeamName/currentVehicleFleetTeamType/currentVehicleFleetTeamSettleType`。
+- `GET /admin/fleet/matrix/grid` 新增 `fleetTeamIds[]`；`fleets[]` 废弃。
+- 矩阵车辆行新增 `fleetTeamId/fleetTeamName/fleetType/settleType`。
+- 响应新增 `fleetTeamCounts[]`，每项包含 `fleetTeamId/teamName/count`；`fleetCount` 仅过渡兼容。
+
+### 对账
+
+- 车费车队分组新增 `fleetTeamId/fleetType/settleType`，名称使用对账快照。
+- `GET /admin/fleet/reconciliation/cars` 与 CSV 导出新增 `fleetTeamIds[]`；传入后优先于旧 `fleets[]`。
+- 保险车队分组新增 `fleetTeamId/fleetName/fleetType/settleType`。
+- 实际结算保存新增 `fleetTeamId`；旧 `fleet` 废弃。
+- 后端按车队类型派生 `OWN_COST/COOP_QUOTE`，不再把 `own` 当特殊业务编码。
+
+## 独立菜单与权限
+
+user-service 新增顶级菜单：
+
+- 路由：`/fleet/teams`
+- 组件：`fleet/teams/index`
+- 权限：`fleet:team:list`、`fleet:team:create`、`fleet:team:update`、`fleet:team:status`
+- 默认角色：`SUPER_ADMIN`、`ADMIN`、`VEHICLE_MANAGER`
+
+前端必须新增对应组件，否则菜单发布后会出现空路由。
+
+## 前端必须修改的范围
+
+### 管理后台
+
+1. 新增 `src/api/fleet/teams.js` 和 `src/views/fleet/teams/index.vue`，完成车队分页、新增、编辑、启停。
+2. 车辆档案：
+   - `src/views/fleet/vehicles/index.vue`
+   - `src/views/fleet/vehicles/components/VehicleEditModal.vue`
+   - `src/api/fleet/vehicles.js`
+   使用 `/admin/fleet/teams/options`，表单和筛选绑定 `fleetTeamId`，展示 `fleetTeamName`。
+3. 自带车审核和车辆选择：
+   - `src/views/fleet/drivers/pending/index.vue`
+   - `src/views/fleet/drivers/components/VehiclePickerModal.vue`
+   - `src/api/fleet/drivers.js`
+   不再读取 `fleet_attribution`。
+4. 派车看板、矩阵和共享甘特：删除 `own/coopA/coopB` 固定数组和固定颜色映射，按 API 返回的 ID/名称动态分组。涉及：
+   - `src/views/fleet/board/composables/useVehicleDriverPicker.js`
+   - `src/views/fleet/board/components/VehiclePickerList.vue`
+   - `src/views/fleet/matrix/**`
+   - `src/views/fleet/_shared/fleetDisplay.js`
+   - `src/views/fleet/_shared/gantt/**`
+5. 车队对账：`src/views/fleet/recon/**` 删除三车队固定循环、固定展开状态和固定 CSV 顺序；实际结算提交 `fleetTeamId`。
+
+动态车队颜色可由 `fleetTeamId` 做稳定哈希映射，但不得用数组下标产生每次刷新变化的颜色。
+
+### 司机 H5
+
+以下文件把硬编码 `<option value="own/coopA/coopB">` 改为初始化响应的 `fleetTeamOptions`，提交 `fleetTeamId`：
+
+- `src/views/h5/driver-intake/DriverIntakeForm.vue`
+- `src/views/h5/driver-intake/composables/useIntakeForm.js`
+- `src/views/h5/driver-intake/composables/useRenewPrefill.js`
+- `src/views/h5/driver-intake/steps/StepVehicleReg.vue`
+- `src/views/h5/driver-intake/steps/RenewUpdate.vue`
+
+## 删除字典与发布顺序
+
+user-service 迁移会精确删除：
+
+```sql
+DELETE FROM sys_dict_data WHERE dict_type = 'fleet_attribution';
+DELETE FROM sys_dict_type WHERE dict_type = 'fleet_attribution';
+```
+
+必须按以下顺序发布，禁止先删字典：
+
+1. 发布 `hl-fleet-service`，完成 `fleet_team` 建表、存量回填和兼容接口上线。
+2. 发布已完成本清单的 `hl-ui`，确认车辆、审核、H5、矩阵和对账不再读取该字典。
+3. 最后发布 `hl-user-service`，新增独立菜单并删除字典。
+
+若环境中曾在字典里新增但从未被车辆、待审核或对账引用的车队，发布前需先在独立车队管理中补建；迁移会自动收集所有已有业务引用编码，但不会跨服务读取未使用的字典配置。
+
+## 兼容与业务规则
+
+- 车队名称唯一；内部 `teamCode` 创建后不可修改。
+- 车队已关联车辆后不能切换自有/合作类型，防止历史结算语义漂移。
+- 停用车队不出现在普通下拉；存量车辆编辑可回显当前停用车队，但不能切入其他停用车队。
+- 车队下仍有 `ACTIVE` 车辆时禁止停用，须先转移或停用车辆。
+- 停用车队的存量车辆不得恢复在役，也不会进入派车候选或矩阵。
+- 对账保存车队名称、类型和付款方式快照，后续改主档不修改历史账期。
+- 负责人电话属于敏感信息，列表只展示脱敏值，不得写日志或进入前端埋点。
+
+## 验收清单
+
+- [ ] 独立车队菜单可分页、新增、编辑、启停，付款方式与资源页选项一致。
+- [ ] 车辆新增/编辑/筛选/详情/导入均使用动态车队，不再出现固定三项。
+- [ ] 司机 H5 新招、续签和管理端自带车审核均可选择动态车队并正确回显。
+- [ ] 派车候选、矩阵、甘特和对账能展示任意新增车队，颜色和分组稳定。
+- [ ] 全前端搜索不到 `fleet_attribution` 运行时读取，也没有业务代码写死 `own/coopA/coopB` 车队集合。
+- [ ] 按发布顺序上线后，删除字典不会导致下拉为空、标签显示编码或请求失败。
+- [ ] 雪花 ID 全程按字符串处理，负责人电话未出现在日志、埋点或列表明文。
+
+## 验证证据
+
+- `mvn -pl hl-fleet-service -am -DskipTests compile`：通过。
+- 受影响链路 12 个测试类定向执行：388 项通过，0 failure，0 error。
+- user-service 菜单迁移审计：1 项通过，0 failure，0 error。
+- `mvn -pl hl-user-service,hl-fleet-service -am test`：通过。
+- `mvn -pl hl-fleet-service -am verify`：通过；fleet 绑定的 `spotless:check` 同步通过。
+- 测试环境已部署 `hl-fleet-service@feat/fleet-team-management`，8087/8187 双实例健康。
+- 测试网关只读实测：车队分页、有效车队下拉、车辆分页均 HTTP/业务码 200；动态车队字段齐全，负责人电话列表脱敏。
+- 前端页面联调及 `hl-user-service` 菜单/删字典迁移：待前端完成动态车队与独立菜单页面后按发布顺序执行。
+
+> 本文是前端接入通知，不代表已修改或发布 `mmg/hl-ui`。

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

@@ -254,8 +254,9 @@ GET /admin/fleet/board/orders/{orderId}
 - `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,158 @@
+---
+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"
+---
+
+# 【修改接口·前端待处理·管理后台】车务派单候选筛选、分页与任意车辆选择
+
+> **服务**: 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` |
+| `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` 或车型不一致禁用车辆；这些情况应显示“需求不匹配/座位不足”提示，但允许车务选中。
+
+### 先选司机与取消车辆
+
+- 仅传 `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` 兜底。单量为司机历史累计，不按赛季清零。
+
+## 最终派单规则
+
+- 车型或座位不匹配：候选项仍可选，预检返回 warning，最终派单不阻断。
+- 档期冲突、车辆/司机不可用、黑名单或跨常驻未确认：仍按现有业务守卫阻断。
+- `strictSeats` 为历史兼容字段，可不再提交；即使提交 `true` 也不会把座位不足变成阻断。
+
+## 前端处理清单
+
+- [ ] 车辆和司机列表分别接 `records/total/page/pageSize` 并增加独立分页控件。
+- [ ] 车队和车型筛选使用 `fleetTeamFacets/vehicleTypeFacets` 动态渲染及计数。
+- [ ] 车辆行展示车型、常驻司机、协议参考价；需求车型或座位不匹配只醒目标记，不禁选。
+- [ ] 支持再次点击已选车辆取消选择，并传 `selectedVehicleId: null`。
+- [ ] 支持先选司机，并展示/置顶 `selectedDriverResidentVehicle`。
+- [ ] 司机无评价显示“暂无评价”，不伪造 `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`。