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

变更类型：⚠️ 多项修复（金额类型 / 字段补全 / 可见性收紧 / 缓存行为，多数前端正向受益）端类型：小程序（hl-mp-service BFF）日期：2026-06-17 服务：hl-mp-service PR：wx/HL#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 节金额字段按字符串解析。
第 2 节字段现在有值，可接入使用。
下架资源详情做空态处理（第 3.1）。
定制状态映射用真实枚举（第 3.3）。

6. 关联

项目	信息
PR	wx/HL#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

4.3 KiB 原始文件 Blame 文件历史 Unescape Escape