123 行
4.1 KiB
Markdown
123 行
4.1 KiB
Markdown
# 文案优化：退款政策校验错误提示人性化（去技术代码/去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)
|
||
```
|
||
|
||
问题：
|
||
1. 带 `FULL`/`DEPOSIT` 英文代码,非技术用户看不懂
|
||
2. 带 `productId`/`refundPolicyId` 内部主键,对用户毫无意义且污染 toast
|
||
3. 不告诉用户"哪条"退款政策不对,只能靠记
|
||
|
||
## 改动范围
|
||
|
||
**只改异常消息文案与服务端日志**,校验规则、接口签名、返回结构、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 提供的：
|
||
```js
|
||
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=...`,需移除相关逻辑
|