wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

docs(changelog): 核单导游摄影费用解析失败错误码 584125 细化为 584128（#5674）
一些检查失败了
changelog-filename-gate / validate (push) Failing after 2s
详情

浏览代码 
PR #5677 已合并 dev-v3：4 个核单导游/摄影费用接口请求体解析失败/Bean 校验失败
错误码由 584125 细化为 584128，message 透出具体字段原因；请求体为空仍 584125 不变。
这个提交包含在：
yaosutu 2026-08-08 10:56:14 +08:00
父节点 8af962ba55
当前提交 afeb26cf31
共有 1 个文件被更改，包括 236 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

236
changelogs-v2/2026-08/08_5674_导游摄影费用解析透出字段错误-修改接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,236 @@
---
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: "pending"
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)