@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-cache/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: meritdata-platform-cache
+description: |
+  平台缓存（Redis）。CacheManager 配置、@Cacheable 用法、缓存 key 设计（必须包含用户标识）、过期策略、缓存穿透/击穿/雪崩防护、分布式锁。
+  触发场景：需要加缓存提升查询性能；需要分布式锁；需要防缓存雪崩。
+  何时不用：纯业务逻辑 → 用 code-spec；Feign 调用 → 用 data-access。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: medium
+  layer: L3
+  sub-layer: L3-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 平台缓存（cache）
+
+## 触发
+- 列表/详情查询性能差，需要加 Redis 缓存
+- 需要分布式锁防止并发
+- 防止缓存击穿 / 雪崩 / 穿透
+- 需要缓存预热 / 主动刷新
+
+## 不触发
+- 纯业务逻辑 → 用 `meritdata-platform-code-spec`
+- 跨服务数据访问 → 用 `meritdata-platform-data-access`
+- Nacos 配置中心 → 用 `meritdata-platform-nacos-config`
+
+## 前置约束
+- 缓存 key **必须包含用户/租户标识**实现隔离（详见 [rules/performance-rules.md §二](../../rules/performance-rules.md)）
+- 缓存必须有 TTL，防止内存泄漏
+- 敏感数据（密码 / token）**禁止**缓存
+
+## 路由
+- Spring Cache + Redis 接入 → [references/guide.md](references/guide.md)
+- 缓存 key 设计 + 用户隔离 → [references/key-design.md](references/key-design.md)
+- 防穿透 / 击穿 / 雪崩 → [references/resilience.md](references/resilience.md)
+- 分布式锁 → [references/distributed-lock.md](references/distributed-lock.md)

package/skills/meritdata-platform-cache/references/distributed-lock.md

