docs: 轮播图缓存修复 (PR #891, Issue #888)

changelogs/2026-04/2026-04-19_banner-cache-evict-fix.md

@@ -0,0 +1,72 @@
+# fix(user,mp): 轮播图修改后小程序立即生效（修缓存不清导致最长 30min 延迟）
+
+> **服务**: hl-user-service + hl-mp-service
+> **PR**: #891
+> **Issue**: #888
+> **Merge commit**: 已合并到 dev
+> **日期**: 2026-04-19
+> **影响范围**: 管理端修改轮播图后小程序实时性
+> **前端是否需要改动**: **无需改动**（后端行为修复，前端原调用继续工作且立即可见新数据）
+
+---
+
+## 一、背景
+
+管理端 `PUT /admin/banner/{id}` 修改轮播图保存成功后，小程序端 `GET /mp/banner/active` 仍返回旧数据，最长 30 分钟才自动更新。
+
+**前端影响**：如果之前前端有以下 workaround，**现在可以移除**：
+- 强制刷新页面、二次请求、轮询轮播图接口
+- "保存后等一会儿"的用户提示
+
+---
+
+## 二、变更接口
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 前端改动 |
+|---|------|------|------|---------|---------|
+| 1 | 新建/修改/删除轮播图 | POST/PUT/DELETE | `/admin/banner` `/admin/banner/{id}` | **行为修复**：保存立即生效 | 无需 |
+| 2 | 小程序轮播图列表 | GET | `/mp/banner/active` | 缓存 TTL 由 30min 降到 5min | 无需 |
+
+两个接口的请求/响应结构**完全不变**。
+
+---
+
+## 三、修复说明
+
+两层原因叠加导致 bug：
+
+1. **代码层**：`BannerService.create/update/delete` 在 `@Transactional` 事务体内调用缓存清理，事务提交前存在时间窗口，并发读请求把旧数据写回 `mp:banner:active` 开启新 30min TTL
+2. **配置层**：测试环境 Nacos 把 `hl-mp-service-test.yml` 的 `redis.database` 配成 `1`，而 user/resource 服务未显式配置（默认 DB 0），跨 DB 导致 `MpCacheEvict` 一直清不到 mp 缓存
+
+**已修**：
+- 代码：evict 移到 `TransactionSynchronization.afterCommit()` 回调；TTL 30min → 5min（兜底）
+- 配置：Nacos `hl-mp-service-test.yml` 的 `redis.database: 1` 改为 `0`，与其他服务对齐
+
+---
+
+## 四、前端行动项
+
+**无需任何改动**。清理历史 workaround 的列表：
+
+| 可移除的 workaround | 原因 |
+|--------------------|------|
+| 保存轮播图后调用 `refresh()` / 延迟 2 秒重拉 | 后端已立即清缓存 |
+| 本地存储一份"乐观更新"轮播图 | 不再必要 |
+| "请稍后刷新"类 toast 提示 | 可改为"保存成功" |
+
+---
+
+## 五、测试环境已验证
+
+端到端实测（2026-04-19 01:35）：
+
+```bash
+# 步骤 1：PUT banner/5 title="嗨冰雪" → code=200
+# 步骤 2：GET /mp/banner/active → "嗨冰雪" ✓
+# 步骤 3：PUT banner/5 title="嗨冰雪(V2验证)" → code=200
+# 步骤 4：GET /mp/banner/active → "嗨冰雪(V2验证)" ✓ 立即生效
+# 步骤 5：PUT 回滚 title="嗨冰雪" → code=200
+# 步骤 6：GET /mp/banner/active → "嗨冰雪" ✓
+```
+
+后端团队下一步计划：同类"事务内清缓存 + 跨 DB"隐患还存在于 SysDict/FrontendConfig/Hotel/Activity/Scenic/Restaurant 6 个 Service，将以批量 PR 统一抽 `CacheEvictAfterCommit` 公共工具类解决。前端同样**无需改动**。