# 产品服务接口契约审计修复（金额 String + 错误码补全 + 删除守卫 + 行程保障禁用端点）— 修改接口 — 管理后台 / 小程序

> 变更类型：⚠️ 部分行为收紧 + 1 个新增端点（含前端需配合的金额类型/校验/错误码变更）
> 端类型：管理后台（产品）+ 小程序（mp 产品/定制）
> 日期：2026-06-16
> 服务：hl-product-service-v2
> PR：https://git.1814.love:8443/wx/HL/pulls/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. **金额字段一律按字符串解析**（第 1 节），有数字运算的地方先转数值。
2. 补充第 2 节各业务错误码的文案/分支处理。
3. 删除服务标准/行程保障模板：处理 440401/440501「先解绑」提示（第 3 节）。
4. 行程保障模板：可接入新的启用/禁用端点 `PUT /{id}/toggle?enabled=`；保存表单加保障项/标题非空校验（第 4 节）。
5. 定制产品状态映射按真实枚举 PENDING/PROCESSING/REPLIED/CONVERTED/CANCELLED（第 6.1 节）。
6. 班期列表可展示「即将满额」(NEARLY_FULL) 态（第 6.2 节）。

---

## 8. 关联

| 项目 | 信息 |
|---|---|
| PR | https://git.1814.love:8443/wx/HL/pulls/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 |