From afeb26cf311baeae5592612bfd3a15efe6a407cc Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Sat, 8 Aug 2026 10:56:14 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E6=A0=B8=E5=8D=95=E5=AF=BC?= =?UTF-8?q?=E6=B8=B8=E6=91=84=E5=BD=B1=E8=B4=B9=E7=94=A8=E8=A7=A3=E6=9E=90?= =?UTF-8?q?=E5=A4=B1=E8=B4=A5=E9=94=99=E8=AF=AF=E7=A0=81=20584125=20?= =?UTF-8?q?=E7=BB=86=E5=8C=96=E4=B8=BA=20584128=EF=BC=88#5674=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #5677 已合并 dev-v3：4 个核单导游/摄影费用接口请求体解析失败/Bean 校验失败 错误码由 584125 细化为 584128，message 透出具体字段原因；请求体为空仍 584125 不变。 --- ...影费用解析透出字段错误-修改接口-管理后台.md | 236 ++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 changelogs-v2/2026-08/08_5674_导游摄影费用解析透出字段错误-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/08_5674_导游摄影费用解析透出字段错误-修改接口-管理后台.md b/changelogs-v2/2026-08/08_5674_导游摄影费用解析透出字段错误-修改接口-管理后台.md new file mode 100644 index 0000000..3bc9142 --- /dev/null +++ b/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 +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 +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 +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 +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)