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);
+```