docs: hand off API contract (#8068)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-21 19:24:12 +08:00
@@ -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