# 缓存依赖系统 - 彻底解决管理端改 / MP 不同步

**日期**：2026-04-21（晚）
**PR 链**：#1099（Issue）→ #1102（D1 基础设施）→ #1103（product-v2）→ #1105（mp）→ #1110（user）→ #1111（resource）
**后端**：hl-common-redis / hl-user / hl-resource / hl-product-v2 / hl-mp（已部署测试服）
**影响**：前端基本**零感知**（仅字段新增 `linkUrl`，其它对外接口不变）；**根本解决了管理端编辑后小程序要等 5-30min TTL 才刷新的痛点**

---

## 前端感知变化

### ✅ 唯一新增字段
- `MpHomeScreen2VO.cards[].linkUrl`（已在 2026-04-21_brand-card-link-url-from-dict-remark.md 说明）

### ✅ 其它一切不变
- REST 路径 / 请求体 / 响应体 / 错误码全部**保持兼容**
- 老小程序继续运行不受影响

---

## 缓存行为彻底改变（对前端的关键价值）

**之前**：
```
管理端改字典 / brand-story / banner / 产品 / 酒店 / 景点...
  ↓ 后端清了"自己那层"缓存
  ↓ 但聚合缓存 (home:screen2 / mp:product:detail / ...) 没清
小程序继续读旧缓存, 5-30 min 后 TTL 到了才刷新
```

**现在**：
```
管理端改任意源数据 (表/字典/配置)
  ↓ afterCommit 触发 invalidateSource("table:xxx")
  ↓ Redis 反向索引 cache:deps:index:table:xxx Set 里所有 cache key 被逐个 DEL
小程序下一次 curl 立即拿到新数据 (不等 TTL)
```

**测试服 E2E 已验证**：管理端 PUT `brand-story` 改 title → 立即 curl `/mp/home-config/screen2` → title 已刷新（不等 30min TTL）✅

---

## 不用管的（后端基础设施层）

- `DependencyAwareCacheManager` 新类（共享 Redis 反向索引）
- `MpCacheEvict` 改成 @Deprecated 委托层（老调用继续工作）
- `docs/cache-deps.md` 新文档，后端 PR review 硬卡
- 47 个 `@MpCache` 补 `deps` 数组（mp-service 17 Controller）
- 27 个 resource Service + 9 个 user Service + 8 个 product-v2 Service 写点补 `invalidateSource` 

---

## 回归风险 → 已压实

| 风险 | 压实方式 |
|------|---------|
| 单测回归 | 2117 (resource) + 774 (mp) + 2307 (user) + 112 (product-v2) + 26+3 (common-redis) **全绿** |
| E2E 回归 | 测试服 brand-story → screen2 全链路实测通过 |
| Redis 集群兼容 | 不用 Lua 批量 DEL / 不用 Pipeline, 逐命令（Spring Data Redis cluster 自动路由） |
| SADD 失败降级 | log.warn 不抛, TTL 兜底（最多 30min 自愈） |
| 跨服务联动 | 共享 Redis, 无 MQ/Feign, 零额外基础设施 |
| 业务灰度 | 不引入 Nacos 开关（用户明确要求 "彻底修改"） |

---

## 前端不用改代码

就一条事：**下次看到「管理端改了 MP 没同步」请重新测试，如果还有问题告诉后端**（大概率是某张源表的 deps 没登记，在 `docs/cache-deps.md` 里补上即可，不需要动业务代码）。