产品服务错误提示批量人性化 (去英文状态码+去内部ID) - PR #765
这个提交包含在：
API Changelog Bot
父节点
317db70fd8
当前提交
30e337b920
@ -0,0 +1,159 @@
|
||||
# 文案优化：产品服务错误提示批量人性化（去英文状态码/去内部ID）
|
||||
|
||||
> **服务**: hl-product-service-v2 (端口 8083)
|
||||
> **PR**: #765
|
||||
> **Issue**: #764
|
||||
> **日期**: 2026-04-17
|
||||
> **影响范围**: 管理端产品删除/编辑/价格配置/班期管理 + 小程序端报价/库存扣减/报名 的错误提示文案
|
||||
> **前置 PR**: #762（2026-04-17_refund-policy-error-message-humanize.md）
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
延续 #762 的思路,对 `hl-product-service-v2` 里其他对用户可见的 `BusinessException` / `NotFoundException` 文案做一轮批量改造,避免向普通运营展示:
|
||||
|
||||
1. **英文状态码**(`PUBLISHED` / `PENDING_REVIEW` / `DRAFT` 等)
|
||||
2. **内部主键 ID**(`productId=2045018xxx` / `batchId=xxx` 等)
|
||||
3. **开发术语**(如"调用此接口")
|
||||
|
||||
技术 ID 全部下沉到 `log.warn` 供后端排查,不再污染用户 toast。
|
||||
|
||||
## 改动范围
|
||||
|
||||
**只改异常消息文案与服务端日志**,校验规则、接口签名、返回结构、HTTP code 全部不变。
|
||||
前端**无需改造**,toast 显示新文案即可。
|
||||
|
||||
---
|
||||
|
||||
## 文案前后对照
|
||||
|
||||
### 产品删除/编辑状态校验
|
||||
|
||||
| 场景 | 旧文案 | 新文案 |
|
||||
|------|--------|--------|
|
||||
| 已上架产品删除 | `当前状态不允许删除: PUBLISHED` | `当前状态「已上架」不允许删除` |
|
||||
| 已下单产品编辑 | `当前状态不允许编辑: ORDERED` | `当前状态「已下单」不允许编辑` |
|
||||
| 待审核产品编辑 | `当前状态不允许编辑: PENDING_REVIEW` | `当前状态「待审核」不允许编辑` |
|
||||
|
||||
状态码→中文映射表(通过新增的 `ProductStatusEnum.nameOfOrCode` 容错方法):
|
||||
|
||||
| code | 中文 |
|
||||
|------|------|
|
||||
| DRAFT | 草稿 |
|
||||
| PENDING_REVIEW | 待审核 |
|
||||
| PUBLISHED | 已上架 |
|
||||
| UNPUBLISHED | 已下架 |
|
||||
| REJECTED | 已驳回 |
|
||||
| COMPLETED | 已完成 |
|
||||
| ORDERED | 已下单 |
|
||||
| `null` / 空 | 未知 |
|
||||
| 未知值 | 原值回显(降级) |
|
||||
|
||||
### 价格日历/成人售价
|
||||
|
||||
| 场景 | 旧文案 | 新文案 |
|
||||
|------|--------|--------|
|
||||
| 价格日历缺失 | `日期 xxx 档位1 未设置价格日历（产品ID=2045018xxx）` | `日期 xxx 档位1 未设置价格日历,请先配置价格` |
|
||||
| 成人售价未设置 | `日期 xxx 档位1 的成人售价未设置（产品ID=2045018xxx）` | `日期 xxx 档位1 的成人售价未设置,请先配置价格` |
|
||||
|
||||
### 班期管理
|
||||
|
||||
| 场景 | 旧文案 | 新文案 |
|
||||
|------|--------|--------|
|
||||
| 班期不存在(查询/删除/修改/取消/配员) | `班期不存在: 20450185xxx` | `班期不存在或已删除` |
|
||||
|
||||
### 库存与报名(InternalProductService,被 order-service-v2 Feign 调用)
|
||||
|
||||
| 场景 | 旧文案 | 新文案 |
|
||||
|------|--------|--------|
|
||||
| 库存扣减失败 | `库存不足或日期不存在, productId=xxx, date=2026-05-10` | `该日期库存不足或未开放,请重新选择出发日期` |
|
||||
| 报名入团失败 | `报名失败（名额不足或房间不足）, batchId=xxx` | `报名失败,该班期剩余名额或房间不足` |
|
||||
| 非定制产品调用 | `仅定制产品可调用此接口, productId=xxx` | `该操作仅支持定制类产品` |
|
||||
|
||||
---
|
||||
|
||||
## 接口影响(均无签名变化)
|
||||
|
||||
| 接口 | 变化 |
|
||||
|------|------|
|
||||
| `DELETE /admin/product/item/{id}` | 错误 `message` 文案变更 |
|
||||
| `PUT /admin/product/item/{id}/*`(所有编辑类接口) | 状态拒绝文案变更 |
|
||||
| `POST /admin/product/price-calendar/batch` | 价格相关文案变更 |
|
||||
| `POST/PUT/DELETE /admin/product/schedule/*` | 班期不存在文案变更 |
|
||||
| `POST /admin/product/schedule/team/*` | 班期不存在文案变更 |
|
||||
| `POST /internal/product/simple-quote` | 成人售价文案变更 |
|
||||
| `POST /internal/product/deduct-stock` | 库存扣减失败文案变更 |
|
||||
| `POST /internal/product/enroll-batch` | 报名失败文案变更 |
|
||||
| `POST /internal/product/custom/change-status` | 非定制产品文案变更 |
|
||||
|
||||
HTTP 状态码、`code`、JSON 结构均保持原样。
|
||||
|
||||
---
|
||||
|
||||
## 保留未改的文案
|
||||
|
||||
以下文案**主动保留**,因为它们不属于"不友好"范畴:
|
||||
|
||||
1. **公式编辑器**(FormulaGroupService / FormulaStepService / FormulaVarService)
|
||||
- 例如:`公式组编码已存在: {code}` / `变量名已存在: {name}`
|
||||
- 原因:公式编辑功能的使用者是技术人员,编码本身就是用户自己输入的值,回显是必要上下文
|
||||
2. **纯中文/数字约束类**
|
||||
- `请填写【轻奢】正价的成人售价` — 档位名+价格类型 label 均为中文
|
||||
- `档位序号99不存在,本产品只有5档` — 数字是必要定位信息
|
||||
- `该班期已有3个报名订单,不允许删除` — 数字为必要业务信息
|
||||
- `批量创建跨度不能超过12个月`
|
||||
- `小童优惠额不能超过儿童售价`
|
||||
|
||||
---
|
||||
|
||||
## 排查信息的去向
|
||||
|
||||
所有移除的 ID/代码都下沉到 `log.warn`,后端排查时通过日志+时间戳即可定位:
|
||||
|
||||
```
|
||||
WARN ProductDeleteService - 产品当前状态不允许删除: productId=1001, status=PUBLISHED
|
||||
WARN ProductHelperService - 产品当前状态不允许编辑: productId=1001, status=ORDERED
|
||||
WARN ProductPricingService - 价格日历未设置: productId=1001, date=2026-05-10, tierSeq=1
|
||||
WARN ProductPricingService - 成人售价未设置: productId=1001, date=2026-05-10, tierSeq=1
|
||||
WARN ProductPricingService - 班期不存在(删除): productId=1001, batchId=8001
|
||||
WARN GroupBatchStaffService - 班期不存在(操作员工): productId=1001, batchId=8001
|
||||
WARN InternalProductService - 库存扣减失败: productId=1001, date=2026-05-10, count=2
|
||||
WARN InternalProductService - 报名入团失败: batchId=8001, people=2, rooms=1
|
||||
WARN InternalProductService - 非定制产品调用定制产品状态变更: productId=1001, productType=CORE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 前端适配建议
|
||||
|
||||
- **无需改代码**:直接显示后端返回 `message` 即可
|
||||
- 如果之前对 error message 做过字符串匹配/正则提取 `productId=...`、`batchId=...`、英文状态码等,需要移除相关逻辑 —— 新消息不含这些
|
||||
- 状态码中文展示(如果前端自己有映射表)可以沿用本 changelog 顶部的对照表
|
||||
|
||||
---
|
||||
|
||||
## 单元测试
|
||||
|
||||
- `ProductStatusEnumTest` — 新增 3 个用例(合法/null/未知),共 11 个全部通过
|
||||
- `ProductHelperServiceTest` — 强化「checkEditable PUBLISHED/PENDING_REVIEW」用例断言:必须含中文状态名、必须不含英文码
|
||||
- `ProductDeleteServiceTest` — 强化「deleteProduct PUBLISHED」用例断言:必须含「已上架」、必须不含 `PUBLISHED`
|
||||
- `GroupBatchStaffServiceTest` — 强化「queryTeam 班期不存在」用例断言:必须含「班期不存在或已删除」、必须不含 batchId
|
||||
- 受影响测试合计 98/98 通过(覆盖 7 个测试类)
|
||||
|
||||
---
|
||||
|
||||
## 部署
|
||||
|
||||
- 仅需重启 `hl-product-service-v2`(端口 8083 + 8183)
|
||||
- 无 DDL 变更
|
||||
- 无配置变更
|
||||
|
||||
---
|
||||
|
||||
## 向后兼容性
|
||||
|
||||
- ✅ 接口签名、响应结构、HTTP code 完全不变
|
||||
- ✅ 前端可不改代码直接升级
|
||||
- ✅ `ProductStatusEnum.nameOfOrCode` 容错降级(未知状态码原值回显,新状态加入枚举前不会挂)
|
||||
- ⚠️ 如果前端之前解析过错误消息中的 `productId=` / `batchId=` / 英文状态码,需要移除相关逻辑
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户