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