wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

#8068 派单操作时间线新增软清记录留痕 #85

已关闭
wx 请求将 1 次代码提交从 pr-8068 合并至 main
拉取从: pr-8068
合并到: :main
对话内容 1 代码提交 1 文件变动 1
+414
共修改 1 个文件，包含 414 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
仅显示提交 75bfc39db2 的更改 - 显示所有提交
changelogs-v2/2026-09/21_8068_车务手动软清派车行记录留痕-修改接口-管理后台.md
+414
查看文件
@@ -0,0 +1,414 @@
---
schema: "hl-changelog/v2"
ticket: "8068"
title: "派单操作时间线新增软清记录留痕"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: ""
updated_at: "2026-09-21"
base: "dev-v3"
---
# fleet: 派单操作时间线新增软清记录留痕
> **存放目录**: `changelogs-v2/2026-09/`
>
> **服务**: hl-fleet-service (端口 8003)
> **PR**: #8113
> **Issue**: #8068
> **日期**: 2026-09-21
> **影响范围**: 车务手动派车清空链路；派单操作时间线接口返回的操作记录
---
## ⚠️ 关键变化
车务手动软清派车行（清空所选行的车辆/司机），以前在 `fleet_assignment` 表直接清空不留痕迹。现已补齐写口留痕：`fleet_assignment_operation_log` 新增 `soft_cleared` 操作类型。
**前端影响**：派单看板订单卡片「查看日志」时间线会新增这类记录。如果前端按 `operation_type` 做了白名单过滤，`soft_cleared` 需要加进去——不加会静默漏渲染。
---
## 一、背景
软清是车务人员在派车界面一次性清空多个选中行的车辆/司机字段，状态置回「待改派」。此前的实现直接 UPDATE 字段不写日志，导致事后无法查证「是谁、什么时候、清掉了哪个司机/哪台车」（工单 #8051 #8068 提及）。
本次补齐留痕机制：每次软清都在 `fleet_assignment_operation_log` 写一行，记录被清空前的身份快照及操作范围。
---
## 二、变更接口清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 派单操作时间线 | GET | `/admin/fleet/orders/{orderId}/operation-log` | 响应新增操作类型 | 新增 `soft_cleared` 枚举值 + `detail_json` 字段扩展 |
---
## 三、接口详情
### 1. 派单操作时间线 `GET /admin/fleet/orders/{orderId}/operation-log`
**VO**: `FleetOperationLogItemVO → FleetOrderOperationLogRespVO`
#### 使用场景
车务在派车看板订单卡片内点「查看日志」，实时呈现该订单全部派车操作的不可变时间线。新操作类型 `soft_cleared` 会在此时间线中出现。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| orderId | Path | Long | ✅ | 雪花 ID | 订单 ID |
| page | Query | Integer | ❌ | 默认 1，上限 100000 | 分页页码 |
| pageSize | Query | Integer | ❌ | 默认 50，上限 200 | 每页条数 |
| sortBy | Query | String | ❌ | 支持 `time,asc` | 排序字段，默认 create_time 倒序 |
#### 出参 `Result<FleetOrderOperationLogRespVO>`
| 字段 | 类型 | 说明 |
|------|------|------|
| data.records | List<FleetOperationLogItemVO> | 当前页操作日志行 |
| data.records[].id | String | 日志行 ID（雪花号，以字符串返回防精度丢失） |
| data.records[].time | LocalDateTime | 操作时间（ISO 8601 格式） |
| data.records[].opType | String | 操作类型英文枚举值，**含新增的 `soft_cleared`** |
| data.records[].opTypeLabel | String | 操作类型中文标签（由后端从枚举翻译） |
| data.records[].summary | String | 可读摘要（后端拼接：操作人 + 动作 + 前后值对比） |
| data.records[].operatorName | String | 操作人（企微名优先，无则用户名，系统动作显示「系统」） |
| data.records[].effectiveDate | LocalDate | 生效日期（按天改派等动作有值，无则 null） |
| data.records[].detailJson | String | 明细 JSON，格式见下节 |
| data.total | Long | 总条数 |
| data.page | Integer | 当前页码 |
| data.pageSize | Integer | 本页条数 |
#### 新增字段详情
**`opType` 新增枚举值**
| 值 | 中文标签 | 触发场景 |
|----|----------|---------|
| `soft_cleared` | 清空司机/车辆 | 车务在派车界面手动清空选中行的车辆/司机字段 |
**`detailJson` 字段（当 `opType="soft_cleared"` 时）**
响应的 `detailJson` 是字符串化的 JSON，结构如下（示例已脱敏保留字段结构）：
```json
{
"scope": "GROUP",
"assignmentGroupId": "360380081354444801",
"statusBefore": "assigned",
"clearedRowCount": 1,
"vehicleIdBefore": "2085539421276286978",
"driverIdBefore": "2067084362829979650",
"vehiclePlateSnapshot": "蒙A-E2E99",
"driverNameSnapshot": "王信",
"clearedRows": [
{
"assignmentId": "2101990265092984833",
"serviceDate": "2026-12-22",
"vehicleIdBefore": "2085539421276286978",
"vehiclePlateBefore": "蒙A-E2E99",
"driverIdBefore": "2067084362829979650",
"driverNameBefore": "王信"
}
]
}
```
字段说明：
| 字段 | 类型 | 说明 |
|------|------|------|
| scope | String | 清空范围，`GROUP` 表示按派车组（团期）整组清空 |
| assignmentGroupId | String | 派车组 ID（字符串格式，防雪花 ID 过 JS 掉精度） |
| statusBefore | String | 清空前状态，通常为 `assigned`（已派车） |
| clearedRowCount | Integer | 本次清空涉及的派车行数 |
| vehicleIdBefore | String | **清空前的车辆 ID**（19 位雪花号，字符串返回） |
| driverIdBefore | String | **清空前的司机 ID**（19 位雪花号，字符串返回） |
| vehiclePlateSnapshot | String | 清空前的车牌号（可读值快照，用于日志展示） |
| driverNameSnapshot | String | 清空前的司机名（可读值快照，用于日志展示） |
| clearedRows | Array | 本次清空涉及的所有派车行详情，每行包含 assignmentId / serviceDate / 清空前的车辆/司机 ID 与车牌/司机名 |
**关键说明：所有 ID 字段都以字符串返回**
派车 ID、司机 ID、车辆 ID 等均采用字符串格式。**这很重要**：JavaScript 的 `Number` 类型只能精确表示到 16 位数字，而雪花 ID 是 19 位。若以数字解析，末位会被四舍五入，导致 ID 失真且无任何错误提示。
#### 请求示例
```http
GET /admin/fleet/orders/2085539421276286978/operation-log?page=1&pageSize=50 HTTP/1.1
Host: {后台域名}
Authorization: Bearer {token}
Accept: application/json
```
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"records": [
{
"id": "2101990265092984834",
"time": "2026-09-21T18:45:32",
"opType": "soft_cleared",
"opTypeLabel": "清空司机/车辆",
"summary": "车务 王信 清空司机/车辆：蒙A-E2E99王信，派车行 1 行待改派",
"operatorName": "王信",
"effectiveDate": null,
"detailJson": "{\"scope\":\"GROUP\",\"assignmentGroupId\":\"360380081354444801\",\"statusBefore\":\"assigned\",\"clearedRowCount\":1,\"vehicleIdBefore\":\"2085539421276286978\",\"driverIdBefore\":\"2067084362829979650\",\"vehiclePlateSnapshot\":\"蒙A-E2E99\",\"driverNameSnapshot\":\"王信\",\"clearedRows\":[{\"assignmentId\":\"2101990265092984833\",\"serviceDate\":\"2026-12-22\",\"vehicleIdBefore\":\"2085539421276286978\",\"vehiclePlateBefore\":\"蒙A-E2E99\",\"driverIdBefore\":\"2067084362829979650\",\"driverNameBefore\":\"王信\"}]}",
"changeDetail": null
},
{
"id": "2101990265092984833",
"time": "2026-09-21T18:45:31",
"opType": "assignment_created",
"opTypeLabel": "新建派单",
"summary": "系统 新建派单：蒙A-E2E99王信，生效日 12/22",
"operatorName": "系统",
"effectiveDate": "2026-12-22",
"detailJson": null,
"changeDetail": null
}
],
"total": 2,
"page": 1,
"pageSize": 50
}
}
```
#### 空数据 / 降级响应
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"records": [],
"total": 0,
"page": 1,
"pageSize": 50
}
}
```
#### 错误响应
```json
{
"code": 404,
"message": "订单不存在",
"success": false,
"data": null
}
```
#### 业务边界
- **权限**：网关 `/admin/fleet/**` 统一鉴权，车务/管理员可访问
- **分页上限**：pageSize 最高 200，page 最高 100000
- **排序**：默认按 create_time 倒序（新操作在前）；支持 `sortBy=time,asc` 升序
- **ID 精度**：所有雪花号均以字符串返回，前端切勿转为 Number 类型
- **历史数据兼容**：该接口是只读时间线，查询时包含所有 `operation_type` 值（包括本次新增的 `soft_cleared`）
---
## 四、契约约束与正确调用方式
### ✅ 正确 / ❌ 错误 payload 对照
此接口为只读 GET，无请求体。正确调用示例：
| 场景 | URL |
|------|-----|
| ✅ 第一页，默认排序 | `GET /admin/fleet/orders/2085539421276286978/operation-log?page=1&pageSize=50` |
| ✅ 升序时间线 | `GET /admin/fleet/orders/2085539421276286978/operation-log?sortBy=time,asc&pageSize=50` |
| ✅ 处理 detailJson 字符串 | `JSON.parse(record.detailJson)` 转为对象后访问字段 |
| ❌ ID 作为 Number | `parseInt(record.id)` 会导致末位精度丢失 |
| ❌ 分页超过上限 | `pageSize=500` → 400 Bad Request |
### 处理 detailJson 的正确方式
`detailJson` 字段值本身是 JSON 字符串（因为在 SQL 层 `detail_json` 列是 text 类型，序列化到 JSON 响应时被转义成字符串）。前端需要先 parse 再访问：
```javascript
// ❌ 错误：直接访问
const vehicleId = record.detailJson.vehicleIdBefore; // undefined
// ✅ 正确：先 parse
const detail = JSON.parse(record.detailJson);
const vehicleId = detail.vehicleIdBefore; // "2085539421276286978"
// ✅ 保持字符串，不转 Number
const id = detail.vehicleIdBefore; // String，保持精度
// ❌ 禁止转数字
const id = Number(detail.vehicleIdBefore); // 末位被四舍五入
```
---
## 五、数据库行为
| 场景 | 数据库表 | 操作 |
|------|----------|------|
| 软清执行 | `fleet_assignment` | UPDATE `driver_id = null, vehicle_id = null` 等字段 |
| 软清写口 | `fleet_assignment_operation_log` | INSERT 一行，`operation_type = 'soft_cleared'`，`detail_json` 记录清空前的身份 |
---
## 六、边界行为
- **订单不存在** → 404
- **分页参数超范围** → 400（pageSize > 200 或 page > 100000）
- **无鉴权** → 401（网关拦截）
- **权限不足** → 403（非车务/管理员）
- **sortBy 值非法** → 忽略，使用默认倒序
- **历史数据**：该接口返回的是操作日志的完整历史，不因本次变更而改变已有记录；本次新增的 `soft_cleared` 仅出现在 2026-09-21 18:43 之后发生的清空操作
---
## 六.5、枚举 / 数据字典
### operation_type 枚举（`AssignmentOperationTypeEnum`）
**所属字段**: `FleetOperationLogItemVO.opType` | **类型**: `String`
新增值：
| 值 | 中文标签 | 说明 |
|----|----------|------|
| `soft_cleared` | 清空司机/车辆 | 车务手动清空派车行的车辆/司机字段，状态置回待改派 |
现有值（不含全列表，仅示例）：
| 值 | 中文标签 | 说明 |
|----|----------|------|
| `assignment_created` | 新建派单 | 订单新建派单时 |
| `change_completed` | 修改派单完成 | 改派操作完成 |
| `share_release_cleared` | 共用关系解除释放占用 | 共用关系解除时，共用组成员释放占用（#8061 新增） |
| `confirmed` | 确认执行 | 司机确认执行派单 |
| `completed` | 完结派单 | 派单完成 |
---
## 六.6、修改前后对比
### 响应字段级对比
| 字段 | 改前 | 改后 | 备注 |
|------|------|------|------|
| `records[].opType` | 不含 `soft_cleared` | 新增 `soft_cleared` | 前端若按白名单过滤需要加入 |
| `records[].detailJson` | 已有其他操作类型的内容 | 新增 `soft_cleared` 时的 detail_json 结构 | 当 opType 为 `soft_cleared` 时，detailJson 包含 scope/statusBefore/vehicleIdBefore 等字段 |
### 行为级对比
| 行为 | 改前 | 改后 |
|------|------|------|
| 软清留痕 | 派车行直接清空，无操作日志 | 调用软清写口时同步在 `fleet_assignment_operation_log` 写一行，记录被清空前的车/司机 |
| 时间线查询 | 软清操作不可见 | 软清操作以 `soft_cleared` 行显示在时间线中 |
| 事后取证 | 无法查证谁清了、清掉了谁 | `detail_json` 中记录清空前的 vehicleId/driverId 快照，支持事后追溯 |
---
## 六.7、影响评估
- **是否破坏向后兼容**: 否
- 新增操作类型 `soft_cleared` 不影响既有操作类型的解析
- 响应字段无删除，仅新增返回内容
- **前端是否必须同步上线**: 否（但需适配白名单过滤）
- 后端接口变更无必须的前端代码改动
- **但是**：如果前端在渲染时间线时对 `operation_type` 做了白名单过滤，白名单中**必须加入 `soft_cleared`**，否则该操作会静默漏渲染
- **前端 workaround 清理点**:
- 若有硬编码的 operation_type 白名单（例如 `['assignment_created', 'change_completed', ...]`），需补充 `'soft_cleared'`
- 若用了枚举常量或字典，确保后台下发的字典已包含 `soft_cleared` 标签
---
## 七、不影响范围
- **仅影响**：派单操作时间线接口 `/admin/fleet/orders/{orderId}/operation-log` 的响应内容
- **零影响**：
- 派车创建/改派/确认等业务流程
- 订单详情接口
- 派车行状态字段（清空行为本身不变，仍是直接 UPDATE 派车表）
- 其他模块的操作日志接口（如房务）
- 前端派车列表/派车详情等其他功能模块
---
## 八、测试环境已验证
测试服 `hl-fleet-service` 版本 `dev-v3@9f6443de4`（2026-09-21 18:46 部署，STATE=ok）
实测验证（订单 `2085539421276286978`、派车行已清空）：
```
GET /admin/fleet/orders/2085539421276286978/operation-log?page=1&pageSize=50
↓
200 OK
响应中 records[0]:
{
"opType": "soft_cleared",
"opTypeLabel": "清空司机/车辆",
"operatorName": "王信",
"time": "2026-09-21T18:45:32",
"detailJson": "{\"scope\":\"GROUP\",\"assignmentGroupId\":\"360380081354444801\",\"statusBefore\":\"assigned\",\"vehicleIdBefore\":\"2085539421276286978\",\"driverIdBefore\":\"2067084362829979650\",\"vehiclePlateSnapshot\":\"蒙A-E2E99\",\"driverNameSnapshot\":\"王信\", ...}",
...
}
✓ opType 正确为 soft_cleared
✓ detailJson 包含清空前的 vehicleId/driverId（字符串格式）
✓ 快照字段 vehiclePlateSnapshot/driverNameSnapshot 可读
```
---
## 九、特别说明：共用关系解除时的双行记录
共用关系解除（#8061）会在同一次操作中产生**两条连续的操作日志**：
1. **`share_release_cleared`** — 由共用关系解除的调用点写，答「哪个共用关系、解除原因、采用何种幸存者策略」
- `detail_json` 含 `shareGroupId` / `releaseReason` / `survivorPolicy` / `vehicleIdBefore` 等字段
2. **`soft_cleared`** — 由软清写口本身写，答「派车行被清了、清前是什么」（本次新增）
- `detail_json` 含 `scope` / `statusBefore` / `vehicleIdBefore` / `driverIdBefore` / `clearedRows` 等字段
**这不是重复数据**——两行记的是同一次操作的不同侧面，各自的 `detail_json` 内容完全不同，都有独特的业务含义。前端在渲染时间线时需要正确识别两种类型，包括在任何过滤/搜索逻辑中都要同时考虑这两个 operation_type。
---
## 十、相关文档
- 关联 Issue: [wx/HL#8068](https://git.1814.love:8443/wx/HL/issues/8068)
- 关联 PR: [wx/HL#8113](https://git.1814.love:8443/wx/HL/pulls/8113)
- 相关工单: [#8061](https://git.1814.love:8443/wx/HL/issues/8061)（共用关系解除），[#8051](https://git.1814.love:8443/wx/HL/issues/8051)（库内取证需求）
---
## 关联 / 联系人
### 链接
- **Issue**: [#8068](https://git.1814.love:8443/wx/HL/issues/8068)
- **PR**: [#8113](https://git.1814.love:8443/wx/HL/pulls/8113)
- **Merge commit**: [9f6443de4](https://git.1814.love:8443/wx/HL/commit/9f6443de4)
### 联系人
- **后端负责人**: @wx