---
schema: "hl-changelog/v2"
ticket: "5862"
title: "派单操作日志补全操作人、操作时间与改派资源快照"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "PR #5869 已合入 dev-v3 并部署 TEST；真实登录经 Gateway 验证操作时间、操作人、动作摘要及历史改派降级契约。现有管理端可直接展示，无前端代码变更。"
updated_at: "2026-08-11"
base: "dev-v3"
---

# 车务派单：操作日志补全操作人、操作时间与改派资源快照

> **服务**: hl-fleet-service（8087）
> **PR**: #5869
> **Issue**: #5862
> **日期**: 2026-08-11
> **影响范围**: 管理端车务看板订单详情和“查看日志”中的派单操作记录

---

## ⚠️ 关键变化

- 操作日志现在稳定返回 `time`、`operatorName`、`opTypeLabel` 和 `summary`，操作人按“企业微信姓名 → 系统用户名 → 系统”的顺序解析。
- 改派日志新增结构化 `changeDetail`。新日志保存操作当时的新旧车牌、司机姓名快照，不再要求调用方解析 `detailJson` 中的 ID 后查询当前车辆或司机档案。
- 历史日志没有快照时保持兼容：展示字段允许按 ID 查询当前档案，`dataCompleteness` 明确返回 `HISTORICAL_PARTIAL`，不得把当前档案值误认为操作时快照。

## 一、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 派单操作时间线 | GET | `/admin/fleet/orders/{orderId}/operation-log` | 响应增强 | 日志行补全操作信息与结构化改派详情 |
| 2 | 车务看板订单详情 | GET | `/admin/fleet/board/orders/{orderId}` | 响应增强 | `operationLog.records[]` 同步返回相同字段 |

两个接口沿用原有路径、鉴权和分页契约，不新增请求字段。

## 二、接口详情

### 1. 派单操作时间线 `GET /admin/fleet/orders/{orderId}/operation-log`

**响应模型**: `Result<FleetOrderOperationLogRespVO>`

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| orderId | Path | String | 是 | Long 字符串 | 订单 ID |
| page | Query | Integer | 否 | 默认 1 | 页码 |
| pageSize | Query | Integer | 否 | 默认 50，最大 200 | 每页条数 |
| sortBy | Query | String | 否 | `time,desc` / `time,asc` | 默认按操作时间倒序 |
| keyword | Query | String | 否 | 最长 32 字 | 按展示后的摘要、操作人等内容搜索 |
| startDate | Query | LocalDateTime | 否 | ISO 8601 | 操作时间起点 |
| endDate | Query | LocalDateTime | 否 | ISO 8601 | 操作时间终点 |

#### 日志行出参

| 字段 | 类型 | 说明 |
|---|---|---|
| id | String / null | 日志 ID；合成里程碑记录可为 null |
| time | String | 操作时间，格式 `yyyy-MM-dd HH:mm:ss` |
| opType | String | 操作类型英文枚举 |
| opTypeLabel | String | 可直接展示的中文动作名称 |
| summary | String | 后端生成的操作摘要，改派时包含前后资源和生效日 |
| operatorName | String | 企业微信姓名优先，无企业微信姓名时使用系统用户名；自动任务为“系统” |
| effectiveDate | String / null | 生效日期，格式 `yyyy-MM-dd` |
| detailJson | String / null | 兼容保留的原始明细 JSON，不建议前端再自行解析 ID |
| changeDetail | Object / null | 改派结构化详情；非改派动作返回 null |

#### `changeDetail` 字段

