---
schema: "hl-changelog/v2"
ticket: "5380"
title: "核单人员页签收口与车辆空态契约"
consumer: "admin"
change_type: "删除接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "implemented"
frontend_owner: "Pi"
frontend_ref: "v2.1@21dccf38d1413b098cfd5a456d3fb76611581ebb"
target_release: ""
verified_at: "2026-08-02"
status_note: "管理后台已仅保留导游、摄影师人员页签，删除领队/司机/其他人员 API 链路，并按 settlementReady/blockReasonCode 区分车辆两类空态；finalize 前重读权威 Step3。checkpoint 全量通过，业务提交 21dccf38d1413b098cfd5a456d3fb76611581ebb 已推送 origin/v2.1。网关有效登录态正向 curl 仍未完成，不标记 verified。"
updated_at: "2026-08-02"
base: "dev-v3"
---


# ⚠️【删除接口·管理后台】核单人员页签收口与车辆空态契约 (#5380)

> **PR**: #5393 | **服务**: order-v3 | **更新时间**: 2026-08-01

## 1. 接口背景

核单页面的人员费用仅保留导游、摄影师两类。领队、司机、其他人员不再作为核单人员费用页签，原有三组查询与保存接口同步删除。

车辆费用查询同时补齐两种空结果语义：订单没有当前用车需求时，空结果可以继续核单；订单有当前用车需求但车辆费用尚未就绪时，也返回成功空结果，并通过机器可读字段明确阻断原因。

## 变更接口清单

| # | 接口名 | 方法 | 路径 | 变更类型 | 说明 |
|---|--------|------|------|----------|------|
| 1 | 查询领队人员费用 | GET | `/v3/admin/order/:orderId/settlement/staff-fees/leaders` | 删除 | 不再提供领队核单 Tab 查询 |
| 2 | 全量替换领队人员费用 | PUT | `/v3/admin/order/:orderId/settlement/staff-fees/leaders` | 删除 | 不再提供领队核单 Tab 保存 |
| 3 | 查询司机人员费用 | GET | `/v3/admin/order/:orderId/settlement/staff-fees/drivers` | 删除 | 不再提供司机核单 Tab 查询 |
| 4 | 全量替换司机人员费用 | PUT | `/v3/admin/order/:orderId/settlement/staff-fees/drivers` | 删除 | 不再提供司机核单 Tab 保存 |
| 5 | 查询其他人员费用 | GET | `/v3/admin/order/:orderId/settlement/staff-fees/others` | 删除 | 不再提供其他人员核单 Tab 查询 |
| 6 | 全量替换其他人员费用 | PUT | `/v3/admin/order/:orderId/settlement/staff-fees/others` | 删除 | 不再提供其他人员核单 Tab 保存 |
| 7 | 查询车辆核单草稿 | GET | `/v3/admin/order/:orderId/settlement/step3/vehicles` | 修改 | 出参新增 `settlementReady`、`blockReasonCode`，并区分两种成功空结果 |

人员费用继续保留以下两组接口，路径和方法不变：

| Tab | 查询 | 保存 |
|-----|------|------|
| 导游 | `GET /v3/admin/order/:orderId/settlement/staff-fees/guides` | `PUT /v3/admin/order/:orderId/settlement/staff-fees/guides` |
| 摄影师 | `GET /v3/admin/order/:orderId/settlement/staff-fees/photographers` | `PUT /v3/admin/order/:orderId/settlement/staff-fees/photographers` |

## 3. 接口详情

### 3.1 删除：领队人员费用查询与保存

- **原接口名**：查询领队人员费用 / 全量替换领队人员费用
- **原方法与路径**：
  - `GET /v3/admin/order/:orderId/settlement/staff-fees/leaders`
  - `PUT /v3/admin/order/:orderId/settlement/staff-fees/leaders`
