From e196f20b3ce213af305aa813de5e26370e0e5dbf Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 9 May 2026 16:52:22 +0800 Subject: [PATCH] =?UTF-8?q?docs(user):=20AgreementService.saveByType=20?= =?UTF-8?q?=E6=BC=8F=E8=B0=83=20invalidateSource=20=E8=87=B4=20mp=20?= =?UTF-8?q?=E5=8D=8F=E8=AE=AE=E7=BC=93=E5=AD=98=E4=B8=8D=E5=AE=9E=E6=97=B6?= =?UTF-8?q?=20(PR=20#1917)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...ix_user_agreement_save_cache_invalidate.md | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 changelogs/2026-05/09_fix_user_agreement_save_cache_invalidate.md diff --git a/changelogs/2026-05/09_fix_user_agreement_save_cache_invalidate.md b/changelogs/2026-05/09_fix_user_agreement_save_cache_invalidate.md new file mode 100644 index 0000000..ed14bdf --- /dev/null +++ b/changelogs/2026-05/09_fix_user_agreement_save_cache_invalidate.md @@ -0,0 +1,90 @@ +# user/AgreementService: saveByType 漏调 invalidateSource 致 mp 协议缓存 1800s 不更新 + +> **服务**: hl-user-service (端口 8081) +> **PR**: [#1917](https://git.1814.love:8443/wx/HL/pulls/1917) +> **Issue**: 无关联工单 (prod 实战根因修复) +> **日期**: 2026-05-09 +> **影响范围**: 后端纯内部缓存失效逻辑;**API 字段/响应/路径全不变,前端无需任何改动** + +--- + +## ⚠️ 关键变化 + +- 本次只动后端 service 层缓存触发逻辑, **前端 0 改动** +- mp 端 `GET /mp/agreement/detail?type=USER_AGREEMENT|PRIVACY_POLICY` 行为变化:admin 后台保存协议后, mp 立即返回新内容(此前需等 ≤ 1800 秒 TTL 自然过期才生效) +- 不会出现接口字段/路径/状态码/响应壳变化,只是数据"更新及时性"提升 + +--- + +## 一、背景(prod 实战触发) + +2026-05-09 prod 协议数据被误改后,管理员通过 admin API 改回正确值,**但 mp 端继续显示 30 分钟前的旧内容**,最终 SSH redis-cli DEL 三个 mp 协议缓存 key 才即时恢复。 + +复盘根因: + +| 链路 | 期望行为 | 实际行为 | +|------|---------|---------| +| `AgreementService.saveById` 路径 | save → invalidateSource(`agreement`) → mp 缓存依赖链清空 | ✅ 正确 | +| `AgreementService.saveByType` 路径(本次问题) | save → invalidateSource(`agreement`) | ❌ 漏调 | + +`saveByType` 是按 type(`USER_AGREEMENT` / `PRIVACY_POLICY`)写入的分支,有两个落库出口(insert / update),两个分支都漏 schedule 缓存失效;mp 端读路径有 1800s TTL,所以 admin 改完正确数据,mp 仍读到 redis 内旧值。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| - | (无) | - | - | - | API 入参/出参/路径全部 0 改动 | + +--- + +## 三、行为变化(纯后端缓存) + +### admin 端写入 + +`POST /admin/agreement/save-by-type` (`AgreementService.saveByType`) +- 触发链补充:写库成功 → 注册 `cacheEvictAfterCommit.scheduleAfterCommit(depsManager.invalidateSource("agreement"))` → 事务提交后异步清空 `agreement:*` 依赖链上所有 mp 缓存 key + +### mp 端读取(透明,无显式变更) + +- `GET /mp/agreement/detail?type=USER_AGREEMENT` +- `GET /mp/agreement/detail?type=PRIVACY_POLICY` + +读路径与缓存逻辑均**不动**,只是 admin 写之后能立即看到新值。 + +--- + +## 四、不影响范围(显式声明) + +- **仅影响**: admin 保存协议后, mp 协议详情的"实时性" +- **零影响**: + - mp 协议接口字段/路径/响应壳 + - admin 协议保存接口字段/路径/响应壳 + - 协议历史版本逻辑 + - 其他模块缓存(banner / dict / review 等) + - 数据库 schema / DDL + +--- + +## 五、测试环境已验证 + +- 单元测试:`AgreementServiceTest` 新增 2 个 Mockito case,断言 `saveByType` 两个分支(insert / update)都会调用 `cacheEvictAfterCommit.scheduleAfterCommit(...)` +- 回归:`mvn test -pl hl-user-service` 全绿 + +--- + +## 六、相关历史 PR + +| PR | Issue | 说明 | 是否仍有效 | +|----|-------|------|------------| +| (cache-deps 总治理批次) | - | banner / dict / review 等模块迁 cacheEvictAfterCommit + depsManager 的成果 | ✅ 有效 | +| **本 PR #1917** | (无) | 补 `AgreementService.saveByType` 这处遗漏 | ✅ 最新 | + +--- + +## 七、相关文档 + +- 关联 PR: [wx/HL#1917](https://git.1814.love:8443/wx/HL/pulls/1917) +- 关联 commit (squash): `8556ab60` +- 前端通知:**本次后端纯内部 BUG 修复, mmg 不需要做任何前端改动**(changelog 留底备查,不拉群)