bae6a58183
所有检测均成功
changelog-filename-gate / validate (push) Successful in 1s
修改原因：hl-ui changelog loop 需要把前端消费进度回写到契约源，避免领取、实现状态与实际交付脱节。 修改内容：将 frontend_status 与已有 legacy frontend 同步为 implemented，记录负责人 hl-ui-codex，并关联 mmg/hl-ui@ac4d5fd6292b13eb504f5393dfe07781800b9233；发布和验收字段保持不变。 实际验证：回写器已校验目标文件、状态单调性、提交范围和 Front Matter 内容，提交只包含当前 changelog。 Frontend-Status: tools/mcp-api-sync/.changelog-repo/changelogs-v2/2026-07/5131-fleet-team-management.md
239 行
13 KiB
Markdown
239 行
13 KiB
Markdown
---
|
||
schema: "hl-changelog/v1"
|
||
ticket: "5131"
|
||
title: "车队独立管理及车队字典下线"
|
||
consumer: "admin"
|
||
backend: "verified"
|
||
gateway: "verified"
|
||
frontend: "implemented"
|
||
frontend_status: "implemented"
|
||
frontend_owner: "hl-ui-codex"
|
||
frontend_ref: "mmg/hl-ui@ac4d5fd6292b13eb504f5393dfe07781800b9233"
|
||
updated_at: "2026-07-25T01:18:23.686Z"
|
||
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` | 编辑 |
|
||
| DELETE | `/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` 当特殊业务编码。
|
||
|
||
历史字典迁入的车队可能没有负责人资料。新增、编辑请求中的 `leaderName`、`leaderPhone`、
|
||
`settleType`、`sortOrder` 均为必填；前端编辑存量车队时必须提示车务人员补录真实资料，禁止用占位姓名或虚假电话自动填充。
|
||
|
||
## 独立菜单与权限
|
||
|
||
user-service 在“车务管理”目录下新增子菜单：
|
||
|
||
- 路由：`/fleet/teams`
|
||
- 组件：`fleet/teams/index`
|
||
- 权限：`fleet:team:list`、`fleet:team:create`、`fleet:team:update`、`fleet:team:status`、`fleet:team:delete`
|
||
- 默认角色：`SUPER_ADMIN`、`ADMIN`、`VEHICLE_MANAGER`
|
||
|
||
前端必须新增对应组件，否则菜单发布后会出现空路由。
|
||
|
||
## 前端必须修改的范围
|
||
|
||
### 2026-07-24 页面复测反馈：列表列宽与暗色模式
|
||
|
||
测试环境 `/fleet/teams` 页面已经能展示负责人和脱敏电话，但当前样式仍需前端修正，本反馈不涉及后端接口或字段变化：
|
||
|
||
1. 表格列宽分配失衡。“车队名称”列占用过多空白，把“负责人 / 负责人电话”等核心联系人信息推到页面右侧，首屏信息密度过低。
|
||
2. 暗色模式不能只替换页面背景。当前筛选区、表头、行分隔线、空值、状态标签和操作区的层级与对比度不足，部分边界难以辨认。
|
||
3. 样式必须复用项目主题 token；禁止在本页写死仅适用于浅色模式的背景色、文字色或边框色。负责人电话仍只展示接口返回的脱敏值，样式调整不得绕过脱敏。
|
||
|
||
#### 展示矩阵
|
||
|
||
| 视口 / 主题 | 车队名称 | 负责人 / 负责人电话 | 其他列 | 验收表现 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `>= 1440px`，浅色 | 弹性列，限制最大占比；超长省略并可查看完整名称 | 建议分别保留约 `120px / 140px`，左对齐 | 类型、付款方式、数量、排序、状态和操作按内容定宽 | 联系人紧邻业务字段，首屏无大段无意义空白 |
|
||
| `>= 1440px`，暗色 | 同浅色列宽规则 | 同浅色列宽规则 | 使用暗色主题 token | 页面、筛选区、表头、数据行、状态标签和操作区层级清楚 |
|
||
| `1024px - 1439px`，浅色/暗色 | 优先收缩并省略，不能无限占宽 | 不压缩为空或挤出主要阅读区 | 保留操作列可用宽度 | 联系人信息仍可直接阅读 |
|
||
| `< 1024px`，浅色/暗色 | 设置表格最小宽度 | 保持可读宽度 | 允许横向滚动 | 不通过隐藏关键列或强行挤压完成适配 |
|
||
|
||
空负责人和空电话统一显示 `—`。联系人文本左对齐；车辆数、排序、状态和操作居中。浅色与暗色模式都必须覆盖默认、悬停、聚焦、禁用和空数据状态；普通文本与背景建议至少达到 `4.5:1` 对比度，控件边界和状态提示应清晰可辨。
|
||
|
||
### 管理后台
|
||
|
||
1. 新增 `src/api/fleet/teams.js` 和 `src/views/fleet/teams/index.vue`，完成车队分页、新增、编辑、启停和删除：
|
||
- “车队管理”必须显示在“车务管理”目录内，不得作为一级菜单处理。
|
||
- 按上面的展示矩阵修正表格列宽和明暗主题样式，不能让“车队名称”列挤占联系人信息区域。
|
||
- 仅 `vehicleCount === 0` 时展示/启用删除动作；调用删除接口后刷新列表。
|
||
- 后端仍会独立校验车辆及未完结司机录入关联，返回 `601107` 时提示“请先完成车辆/司机转移”。
|
||
- 编辑历史迁入车队时补齐负责人、负责人电话、付款方式和排序。
|
||
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` 车辆时禁止停用，须先转移或停用车辆。
|
||
- 车队只有在名下无车辆、无未完结司机自助录入时才能删除；正式司机通过常驻车辆归属，车辆未转移时删除同样会被拒绝（`601107`）。
|
||
- 停用车队的存量车辆不得恢复在役，也不会进入派车候选或矩阵。
|
||
- 对账保存车队名称、类型和付款方式快照，后续改主档不修改历史账期。
|
||
- 负责人电话属于敏感信息，列表只展示脱敏值，不得写日志或进入前端埋点。
|
||
|
||
## 验收清单
|
||
|
||
- [ ] 独立车队菜单可分页、新增、编辑、启停，付款方式与资源页选项一致。
|
||
- [ ] `/fleet/teams` 在桌面端不再由“车队名称”列制造大段空白，负责人和脱敏电话位于首屏连续阅读区；窄屏按展示矩阵滚动而不是隐藏或挤压关键列。
|
||
- [ ] `/fleet/teams` 的浅色、暗色模式均使用主题 token，筛选区、表头、数据行、空值、状态标签和操作区在默认/悬停/聚焦/禁用状态下层级清晰。
|
||
- [ ] “车队管理”位于“车务管理”目录下；空车队可删除，非空车队删除入口禁用或明确提示后端 `601107`。
|
||
- [ ] 历史迁入车队可通过编辑补齐负责人、负责人电话、付款方式和排序，保存时不允许提交空资料。
|
||
- [ ] 车辆新增/编辑/筛选/详情/导入均使用动态车队，不再出现固定三项。
|
||
- [ ] 司机 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`。
|