- **使用场景**：已删除，不再用于核单页面。
- **认证**：原接口要求管理后台登录态；接口删除后，即使登录态有效也返回 HTTP 404。
- **幂等性**：不适用。
- **限流**：无接口级特殊限流。

**路径参数**

| 字段 | 类型 | 必填 | 说明 | 校验 |
|------|------|------|------|------|
| `orderId` | String(Long) | 是 | 订单 ID | 原校验为正整数；接口删除后不再进入参数校验 |

**请求体**

GET 无请求体。PUT 原有请求体不再接受；不得继续提交领队费用 `items`。

**出参与错误码**

两个接口均无业务成功响应。任意订单调用均返回 HTTP 404，不能用其他人员费用路径替代领队路径。

| code | 含义 | 触发场景 |
|------|------|----------|
| `404` | 请求地址不存在 | 调用任一已删除的领队接口 |

**业务边界**

- 有效订单、历史订单和不存在的订单调用结果一致：路由不存在。
- 原有领队费用数据不构成前端可继续调用该接口的兼容理由。

**示例：GET 已删除**

请求：

```http
GET /v3/admin/order/2080000000000000001/settlement/staff-fees/leaders
Authorization: Bearer JWT_TOKEN
```

无请求体。

响应：

```json
{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}
```

**示例：PUT 已删除**

请求：

```http
PUT /v3/admin/order/2080000000000000001/settlement/staff-fees/leaders
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
```

```json
{
  "items": []
}
```

响应：

```json
{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}
```

### 3.2 删除：司机人员费用查询与保存

- **原接口名**：查询司机人员费用 / 全量替换司机人员费用
- **原方法与路径**：
  - `GET /v3/admin/order/:orderId/settlement/staff-fees/drivers`
  - `PUT /v3/admin/order/:orderId/settlement/staff-fees/drivers`
- **使用场景**：已删除，不再用于核单页面；车辆费用继续使用 §3.4 的车辆核单草稿查询。
- **认证**：原接口要求管理后台登录态；接口删除后，即使登录态有效也返回 HTTP 404。
- **幂等性**：不适用。
- **限流**：无接口级特殊限流。

**路径参数**

| 字段 | 类型 | 必填 | 说明 | 校验 |
|------|------|------|------|------|
| `orderId` | String(Long) | 是 | 订单 ID | 原校验为正整数；接口删除后不再进入参数校验 |

**请求体**

GET 无请求体。PUT 原有请求体不再接受；不得继续提交司机费用 `items`。

**出参与错误码**

两个接口均无业务成功响应。任意订单调用均返回 HTTP 404。司机人员费用接口与车辆核单草稿接口不是同一路由，不得改路径尾段后继续提交原司机费用请求体。

| code | 含义 | 触发场景 |
|------|------|----------|
| `404` | 请求地址不存在 | 调用任一已删除的司机接口 |

**业务边界**

- 有效订单、历史订单和不存在的订单调用结果一致：路由不存在。
- 车辆费用只读取 `/settlement/step3/vehicles` 的契约；已删除司机接口不再提供车辆费用补充入口。

**示例：GET 已删除**

请求：

```http
GET /v3/admin/order/2080000000000000001/settlement/staff-fees/drivers
Authorization: Bearer JWT_TOKEN
```

无请求体。

响应：

```json
{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}
```

**示例：PUT 已删除**

请求：

```http
PUT /v3/admin/order/2080000000000000001/settlement/staff-fees/drivers
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
```

```json
{
  "items": []
}
```

响应：

```json
{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}
```

### 3.3 删除：其他人员费用查询与保存

- **原接口名**：查询其他人员费用 / 全量替换其他人员费用
- **原方法与路径**：
  - `GET /v3/admin/order/:orderId/settlement/staff-fees/others`
  - `PUT /v3/admin/order/:orderId/settlement/staff-fees/others`
- **使用场景**：已删除，不再用于核单页面。
- **认证**：原接口要求管理后台登录态；接口删除后，即使登录态有效也返回 HTTP 404。
- **幂等性**：不适用。
- **限流**：无接口级特殊限流。

