docs(api): 交接保险任务与派单候选团号契约 (#5374) #71
@ -0,0 +1,203 @@
|
|||||||
|
---
|
||||||
|
schema: "hl-changelog/v2"
|
||||||
|
ticket: "5374"
|
||||||
|
title: "保险任务与派单候选补齐真实团号契约"
|
||||||
|
consumer: "admin"
|
||||||
|
change_type: "修改接口"
|
||||||
|
backend_status: "pending"
|
||||||
|
gateway_status: "pending"
|
||||||
|
frontend_status: "pending"
|
||||||
|
frontend_owner: ""
|
||||||
|
frontend_ref: ""
|
||||||
|
target_release: ""
|
||||||
|
verified_at: ""
|
||||||
|
status_note: "后端 PR #5415 已创建；MySQL 8 门禁通过，等待合并、测试部署与网关验证"
|
||||||
|
updated_at: "2026-08-02"
|
||||||
|
base: "dev-v3"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Fleet：保险任务与派单候选补齐真实团号契约
|
||||||
|
|
||||||
|
> **服务**: hl-fleet-service (端口 8087)
|
||||||
|
> **PR**: [wx/HL#5415](https://git.1814.love:8443/wx/HL/pulls/5415)
|
||||||
|
> **Issue**: [wx/HL#5374](https://git.1814.love:8443/wx/HL/issues/5374)
|
||||||
|
> **日期**: 2026-08-02
|
||||||
|
> **影响范围**: 管理后台车务保险任务列表与派单候选冲突提示
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一、关键变化
|
||||||
|
|
||||||
|
- 保险任务列表新增独立 `teamNo` 团号 contains 查询，并在任务项返回真实 `teamNo`。
|
||||||
|
- 派单候选的车辆、司机冲突快照新增真实 `teamNo`。
|
||||||
|
- 无团号统一返回 `null`，**禁止回退或伪装为 `orderNo`**；现有订单号和雪花 ID 字符串序列化契约不变。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 变更接口
|
||||||
|
|
||||||
|
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||||||
|
|---|---|---|---|---|---|
|
||||||
|
| 1 | 司机险任务/流水分页 | GET | `/admin/fleet/insurance/tasks` | 请求与响应字段新增 | 新增 `teamNo` 查询及任务团号 |
|
||||||
|
| 2 | 派单车辆/司机候选 | POST | `/admin/fleet/assignments/candidates` | 嵌套响应字段新增 | 两类 `conflicts[]` 新增真实团号 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、接口详情
|
||||||
|
|
||||||
|
### 1. 司机险任务/流水分页 `GET /admin/fleet/insurance/tasks`
|
||||||
|
|
||||||
|
**请求 VO**: `FleetInsuranceTaskPageReqVO`
|
||||||
|
|
||||||
|
#### 新增入参
|
||||||
|
|
||||||
|
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||||||
|
|---|---|---|---|---|---|
|
||||||
|
| `teamNo` | Query | String | 否 | contains 模糊匹配 | 只搜索团号；不会 OR 匹配订单号；过滤在分页前完成 |
|
||||||
|
|
||||||
|
#### 新增出参 `Result<PageResult<FleetInsuranceTaskRespVO>>`
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| `data.records[].teamNo` | `String|null` | 保险任务冻结的真实团号快照；无团号返回 `null` |
|
||||||
|
|
||||||
|
请求示例：
|
||||||
|
|
||||||
|
```http
|
||||||
|
GET /admin/fleet/insurance/tasks?teamNo=2607&page=1&pageSize=20
|
||||||
|
```
|
||||||
|
|
||||||
|
响应字段示例：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"records": [
|
||||||
|
{
|
||||||
|
"taskId": "9007199254740993",
|
||||||
|
"orderId": "9007199254740995",
|
||||||
|
"orderNo": "26-0701",
|
||||||
|
"teamNo": "HL-2607-001"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 1,
|
||||||
|
"page": 1,
|
||||||
|
"pageSize": 20
|
||||||
|
},
|
||||||
|
"success": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 派单车辆/司机候选 `POST /admin/fleet/assignments/candidates`
|
||||||
|
|
||||||
|
**响应 VO**: `AssignmentCandidateRespVO.ConflictVO`
|
||||||
|
|
||||||
|
#### 新增出参
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| `data.vehicles.records[].conflicts[].teamNo` | `String|null` | 冲突派单的 Fleet 本地真实团号快照 |
|
||||||
|
| `data.vehicles.list[].conflicts[].teamNo` | `String|null` | `records` 的兼容序列化别名，字段一致 |
|
||||||
|
| `data.drivers.records[].conflicts[].teamNo` | `String|null` | 冲突派单的 Fleet 本地真实团号快照 |
|
||||||
|
| `data.drivers.list[].conflicts[].teamNo` | `String|null` | `records` 的兼容序列化别名，字段一致 |
|
||||||
|
|
||||||
|
响应片段：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"vehicles": {
|
||||||
|
"records": [
|
||||||
|
{
|
||||||
|
"vehicleId": "101",
|
||||||
|
"conflicts": [
|
||||||
|
{
|
||||||
|
"assignmentId": "9001",
|
||||||
|
"assignmentGroupId": "9101",
|
||||||
|
"orderNo": "26-0701",
|
||||||
|
"teamNo": "HL-2607-001",
|
||||||
|
"blocking": true,
|
||||||
|
"reasonCode": "ASSIGNMENT_CONFLICT"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"drivers": {
|
||||||
|
"records": [
|
||||||
|
{
|
||||||
|
"driverId": "201",
|
||||||
|
"conflicts": [
|
||||||
|
{
|
||||||
|
"assignmentId": "9001",
|
||||||
|
"assignmentGroupId": "9101",
|
||||||
|
"orderNo": "26-0701",
|
||||||
|
"teamNo": null,
|
||||||
|
"blocking": true,
|
||||||
|
"reasonCode": "ASSIGNMENT_CONFLICT"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、契约约束与正确调用方式
|
||||||
|
|
||||||
|
- 前端展示团号必须读取 `teamNo`；值为 `null` 时展示 `-`。
|
||||||
|
- 不得把 `orderNo` 当作团号回退值。
|
||||||
|
- `orderNo`、`orderId`、`assignmentId`、`assignmentGroupId` 继续保留；雪花 ID 继续按 JSON String 返回，用于路由和动作。
|
||||||
|
- `teamNo` 只增加展示与查询能力，不改变候选 `available`、`blocking`、同城首尾衔接、可用窗口或派单写侧锁内复核。
|
||||||
|
- 保险任务查询的 `teamNo` 是独立参数，不沿用派车看板兼容匹配订单号的既有语义。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、数据库行为
|
||||||
|
|
||||||
|
- `fleet_insurance_task.team_no VARCHAR(32) NULL` 与 `fleet_assignment.team_no` 对齐。
|
||||||
|
- nullable DDL 与历史回填 DML 使用两个独立 Flyway 版本。
|
||||||
|
- 历史数据仅按 `assignment_id` 从 `fleet_assignment.team_no` 回填。
|
||||||
|
- 无匹配派单、来源团号为空或任务已有非空团号时保持原值；不跨服务查询、不按订单号猜测。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、边界行为
|
||||||
|
|
||||||
|
- `teamNo` 完整或部分关键词均按 contains 命中。
|
||||||
|
- 只有 `orderNo` 含关键词而 `teamNo` 不含时，不命中保险任务列表。
|
||||||
|
- 历史任务或冲突派单没有团号时，响应字段为 `null`，接口不异常。
|
||||||
|
- 空 `teamNo` 等同不启用该筛选；其他现有筛选条件与其按 AND 组合。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 七、不影响范围
|
||||||
|
|
||||||
|
- 不修改派车矩阵、甘特、车务工作台或派车看板字段与搜索语义。
|
||||||
|
- 不修改司机档案 `relatedOrders`。
|
||||||
|
- 不新增 order-v3 Feign，不修改 `hl-common-feign`、内部接口或共享 Java DTO。
|
||||||
|
- 不修改 `hl-ui`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 验证证据
|
||||||
|
|
||||||
|
- 定向测试：226 项通过，0 failures、0 errors、0 skipped。
|
||||||
|
- Fleet Spotless：通过。
|
||||||
|
- JaCoCo changed executable lines：9/9（100%）。
|
||||||
|
- 独立 Reviewer(max)：无 P0–P2。
|
||||||
|
- oasdiff：项目缺少可复现 Swagger 2 → OAS3 转换链，标记 `not_configured`；已完成源码级手工契约对比。
|
||||||
|
- MySQL 8.0.33 隔离实例：`FleetInsuranceTaskTeamNoMysqlTest` 3/3 通过，0 skipped；H2 全迁移回归 `FleetInsuranceTaskMigrationTest` 8/8 通过。
|
||||||
|
- Fleet 全模块 `verify` 已执行 2764 项；本工单迁移兼容缺陷修复后，仅余 6 项既有环境/并发测试失败（Redis 不可达 4 项、Release E 时序 1 项、保险并发夹具 1 项），未将该次命令记为通过。
|
||||||
|
- 测试部署及网关真实 round-trip 结果将在后端完成后更新本文件元数据与本节。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 九、前端消费动作
|
||||||
|
|
||||||
|
1. 保险任务列表筛选增加 `teamNo` 参数，并按 `data.records[].teamNo` 展示团号。
|
||||||
|
2. 派单候选的车辆/司机冲突提示改用各自 `conflicts[].teamNo` 展示团号。
|
||||||
|
3. `teamNo === null` 时展示 `-`，不得显示 `orderNo` 作为替代团号。
|
||||||
|
4. 保留现有 ID 与订单号用于路由、动作及兼容逻辑。
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户