97 行
4.8 KiB
Markdown
97 行
4.8 KiB
Markdown
# 【后端修复 + 前端优化·管理后台】退费说明保存 500 已修 + 提交确认弹窗字段显示
|
||
|
||
> **PR**: #3429（后端修复）| **关联工单**: #3428
|
||
> **服务**: hl-resource-service | **更新时间**: 2026-06-04
|
||
>
|
||
> **存放目录**: `changelogs-v2/2026-06/`
|
||
> **影响范围**: 管理后台「编辑景区 / 活动 → 退费说明」tab；前端列表行「确认提交修改」弹窗
|
||
|
||
---
|
||
|
||
## ⚠️ 关键说明
|
||
|
||
1. **后端 bug 已修（前端可重测）**：景区/活动「退费说明」保存**带「生效起 / 生效止」日期**的退费明细时报 500，现已修复并部署测试服。接口契约**未变**，前端无需改调用方式，重新走原保存流程即可。
|
||
2. **前端待优化（§2）**：列表「确认提交修改」弹窗里 `refundNote` 字段显示为英文字段名 + 值「[复杂对象]」，普通运营看不懂，建议改为中文标签「退费说明」+ 可读摘要。
|
||
3. **测试数据已补**：已给测试库 **66 个景区**全部补充退费说明示例数据（每个 3 条明细，含带日期明细），方便前端联调展示。
|
||
|
||
---
|
||
|
||
## 1. 后端修复说明
|
||
|
||
### 现象
|
||
「编辑景区 → 退费说明」填入带「生效起 / 生效止」日期的退费明细，点保存 → 500：
|
||
```
|
||
服务器内部错误[MyBatisSystemException]: org.apache.ibatis.type.TypeException:
|
||
Could not set parameters for mapping: Para...
|
||
```
|
||
不填日期则保存成功。这也是此前测试库退费说明（带日期）一直存不进的原因。
|
||
|
||
### 根因
|
||
退费明细数组（`items`）以 JSON 列存库（MyBatis-Plus JacksonTypeHandler），明细条目含 `effectiveFrom` / `effectiveTo`（LocalDate）。MP 默认的 JacksonTypeHandler ObjectMapper 未注册 JavaTimeModule，序列化 Java 8 时间类型抛异常，在写库参数阶段表现为「Could not set parameters」→ 500。
|
||
|
||
### 修复
|
||
hl-resource-service 给 JacksonTypeHandler 配置注册了 JavaTimeModule 的 ObjectMapper（日期以 ISO 字符串 `yyyy-MM-dd` 存储），纯加性修复，不改接口契约。
|
||
|
||
### 受影响接口（契约不变，仅恢复正常保存）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| PUT | `/admin/refund-note` | 退费说明独立保存（upsert） |
|
||
| PUT | `/admin/scenic/spot/{scenicId}` | 景区编辑（融合 refundNote 字段） |
|
||
| PUT | `/admin/activity/...`（编辑） | 活动编辑（融合 refundNote 字段） |
|
||
|
||
### 测试服实测（已通过）
|
||
- 带生效起止日期保存 → **200**，回读确认 `effectiveFrom/effectiveTo` 正确落库、`settleScopeLabel` 正常拼装（如「按人」）
|
||
- 不带日期保存 → **200**（不回归）
|
||
|
||
---
|
||
|
||
## 2. 前端待优化：「确认提交修改」弹窗字段显示
|
||
|
||
### 现状（截图）
|
||
列表行编辑提交时的「确认提交修改」弹窗，对 `refundNote` 字段显示为：
|
||
|
||
| 字段 | 原值 | 新值 |
|
||
|---|---|---|
|
||
| `refundNote` | [复杂对象] | [复杂对象] |
|
||
|
||
两个问题：
|
||
1. **字段名是英文 `refundNote`** —— 运营看不懂，应显示中文「退费说明」。
|
||
2. **值显示「[复杂对象]」** —— 退费说明是结构化对象（整体介绍 + 明细数组），无法直接 diff，建议给个可读摘要而非「复杂对象」。
|
||
|
||
### 期望
|
||
|
||
| 字段 | 期望显示 |
|
||
|---|---|
|
||
| 字段名 | 「退费说明」（中文标签，建议前端维护字段 key → 中文名映射表） |
|
||
| 值 | 可读摘要，如「整体介绍 + N 条明细」，或直接提示「退费说明已修改（点开退费说明 tab 查看）」，避免「复杂对象」字样 |
|
||
|
||
> 说明：`refundNote` 是后端字段 key，后端不下发中文标签；字段名→中文、复杂对象的友好展示属前端渲染逻辑。其他类似的结构化对象字段（如未来的多媒体、行程节点等）建议一并按此约定处理。
|
||
|
||
---
|
||
|
||
## 3. 测试数据
|
||
|
||
已通过 `PUT /admin/refund-note` 给测试库 **全部 66 个景区**补充退费说明示例数据：
|
||
- 整体介绍：「退改规则如下，赠送项目不退费，具体以下方明细为准。」
|
||
- 明细 3 条：出发前 7 天以上（0/人，全额退款）/ 出发前 3-6 天（30/人，带生效起止 2026-01-01~2026-12-31）/ 出发前 48 小时内（100/人，不可退）
|
||
|
||
前端可直接在景区编辑页「退费说明」tab 看到回显数据联调。
|
||
|
||
---
|
||
|
||
## 4. 前端动作
|
||
|
||
1. **重测退费说明保存**：带生效起止日期的明细现可正常保存（原 500 已修）。
|
||
2. **优化提交确认弹窗**（§2）：`refundNote` → 中文「退费说明」；值「[复杂对象]」→ 可读摘要。
|
||
3. 联调可用测试库已补的 66 个景区退费说明数据。
|
||
|
||
---
|
||
|
||
## 5. 关联 / 联系人
|
||
|
||
- **后端修复 PR**：#3429（Closes #3428）
|
||
- **退费说明模块接口契约**：见同目录退费说明相关 changelog
|
||
- **后端负责人**：@wx
|
||
- **前端对接（管理后台）**：待指派
|