**路径参数**

| 字段 | 类型 | 必填 | 说明 | 校验 |
|------|------|------|------|------|
| `orderId` | String(Long) | 是 | 订单 ID | 原校验为正整数；接口删除后不再进入参数校验 |

**请求体**

GET 无请求体。PUT 原有请求体不再接受；不得继续提交其他人员费用 `items`。

**出参与错误码**

两个接口均无业务成功响应。任意订单调用均返回 HTTP 404，不能用导游或摄影师路径承载其他人员费用。

| code | 含义 | 触发场景 |
|------|------|----------|
| `404` | 请求地址不存在 | 调用任一已删除的其他人员接口 |

**业务边界**

- 有效订单、历史订单和不存在的订单调用结果一致：路由不存在。
- “其他人员”和“其他支出”是不同契约；本次删除不改变其他支出接口。

**示例：GET 已删除**

请求：

```http
GET /v3/admin/order/2080000000000000001/settlement/staff-fees/others
Authorization: Bearer JWT_TOKEN
```

无请求体。

响应：

```json
{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}
```

**示例：PUT 已删除**

请求：

```http
PUT /v3/admin/order/2080000000000000001/settlement/staff-fees/others
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
```

```json
{
  "items": []
}
```

响应：

```json
{
  "code": 404,
  "message": "请求地址不存在",
  "data": null,
  "success": false
}
```

### 3.4 修改：查询车辆核单草稿

- **接口名**：查询车辆核单草稿
- **方法与路径**：`GET /v3/admin/order/:orderId/settlement/step3/vehicles`
- **使用场景**：查询订单当前车辆核单明细及车辆费用是否已具备核单条件。
- **认证**：需要管理后台登录态并满足订单查看权限；房务角色不可访问。
- **幂等性**：是，只读查询。
- **限流**：无接口级特殊限流。

**路径参数**

| 字段 | 类型 | 必填 | 说明 | 校验 |
|------|------|------|------|------|
| `orderId` | String(Long) | 是 | 订单 ID | 正整数 |

无 Query 参数、无请求体。

**统一响应外层**

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | 业务码；成功为 `200` |
| `message` | String | 结果说明 |
| `data` | Object/null | 成功时为车辆核单草稿；失败时为 `null` |
| `traceId` | String/null | 链路追踪 ID，未返回时可为空 |
| `success` | Boolean | `code=200` 时为 `true` |

**成功响应 `data`**

| 字段 | 类型 | 可空 | 说明 |
|------|------|------|------|
| `orderId` | String(Long) | 否 | 订单 ID，按字符串返回 |
| `version` | Long | 否 | 车辆核单草稿版本；空结果为 `0` |
| `totalAmount` | Decimal | 否 | 当前全部车辆明细金额合计；空结果为 `0.00` |
| `allConfirmed` | Boolean | 否 | 当前明细是否全部已确认；有需求但费用未就绪的空结果为 `false` |
| `settlementReady` | Boolean | 否 | 车辆费用是否已具备核单条件；本次新增公开字段 |
| `blockReasonCode` | String | 是 | 不具备核单条件时的机器可读原因；可核单时为 `null` |
| `items` | Array | 否 | 当前车辆费用全量明细；无明细时为 `[]` |

**`data.items[]`**

