8.9 KiB
产品服务接口契约审计修复（金额 String + 错误码补全 + 删除守卫 + 行程保障禁用端点）— 修改接口 — 管理后台 / 小程序
变更类型：⚠️ 部分行为收紧 + 1 个新增端点（含前端需配合的金额类型/校验/错误码变更） 端类型：管理后台（产品）+ 小程序（mp 产品/定制） 日期：2026-06-16 服务：hl-product-service-v2 PR：wx/HL#3887
⚠️ 关键说明
用接口契约语义审计工作流全量扫描产品服务（hl-product-service-v2）全部 22 个 Controller，逐端点比对「Swagger @ApiOperation 声明的契约 ⨯ 实际实现 ⨯ 业务规则」，对抗复核实锤 50 项「接口能跑但返回值/落库逻辑与契约不符」并修复。已合并 dev-v3、部署测试服、网关 9443 + 真 admin token 实测金额字段已为 String、双实例健康、本地 1513 单测全绿。
下面只列与前端对接相关的变更。最影响前端的是第 1 节（金额字段统一为 JSON 字符串）和第 4 节（新增 1 个端点 + 校验收紧）。
1. 金额字段统一为 JSON 字符串（前端按字符串解析，影响面最广）
产品服务此前有 13 个响应 VO 的金额（BigDecimal）字段直接输出成 JSON 数字（如 1980.00），本次统一加 @JsonSerialize(ToStringSerializer)，改为输出字符串（如 "1980.00"），与平台其它服务及 mp 侧口径一致。
涉及端点（金额字段从 number → string）：
| 端 | 端点 | 受影响金额字段 |
|---|---|---|
| admin | GET /admin/product/item/{id}/schedule/list |
adultPrice/childPrice/toddlerDiscount/infantPrice/singleRoomDiff |
| admin | GET /admin/product/item/{id}/pricing-calendar |
adultPrice/childPrice/toddlerDiscount/infantPrice |
| admin | POST /admin/product/item/{id}/quote |
全部单价/小计/总价/单房差等 |
| admin | GET /admin/product/item/{id}/price-calendar |
adultSellPrice/childSellPrice/toddlerDiscount/infantPrice/singleRoomDiff |
| admin | GET /admin/product/item/{id}/suggest-price |
adultPrice/childPrice/各项成本 |
| admin | GET /admin/product/line/order-picker |
fromPrice |
| mp | POST /mp/product/{id}/quote |
全部金额字段 |
| mp | GET /mp/product/{id} |
startPrice/depositAmount/档位 startPrice·depositAmount |
| mp | GET /mp/product/{id}/schedules |
adultPrice/childPrice/toddlerDiscount/infantPrice |
| mp | GET /mp/product/{id}/price-calendar |
adultPrice/childPrice |
| mp | GET /mp/product-line/list、GET /mp/product-line/{lineId}/products |
startPrice |
| internal | GET /internal/product/{productId}/group-quote、/internal/product/batch-brief 等 |
报价金额字段 |
前端处理：金额一律按字符串接收（用于展示/
Number()/new Decimal()）。绝大多数展示场景无感；若此前对金额字段做了数字运算，请改为先转数值。里程（totalMileage/dailyMileage）等非金额字段不变，仍为数字。
2. 错误码补全 + 规范化（前端按业务码做错误处理）
平台 HTTP 始终 200，业务码在 Result.code。以下为新增/规范化的业务错误码：
| 接口 | 方法 | 新增/变更错误码 | 触发场景 |
|---|---|---|---|
| 批量设置价格日历 | POST /admin/product/item/{id}/price-calendar/batch |
410110 | 档位序号不在产品已配置档位内（原来是通用 500，现为稳定业务码） |
| 温馨提示详情/编辑/删除 | /admin/product/warm-tips/{tipsId} |
440302 | 温馨提示不存在（原来是 404，现为业务码） |
| 删除服务标准模板 | DELETE /admin/product/service-standard-template/{id} |
440401 | 模板已被产品引用，禁止删除（见第 3 节） |
| 删除行程保障模板 | DELETE /admin/travel-guarantee-template/{id} |
440501 | 模板已被产品引用，禁止删除（见第 3 节） |
| 定制产品详情（mp） | /internal/mp/product/custom-completed/{productId} |
480304 | 定制产品不存在（原来是 404，现为业务码） |
| 创建/编辑产品线 | POST /admin/product/line |
notes 补列 440103 / 430201 / 404 / 越权 | 装备模板不存在 / 管理员身份缺失 / 产品线不存在 / 无数据权限 |
| 删除预订条款 / 温馨提示 | DELETE /admin/product/booking-terms/{id}、/warm-tips/{id} |
notes 补列 440201 / 440301 | 被产品引用时拒删（实现一直如此，本次补进文档） |
3. 删除模板引用守卫（收紧，新增拦截）
模板被产品引用时禁止删除（需先解绑），统一四类模板口径。预订条款 / 温馨提示此前已拦截；本次给服务标准 / 行程保障补上同样的守卫：
| 接口 | 被引用时返回 |
|---|---|
DELETE /admin/product/service-standard-template/{id} |
440401（该服务标准模板已被 N 个产品绑定，请先解除绑定再删除） |
DELETE /admin/travel-guarantee-template/{id} |
440501（该行程保障模板已被 N 个产品绑定，请先解除绑定再删除） |
前端处理：删除模板收到 440401/440501 时，提示用户「该模板已被 N 个产品绑定，请先解绑再删除」。
4. 行程保障模板：新增「启用/禁用」端点 + 保存校验收紧
4.1 新增端点（与温馨提示/预订条款一致）
PUT /admin/travel-guarantee-template/{id}/toggle?enabled=true|false
- 作用：启用/禁用行程保障模板。禁用后不再出现在产品设计的「启用下拉」（
listEnabled，enabled=true 才返回）中。 - 此前行程保障模板缺禁用入口（启用态永远到不了），本次补齐。
- 请求示例：
PUT /admin/travel-guarantee-template/1001/toggle?enabled=false，返回Result.success()。
4.2 保存校验收紧
POST /admin/travel-guarantee-template：
items（保障项列表）由「可空」改为必填非空（空数组会被拒绝）。- 每个保障项的
title（标题）必填非空。
前端处理：行程保障模板表单提交前做非空校验（至少一个保障项 + 每项标题不空），避免后端 400。
5. 定制产品 C 端可见性收紧（mp）
/internal/mp/product/custom-completed/{productId}、/custom-completed/batch、/custom-completed/all-page（mp BFF 经 Feign 调用）此前未过滤状态，会把 DRAFT/待审核/已驳回等未完成定制产品也返回给 C 端。本次收紧为仅返回 COMPLETED/ORDERED（与定制产品 C 端可见性规则一致）。
前端影响：小程序定制产品浏览/详情页不再出现未完成的定制产品（此前是 bug）。
6. 其它前端相关
6.1 定制需求状态字典修正（mp）
POST /mp/custom/submit、POST /mp/custom/{requestId}/cancel 的 notes 状态字典此前写的是不存在的 ACCEPTED/DESIGNING/QUOTED/COMPLETED，与实际枚举对不上。实际状态字典为：
PENDING(待处理) / PROCESSING(处理中) / REPLIED(已回复) / CONVERTED(已转化) / CANCELLED(已取消)
取消可执行态为 PENDING / PROCESSING（此前 notes 误写 PENDING/ACCEPTED/DESIGNING）。
前端处理：定制需求状态码→中文映射按上面 5 个真实枚举值；「取消」按钮在 PENDING/PROCESSING 态可用。
6.2 班期「即将满额」状态已实现（mp）
GET /mp/product/{id}/schedules 的 batchStatus 此前字典里有 NEARLY_FULL（即将满额）但实现永不产出。本次实现：剩余名额 ≤ 容量 20% 时返回 NEARLY_FULL。前端可据此展示「即将满额」角标。
6.3 创建快照状态限制取消
POST /admin/product/item/{productId}/snapshots 此前 notes 称「仅 DRAFT/COMPLETED 可保存」，实际任意状态均可保存（同名/上限校验保留）。notes 已对齐实现。
7. 前端 Action 清单
- 金额字段一律按字符串解析（第 1 节），有数字运算的地方先转数值。
- 补充第 2 节各业务错误码的文案/分支处理。
- 删除服务标准/行程保障模板：处理 440401/440501「先解绑」提示（第 3 节）。
- 行程保障模板：可接入新的启用/禁用端点
PUT /{id}/toggle?enabled=；保存表单加保障项/标题非空校验（第 4 节）。 - 定制产品状态映射按真实枚举 PENDING/PROCESSING/REPLIED/CONVERTED/CANCELLED（第 6.1 节）。
- 班期列表可展示「即将满额」(NEARLY_FULL) 态（第 6.2 节）。
8. 关联
| 项目 | 信息 |
|---|---|
| PR | wx/HL#3887（squash 合并 dev-v3，via api-contract-audit workflow） |
| 部署 | 已部署测试服并实测：product-v2 双实例健康；网关 9443 + admin token 调 /admin/product/line/order-picker 实测 fromPrice 已为字符串 "3105.00" |
| 本地测试 | mvn test 全绿（1513 tests，含 H2 集成测试） |
| 错误码段位 | 410110 / 440302 / 440401 / 440501 / 480304（预分配无撞号） |
| 后端负责人 | wx |