first commit

ai/conventions.md

@@ -0,0 +1,33 @@
+# brick-common-cache 编码规范
+
+## 职责边界
+
+cache 模块提供统一的缓存抽象，业务代码只与 `CacheService` 接口交互，不感知底层实现。
+
+## 使用准则
+
+- 所有缓存操作通过 `CacheService`，不得直接注入 Redis/Redisson/Caffeine 客户端。
+- 缓存 Key 统一使用 `CacheKey` 构造，禁止裸字符串拼接。
+- 缓存是可重建的临时数据，不可替代数据库持久化。
+
+## 正例
+
+```java
+@Autowired
+private CacheService cacheService;
+
+CacheKey key = CacheKey.of("user", userId);
+User user = cacheService.get(key, User.class);
+```
+
+## 反例
+
+```java
+// 直接注入底层客户端
+@Autowired
+private RedisTemplate<String, Object> redisTemplate;
+
+// 裸字符串拼接 Key
+String key = "user:" + userId;
+User user = (User) redisTemplate.opsForValue().get(key);
+```

ai/module.yaml

@@ -0,0 +1,13 @@
+module: cache
+summary: 统一缓存访问层，屏蔽具体缓存实现。
+dos:
+  - 所有缓存读写必须通过 CacheService。
+  - 缓存 key 统一通过 CacheKey 构造，禁止裸字符串拼接。
+donts:
+  - 不要在业务代码里直接注入 RedisTemplate / RedissonClient。
+  - 不要把缓存当作数据库，缓存必须可重建。
+examples:
+  - path: src/main/java/{{basePkgPath}}/cache/CacheService.java
+    note: 缓存访问入口。
+  - path: src/main/java/{{basePkgPath}}/cache/CacheKey.java
+    note: 缓存 Key 构造器。