# 小程序 BFF 接口契约审计修复（金额 String + 字段映射 + 可见性 + 缓存）— 修改接口 — 小程序

> 变更类型：⚠️ 多项修复（金额类型 / 字段补全 / 可见性收紧 / 缓存行为，多数前端正向受益）
> 端类型：小程序（hl-mp-service BFF）
> 日期：2026-06-17
> 服务：hl-mp-service
> PR：https://git.1814.love:8443/wx/HL/pulls/3915

---

## ⚠️ 关键说明

`api-contract-audit` 全量审计小程序 BFF 40 个核心 Controller，对抗复核实锤 100 项契约偏差。mp 是聚合层，本次修复 **mp BFF 自身的 67 处**；另有约 40 项根因在下游服务（订单/用户/资源服务），列在文末「待修清单」，会在后续审计中处理。已合并 dev-v3、部署测试服、双实例健康。

最影响前端的是第 1 节（金额→字符串）和第 2 节（原本恒 null 的字段现已修复）。

---

## 1. 金额字段统一为 JSON 字符串

多个 mp 响应 VO 的金额（BigDecimal）此前输出成 JSON 数字，本次统一改为**字符串**（与平台口径一致）。涉及：退款（退款预览/进度/详情）、发票、订单详情/列表、票务、价格明细（含按人群/优惠/附加费的逐项明细）、保费、推荐产品起价等。

> 前端处理：相关金额字段一律按**字符串**接收；若做过数字运算需先转数值。非金额（里程/经纬度/评分）不变。

---

## 2. 原本恒为 null 的字段已修复（前端可正常取值）

以下字段此前因 BFF 与下游字段名不一致（反序列化失败）或 BFF 未填充而恒为 null，现已修复：

| 模块 | 字段 |
|---|---|
| 相册文件 | thumbnailUrl、fileName、fileSize、createdAt |
| 相册订单 | coverUrl、fileCount |
| 发票详情 | invoiceTitle、taxNumber、createdAt |
| 合同 | 状态日志 *Label、出行人证件类型标签 |
| 出行人 | race、roomGroupNo（订单出行人）、travelerTypeLabel |
| 到达计划 | updateTime |

> 前端处理：这些字段现在会返回真实值，可直接使用（之前拿到的是 null）。

---

## 3. 行为收紧（前端需配合）

### 3.1 下架资源详情不再返回（可见性收紧）
景点 / 酒店 / 餐厅 / 活动 详情接口在 BFF 层补了「是否上架」校验，**下架（status=0）的资源详情不再返回**给小程序（之前会原样返回）。前端访问已下架资源详情会得到「不存在/不可见」，请正常处理空态。

### 3.2 浏览量统计 / 错误不再被缓存
- 探索/百科详情的「浏览量+1」此前在缓存命中时不执行（统计失真），现已修复（浏览量正确累加）。
- BFF 缓存不再缓存下游降级错误（避免 TTL 内持续返回陈旧错误）。
- 前端无感，仅数据更准确。

### 3.3 定制需求状态字典修正
定制（/mp/custom）相关接口的状态字典此前文档值有误，实际枚举为 `PENDING/PROCESSING/REPLIED/CONVERTED/CANCELLED`，请前端按此映射。

---

## 4. 待修清单（根因在下游服务，本次未修，后续处理）

以下问题审计已发现，但根因在下游服务，不在本 PR；记录在此供前端知晓（暂仍按现状）：

- **订单服务（order-v2）相关 ~21 项**：部分字段缺失/状态机/错误码等（其中相册 4 个越权 P0 已由 PR #3911 安全热修修复）。
- **用户服务相关 ~11 项**：出行人默认删除守卫、token 轮转、资料完善校验、足迹 HOTEL 等 — 将在用户服务审计时在源头修复。
- **资源服务相关 ~3 项**：百科推荐排序、足迹等 — 将在资源服务审计时修复。

---

## 5. 前端 Action 清单

1. 第 1 节金额字段按字符串解析。
2. 第 2 节字段现在有值，可接入使用。
3. 下架资源详情做空态处理（第 3.1）。
4. 定制状态映射用真实枚举（第 3.3）。

---

## 6. 关联

| 项目 | 信息 |
|---|---|
| PR | https://git.1814.love:8443/wx/HL/pulls/3915（squash 合并 dev-v3，via api-contract-audit + mp-internal-fix workflow） |
| 部署 | 已部署测试服，mp 双实例健康（滚动重启 uptime 刷新）；公开端点 /mp/banner/active 等返 code:200 |
| 测试 | 963 单测，本次改动 add 0 新失败（另有 3 个 dev-v3 预存红与本次无关，已单独反馈后端） |
| 后端负责人 | wx |