| 字段 | 类型 | 可空 | 说明 |
|------|------|------|------|
| `id` | String(Long) | 否 | 车辆核单明细 ID |
| `sourceType` | String | 否 | 来源编码，见 §6.1 |
| `sourceTypeName` | String | 否 | 来源名称 |
| `serviceDate` | String(date) | 否 | 服务日期，格式 `YYYY-MM-DD` |
| `vehicleId` | String(Long) | 是 | 车辆 ID |
| `vehiclePlate` | String | 是 | 车牌号 |
| `vehicleModelId` | String(Long) | 是 | 车型 ID |
| `vehicleModelName` | String | 是 | 车型名称 |
| `driverId` | String(Long) | 是 | 司机 ID |
| `driverName` | String | 是 | 司机姓名 |
| `amount` | Decimal | 否 | 核单金额 |
| `paymentMethod` | String | 否 | 付款方式编码，见 §6.2 |
| `paymentMethodName` | String | 否 | 付款方式名称 |
| `settlementConfirmStatus` | String | 否 | 核单确认状态编码，见 §6.3 |
| `settlementConfirmStatusName` | String | 否 | 核单确认状态名称 |
| `remark` | String | 是 | 备注 |
| `voucherUrls` | String[] | 否 | 凭证 URL；无凭证时为 `[]` |

**错误码**

| code | 含义 | 触发场景 |
|------|------|----------|
| `400` | 请求参数错误 | `orderId` 不是正整数 |
| `403` | 无访问权限 | 登录态或角色无权访问该接口 |
| `581007` | 订单不存在 | `orderId` 对应订单不存在 |
| `584071` | 无权访问该订单 | 当前账号不在订单可访问范围内 |
| `584100` | 车辆费用暂时不可用 | 车辆费用来源调用失败、响应身份不匹配或必要字段无效 |
| `584101` | 车辆费用尚未满足核单条件 | 已返回非空车辆明细，但存在未完结或未满足费用条件的明细 |

`584102` 不再用于本 GET 的“当前需求存在但车辆费用尚未生成”场景；该场景改为 `code=200` 的空结果，见下方示例。

**业务边界与判定表**

| 场景 | `items` | `totalAmount` | `settlementReady` | `blockReasonCode` | `allConfirmed` | 结果 |
|------|---------|---------------|-------------------|-------------------|----------------|------|
| 无当前用车需求 | `[]` | `0.00` | `true` | `null` | `true` | 成功，可继续完成核单 |
| 有当前用车需求，但车辆费用尚未生成 | `[]` | `0.00` | `false` | `VEHICLE_FEE_NOT_READY` | `false` | 成功，但不能完成核单 |
| 有明细且来源已就绪，仍有行未确认 | 非空 | 合计金额 | `true` | `null` | `false` | 成功，需先完成明细确认 |
| 有明细且来源已就绪，所有行已确认 | 非空 | 合计金额 | `true` | `null` | `true` | 成功，可继续完成核单 |

- `items=[]` 不是失败判据，必须结合 `settlementReady` 判断。
- `allConfirmed=true` 只表示没有未确认行；是否具备核单条件仍以 `settlementReady` 为准。
- 车辆费用来源调用失败或明细必要字段无效仍返回业务错误，不转换为空结果。

**示例 1：典型成功，有已确认车辆明细**

请求：

```http
GET /v3/admin/order/900000000001/settlement/step3/vehicles
Authorization: Bearer JWT_TOKEN
```

无请求体。

响应：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": "900000000001",
    "version": 4,
    "totalAmount": 1200.00,
    "allConfirmed": true,
    "settlementReady": true,
    "blockReasonCode": null,
    "items": [
      {
        "id": "930000000001",
        "sourceType": "FLEET",
        "sourceTypeName": "车务",
        "serviceDate": "2026-08-01",
        "vehicleId": "880000000001",
        "vehiclePlate": "藏A12345",
        "vehicleModelId": "870000000001",
        "vehicleModelName": "七座商务车",
        "driverId": "860000000001",
        "driverName": "张师傅",
        "amount": 1200.00,
        "paymentMethod": "COMPANY_PAID",
        "paymentMethodName": "公司付款",
        "settlementConfirmStatus": "CONFIRMED",
        "settlementConfirmStatusName": "已确认",
        "remark": "金额已核对",
        "voucherUrls": []
      }
    ]
  },
  "traceId": null,
  "success": true
}
```

**示例 2：边界成功，无当前用车需求**

请求：

```http
GET /v3/admin/order/900000000002/settlement/step3/vehicles
Authorization: Bearer JWT_TOKEN
```

无请求体。

响应：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": "900000000002",
    "version": 0,
    "totalAmount": 0.00,
    "allConfirmed": true,
    "settlementReady": true,
    "blockReasonCode": null,
    "items": []
  },
  "traceId": null,
  "success": true
}
```

