docs(user): AgreementService.saveByType 漏调 invalidateSource 致 mp 协议缓存不实时 (PR #1917)

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 留底备查,不拉群)