From 9b383becdf15b3c91cf83a5396952b5450e3c0de Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 4 Jun 2026 09:32:50 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E9=80=80=E8=B4=B9?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E4=BF=9D=E5=AD=98500=E4=BF=AE=E5=A4=8D?= =?UTF-8?q?=E9=80=9A=E6=8A=A5=20+=20=E6=8F=90=E4=BA=A4=E5=BC=B9=E7=AA=97?= =?UTF-8?q?=E5=AD=97=E6=AE=B5=E6=98=BE=E7=A4=BA=E4=BC=98=E5=8C=96(?= =?UTF-8?q?=E5=89=8D=E7=AB=AF)=20+=20=E6=B5=8B=E8=AF=95=E5=BA=93=E8=A1=A56?= =?UTF-8?q?6=E6=99=AF=E5=8C=BA=E6=95=B0=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...保存500修复+提交弹窗字段显示优化-管理后台.md | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 changelogs-v2/2026-06/04_3428_退费说明保存500修复+提交弹窗字段显示优化-管理后台.md diff --git a/changelogs-v2/2026-06/04_3428_退费说明保存500修复+提交弹窗字段显示优化-管理后台.md b/changelogs-v2/2026-06/04_3428_退费说明保存500修复+提交弹窗字段显示优化-管理后台.md new file mode 100644 index 0000000..a073794 --- /dev/null +++ b/changelogs-v2/2026-06/04_3428_退费说明保存500修复+提交弹窗字段显示优化-管理后台.md @@ -0,0 +1,96 @@ +# 【后端修复 + 前端优化·管理后台】退费说明保存 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 +- **前端对接（管理后台）**：待指派