文案优化：退款政策校验错误提示人性化（去技术代码/去ID）

服务: hl-product-service-v2 (端口 8083) PR: #762 Issue: #761 日期: 2026-04-17 影响范围: 管理端产品 Step5 保存 + 产品上架预检时,退款政策不匹配/不存在的错误提示文案 前置 PR: #755（2026-04-17_refund-policy-apply-pay-type.md）

背景

前置 PR（#755）接入退款政策与产品支付类型的匹配校验后,错误提示对普通运营不友好：

旧：

退款政策支付类型不匹配:产品为 DEPOSIT,政策仅适用于 FULL。请选择匹配的退款政策(productId=2045018534152478721, refundPolicyId=2)

问题：

带 FULL/DEPOSIT 英文代码,非技术用户看不懂
带 productId/refundPolicyId 内部主键,对用户毫无意义且污染 toast
不告诉用户"哪条"退款政策不对,只能靠记

改动范围

只改异常消息文案与服务端日志,校验规则、接口签名、返回结构、HTTP code 全部不变。

前端无需改造,已对接的 toast 显示新文案即可。

文案对照

场景 1：不匹配（最常见）

产品 paymentType	政策 applyPayType	新提示
DEPOSIT	FULL (有政策名「全款默认」)	`退款政策「全款默认」仅适用于全款产品,当前产品为定金,不匹配。请重新选择退款政策`
FULL	DEPOSIT (有政策名「定金退款」)	`退款政策「定金退款」仅适用于定金产品,当前产品为全款,不匹配。请重新选择退款政策`
DEPOSIT	FULL (政策名缺失/null)	`所选退款政策仅适用于全款产品,当前产品为定金,不匹配。请重新选择退款政策`

支付类型代码 FULL/DEPOSIT → 中文「全款」/「定金」
政策带名称时展示 退款政策「xxx」,方便用户定位具体政策
政策名为空时降级为 所选退款政策
不再暴露 productId/refundPolicyId

场景 2：政策不存在/已停用

旧：所选退款政策不存在或已停用: productId=xxx, refundPolicyId=xxx
新：所选退款政策不存在或已停用,请重新选择

场景 3：订单服务 Feign 不可达

不变：退款政策服务暂时不可用,请稍后重试

排查信息的去向

productId/refundPolicyId 从用户可见消息中移除,但仍通过 log.warn 写入后端日志供排查：

WARN  ProductRefundPolicyValidator - 退款政策支付类型不匹配:
      productId=1001, productPayType=DEPOSIT, refundPolicyId=8001, policyPayType=FULL

WARN  ProductRefundPolicyValidator - 退款政策不存在或已停用:
      productId=1001, refundPolicyId=8001

接口影响（均无签名变化）

接口	变化
`PUT /admin/product/item/{id}/supplement`	错误 `message` 文案变更
`GET /admin/product/item/{id}/validate-publish`	`issues` 列表中该类文案变更

HTTP 状态码、code、结构均保持原样。

前端适配建议

无需改代码：直接显示后端返回 message 即可
如果之前对消息内容做过字符串匹配（比如正则提取 productId=...),需要移除相关逻辑 —— 新消息不含 ID

字典值中文映射（如列表展示时用）仍沿用 #755 changelog 提供的：

const applyPayTypeMap = {
  FULL: '仅全款产品',
  DEPOSIT: '仅定金产品',
  BOTH: '全款/定金均可'
};

单元测试

ProductRefundPolicyValidatorTest 13/13 全部通过：

原 12 条覆盖匹配矩阵（FULL/DEPOSIT/BOTH + Feign 异常 + 政策不存在）全部更新断言为中文文案
新增「政策名为空时降级为所选退款政策」用例
新增 hasMessageNotContaining 兜底断言：不再出现 FULL/DEPOSIT/productId/refundPolicyId

部署

仅需重启 hl-product-service-v2（端口 8083 + 8183）
无 DDL 变更
无配置变更

向后兼容性

✅ 接口签名、响应结构、HTTP code 完全不变
✅ 前端可不改代码直接升级
⚠️ 如果前端此前解析过错误消息中的 productId=...,需移除相关逻辑

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