| 字段 | 类型 | 说明 |
|---|---|---|
| changeDimensions | String[] | 变更维度：`VEHICLE`、`DRIVER`、`VEHICLE_FEE` |
| previousVehicleId / newVehicleId | String / null | 原车、新车 ID |
| previousVehiclePlateSnapshot / newVehiclePlateSnapshot | String / null | 操作当时的原车牌、新车牌快照；历史无快照时为 null |
| previousVehiclePlate / newVehiclePlate | String / null | 展示值；优先使用快照，历史数据才按 ID 降级查询当前档案 |
| previousDriverId / newDriverId | String / null | 原司机、新司机 ID |
| previousDriverNameSnapshot / newDriverNameSnapshot | String / null | 操作当时的原司机、新司机姓名快照；历史无快照时为 null |
| previousDriverName / newDriverName | String / null | 展示值；优先使用快照，历史数据才按 ID 降级查询当前档案 |
| effectiveDate / endDate | String / null | 本次变更的生效日和结束日 |
| previousUsedDays | Integer / null | 生效日前原资源在同一槽位已使用的有效服务日数；历史未知为 null |
| affectedServiceDates | String[] | 本次实际变更的服务日期，支持非连续日期集合 |
| affectedDays | Integer / null | 本次实际变更服务日数；历史未知为 null |
| reason | String / null | 变更原因 |
| dataCompleteness | String | `COMPLETE` 或 `HISTORICAL_PARTIAL` |

