2026-04-21 缓存依赖系统彻底解决管理端改/MP 不同步 (#1099 D1+D3×4)

changelogs/2026-04/2026-04-21_cache-dependency-system.md

@@ -0,0 +1,68 @@
+# 缓存依赖系统 - 彻底解决管理端改 / 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` 里补上即可，不需要动业务代码）。