---
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