#### 完整快照响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "id": "2086386125831561218",
        "time": "2026-08-11 15:05:14",
        "opType": "change_completed",
        "opTypeLabel": "修改派单完成",
        "summary": "lc 修改派单完成：蒙A-E2E99王信 → 蒙A-E2E01道尔吉，生效日 2026-08-23",
        "operatorName": "lc",
        "effectiveDate": "2026-08-23",
        "detailJson": "{...}",
        "changeDetail": {
          "changeDimensions": ["VEHICLE", "DRIVER"],
          "previousVehicleId": "2086000000000000001",
          "previousVehiclePlateSnapshot": "蒙A-E2E99",
          "previousVehiclePlate": "蒙A-E2E99",
          "previousDriverId": "2086000000000000002",
          "previousDriverNameSnapshot": "王信",
          "previousDriverName": "王信",
          "newVehicleId": "2086000000000000003",
          "newVehiclePlateSnapshot": "蒙A-E2E01",
          "newVehiclePlate": "蒙A-E2E01",
          "newDriverId": "2086000000000000004",
          "newDriverNameSnapshot": "道尔吉",
          "newDriverName": "道尔吉",
          "effectiveDate": "2026-08-23",
          "endDate": "2026-08-25",
          "previousUsedDays": 2,
          "affectedServiceDates": ["2026-08-23", "2026-08-24", "2026-08-25"],
          "affectedDays": 3,
          "reason": "调整车辆与司机",
          "dataCompleteness": "COMPLETE"
        }
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 50
  },
  "success": true
}
```

#### 历史日志降级示例

```json
{
  "previousVehiclePlateSnapshot": null,
  "previousVehiclePlate": "蒙A-E2E99",
  "previousDriverNameSnapshot": null,
  "previousDriverName": "王信",
  "newVehiclePlateSnapshot": null,
  "newVehiclePlate": "蒙A-E2E01",
  "newDriverNameSnapshot": null,
  "newDriverName": "道尔吉",
  "previousUsedDays": null,
  "affectedServiceDates": [],
  "affectedDays": null,
  "dataCompleteness": "HISTORICAL_PARTIAL"
}
```

### 2. 车务看板订单详情 `GET /admin/fleet/board/orders/{orderId}`

订单详情原有 `operationLog.records[]` 复用上述日志行模型。本次同步增加并补全 `time`、`opTypeLabel`、`summary`、`operatorName` 和 `changeDetail`，字段含义及历史降级规则与独立操作时间线接口一致。

## 三、修改前后对比

### 字段级对比

| 字段 | 修改前 | 修改后 |
|---|---|---|
| time | 部分操作记录展示字段不完整 | 每条可展示记录返回标准操作时间 |
| operatorName | 可能只有泛化角色名或缺失 | 企业微信姓名优先，系统用户名兜底，自动任务显示“系统” |
| summary / opTypeLabel | 动作信息不完整或需要调用方拼装 | 返回中文动作名称和可直接展示的完整摘要 |
| detailJson | 调用方需解析车辆、司机 ID，且查询结果会受当前档案变化影响 | 兼容保留，不再作为稳定展示契约 |
| changeDetail | 无 | 返回新旧车辆、司机、使用天数、影响日期及完整性标记 |
| 车牌与司机姓名 | 可能展示当前档案值，无法证明操作当时名称 | 新日志保存操作时快照；历史日志明确标记降级状态 |

### 行为级对比

| 场景 | 修改前 | 修改后 |
|---|---|---|
| 操作人展示 | 可能无法识别具体人员 | 企微姓名优先，无企微姓名时显示系统用户名 |
| 换车或换司机 | 仅凭 ID 无法稳定还原前后资源 | 直接返回操作当时的新旧车牌与司机姓名快照 |
| 历史无快照 | 容易把当前档案误当作历史事实 | 可降级展示，但通过 `HISTORICAL_PARTIAL` 明确说明不完整 |
| 车辆费用单独变化 | 可能被误写成换车或换司机 | `changeDimensions` 单独标记 `VEHICLE_FEE`，动作摘要按实际维度生成 |

## 四、契约约束与兼容边界

- 调用方应优先读取结构化 `changeDetail`；`detailJson` 仅为兼容字段，不保证适合作为长期展示数据源。
- `*Snapshot` 是操作时事实；不带 `Snapshot` 的车牌、司机展示字段可能是历史数据按 ID 查询当前档案后的降级值。
- 只有本次操作应保存的车牌和司机姓名快照均齐全时，`dataCompleteness` 才返回 `COMPLETE`；存量日志不会伪造快照。
- 仅变更车辆、仅变更司机、同时变更车辆与司机、仅变更车辆费用，均以 `changeDimensions` 的实际值为准。
- ID 按字符串返回，调用方不得转换为 JavaScript Number。
- 本次不改变接口路径、请求参数、权限、分页、排序和统一 `Result` 响应结构。
- 快照仅包含车牌和司机姓名，不新增手机号、证件号或其他敏感信息。

## 五、前端影响

`frontend_status=not_required`。现有管理端已经可以直接展示操作时间、操作人和后端摘要，本次 TEST 页面已看到“原车牌/原司机 → 新车牌/新司机”的改派结果，无需同步修改前端代码。其他调用方如仍解析 `detailJson`，应逐步改为优先消费 `changeDetail`。

## 六、验证与测试证据

- PR #5869 已合入 `dev-v3`，合并提交：`2d9c6ba4f8af1ad997b8b6e3ba7d215b9754ae66`；TEST 的 Fleet 服务双实例健康。
- 使用真实登录身份经 TEST Gateway 调用 `GET /admin/fleet/orders/{orderId}/operation-log` 返回 200。订单 `26-3420` 的 10 条记录均具有非空操作时间、动作、操作人和摘要。
- TEST 管理端订单 `26-6436` 的日志页面直接展示 `蒙A-E2E99/王信 → 蒙A-E2E01/道尔吉`、动作、生效日、操作人和时间。
- 同一订单 3 条存量改派记录均返回 `HISTORICAL_PARTIAL`，且 `changeDetail` 快照、展示值、使用天数和受影响日期等契约字段完整存在，历史无快照字段保持 null。
- #5862 定向自动化测试 620 项通过；Fleet 扩大测试 3604 项通过、0 失败、0 错误、7 跳过；固定端口 MySQL 集成测试 11/11 通过。
- 为避免通知、派单和审计副作用，TEST 验收未提交新的改派操作；新写日志 `COMPLETE` 快照路径由自动化测试覆盖，测试业务数据状态未改变。
- 工单验收标准 14/14 已勾选，验收记录已写入，Issue #5862 已关闭。

## 七、不影响范围

- 不新增或修改数据库结构。
- 不修改管理端、小程序、H5 或其他前端代码。
- 不改变派单状态机、派单确认、司机通知、保险、结算和车辆费用计算规则。
- 不回填或改写历史日志；历史记录只做只读降级展示。

## 关联

- Issue: #5862
- PR: #5869
- 后端合并提交: `2d9c6ba4f8af1ad997b8b6e3ba7d215b9754ae66`
- 联系人: @lc