---
schema: "hl-changelog/v2"
ticket: "5674"
title: "核单导游/摄影费用 4 接口请求解析失败错误码 584125 细化为 584128 并透出具体字段原因"
consumer: "admin"
change_type: "修改接口"
author: "yaosutu(GIT)"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "PR #5677 已合并 dev-v3；请求体解析失败/Bean 校验失败错误码由 584125 细化为 584128，message 透出具体字段原因；请求体为空仍返回 584125 不变。成功路径入参/出参字段不变。"
updated_at: "2026-08-08"
base: "dev-v3"
---

# 【⚠️ 修改接口·管理后台】核单导游/摄影费用解析失败错误码细化为 584128 并透出字段原因（#5674）

> **PR**: [#5677](https://git.1814.love:8443/wx/HL/pulls/5677) | **服务**: hl-order-service-v3 | **更新时间**: 2026-08-08

## 1. 接口背景

核单「导游费用」「摄影费用」两个页签共 4 个写接口，此前在请求体 JSON 解析失败或 Bean 校验失败时统一返回 `584125 导游或摄影费用请求字段不合法`，message 不带具体字段原因，前端和核单人员无法自助定位是哪个字段不合法。本次将解析/校验失败细化为新错误码 `584128`，message 透出具体字段路径与原因；成功路径的入参/出参字段、枚举值、行为全部不变。

## 2. 变更清单

| # | 接口 | 方法 | 路径 | 变更类型 | 前端动作 |
|---|---|---|---|---|---|
| 1 | 保存导游费用 | PUT | `/v3/admin/order/{orderId}/settlement/guide-fees` | 错误码语义修改 | 若对 `584125` 做过特判需知悉；建议直接展示后端 message |
| 2 | 确认导游费用 | PUT | `/v3/admin/order/{orderId}/settlement/guide-fees/confirm` | 错误码语义修改 | 同上 |
| 3 | 保存摄影费用 | PUT | `/v3/admin/order/{orderId}/settlement/photographer-fees` | 错误码语义修改 | 同上 |
| 4 | 确认摄影费用 | PUT | `/v3/admin/order/{orderId}/settlement/photographer-fees/confirm` | 错误码语义修改 | 同上 |

> 成功路径的请求体字段、响应结构、状态码 200 行为均未变化，不属于本次契约变更范围。

## 3. 接口详情

4 个接口的协议层约定一致，统一说明：

- **使用场景**：核单人员在订单核单页维护/确认导游费用、摄影费用明细。
- **认证**：需要管理后台登录态（Bearer Token）。
- **幂等性**：保存类接口按订单维度覆盖式保存，重复提交相同载荷结果一致；确认接口带 `expectedSourceFingerprint` 乐观校验，重放安全。
- **限流**：未声明接口专属限流。
- **方法/路径**：
  - `PUT /v3/admin/order/{orderId}/settlement/guide-fees`
  - `PUT /v3/admin/order/{orderId}/settlement/guide-fees/confirm`
  - `PUT /v3/admin/order/{orderId}/settlement/photographer-fees`
  - `PUT /v3/admin/order/{orderId}/settlement/photographer-fees/confirm`

## 4. 接口入参

成功路径入参字段本次**无变化**（保存接口为费用明细列表请求体；确认接口在保存基础上多 `expectedSourceFingerprint` 字段，须为 64 位十六进制字符串）。与本次变更相关的入参行为：

| 场景 | 原来 | 现在 |
|---|---|---|
| 请求体含未知字段（如把出参字段 `settlementConfirmStatus` 回传进请求体） | `584125`，无具体原因 | `584128`，message 指出不支持的字段名 |
| 请求体 JSON 反序列化失败（类型不匹配/格式错误） | `584125`，无具体原因 | `584128`，message 透出解析原因 |
| 字段 Bean 校验失败（如 `expectedSourceFingerprint` 不合 Pattern） | `584125`，无具体字段 | `584128`，message 透出 `字段路径: 校验提示` |
| 请求体为空 / null | `584125` | `584125`（不变） |

## 5. 出参字段

成功响应出参字段本次**无变化**。失败响应统一为：

| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | Integer | 业务错误码，本次新增透出 `584128` |
| `message` | String | 错误描述，`584128` 时含具体字段原因 |
| `data` | Object | 恒为 `null` |
| `success` | Boolean | 恒为 `false` |

## 6. 枚举 / 数据字典

本次不涉及枚举或字典的新增、删除、改值、改语义。`settlementConfirmStatus` 等既有枚举取值不变。

## 7. 错误码

| code | 含义 | 触发场景 | 本次变化 |
|---:|---|---|---|
| `584125` | 导游或摄影费用请求字段不合法 | 请求体为空 / null | 不变（仅剩该场景触发） |
| `584128` | 导游或摄影费用请求字段不合法：{具体原因} | 请求体含未知字段 / 反序列化失败 / Bean 校验失败 | **新增**，替代原 `584125` 的解析/校验场景 |

`584128` message 构成为固定前缀 + 具体原因：

- 未知字段：`导游或摄影费用请求字段不合法：导游费用明细不支持字段： settlementConfirmStatus`（摄影接口为「摄影费用明细不支持字段： ...」）
- 校验失败：`导游或摄影费用请求字段不合法：expectedSourceFingerprint: 须为 64 位十六进制`

## 8. 示例

### 8.1 典型成功（保存导游费用，入参出参与改前一致）

```http
PUT /v3/admin/order/2084000000000002978/settlement/guide-fees
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "fees": [
    {
      "feeDate": "2026-08-08",
      "guideName": "张三",
      "quantity": 1,
      "unitPrice": 300.00,
      "settlementAmount": 300.00,
      "paymentMethod": "COMPANY_PAID",
      "remark": null
    }
  ]
}
```

```json
{"code": 200, "message": "success", "data": {"saved": true}, "success": true}
```

### 8.2 边界（请求体为空，错误码不变仍为 584125）

```http
PUT /v3/admin/order/2084000000000002978/settlement/guide-fees
Authorization: Bearer <token>
Content-Type: application/json
```

```json
null
```

```json
{"code": 584125, "message": "导游或摄影费用请求字段不合法", "data": null, "success": false}
```

### 8.3 业务失败（新增 584128，透出具体字段原因）

场景 A：把出参字段 `settlementConfirmStatus` 误回传进请求体（未知字段）。

```http
PUT /v3/admin/order/2084000000000002978/settlement/guide-fees
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "fees": [
    {
      "feeDate": "2026-08-08",
      "guideName": "张三",
      "quantity": 1,
      "unitPrice": 300.00,
      "settlementAmount": 300.00,
      "paymentMethod": "COMPANY_PAID",
      "settlementConfirmStatus": "UNCONFIRMED"
    }
  ]
}
```

```json
{"code": 584128, "message": "导游或摄影费用请求字段不合法：导游费用明细不支持字段： settlementConfirmStatus", "data": null, "success": false}
```

场景 B：确认接口指纹字段不合 Pattern（Bean 校验失败）。

```http
PUT /v3/admin/order/2084000000000002978/settlement/guide-fees/confirm
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "expectedSourceFingerprint": "abc123",
  "fees": []
}
```

```json
{"code": 584128, "message": "导游或摄影费用请求字段不合法：expectedSourceFingerprint: 须为 64 位十六进制", "data": null, "success": false}
```

## 9. 业务边界

- ✅ 4 个接口的请求体均接受完整费用明细载荷，成功路径行为与改前完全一致。
- ✅ 请求体为空 / null 仍返回 `584125`，该场景未变。
- ⚠️ 请求体含未知字段会被明确拒绝并返回 `584128`；不要把查询/详情响应里的出参字段（如 `settlementConfirmStatus`）原样 echo 回保存/确认请求体。
- ❌ `expectedSourceFingerprint` 必须是 64 位十六进制字符串，短串或非法字符会被 `584128` 拦截。

## 10. 修改前后对比

### 10.1 字段级对比

成功路径入参/出参字段**无变化**，略。

### 10.2 行为级对比

| 场景 | 原来 | 现在 |
|---|---|---|
| 请求体含未知字段 / 反序列化失败 | `584125 导游或摄影费用请求字段不合法` | `584128 导游或摄影费用请求字段不合法：{具体原因}` |
| Bean 校验失败（字段格式/取值不合法） | `584125`，无具体字段 | `584128`，message 透出 `{字段路径}: {校验提示}` |
| 请求体为空 / null | `584125` | `584125`（不变） |
| 成功保存 / 确认 | `code=200` | `code=200`（不变） |

## 11. 影响评估 / 回滚

### 11.1 影响评估

- **是否破坏向后兼容**：弱破坏。仅错误码语义变化——原来命中 `584125` 的解析/校验失败场景现在返回 `584128`；若前端对 `584125` 做了特判（专属 toast 文案 / 分支逻辑），这些场景将不再命中。
- **前端是否必须同步上线**：不强制。建议直接展示后端 `message`（已含具体字段原因，用户可自助定位），无需为 `584128` 再写翻译表。
- **上线顺序边界**：无顺序要求，新旧前端均可工作。

### 11.2 回滚方案

- 后端回滚后解析/校验失败恢复返回 `584125`，message 不再含具体原因；前端若已改为直显 message，不受影响。

## 12. 注意事项

- 若前端此前对 `584125` 写过特判文案（如「请检查导游费用字段」），请知悉解析/校验失败场景的错误码已变为 `584128`；保留 `584125` 的特判仍覆盖「请求体为空」场景。
- 推荐做法：失败 toast 直接展示后端 `message`，不要按错误码硬编码文案。
- 排查用户报错时，`584128` 的 message 即包含具体字段路径与原因，可直接据此定位，无需找后端查日志。

## 13. 关联 / 联系人

### 13.1 链接

- **Issue**: [#5674](https://git.1814.love:8443/wx/HL/issues/5674)
- **PR**: [#5677](https://git.1814.love:8443/wx/HL/pulls/5677)
- **Commit**: [146cc2ae48](https://git.1814.love:8443/wx/HL/commit/146cc2ae48)

### 13.2 联系人

- **后端负责人**: @yaosutu (yst)
