docs: 车队关联供应商并展示供应商全名（#6717） #83
@@ -0,0 +1,805 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "6717"
|
||||
title: "车队关联供应商并展示供应商全名"
|
||||
consumer: "admin"
|
||||
author: "wx(GIT)"
|
||||
change_type: "修改接口"
|
||||
backend_status: "deployed"
|
||||
gateway_status: "verified"
|
||||
frontend_status: "pending"
|
||||
frontend_owner: "mmg"
|
||||
frontend_ref: ""
|
||||
target_release: "v2.1"
|
||||
verified_at: "2026-08-30"
|
||||
status_note: "PR #6753 已合并 dev-v3（merge commit 447b92f5）；Deploy Panel 任务 2fe21f84（hl-fleet-service，2026-08-30 17:20）与 f29a293f（hl-resource-service，2026-08-30 17:22）均已部署测试服成功。真实 TEST 身份已验证 5 条负向链路全绿 + 列表字段结构正确，测试数据已清理。车队列表操作列的「供应商」按钮需下线，改为在车队新增/编辑弹窗选择供应商。"
|
||||
updated_at: "2026-08-30"
|
||||
base: "dev-v3"
|
||||
---
|
||||
|
||||
# 车队管理：车队关联供应商并展示供应商全名
|
||||
|
||||
> **存放目录**:
|
||||
> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/2026-08/`
|
||||
>
|
||||
> **服务**: hl-fleet-service（端口 8094）/ hl-resource-service（内部依赖）
|
||||
> **PR**: #6753
|
||||
> **Issue**: #6717
|
||||
> **日期**: 2026-08-30
|
||||
> **影响范围**: 管理后台「车辆管理 - 车队管理」列表/新增/编辑/启用
|
||||
|
||||
车队管理新增供应商归属字段（可空），供应商只能随车队新增/编辑一起提交，不再提供单独配置入口。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 关键变化
|
||||
|
||||
- 车队列表操作列的「供应商」按钮（`views/fleet/teams/index.vue` 弹窗 `SupplierResourceRelModal`）**需要下线**；供应商关联改为在车队新增/编辑弹窗里选择。
|
||||
- 「不选供应商不能启动，只能停用」：未关联供应商的车队调用启用接口会被 601108 拦截；新建时不选供应商则车队落停用态。
|
||||
- 已有订单（名下车辆存在非取消派单）的车队，**不允许更换或清除供应商**；允许首次绑定。
|
||||
|
||||
---
|
||||
|
||||
## 一、背景
|
||||
|
||||
车队此前没有供应商归属字段；供应商域（`supplier_main`，类型字典 `supplier_type`）已支持车队类型供应商（FLEET），但车队主数据与供应商档案之间未建立关联。工单 #6717 要求车队管理列表展示供应商全名，并在车队新增/编辑时明确供应商归属。
|
||||
|
||||
**最终口径（2026-08-30 用户确认，覆盖工单原文「必选」语义）**：
|
||||
|
||||
1. 供应商字段**不必填**（可选）；不选 → 不能启用，只能停用。
|
||||
2. 车队已有订单时，不允许**更换**或**清除**供应商（含已有订单的历史车队豁免存量，不动存量数据）。
|
||||
3. 去掉单独配置供应商接口入口：前端车队列表的「供应商」按钮下线；供应商关联只随车队新增/编辑一起提交。
|
||||
4. 供应商全名以**写时快照**存于 `fleet_team.supplier_name`；列表/详情零 Feign 读，供应商改名后陈旧、重新编辑可刷新。
|
||||
5. 供应商资格校验走跨服务 Feign（fleet → resource `GET /internal/supplier/{supplierId}/fleet-eligibility`）：主体存在 + 状态 ACTIVE + 类型关联含 FLEET。
|
||||
|
||||
---
|
||||
|
||||
## 二、变更接口清单
|
||||
|
||||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||||
|---|------|------|------|----------|------|
|
||||
| 1 | 分页查询车队 | GET | `/admin/fleet/teams/page` | 响应新增字段 | `records[]` 增加 `supplierId`(String/null) + `supplierName`(String/null) |
|
||||
| 2 | 查询车队详情 | GET | `/admin/fleet/teams/{fleetTeamId}` | 响应新增字段 | 同 #1 |
|
||||
| 3 | 新增车队 | POST | `/admin/fleet/teams` | 请求体新增可选字段 + 响应新增字段 | 请求体加 `supplierId`(Long 字符串/可空)；响应同 #2 |
|
||||
| 4 | 编辑车队 | PUT | `/admin/fleet/teams/{fleetTeamId}` | 请求体新增可选字段 + 响应新增字段 + 失败语义 | 请求体加 `supplierId`；更换/清除时已有订单被 601111 拦截；清除且当前 ACTIVE 会强制落 DISABLED |
|
||||
| 5 | 启用车队 | POST | `/admin/fleet/teams/{fleetTeamId}/enable` | 失败语义新增 | `supplierId==null` 时抛 601108「车队未关联供应商，不能启用」 |
|
||||
|
||||
---
|
||||
|
||||
## 三、接口详情
|
||||
|
||||
### 1. 分页查询车队 `GET /admin/fleet/teams/page`
|
||||
|
||||
**VO**: `FleetTeamPageReqVO` / `Result<PageResult<FleetTeamRespVO>>`
|
||||
|
||||
#### 使用场景
|
||||
|
||||
管理后台「车辆管理 - 车队管理」列表页加载时调用。供应商列新增展示。
|
||||
|
||||
#### 入参
|
||||
|
||||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||||
|------|------|------|------|------|------|
|
||||
| `page` | Query | Integer | 否 | ≥1，默认 1 | 页码 |
|
||||
| `pageSize` | Query | Integer | 否 | 1..100，默认 10 | 每页大小 |
|
||||
| `keyword` | Query | String | 否 | ≤64 | 车队名称/负责人姓名模糊搜索 |
|
||||
| `teamType` | Query | String | 否 | `SELF_OPERATED`/`COOPERATIVE` | 车队类型筛选 |
|
||||
| `status` | Query | String | 否 | `ACTIVE`/`DISABLED` | 状态筛选 |
|
||||
| `settleType` | Query | String | 否 | `cash`/`sign`/`company` | 付款方式筛选 |
|
||||
|
||||
#### 出参 `Result<PageResult<FleetTeamRespVO>>`
|
||||
|
||||
`records[]` 每一项 `FleetTeamRespVO` 字段（与改前相比只多两列，其余字段语义不变）：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `fleetTeamId` | String | 车队 ID（雪花序列化为字符串，禁止转 Number） |
|
||||
| `teamCode` | String | 内部稳定编码（`ft_xxx`） |
|
||||
| `teamName` | String | 车队名称 |
|
||||
| `teamType` | String | `SELF_OPERATED`/`COOPERATIVE` |
|
||||
| `leaderName` | String | 负责人姓名 |
|
||||
| `leaderPhone` | String | 负责人电话（**分页脱敏**：`138****8000`） |
|
||||
| `settleType` | String | `cash`/`sign`/`company` |
|
||||
| `status` | String | `ACTIVE`/`DISABLED` |
|
||||
| `sortOrder` | Integer | 排序值 |
|
||||
| `remark` | String | 备注 |
|
||||
| `vehicleCount` | Integer | 名下车辆总数（含停用） |
|
||||
| `activeVehicleCount` | Integer | 名下在役车辆数 |
|
||||
| **`supplierId`** | **String/null** | **关联供应商 ID（雪花字符串；未关联为 null）** |
|
||||
| **`supplierName`** | **String/null** | **关联供应商全称快照（写时同步，未关联为 null）** |
|
||||
| `createTime` | String | 创建时间 `yyyy-MM-dd HH:mm:ss` |
|
||||
| `updateTime` | String | 最后更新时间 `yyyy-MM-dd HH:mm:ss` |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```http
|
||||
GET /admin/fleet/teams/page?page=1&pageSize=10&status=ACTIVE
|
||||
Authorization: Bearer <admin-token>
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"success": true,
|
||||
"data": {
|
||||
"total": 2,
|
||||
"page": 1,
|
||||
"pageSize": 10,
|
||||
"records": [
|
||||
{
|
||||
"fleetTeamId": "2102345678901234567",
|
||||
"teamCode": "ft_2x9k3m",
|
||||
"teamName": "合作车队A",
|
||||
"teamType": "COOPERATIVE",
|
||||
"leaderName": "测试负责人甲",
|
||||
"leaderPhone": "138****0001",
|
||||
"settleType": "cash",
|
||||
"status": "ACTIVE",
|
||||
"sortOrder": 10,
|
||||
"remark": "由 fleet_attribution/历史业务数据迁移",
|
||||
"vehicleCount": 12,
|
||||
"activeVehicleCount": 9,
|
||||
"supplierId": "2091381911266967553",
|
||||
"supplierName": "内蒙古呼籁旅游服务有限公司",
|
||||
"createTime": "2026-06-01 10:00:00",
|
||||
"updateTime": "2026-08-30 15:30:00"
|
||||
},
|
||||
{
|
||||
"fleetTeamId": "2102345678901234568",
|
||||
"teamCode": "ft_2x9k3n",
|
||||
"teamName": "自有车队",
|
||||
"teamType": "SELF_OPERATED",
|
||||
"leaderName": "自有负责人",
|
||||
"leaderPhone": "139****0002",
|
||||
"settleType": "company",
|
||||
"status": "DISABLED",
|
||||
"sortOrder": 20,
|
||||
"remark": "",
|
||||
"vehicleCount": 0,
|
||||
"activeVehicleCount": 0,
|
||||
"supplierId": null,
|
||||
"supplierName": null,
|
||||
"createTime": "2026-08-01 09:00:00",
|
||||
"updateTime": "2026-08-30 15:30:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 空数据 / 降级响应
|
||||
|
||||
无车队时 `records=[]` `total=0`，`code=200`。供应商字段未关联时为 `null`（不是空串），前端按未关联渲染。
|
||||
|
||||
#### 错误响应
|
||||
|
||||
分页查询无业务错误分支。网关/框架错误：
|
||||
|
||||
```json
|
||||
{ "code": 401, "message": "未登录", "success": false, "data": null }
|
||||
```
|
||||
|
||||
#### 业务边界
|
||||
|
||||
- 只读查询；返回的 `supplierId`/`supplierName` 来自 `fleet_team.supplier_id/supplier_name` 列快照，不做实时跨服务取数。
|
||||
- 供应商改名后列表展示旧名（快照口径）；如需最新名称，让用户重新编辑车队保存触发刷新。
|
||||
- 车队停用车队（`status=DISABLED`）也可被列表查到（不带状态筛选时默认返回全部状态）。
|
||||
|
||||
---
|
||||
|
||||
### 2. 查询车队详情 `GET /admin/fleet/teams/{fleetTeamId}`
|
||||
|
||||
**VO**: `Result<FleetTeamRespVO>`
|
||||
|
||||
#### 使用场景
|
||||
|
||||
管理后台编辑车队弹窗初始化时调用，回填 `supplierId`/`supplierName` 到供应商选择器。
|
||||
|
||||
#### 入参
|
||||
|
||||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||||
|------|------|------|------|------|------|
|
||||
| `fleetTeamId` | Path | String(Long) | 是 | 正整数 ID 字符串 | 目标车队 ID（雪花，不得转 Number） |
|
||||
|
||||
#### 出参 `Result<FleetTeamRespVO>`
|
||||
|
||||
字段与 #1 `records[]` 项结构一致（含新增 `supplierId`/`supplierName`）：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `fleetTeamId` | String | 车队 ID（雪花序列化为字符串，禁止转 Number） |
|
||||
| `teamCode` | String | 内部稳定编码（`ft_xxx`） |
|
||||
| `teamName` | String | 车队名称 |
|
||||
| `teamType` | String | `SELF_OPERATED`/`COOPERATIVE` |
|
||||
| `leaderName` | String | 负责人姓名 |
|
||||
| `leaderPhone` | String | 负责人电话（**详情返回原值**，编辑场景回填用） |
|
||||
| `settleType` | String | `cash`/`sign`/`company` |
|
||||
| `status` | String | `ACTIVE`/`DISABLED` |
|
||||
| `sortOrder` | Integer | 排序值 |
|
||||
| `remark` | String | 备注 |
|
||||
| `vehicleCount` | Integer | 名下车辆总数（含停用） |
|
||||
| `activeVehicleCount` | Integer | 名下在役车辆数 |
|
||||
| `supplierId` | String/null | 关联供应商 ID（雪花字符串；未关联为 null） |
|
||||
| `supplierName` | String/null | 关联供应商全称快照（写时同步） |
|
||||
| `createTime` | String | 创建时间 `yyyy-MM-dd HH:mm:ss` |
|
||||
| `updateTime` | String | 最后更新时间 `yyyy-MM-dd HH:mm:ss` |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```http
|
||||
GET /admin/fleet/teams/2102345678901234567
|
||||
Authorization: Bearer <admin-token>
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"success": true,
|
||||
"data": {
|
||||
"fleetTeamId": "2102345678901234567",
|
||||
"teamCode": "ft_2x9k3m",
|
||||
"teamName": "合作车队A",
|
||||
"teamType": "COOPERATIVE",
|
||||
"leaderName": "测试负责人甲",
|
||||
"leaderPhone": "13800000001",
|
||||
"settleType": "cash",
|
||||
"status": "ACTIVE",
|
||||
"sortOrder": 10,
|
||||
"remark": "由 fleet_attribution/历史业务数据迁移",
|
||||
"vehicleCount": 12,
|
||||
"activeVehicleCount": 9,
|
||||
"supplierId": "2091381911266967553",
|
||||
"supplierName": "内蒙古呼籁旅游服务有限公司",
|
||||
"createTime": "2026-06-01 10:00:00",
|
||||
"updateTime": "2026-08-30 15:30:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 空数据 / 降级响应
|
||||
|
||||
车队不存在或已软删除（业务错误，见下方错误响应）；无空数据分支。
|
||||
|
||||
#### 错误响应
|
||||
|
||||
车队不存在或已软删除：
|
||||
|
||||
```json
|
||||
{ "code": 601100, "message": "车队不存在", "success": false, "data": null }
|
||||
```
|
||||
|
||||
未登录（网关拦截）：
|
||||
|
||||
```json
|
||||
{ "code": 401, "message": "未登录", "success": false, "data": null }
|
||||
```
|
||||
|
||||
#### 业务边界
|
||||
|
||||
- 详情接口返回 `leaderPhone` 为原值（编辑场景需要回填），分页接口脱敏。
|
||||
- `supplierId` 必须按字符串处理，禁止转 JavaScript Number。
|
||||
|
||||
---
|
||||
|
||||
### 3. 新增车队 `POST /admin/fleet/teams`
|
||||
|
||||
**VO**: `FleetTeamSaveReqVO` / `Result<FleetTeamRespVO>`
|
||||
|
||||
#### 使用场景
|
||||
|
||||
管理后台「车辆管理 - 车队管理」点击「新增车队」，在表单里可选填供应商。
|
||||
|
||||
#### 入参
|
||||
|
||||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||||
|------|------|------|------|------|------|
|
||||
| `teamName` | Body | String | 是 | ≤64，唯一 | 车队名称 |
|
||||
| `teamType` | Body | String | 是 | `SELF_OPERATED`/`COOPERATIVE` | 车队类型 |
|
||||
| `leaderName` | Body | String | 是 | ≤64 | 负责人姓名 |
|
||||
| `leaderPhone` | Body | String | 是 | 电话格式正则 | 负责人电话 |
|
||||
| `settleType` | Body | String | 是 | `cash`/`sign`/`company` | 付款方式 |
|
||||
| `sortOrder` | Body | Integer | 是 | ≥0 | 排序 |
|
||||
| `remark` | Body | String | 否 | ≤256 | 备注 |
|
||||
| **`supplierId`** | Body | **String(Long)/null** | **否** | **`@Positive`** | **关联供应商 ID（雪花字符串；不填=不选供应商，新建车队落 DISABLED）** |
|
||||
|
||||
#### 出参 `Result<FleetTeamRespVO>`
|
||||
|
||||
响应结构同 #2；`supplierId`/`supplierName` 按请求回填（选了供应商且校验通过则写入快照，否则为 null）。
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `fleetTeamId` | String | 新车队 ID（雪花序列化为字符串） |
|
||||
| `supplierId` | String/null | 按请求回填（选了且校验通过） |
|
||||
| `supplierName` | String/null | 写时同步的供应商全称快照；未选为 null |
|
||||
| `status` | String | 选供应商=`ACTIVE`；不选=`DISABLED` |
|
||||
| `createTime` | String | 创建时间 `yyyy-MM-dd HH:mm:ss` |
|
||||
| `updateTime` | String | 创建时间（与 createTime 相同） |
|
||||
| （其余字段） | - | 与详情 #2 同构 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```http
|
||||
POST /admin/fleet/teams
|
||||
Authorization: Bearer <admin-token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"teamName": "新合作车队B",
|
||||
"teamType": "COOPERATIVE",
|
||||
"leaderName": "王队长",
|
||||
"leaderPhone": "13800138000",
|
||||
"settleType": "sign",
|
||||
"sortOrder": 20,
|
||||
"remark": "新签约车队",
|
||||
"supplierId": "2091381911266967553"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"success": true,
|
||||
"data": {
|
||||
"fleetTeamId": "2103456789012345678",
|
||||
"teamCode": "ft_3a1b2c",
|
||||
"teamName": "新合作车队B",
|
||||
"teamType": "COOPERATIVE",
|
||||
"leaderName": "王队长",
|
||||
"leaderPhone": "13800138000",
|
||||
"settleType": "sign",
|
||||
"status": "ACTIVE",
|
||||
"sortOrder": 20,
|
||||
"remark": "新签约车队",
|
||||
"vehicleCount": 0,
|
||||
"activeVehicleCount": 0,
|
||||
"supplierId": "2091381911266967553",
|
||||
"supplierName": "内蒙古呼籁旅游服务有限公司",
|
||||
"createTime": "2026-08-30 16:00:00",
|
||||
"updateTime": "2026-08-30 16:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 空数据 / 降级响应
|
||||
|
||||
未选供应商创建（落 DISABLED，供应商字段为 null）：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"success": true,
|
||||
"data": {
|
||||
"fleetTeamId": "2103456789012345679",
|
||||
"teamCode": "ft_3a1b2d",
|
||||
"teamName": "临时车队",
|
||||
"teamType": "COOPERATIVE",
|
||||
"leaderName": "临时负责人",
|
||||
"leaderPhone": "13900139000",
|
||||
"settleType": "cash",
|
||||
"status": "DISABLED",
|
||||
"sortOrder": 30,
|
||||
"remark": "",
|
||||
"vehicleCount": 0,
|
||||
"activeVehicleCount": 0,
|
||||
"supplierId": null,
|
||||
"supplierName": null,
|
||||
"createTime": "2026-08-30 16:00:00",
|
||||
"updateTime": "2026-08-30 16:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
供应商不存在/未生效/不含车队类型（不写库）：
|
||||
|
||||
```json
|
||||
{ "code": 601109, "message": "供应商不存在、未生效或不包含车队类型", "success": false, "data": null }
|
||||
```
|
||||
|
||||
供应商校验依赖故障（Feign 不可用，不写库）：
|
||||
|
||||
```json
|
||||
{ "code": 601110, "message": "暂时无法校验供应商，请稍后重试", "success": false, "data": null }
|
||||
```
|
||||
|
||||
车队名称重复（`uk_fleet_team_name` 唯一索引兜底）：
|
||||
|
||||
```json
|
||||
{ "code": 601101, "message": "车队名称已存在", "success": false, "data": null }
|
||||
```
|
||||
|
||||
Bean Validation 校验失败：
|
||||
|
||||
```json
|
||||
{ "code": 400, "message": "供应商ID必须为正数", "success": false, "data": null }
|
||||
```
|
||||
|
||||
#### 业务边界
|
||||
|
||||
- 幂等：同一 teamName + 请求摘要 10 秒窗口内重复提交只生效一次（@Idempotent key=`fleet:team:create:{teamName}`）。
|
||||
- 分布式锁：同 teamName 创建串行化（@Lock4j）。
|
||||
- 选供应商时先 Feign 校验（事务外），通过后写库（事务内），Feign 失败/不合格一律不写库（失败关闭）。
|
||||
- 不写供应商时新建车队 status=DISABLED，需后续编辑绑定供应商后才能启用。
|
||||
|
||||
---
|
||||
|
||||
### 4. 编辑车队 `PUT /admin/fleet/teams/{fleetTeamId}`
|
||||
|
||||
**VO**: `FleetTeamSaveReqVO` / `Result<FleetTeamRespVO>`
|
||||
|
||||
#### 使用场景
|
||||
|
||||
管理后台编辑车队弹窗提交。可修改基础字段 + 供应商；**不允许修改 status**（启停用走独立接口）。
|
||||
|
||||
#### 入参
|
||||
|
||||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||||
|------|------|------|------|------|------|
|
||||
| `fleetTeamId` | Path | String(Long) | 是 | 正整数 ID 字符串 | 目标车队 ID（不得转 Number） |
|
||||
| （其余字段） | Body | String | 同新增 | 同新增 | 全字段提交（SaveReqVO 整体语义） |
|
||||
| `supplierId` | Body | String(Long)/null | 否 | `@Positive` | 供应商 ID；更换/清除受订单围栏 |
|
||||
|
||||
#### 出参 `Result<FleetTeamRespVO>`
|
||||
|
||||
同 #2；`supplierId`/`supplierName` 反映最新写入值。
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `fleetTeamId` | String | 车队 ID（路径回显） |
|
||||
| `supplierId` | String/null | 最新写入值（更换/清除后刷新） |
|
||||
| `supplierName` | String/null | 最新写入快照（更换时取新供应商 full_name；清除时为 null） |
|
||||
| `status` | String | 清除供应商且当前 ACTIVE 时强制落 `DISABLED`；其余场景不变 |
|
||||
| `updateTime` | String | 本次写入时间（秒级严格递增） |
|
||||
| （其余字段） | - | 与详情 #2 同构 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```http
|
||||
PUT /admin/fleet/teams/2102345678901234567
|
||||
Authorization: Bearer <admin-token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"teamName": "合作车队A",
|
||||
"teamType": "COOPERATIVE",
|
||||
"leaderName": "测试负责人甲",
|
||||
"leaderPhone": "13800000001",
|
||||
"settleType": "cash",
|
||||
"sortOrder": 10,
|
||||
"remark": "",
|
||||
"supplierId": "2091381911266967553"
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
成功（更换供应商且无订单）：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"success": true,
|
||||
"data": {
|
||||
"fleetTeamId": "2102345678901234567",
|
||||
"teamCode": "ft_2x9k3m",
|
||||
"teamName": "合作车队A",
|
||||
"teamType": "COOPERATIVE",
|
||||
"leaderName": "测试负责人甲",
|
||||
"leaderPhone": "13800000001",
|
||||
"settleType": "cash",
|
||||
"status": "ACTIVE",
|
||||
"sortOrder": 10,
|
||||
"remark": "",
|
||||
"vehicleCount": 12,
|
||||
"activeVehicleCount": 9,
|
||||
"supplierId": "2091381911266967553",
|
||||
"supplierName": "内蒙古呼籁旅游服务有限公司",
|
||||
"createTime": "2026-06-01 10:00:00",
|
||||
"updateTime": "2026-08-30 16:30:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 空数据 / 降级响应
|
||||
|
||||
清除供应商（原值 → null）且车队无订单：快照清空，若当前 ACTIVE 强制落 DISABLED（保持不变量：ACTIVE ⇒ 已绑供应商）。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"success": true,
|
||||
"data": {
|
||||
"fleetTeamId": "2102345678901234567",
|
||||
"teamCode": "ft_2x9k3m",
|
||||
"teamName": "合作车队A",
|
||||
"teamType": "COOPERATIVE",
|
||||
"status": "DISABLED",
|
||||
"supplierId": null,
|
||||
"supplierName": null,
|
||||
"updateTime": "2026-08-30 16:30:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
车队已有订单时更换/清除供应商（含从原供应商换到新供应商、从原供应商清为空）：
|
||||
|
||||
```json
|
||||
{ "code": 601111, "message": "车队已关联订单，不能更换供应商", "success": false, "data": null }
|
||||
```
|
||||
|
||||
供应商校验失败（同新增 #3 的 601109/601110）；车队不存在：
|
||||
|
||||
```json
|
||||
{ "code": 601100, "message": "车队不存在", "success": false, "data": null }
|
||||
```
|
||||
|
||||
#### 业务边界
|
||||
|
||||
- 幂等：同 fleetTeamId + 请求摘要（含 supplierId 参与摘要）10 秒窗口内重复提交只生效一次（@Idempotent key=`fleet:team:update:{fleetTeamId}:{sha256}`）。
|
||||
- 分布式锁：同 fleetTeamId 编辑串行化（@Lock4j）。
|
||||
- 更换供应商校验顺序：订单围栏（601111）→ Feign 资格校验（601109/601110）→ 写库。
|
||||
- 供应商不变时（含 null→null）不触发订单围栏，也不调 Feign。
|
||||
- 首次绑定（null → 新值）即使已有订单也允许。
|
||||
- `status` 不在 SaveReqVO，本接口不修改启停状态；清除供应商且当前 ACTIVE 时强制落 DISABLED 是唯一例外。
|
||||
|
||||
---
|
||||
|
||||
### 5. 启用车队 `POST /admin/fleet/teams/{fleetTeamId}/enable`
|
||||
|
||||
**VO**: `Result<Void>`
|
||||
|
||||
#### 使用场景
|
||||
|
||||
管理后台对已停用车队点击「启用」。
|
||||
|
||||
#### 入参
|
||||
|
||||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||||
|------|------|------|------|------|------|
|
||||
| `fleetTeamId` | Path | String(Long) | 是 | 正整数 ID 字符串 | 目标车队 ID |
|
||||
|
||||
#### 出参 `Result<Void>`
|
||||
|
||||
成功时 `data=null`：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | Integer | 恒为 `200` 表示成功 |
|
||||
| `data` | null | 启用接口无返回体 |
|
||||
|
||||
#### 空数据 / 降级响应
|
||||
|
||||
启用成功恒返回 `{"code":200,"success":true,"data":null}`；无空数据分支。已是启用态时幂等放行不重复写（返回同样结构）。
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```http
|
||||
POST /admin/fleet/teams/2102345678901234567/enable
|
||||
Authorization: Bearer <admin-token>
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{ "code": 200, "message": "成功", "success": true, "data": null }
|
||||
```
|
||||
|
||||
#### 错误响应
|
||||
|
||||
未关联供应商（新增语义）：
|
||||
|
||||
```json
|
||||
{ "code": 601108, "message": "车队未关联供应商，不能启用", "success": false, "data": null }
|
||||
```
|
||||
|
||||
已是启用态（幂等放行，不重复写）：
|
||||
|
||||
```json
|
||||
{ "code": 200, "message": "成功", "success": true, "data": null }
|
||||
```
|
||||
|
||||
车队不存在：`601100`。
|
||||
|
||||
#### 业务边界
|
||||
|
||||
- 幂等：同 fleetTeamId 重复调用只生效一次（@Idempotent key=`fleet:team:enable:{fleetTeamId}`）。
|
||||
- 分布式锁：同 fleetTeamId 启停用串行化（@Lock4j key=`fleet:team:status:{fleetTeamId}`）。
|
||||
- 存量迁移车队（own/coopA/coopB）当前 ACTIVE 且无供应商：enable 若已被置 DISABLED 后会被 601108 拦截，需先编辑绑定供应商再启用。
|
||||
|
||||
---
|
||||
|
||||
## 四、契约约束与正确调用方式
|
||||
|
||||
### ✅ 正确 / ❌ 错误 payload 对照
|
||||
|
||||
| 场景 | 调用 / 结果 |
|
||||
|---|---|
|
||||
| ✅ 新增时不选供应商 | `{ "supplierId": null }`（或不传）→ 车队落 DISABLED，待绑定后启用 |
|
||||
| ✅ 新增时选供应商 | `{ "supplierId": "2091381911266967553" }` → Feign 校验通过后落 ACTIVE |
|
||||
| ✅ 编辑时供应商不变 | 原 supplierId 原样传回（或省略由后端按原值处理？——必须原样传，SaveReqVO 整份语义） |
|
||||
| ✅ 首次绑定 | 原 supplierId=null，新 supplierId=有效 FLEET 供应商 → 允许（不受订单围栏） |
|
||||
| ✅ 供应商改名后刷新快照 | 重新编辑车队并保存（supplierId 原样），快照重新取最新 full_name |
|
||||
| ❌ 供应商 ID 转 Number | 雪花精度丢失；必须按字符串传输 |
|
||||
| ❌ 已有订单车队换供应商 | 601111，不写库 |
|
||||
| ❌ 已有订单车队清供应商 | 601111，不写库 |
|
||||
| ❌ 清除供应商后期望仍 ACTIVE | 无订单时快照清空+强制 DISABLED；前端收到 200 但 status=DISABLED 属于预期行为 |
|
||||
|
||||
### 关键提示（当前 TEST 构建）
|
||||
|
||||
- `supplierId`/`supplierName` 在所有响应中均按字符串序列化（`@JsonSerialize(ToStringSerializer)`）；**禁止**前端用 `Number()`/`parseInt()`/一元 `+` 转换。
|
||||
- 供应商全名快照为**写时取数**：`supplier_main.full_name` 改名后列表展示旧值，重新编辑车队保存触发刷新。
|
||||
- 供应商选择器数据源：可复用 `GET /admin/supplier/items/list?typeCode=FLEET&status=ACTIVE`（mmg 自查前端是否已有该接口封装；无则后端再补）。
|
||||
|
||||
---
|
||||
|
||||
## 五、数据库行为
|
||||
|
||||
- **写操作只影响 `fleet_team` 一行**（新增 insert / 编辑 update / 启停用 update），不跨服务写 `supplier_resource_rel` 或 `supplier_main`。
|
||||
- 快照列：`supplier_id`（关联 ID）+ `supplier_name`（全称快照）同列写入；清除时同列置 NULL。
|
||||
- 幂等窗口内重复请求只写一次；锁键串行化同车队写。
|
||||
- 迁移：`V20260830_001__add_supplier_to_fleet_team.sql` 对 `fleet_team` 加 `supplier_id BIGINT NULL` + `supplier_name VARCHAR(500) NULL` + 索引 `idx_fleet_team_supplier(supplier_id)`；存量车队两列均为 NULL。
|
||||
- 不动 `supplier_resource_rel`（车队供应商不走资源关系表；关系表仅用于九大资源模块）。
|
||||
|
||||
---
|
||||
|
||||
## 六、边界行为
|
||||
|
||||
- 未登录/登录失效：业务码 `401`（网关拦截）。
|
||||
- 车队不存在：`601100`。
|
||||
- 车队名称重复：`601101`（含 DuplicateKeyException 翻译）。
|
||||
- 车队已停用仍选该车：`601102`（既有口径，本工单不改）。
|
||||
- 车队下有在役车辆时禁止停用：`601103`（既有口径）。
|
||||
- 车队已关联车辆时禁止改自有/合作类型：`601104`（既有口径）。
|
||||
- 车队名下仍有车辆/司机时禁止删除：`601107`（既有口径）。
|
||||
- 车队未关联供应商禁止启用：`601108`（新增）。
|
||||
- 供应商不存在/未生效/不含车队类型：`601109`（新增）。
|
||||
- 供应商校验依赖故障：`601110`（新增，失败关闭不写库）。
|
||||
- 车队已有订单禁止更换/清除供应商：`601111`（新增）。
|
||||
- Bean Validation 校验失败：`400`。
|
||||
- 跨服务 Feign 不可用：写接口一律失败关闭（601110）；读接口（列表/详情）读快照列，不受影响。
|
||||
|
||||
---
|
||||
|
||||
## 六.5、枚举 / 数据字典
|
||||
|
||||
### `status`（车队启停状态）
|
||||
|
||||
**所属字段**: `FleetTeamRespVO.status` | **类型**: `String`
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `ACTIVE` | 启用 | 可被车辆选择；**前提：已关联供应商** |
|
||||
| `DISABLED` | 停用 | 不可被车辆选择；新建未选供应商时默认落此态 |
|
||||
|
||||
### `teamType`（车队类型）
|
||||
|
||||
**所属字段**: `FleetTeamSaveReqVO.teamType` / `FleetTeamRespVO.teamType` | **类型**: `String`
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `SELF_OPERATED` | 自有 | 自有车队 |
|
||||
| `COOPERATIVE` | 合作 | 合作车队 |
|
||||
|
||||
### `settleType`（付款方式，字典 `resource_settle_type`）
|
||||
|
||||
**所属字段**: `FleetTeamSaveReqVO.settleType` / `FleetTeamRespVO.settleType` | **类型**: `String`
|
||||
|
||||
| 值 | 中文 | 说明 |
|
||||
|----|------|------|
|
||||
| `cash` | 现付 | - |
|
||||
| `sign` | 挂账签单 | - |
|
||||
| `company` | 公司月结 | - |
|
||||
|
||||
---
|
||||
|
||||
## 六.6、修改前后对比
|
||||
|
||||
### 字段级对比
|
||||
|
||||
| 字段 | 改前 | 改后 |
|
||||
|------|------|------|
|
||||
| `FleetTeamSaveReqVO.supplierId` | 无 | 新增可选字段，@Positive，参与幂等摘要 |
|
||||
| `FleetTeamRespVO.supplierId` | 无 | 新增，String/null（ToStringSerializer） |
|
||||
| `FleetTeamRespVO.supplierName` | 无 | 新增，String/null（快照） |
|
||||
|
||||
### 行为级对比
|
||||
|
||||
| 行为 | 改前 | 改后 |
|
||||
|------|------|------|
|
||||
| 新建车队默认状态 | ACTIVE | 选供应商=ACTIVE；不选=DISABLED |
|
||||
| 启用校验 | 只查当前状态 | 增加 supplierId==null → 601108 |
|
||||
| 编辑车队供应商 | 无此字段 | 有订单禁换/禁清（601111）；清除+ACTIVE→强制 DISABLED |
|
||||
| 供应商配置入口 | 前端有独立「供应商」按钮（调通用资源关系接口） | 下线；改为车队新增/编辑内嵌选择 |
|
||||
|
||||
---
|
||||
|
||||
## 六.7、影响评估
|
||||
|
||||
- **是否破坏向后兼容**: 否（新增可选字段；响应只多两列，前端旧版忽略即兼容）
|
||||
- **前端是否必须同步上线**: 是（车队列表「供应商」按钮需下线，否则用户仍能从旧入口调通用接口——但通用接口对车队模块本工单起后端侧保留不拦，是前端入口下线）
|
||||
- **前端 workaround 清理点**: 车队列表的「供应商」操作入口（`views/fleet/teams/index.vue` 中 `supplierRelaShow`/`supplierRelaRow`/`openSupplierRelation` 相关代码）整体删除
|
||||
|
||||
---
|
||||
|
||||
## 七、不影响范围
|
||||
|
||||
- **仅影响**: 管理后台「车辆管理 - 车队管理」列表/新增/编辑/启用 4 个端点 + 详情 1 个端点。
|
||||
- **零影响**:
|
||||
- 车辆档案（`fleet_vehicle`）/ 司机档案（`fleet_driver`）/ 派单（`fleet_assignment`）等车队下游域——它们继续经 `FleetTeamService.resolveForVehicle` 解析车队，供应商字段不影响车辆选车队。
|
||||
- 供应商域九大资源模块（景区/餐厅/备品/组合/游玩项目/酒店/服务/额外成本/服务人员/车辆）的独立供应商关系维护（`/admin/supplier/resource-relations/{module}/{id}/update` 等通用接口保留不动）。
|
||||
- 订单/对账/看板读路径（只读 fleet_team 既有字段，新增两列不影响）。
|
||||
- Gateway 路由（`/admin/fleet/**` 通配已覆盖；`/internal/**` 不走网关）。
|
||||
- Redis/MQ（无新增 key/消息）。
|
||||
|
||||
---
|
||||
|
||||
## 八、测试环境已验证
|
||||
|
||||
真实 TEST 环境实测（2026-08-30，网关 `https://api.test.1814.love:9443`，admin token 走 `/admin/auth/login`）：
|
||||
|
||||
```
|
||||
POST /admin/fleet/teams 无供应商新建 → 200, status=DISABLED, supplierId=null, supplierName=null ✓
|
||||
POST /admin/fleet/teams/{id}/enable 无供应商启用 → 601108「车队未关联供应商，不能启用」 ✓
|
||||
PUT /admin/fleet/teams/{id} 绑定 DRAFT 供应商 → 601109 ✓
|
||||
PUT /admin/fleet/teams/{id} 绑定不存在供应商 → 601109 ✓
|
||||
PUT /admin/fleet/teams/{id} 绑定非 FLEET 类型 ACTIVE 供应商（RESTAURANT） → 601109 ✓
|
||||
GET /admin/fleet/teams/page → records[] 含 supplierId/supplierName 键（未关联为 null） ✓
|
||||
```
|
||||
|
||||
- 部署：Deploy Panel 任务 `2fe21f84`（hl-fleet-service，2026-08-30 17:20 success）+ `f29a293f`（hl-resource-service，2026-08-30 17:22 success），预期/实际提交均为 `447b92f5143e9ca4381d590d4f868d518cf66e0a`（dev-v3 HEAD）。
|
||||
- 正向链路（绑定合格 FLEET ACTIVE 供应商 → ACTIVE + 快照写 supplierName）：测试服当前无 ACTIVE 状态的 FLEET 类型供应商（供应商审批链要求必备资质，`supplier_type_qualification_rule` 规则表为空，无法造出合格供应商）；该路径本地单测已覆盖（`FleetTeamServiceTest#create_withEligibleSupplier_activeAndSnapshot` 等 24 用例全绿），建议 mmg 联调时在真实数据上补验。
|
||||
- 有订单换供应商（601111）链路：测试服车队均无订单派单可安全构造验证数据，本地单测覆盖（`FleetTeamServiceTest#update_changeSupplierWithOrders_rejected` / `update_clearSupplierWithOrders_rejected`）。
|
||||
- 本地自动化：fleet 全量 3883 项 0 失败 0 错误（含 FleetRedLineArchTest 13 项门禁）；resource 全量 0 失败 0 错误；spotless:check 绿。
|
||||
- 数据清理：测试车队（352385968453586944）与测试供应商（2093993745543299074）均已删除；未触碰同事真实订单；admin token 已登出。
|
||||
|
||||
---
|
||||
|
||||
## 九、相关历史 PR
|
||||
|
||||
| PR | Issue | 说明 | 是否仍有效 |
|
||||
|----|-------|------|------------|
|
||||
| #6753 | #6717 | 车队关联供应商并展示供应商全名（本次） | ✅ 最新 |
|
||||
|
||||
---
|
||||
|
||||
## 十、相关文档
|
||||
|
||||
- 关联 Issue: [wx/HL#6717](https://git.1814.love:8443/wx/HL/issues/6717)
|
||||
- 关联 PR: [wx/HL#6753](https://git.1814.love:8443/wx/HL/pulls/6753)
|
||||
- 任务设计文档: `docs/tasks/6717-fleet-team-supplier.md`（worktree `D:\work2\HL-v3-0830-fleetsup`）
|
||||
|
||||
## 撤回
|
||||
|
||||
1. 管理端先恢复车队列表「供应商」操作入口（参照改前版本），保持线上可用。
|
||||
2. 从最新 `dev-v3` 建独立回退分支，回退 PR #6753 的合并 commit（`72c9018ab` 及其后续如有），验证后经独立 PR 合入。
|
||||
3. 仅需下线新供应商字段时可先保留两列（快照保留无副作用），只回退 Controller/Service 逻辑与 Feign 校验。
|
||||
4. 使用 Deploy Panel 滚动部署 `hl-fleet-service` 与 `hl-resource-service`；数据库列保留不删（`supplier_id`/`supplier_name` 允许 NULL，回退后不影响）。
|
||||
5. 撤回后经 Gateway 验证新增/编辑/启用接口按改前口径通过；车队列表的供应商列展示空白或下线列头。
|
||||
|
||||
## 关联 / 联系人
|
||||
|
||||
### 链接
|
||||
|
||||
- **Issue**: [#6717](https://git.1814.love:8443/wx/HL/issues/6717)
|
||||
- **PR**: [#6753](https://git.1814.love:8443/wx/HL/pulls/6753)
|
||||
- **Merge commit**: 待合并后回填
|
||||
|
||||
### 联系人
|
||||
|
||||
- **后端负责人**: @wx
|
||||
- **前端联动**: @mmg（下线车队列表「供应商」按钮 + 车队新增/编辑弹窗加供应商选择器）
|
||||
在新工单中引用
屏蔽一个用户