hl-api-changelog/changelogs-v2/2026-08/08_5674_导游摄影费用解析透出字段错误-修改接口-管理后台.md

schema, ticket, title, consumer, change_type, author, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

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

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

PR: #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 典型成功（保存导游费用，入参出参与改前一致）

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

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

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

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

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

null

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

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

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

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

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

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

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

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

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

{"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
• PR: #5677
• Commit: 146cc2ae48

13.2 联系人

• 后端负责人: @yaosutu (yst)