@@ -0,0 +1,199 @@
+# 分布式锁（cache）
+
+> 基于 Redis 的分布式锁实现。防重复提交、防并发修改、防超卖。
+
+---
+
+## 1. 平台封装
+
+平台已封装 `DistributedLock` 接口，二开直接注入即可，不需要自己实现 SETNX。
+
+```java
+@Resource
+private DistributedLock distributedLock;
+```
+
+接口：
+
+```java
+public interface DistributedLock {
+    /**
+     * 尝试加锁
+     * @param key 锁 key
+     * @param waitSeconds 最长等待秒数
+     * @param leaseSeconds 锁自动释放秒数（防死锁）
+     * @return LockHandle（解锁用）
+     */
+    LockHandle tryLock(String key, long waitSeconds, long leaseSeconds);
+
+    /**
+     * 释放锁（必须在 finally 中调用）
+     */
+    void unlock(LockHandle handle);
+}
+```
+
+## 2. 基本用法
+
+### 2.1 防止重复提交
+
+```java
+@PostMapping("/order/submit")
+public Result submit(@RequestBody OrderRequest req) {
+    String userId = SecurityUtils.getCurrentUserId();
+    String lockKey = "lock:order:submit:" + userId;
+
+    LockHandle lock = distributedLock.tryLock(lockKey, 0, 30);
+    if (lock == null) {
+        return Result.error("操作过于频繁，请稍后再试");
+    }
+    try {
+        orderService.submit(req);
+        return Result.success();
+    } finally {
+        distributedLock.unlock(lock);
+    }
+}
+```
+
+### 2.2 防止超卖
+
+```java
+public void deductStock(String skuId, int quantity) {
+    String lockKey = "lock:stock:" + skuId;
+
+    LockHandle lock = distributedLock.tryLock(lockKey, 5, 10);
+    if (lock == null) {
+        throw new BizException("系统繁忙，请重试");
+    }
+    try {
+        int current = stockRepository.getStock(skuId);
+        if (current < quantity) {
+            throw new BizException("库存不足");
+        }
+        stockRepository.deduct(skuId, quantity);
+    } finally {
+        distributedLock.unlock(lock);
+    }
+}
+```
+
+### 2.3 定时任务防并发（多实例部署）
+
+```java
+@Scheduled(cron = "0 0 2 * * ?")
+public void dailyJob() {
+    String lockKey = "lock:job:dailyReport";
+
+    // waitSeconds=0: 不等待，拿不到锁就跳过
+    LockHandle lock = distributedLock.tryLock(lockKey, 0, 3600);
+    if (lock == null) {
+        log.info("另一个实例正在执行 dailyJob，跳过");
+        return;
+    }
+    try {
+        reportService.generate();
+    } finally {
+        distributedLock.unlock(lock);
+    }
+}
+```
+
+## 3. 关键参数
+
+### 3.1 waitSeconds（等待时间）
+
+| 值 | 场景 |
+|----|------|
+| 0 | 不等待，拿不到锁立即失败（防止重复提交） |
+| 1 ~ 5 | 短暂等待（库存扣减） |
+| 30+ | 长时间等待（一般不建议，业务应快速失败） |
+
+### 3.2 leaseSeconds（锁持有时间）
+
+**必须**设置且**必须** < 实际业务执行时间。防宕机导致死锁。
+
+```java
+// ❌ 错：leaseSeconds 不设或太长
+distributedLock.tryLock("key", 0, 99999);  // 30 小时后才会自动释放
+
+// ✅ 正确：根据业务最长执行时间
+distributedLock.tryLock("key", 0, 30);  // 30 秒后自动释放
+```
+
+### 3.3 锁粒度
+
+```java
+// ❌ 错：锁粒度太粗（全部用户一把锁）
+String lockKey = "lock:submit";
+
+// ✅ 正确：按用户隔离
+String lockKey = "lock:submit:" + userId;
+
+// ✅ 正确：按资源隔离
+String lockKey = "lock:stock:" + skuId;
+```
+
+## 4. ❌ 反模式
+
+### 4.1 ❌ 不释放锁
+
+```java
+// ❌ 错：忘记 unlock
+LockHandle lock = distributedLock.tryLock("key", 0, 30);
+if (lock != null) {
+    doSomething();
+    // 漏掉 unlock！
+}
+```
+
+✅ **必须**用 try-finally。
+
+### 4.2 ❌ 在锁内做 HTTP 调用
+
+```java
+// ❌ 错：锁内做远程调用（锁持有时间过长）
+LockHandle lock = distributedLock.tryLock("key", 0, 30);
+try {
+    String data = httpClient.get("https://slow-api.com");  // 慢调用！
+    process(data);
+} finally {
+    distributedLock.unlock(lock);
+}
+```
+
+✅ 锁内**只**做必要的临界区操作。
+
+### 4.3 ❌ 锁粒度过粗导致性能瓶颈
+
+```java
+// ❌ 错：所有订单一把锁
+String lockKey = "lock:order";
+
+// ✅ 正确：按订单 ID 隔离
+String lockKey = "lock:order:" + orderId;
+```
+
+### 4.4 ❌ 自己实现 SETNX
+
+```java
+// ❌ 错：自实现，没有 lease 机制 → 死锁风险
+if (redis.setnx(key, "1")) {
+    // 没有 expire → 如果进程崩溃 → 死锁
+}
+```
+
+✅ 用平台 DistributedLock（内部已用 Lua 脚本保证原子性）。
+
+## 5. Redlock（高级）
+
+需要更高可靠性（如金融场景）时，可考虑 Redlock 算法（多个独立 Redis 实例）。
+
+平台暂未集成，二开需要时使用 [Redisson](https://redisson.org/)。
+
+## 6. 关联阅读
+
+- [guide.md](guide.md) — 缓存基础
+- [resilience.md](resilience.md) — 防穿透/击穿/雪崩
+- [key-design.md](key-design.md) — 缓存 key 设计
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-cache/references/guide.md

@@ -0,0 +1,141 @@
+# 平台缓存指南（cache）
+
+> **核心约束**：缓存 key **必须包含用户/租户标识**；敏感数据禁止缓存；必须有 TTL。
+
+---
+
+## 1. 引入依赖
+
+```xml
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-data-redis</artifactId>
+</dependency>
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-cache</artifactId>
+</dependency>
+```
+
+## 2. application.yml
+
+```yaml
+spring:
+  redis:
+    host: ${REDIS_HOST:localhost}
+    port: ${REDIS_PORT:6379}
+    password: ${REDIS_PASSWORD:}
+    database: 0
+    timeout: 3000
+    lettuce:
+      pool:
+        max-active: 20
+        max-idle: 10
+        min-idle: 5
+        max-wait: 2000
+
+  cache:
+    type: redis
+    redis:
+      time-to-live: 600000      # 默认 TTL 10 分钟
+      cache-null-values: false   # 不缓存 null
+```
+
+## 3. @Cacheable 用法
+
+### 3.1 基本用法
+
+```java
+@Cacheable(value = "user", key = "#userId")
+public UserDTO getById(String userId) {
+    return userRepository.findById(userId).orElse(null);
+}
+```
+
+### 3.2 ✅ 正确：缓存 key 带用户/租户标识
+
+```java
+// ✅ 正确：缓存 key 包含 userId 和 tenantId 实现隔离
+@Cacheable(value = "user", key = "#userId + ':' + T(SecurityUtils).getCurrentTenantId()")
+public UserDTO getById(String userId) { ... }
+
+// ✅ 正确：缓存 key 包含 orgId 实现组织隔离
+@Cacheable(value = "orderList", key = "T(SecurityUtils).getCurrentOrgId() + ':' + #status")
+public List<Order> listByStatus(String status) { ... }
+```
+
+### 3.3 ❌ 反例：缓存 key 全局共享
+
+```java
+// ❌ 错：key 只有 userId → 不同租户的数据混淆
+@Cacheable(value = "user", key = "#userId")
+public UserDTO getById(String userId) { ... }
+
+// ❌ 错：常量 key → 所有人都共享同一份
+@Cacheable(value = "globalConfig", key = "'config'")
+public Config getConfig() { ... }
+```
+
+## 4. 缓存注解
+
+| 注解 | 用途 |
+|------|------|
+| `@Cacheable` | 查：先查缓存，没有再调方法 |
+| `@CachePut` | 改：每次都执行方法，并更新缓存 |
+| `@CacheEvict` | 删：清除缓存 |
+| `@Caching` | 组合多个缓存操作 |
+
+```java
+@Caching(
+    put = @CachePut(value = "user", key = "#user.id"),
+    evict = @CacheEvict(value = "userList", allEntries = true)
+)
+public UserDTO update(UserDTO user) { ... }
+```
+
+## 5. RedisTemplate 用法（精细控制）
+
+```java
+@Autowired
+private StringRedisTemplate redisTemplate;
+
+public void demo() {
+    // 设置（带 TTL）
+    redisTemplate.opsForValue().set("key", "value", Duration.ofMinutes(10));
+
+    // 获取
+    String value = redisTemplate.opsForValue().get("key");
+
+    // 删除
+    redisTemplate.delete("key");
+
+    // 批量删除（按前缀）
+    Set<String> keys = redisTemplate.keys("user:10001:*");
+    redisTemplate.delete(keys);
+}
+```
+
+## 6. 缓存穿透 / 击穿 / 雪崩
+
+详见 [resilience.md](resilience.md)。
+
+## 7. 分布式锁
+
+详见 [distributed-lock.md](distributed-lock.md)。
+
+## 8. ❌ 反模式汇总
+
+| 反模式 | 后果 |
+|--------|------|
+| 缓存 key 无用户标识 | 数据泄露 / 跨租户串数据 |
+| 缓存无 TTL | 内存泄漏 |
+| 缓存敏感数据（密码/token）| 安全风险 |
+| 用 @Cacheable 缓存 null | 缓存穿透 |
+| 缓存更新不及时 | 数据不一致 |
+
+## 9. 关联阅读
+
+- [key-design.md](key-design.md) — 缓存 key 设计
+- [resilience.md](resilience.md) — 防穿透 / 击穿 / 雪崩
+- [distributed-lock.md](distributed-lock.md) — 分布式锁
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-cache/references/key-design.md

@@ -0,0 +1,167 @@
+# 缓存 key 设计规范（cache）
+
+> 缓存 key 是缓存的"身份证"。设计不当 → 数据泄露 / 跨租户串数据 / 缓存失效。
+
+---
+
+## 1. key 命名格式
+
+### 1.1 三段式命名
+
+```
+{业务域}:{资源名}:{业务标识[:扩展标识]}
+```
+
+| 段 | 含义 | 示例 |
+|----|------|------|
+| 业务域 | 模块名（防止不同模块 key 冲突）| `order`、`user`、`config` |
+| 资源名 | 缓存的对象类型 | `info`、`list`、`count` |
+| 业务标识 | 缓存对象的唯一 ID | `userId`、`orderNo` |
+| 扩展标识 | 可选，用于二级隔离 | `tenantId`、`orgId` |
+
+### 1.2 ✅ 正确示例
+
+```java
+// 用户信息（单对象）
+"user:info:" + userId + ":" + tenantId
+
+// 订单列表（按用户 + 状态）
+"order:list:user:" + userId + ":status:" + status + ":" + tenantId
+
+// 字典项（全局但按租户）
+"dict:items:type:" + dictType + ":tenant:" + tenantId
+
+// 配置项（全局共享）
+"config:global:feature_flags"
+```
+
+### 1.3 ❌ 反例
+
+```java
+// ❌ 无业务域前缀（key 冲突风险）
+userId + "_info"
+
+// ❌ 无租户标识（跨租户串数据）
+"user:info:" + userId
+
+// ❌ 把敏感数据放 key
+"user:info:" + userId + ":" + phone  // phone 进 key 可能被日志泄露
+
+// ❌ key 太长（>200 字符）
+"order:list:" + a + ":" + b + ":" + c + ":" + d + ":" + e + ":" + f + ...
+```
+
+## 2. 必须包含的标识
+
+### 2.1 用户级隔离（个人数据）
+
+```java
+// ✅ 正确：key 包含 userId
+"user:info:" + userId
+```
+
+### 2.2 租户/组织级隔离（多租户系统）
+
+```java
+// ✅ 正确：key 包含 tenantId
+"order:list:tenant:" + tenantId + ":user:" + userId
+```
+
+### 2.3 全局共享（无隔离需求）
+
+```java
+// ✅ 正确：配置项等全局数据
+"config:global:datasource"
+```
+
+## 3. TTL 设计
+
+| 数据类型 | 推荐 TTL | 理由 |
+|----------|---------|------|
+| 用户信息 | 10 ~ 30 分钟 | 中等频次更新 |
+| 配置项 | 5 ~ 30 分钟 | 配合 @NacosValue 自动刷新 |
+| 字典项 | 1 ~ 24 小时 | 很少变 |
+| 会话/token | 跟随 token 过期 | 严格匹配 |
+| 临时计算结果 | 1 ~ 5 分钟 | 高频过期 |
+| 列表查询 | 30 秒 ~ 5 分钟 | 频繁变更 |
+
+```java
+// RedisTemplate 设置 TTL
+redisTemplate.opsForValue().set(key, value, Duration.ofMinutes(10));
+
+// @Cacheable 设置 TTL
+@Cacheable(value = "user", key = "#userId", cacheManager = "tenMinutesCacheManager")
+```
+
+## 4. 删除策略
+
+### 4.1 精确删除
+
+```java
+// 删除单个 key
+redisTemplate.delete("user:info:" + userId);
+
+// 删除同前缀的多个 key（慎用 KEYS，性能差）
+Set<String> keys = redisTemplate.keys("user:info:10001:*");
+redisTemplate.delete(keys);
+
+// 推荐：用 SCAN 代替 KEYS
+ScanOptions options = ScanOptions.scanOptions().match("user:info:10001:*").count(100);
+Cursor<byte[]> cursor = redisTemplate.executeWithStickyConnection(
+    connection -> connection.scan(options)
+);
+```
+
+### 4.2 模糊删除（按模式）
+
+```java
+public void evictByPrefix(String prefix) {
+    Set<String> keys = redisTemplate.keys(prefix + "*");
+    if (keys != null && !keys.isEmpty()) {
+        redisTemplate.delete(keys);
+    }
+}
+```
+
+## 5. 序列化
+
+### 5.1 JSON 序列化（推荐）
+
+```java
+@Bean
+public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
+    RedisTemplate<String, Object> template = new RedisTemplate<>();
+    template.setConnectionFactory(factory);
+
+    ObjectMapper mapper = new ObjectMapper();
+    mapper.activateDefaultTyping(
+        mapper.getPolymorphicTypeValidator(),
+        ObjectMapper.DefaultTyping.NON_FINAL,
+        JsonTypeInfo.As.PROPERTY
+    );
+
+    Jackson2JsonRedisSerializer<Object> serializer =
+        new Jackson2JsonRedisSerializer<>(mapper, Object.class);
+
+    template.setKeySerializer(new StringRedisSerializer());
+    template.setValueSerializer(serializer);
+    return template;
+}
+```
+
+### 5.2 序列化选型
+
+| 序列化方式 | 优点 | 缺点 |
+|-----------|------|------|
+| JSON | 可读、跨语言、通用 | 体积较大、性能一般 |
+| Protobuf | 高性能、小体积 | 不可读、需 schema |
+| JDK | 默认 | 体积大、不可读、版本敏感 |
+
+**推荐**：调试阶段用 JSON；性能敏感用 Protobuf。
+
+## 6. 关联阅读
+
+- [guide.md](guide.md) — 缓存基础用法
+- [resilience.md](resilience.md) — 防穿透/击穿/雪崩
+- [distributed-lock.md](distributed-lock.md) — 分布式锁
+- [SKILL.md](../SKILL.md)