**示例 3：边界成功，有当前需求但车辆费用尚未就绪**

请求：

```http
GET /v3/admin/order/900000000003/settlement/step3/vehicles
Authorization: Bearer JWT_TOKEN
```

无请求体。

响应：

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": "900000000003",
    "version": 0,
    "totalAmount": 0.00,
    "allConfirmed": false,
    "settlementReady": false,
    "blockReasonCode": "VEHICLE_FEE_NOT_READY",
    "items": []
  },
  "traceId": null,
  "success": true
}
```

**示例 4：业务失败，车辆费用来源暂时不可用**

请求：

```http
GET /v3/admin/order/900000000004/settlement/step3/vehicles
Authorization: Bearer JWT_TOKEN
```

无请求体。

响应：

```json
{
  "code": 584100,
  "message": "车务车辆总车费暂时不可用，请稍后重试",
  "data": null,
  "traceId": null,
  "success": false
}
```

## 6. 枚举 / 数据字典

### 6.1 `sourceType`

**所属字段**：`data.items[].sourceType` ｜ **类型**：String

| 值 | 中文 | 说明 |
|----|------|------|
| `FLEET` | 车务 | 车辆费用来源于当前车辆安排 |
| `MANUAL` | 手工 | 手工维护的车辆核单明细 |

### 6.2 `paymentMethod`

**所属字段**：`data.items[].paymentMethod` ｜ **类型**：String

| 值 | 中文 | 说明 |
|----|------|------|
| `CASH_PAID` | 现金已付 | 现金支付 |
| `SIGNED` | 签单 | 按签单方式结算 |
| `COMPANY_PAID` | 公司付款 | 由公司支付 |

### 6.3 `settlementConfirmStatus`

**所属字段**：`data.items[].settlementConfirmStatus` ｜ **类型**：String

| 值 | 中文 | 说明 |
|----|------|------|
| `UNCONFIRMED` | 未确认 | 当前车辆费用行尚未完成核单确认 |
| `CONFIRMED` | 已确认 | 当前车辆费用行已完成核单确认 |

### 6.4 `blockReasonCode`

**所属字段**：`data.blockReasonCode` ｜ **类型**：String/null

| 值 | 中文 | 说明 |
|----|------|------|
| `VEHICLE_FEE_NOT_READY` | 车辆费用尚未就绪 | 有当前用车需求，但尚无可返回的车辆费用明细；此时 `settlementReady=false` |
| `null` | 无阻断原因 | 此时 `settlementReady=true`；`null` 是空值，不是字符串 `"null"` |

## 验证证据

- PR #5393 已合并至 `dev-v3`，合并提交为 `e4c1720871f33db38936d709caa7696db199ad1f`。
- 部署任务 `e6720666` 构建成功，按 8186→8086 完成滚动，两个实例均为 UP。
- 测试服管理后台真实页面成功读取 9 条 `FLEET` 车辆费用，未再出现旧的车辆空数据错误。
- 测试服 8086 OpenAPI 已确认仅保留 guides、photographers 两组人员费用接口；leaders、drivers、others 六个路由不存在，车辆响应包含 `settlementReady`、`blockReasonCode`。
- 网关 curl 已确认路由可达，但旧 JWT 返回业务 401；逐接口正向网关 curl 因有效登录态缺失而阻断。
- **验收结论：TARGETED_FALLBACK / PARTIAL**。已确认部署、双实例、页面车辆数据和服务 OpenAPI 契约；未完成带有效登录态的逐接口网关正向验证，不能描述为 Full E2E 或网关全量 `verified`。
- PR 自动化记录：受影响测试 513 项通过，新增规格测试 116 项通过；模块全量 7198 项中 7166 项通过、31 项跳过、1 项失败，唯一失败为既有迁移版本重复问题。

## 10. 修改前后对比

### 10.1 字段级对比

| 字段 | 改前 | 改后 |
|------|------|------|
| 车辆响应 `data.settlementReady` | 不对管理后台输出 | 新增 `Boolean`，明确车辆费用是否具备核单条件 |
| 车辆响应 `data.blockReasonCode` | 不存在 | 新增 `String/null`，不可核单时返回机器可读原因 |

### 10.2 行为级对比

| 行为 | 改前 | 改后 |
|------|------|------|
| 核单人员 Tab | 领队、司机、导游、摄影师、其他人员共 5 个 | 仅保留导游、摄影师 2 个 |
| 领队人员费用 GET/PUT | 可查询、保存 | 路由删除，调用返回 HTTP 404 |
| 司机人员费用 GET/PUT | 可查询、保存 | 路由删除，调用返回 HTTP 404 |
| 其他人员费用 GET/PUT | 可查询、保存 | 路由删除，调用返回 HTTP 404 |
| 无当前用车需求 | 返回空明细，但响应未公开就绪原因字段 | 成功返回空明细，`settlementReady=true`、`blockReasonCode=null` |
| 有当前需求但车辆费用尚未生成 | GET 返回 `584102`，页面无法取得可判定空态 | 成功返回空明细，`settlementReady=false`、`blockReasonCode=VEHICLE_FEE_NOT_READY` |
| 车辆来源失败或明细无效 | 返回业务错误 | 仍返回业务错误，不伪装成空结果 |

## 11. 影响评估 / 回滚

### 11.1 影响评估

- **是否破坏向后兼容**：是。领队、司机、其他人员共 6 个接口已删除。
- **前端是否必须同步上线**：是。管理后台必须移除这 3 个 Tab 及其查询、保存调用，仅保留导游、摄影师 Tab。
- **车辆字段兼容性**：新增字段本身为向后兼容；若仍沿用 `items=[]` 或捕获 `584102` 判断空态，将无法区分“无需求”和“费用未就绪”。

### 11.2 回滚边界

- 前端版本不得回滚到仍调用 leaders、drivers、others 六个路由的版本，否则对应页面请求固定失败。
- 若前端暂时不使用车辆新增字段，JSON 仍可解析，但不能可靠判断空结果是否允许完成核单。

## 12. 注意事项

- 删除领队、司机、其他人员 3 个核单 Tab 及其 GET/PUT 请求封装、请求状态和保存动作。
- 保留导游 `guides`、摄影师 `photographers` 两个 Tab，原路径不变。
- 车辆查询返回 `code=200` 且 `items=[]` 时，不得直接当作异常或无条件放行；必须读取 `settlementReady`。
- 完成核单前同时检查 `settlementReady` 与 `allConfirmed`，不能只判断明细数组是否为空。
- 清理 GET 车辆费用遇到 `584102` 时的空态兼容逻辑；新的“有需求但费用未就绪”结果由 `blockReasonCode=VEHICLE_FEE_NOT_READY` 表达。
- `orderId`、车辆明细 ID、车辆 ID、车型 ID、司机 ID 均按字符串处理；金额按 Decimal 处理。

## 13. 关联 / 联系人

### 13.1 链接

- **Issue**: [#5380](https://git.1814.love:8443/wx/HL/issues/5380)
- **PR**: [#5393](https://git.1814.love:8443/wx/HL/pulls/5393)
- **Merge commit**: [e4c1720871f33db38936d709caa7696db199ad1f](https://git.1814.love:8443/wx/HL/commit/e4c1720871f33db38936d709caa7696db199ad1f)

### 13.2 联系人

- **后端负责人**: @yst