626 行
22 KiB
Markdown
626 行
22 KiB
Markdown
---
|
||
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
|