199 行
11 KiB
Markdown
199 行
11 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "9120"
|
||
title: "派车工作台回收站列表（撤下派车行分页、来源筛选、能否恢复）"
|
||
consumer: "admin"
|
||
author: "wx(GIT)"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "pending"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: "v2.1"
|
||
verified_at: "2026-10-22"
|
||
status_note: "后端 PR #9126 已合并 dev-v3（squash ead771c42），已部署<测试服>并双实例 is UP；真登录经网关实测 GET 两个筛选均 HTTP 200 / code 200（测试库当前无撤下行，records 为空，31 字段由单测映射用例覆盖）。本单只读，无表/Flyway/菜单/网关变更。"
|
||
updated_at: "2026-10-22"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 派车工作台回收站列表（新增接口）
|
||
|
||
> 面向：管理后台前端（hl-ui）
|
||
> 日期：2026-10-22 ｜ 后端：hl-fleet-service（二期 dev-v3）
|
||
> 范围：**纯新增**一个只读分页接口，供「派车工作台 → 回收站」弹窗列出被撤下的派车行，并显示每行能否恢复。
|
||
|
||
## 一、背景（选填）
|
||
|
||
3.9「撤下派车行」把行置为 CANCELLED 并写撤下日志，撤销后这些行不再出现在派车工作台的正常列表里。回收站是这些行的只读入口：按撤下时间倒序列出，可按团号/司机/车牌/车队名称搜索，可按撤下来源筛选，并逐行告诉前端「此刻能不能恢复、不能恢复时为什么」。点「恢复」不调本接口，仍走 3.10（请求体带本接口返回的 dispatchVehicleId 与 version）。
|
||
|
||
本单只交付列表；撤下/恢复事务（3.9/3.10）由后续工单接线，故本单上线后列表可能为空，这是数据现状，不是接口异常。
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|------|------|------|----------|------|
|
||
| 1 | 回收站列表 | GET | `/admin/fleet/dispatch-recycle/page` | 新增接口 | 撤下派车行分页，按撤下时间倒序；每行带 restorable/unrestorableReason |
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 回收站列表 `GET /admin/fleet/dispatch-recycle/page`
|
||
|
||
**VO**: `FleetDispatchRecyclePageReqVO` / `FleetDispatchRecycleRespVO`
|
||
|
||
#### 使用场景
|
||
|
||
派车工作台点「回收站」打开弹窗时调用第一页；改关键词/团/撤下来源时从头查；点「恢复」前用本行 restorable 判断按钮是否可点，不可点时把 unrestorableReason 悬浮显示。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|------|------|------|------|------|------|
|
||
| keyword | Query | String | 否 | 最长 50 字，trim 后空等于不传 | 任意一样包含：团号/司机姓名/车牌/车队名称；不拆词 |
|
||
| focusDispatchVehicleId | Query | String | 否 | 数字 ID | 命中时排到请求页第一条，原位置不再重复；不命中按正常排序 |
|
||
| dispatchGroupId | Query | String | 否 | 数字 ID | 只看该团撤下的行 |
|
||
| cancelSource | Query | String | 否 | MANUAL/UNASSIGN_ALL/NO_VEHICLE/RETIRED/DATE_CHANGED/REQUIREMENT_CANCELLED | 撤下来源；MANUAL 同时包含 cancel_source 为 NULL 的历史行 |
|
||
| page | Query | Integer | 否 | ≥1，默认 1 | 页码 |
|
||
| pageSize | Query | Integer | 否 | 1–100，默认 20 | 每页条数 |
|
||
|
||
#### 出参 `Result<PageResult<FleetDispatchRecycleRespVO>>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| dispatchVehicleId | String | 派车行 ID（雪花号，字符串避免精度丢失） |
|
||
| version | Integer | 行版本号，点「恢复」时原样回传给 3.10 做乐观锁 |
|
||
| dispatchGroupId | String | 所属团 ID；团已不存在也照旧返回 |
|
||
| teamNo | String | 团号；团不存在或老数据为空时为 null |
|
||
| sourceType | String | 团来源：GROUP/CORE/CUSTOM；团不存在时为 null |
|
||
| sourceTypeName | String | 团来源中文 |
|
||
| memberOrderId | String | 成员订单 ID；整行/接送关联的户 |
|
||
| memberTeamNo | String | 成员团号；为空表示整行或未关联户 |
|
||
| contactName | String | 联系人姓名，仅团期产品且成员团号为空时有值 |
|
||
| useType | String | 用车类型：TOUR/PICKUP/DROPOFF/MID_SWAP |
|
||
| useTypeName | String | 用车类型中文 |
|
||
| vehicleTypeId | String | 车型 ID |
|
||
| vehicleTypeName | String | 车型名称 |
|
||
| fleetTeamId | String | 车队 ID |
|
||
| fleetTeamName | String | 车队名称 |
|
||
| driverId | String | 司机 ID |
|
||
| driverName | String | 司机姓名 |
|
||
| plate | String | 车牌 |
|
||
| serviceStartDate | String | 服务开始日 yyyy-MM-dd |
|
||
| serviceEndDate | String | 服务结束日 yyyy-MM-dd |
|
||
| amount | String | 金额，两位小数；无金额为 null |
|
||
| lineStatusBeforeCancel | String | 撤下前状态：PENDING/SENT_TO_FLEET/ASSIGNED |
|
||
| lineStatusBeforeCancelName | String | 撤下前状态中文 |
|
||
| cancelledAt | String | 撤下时间 yyyy-MM-dd HH:mm:ss |
|
||
| cancelReason | String | 撤下原因 |
|
||
| cancelSource | String | 撤下来源六值之一；老数据为 null 时按 MANUAL 输出 |
|
||
| cancelSourceName | String | 撤下来源中文 |
|
||
| cancelOperatorId | String | 撤下操作人 ID；系统或旧系统迁来为 null |
|
||
| cancelOperatorName | String | 撤下操作人；系统或旧系统迁来为「系统」 |
|
||
| restorable | Boolean | 此刻能否恢复；true 表示可点恢复 |
|
||
| unrestorableReason | String | 不能恢复时的提示语，取自 3.10 对应错误码；可恢复为 null |
|
||
|
||
分页外壳 `data` 另有 `total`（Integer，总条数，不受分页影响）、`page`（Integer，当前页）、`pageSize`（Integer，每页条数）；顶层为 `code`/`message`/`data`/`success`/`traceId`。
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /admin/fleet/dispatch-recycle/page?page=1&pageSize=20&keyword=沪A12345&cancelSource=MANUAL
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{"code":200,"message":"成功","data":{"records":[{"dispatchVehicleId":"2103791490167999001","version":3,"dispatchGroupId":"2103791490167888001","teamNo":"HL20261020001","sourceType":"GROUP","sourceTypeName":"团期","memberOrderId":"2103791490167999101","memberTeamNo":"T-0007","contactName":null,"useType":"TOUR","useTypeName":"带团","vehicleTypeId":"2103791490167000001","vehicleTypeName":"7座商务","fleetTeamId":"2103791490166000001","fleetTeamName":"华东车队","driverId":"2103791490165000001","driverName":"王师傅","plate":"沪A12345","serviceStartDate":"2026-10-18","serviceEndDate":"2026-10-20","amount":"3600.00","lineStatusBeforeCancel":"ASSIGNED","lineStatusBeforeCancelName":"已派车","cancelledAt":"2026-10-20 15:12:33","cancelReason":"客户改期","cancelSource":"MANUAL","cancelSourceName":"撤下","cancelOperatorId":"2103791490167934978","cancelOperatorName":"ha_r1_su","restorable":true,"unrestorableReason":null}],"total":1,"page":1,"pageSize":20},"success":true}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无数据时 `records` 为空数组，`total=0`，HTTP 与业务 code 仍为 200：
|
||
|
||
```json
|
||
{"code":200,"message":"成功","data":{"records":[],"total":0,"page":1,"pageSize":20},"success":true}
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
参数非法（page<1、pageSize 不在 1–100、keyword 超过 50 字、cancelSource 不在六值、ID 非数字）统一返回 100001；HTTP 状态码按全局约定：
|
||
|
||
```json
|
||
{"code":100001,"message":"参数非法: page 必须大于等于 1","data":null,"success":false}
|
||
```
|
||
|
||
#### 业务边界
|
||
|
||
- 只读，不写库；无幂等/并发语义。
|
||
- 只列 `line_status='CANCELLED'` 的行；软删行不出现。
|
||
- 排序固定 `cancelled_at DESC, dispatch_vehicle_id DESC`（同秒按 ID 大→小），不接受排序参数。
|
||
- `restorable` 是「拉列表那一刻」的判定；点恢复时 3.10 会从头重判，可能由可恢复变为不可恢复。
|
||
- 不可恢复提示语来自 3.10 的四个错误码：603009 团不存在、603002 团来源订单已取消、603302 这一户已退团、603110 需求已取消。
|
||
- 团不存在时 teamNo/sourceType 等团字段为 null，但该行仍会列出（dispatchGroupId 照旧）。
|
||
- 关键词不拆词：整串对团号/司机姓名/车牌/车队名称做包含匹配。
|
||
|
||
## 四、契约约束与正确调用方式（接口类必写）
|
||
|
||
### ✅ 正确 / ❌ 错误 payload 对照
|
||
|
||
| 场景 | 查询串 |
|
||
|------|--------|
|
||
| ✅ 默认第一页 | `?page=1&pageSize=20` |
|
||
| ✅ 只看某团 | `?page=1&pageSize=20&dispatchGroupId=2103791490167888001` |
|
||
| ✅ 只看手工撤下 | `?page=1&pageSize=20&cancelSource=MANUAL` |
|
||
| ❌ pageSize 超过 100 | `?page=1&pageSize=101` → 100001 |
|
||
| ❌ cancelSource 拼错 | `?cancelSource=manual` → 100001（区分大小写） |
|
||
|
||
### 切换状态时的必要动作
|
||
|
||
- 从回收站点「恢复」时，请求体必须带**本行返回的** `dispatchVehicleId` 与 `version`，不要用列表缓存里的旧 version；恢复成功后应重新拉当前页。
|
||
- 搜索框输入需 trim；空串等价于不传 keyword，不要传空串以外的占位符。
|
||
|
||
## 六、边界行为
|
||
|
||
- 未登录 → 401（网关拦截）。
|
||
- 无权限（缺 `fleet:dispatch-recycle:list`）→ 403（网关/权限拦截）。
|
||
- 参数非法 → 100001。
|
||
- 无数据 → 200 + 空 records。
|
||
- 团/户/需求在列表之后被取消 → 本接口不感知；下次拉列表时 restorable 才变 false。
|
||
|
||
## 七、不影响范围（显式声明，帮前端/QA 缩小排查面）
|
||
|
||
- **仅影响**：新增 `GET /admin/fleet/dispatch-recycle/page` 一个只读端点。
|
||
- **零影响**：
|
||
- 派车工作台团列表/详情/建议接口
|
||
- `/admin/fleet/dispatch-groups/counts` 的 recycleCount 计算（本接口只读复用其口径）
|
||
- 3.9 撤下与 3.10 恢复（均不在本单）
|
||
- 表结构、索引、Flyway、菜单、网关路由（全部沿用现状）
|
||
|
||
## 八、测试环境已验证
|
||
|
||
真实登录（`POST /admin/auth/login`，账号 ha_r1_su，非铸 token）后经测试服网关：
|
||
|
||
```text
|
||
GET /admin/fleet/dispatch-recycle/page?page=1&pageSize=10 → 200 + code 200，total=0，records=[]，page=1，pageSize=10 ✓
|
||
GET /admin/fleet/dispatch-recycle/page?page=1&pageSize=10&cancelSource=MANUAL → 200 + code 200，total=0 ✓
|
||
GET /admin/fleet/dispatch-groups/counts → 200 + code 200，recycleCount=0 ✓
|
||
```
|
||
|
||
说明：测试库当前没有 line_status=CANCELLED 的行（回收站 total 与 /counts 的 recycleCount 双向均为 0），因此响应 records 为空；31 个字段名与顺序由单测映射用例覆盖，不是线上真行核对。前端可先用空列表开发页面骨架，接上 3.9 后自然有数据。
|
||
|
||
## 十、相关文档
|
||
|
||
- 关联 Issue: [wx/HL#9120](https://git.1814.love/wx/HL/issues/9120)
|
||
- 关联 PR: [wx/HL#9126](https://git.1814.love/wx/HL/pulls/9126)
|
||
- 设计文档：`docs/fleet-workbench/1-2接口文档.md` 第 12.2 节「回收站」；`docs/fleet-workbench/1-3详细设计.md` F12.2 与 R12
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#9120](https://git.1814.love/wx/HL/issues/9120)
|
||
- **PR**: [#9126](https://git.1814.love/wx/HL/pulls/9126)
|
||
- **Merge commit**: [ead771c42](https://git.1814.love/wx/HL/commit/ead771c42fadd256adeac6a579f84229b396038e)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|