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

schema, ticket, title, consumer, backend, gateway, frontend, base, generated

schema	ticket	title	consumer	backend	gateway	frontend	base	generated
hl-changelog/v1	5131	车队独立管理及车队字典下线	admin	verified	pending	pending	dev-v3	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	启用

保存请求：

{
  "teamName": "合作车队一队",
  "teamType": "COOPERATIVE",
  "leaderName": "张三",
  "leaderPhone": "13800138000",
  "settleType": "sign",
  "sortOrder": 20,
  "remark": "旺季合作车队"
}

下拉响应项：

{
  "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 迁移会精确删除：

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 同步通过。
• 测试环境网关联调：待前端完成动态车队与独立菜单页面后按发布顺序执行。

本文是前端接入通知，不代表已修改或发布 mmg/hl-ui。