ai-engineering-init 1.4.3 → 1.6.0

package/src/skills/project-navigator/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: project-navigator
+description: |
+  当需要了解项目结构、查找文件、定位代码时自动使用此 Skill。提供 leniu 云食堂项目的精确导航。
+
+  触发场景：
+  - 询问某个功能/文件在哪里
+  - 新建模块时需要确认目录位置
+  - 查找参考代码（Controller/Service/Mapper/Entity 示例）
+  - 了解项目整体结构和模块划分
+  - 查找技能、命令、Hook 的位置
+
+  触发词：项目结构、文件在哪、代码位置、目录结构、模块在哪、参考代码、怎么找、哪个文件、路径、在哪里
+---
+
+# leniu 项目导航指南
+
+## 工程化配置项目
+
+```
+ai-engineering-init/      # 当前工作目录（本仓库根目录）
+├── CLAUDE.md              # 项目规范（核心约束必读）
+├── AGENTS.md              # Agent 配置文档
+├── .claude/
+│   ├── skills/            # 73 个技能模块
+│   ├── commands/          # 10 个快速命令（/dev /crud /check 等）
+│   ├── hooks/             # Hooks（skill-forced-eval.js 强制技能评估）
+│   └── docs/              # 开发文档
+└── .codex/skills/         # Codex CLI 技能同步目录
+```
+
+---
+
+## 后端 Java 项目
+
+**根路径**：由用户在 `CLAUDE.md` 中配置，各安装者路径不同
+
+### 业务模块（25 个 core-* 模块）
+
+| 模块 | 职责 |
+|------|------|
+| `core-order` | 订单管理 |
+| `core-menu` | 菜品管理 |
+| `core-marketing` | 营销（充值/优惠） |
+| `core-report` | 报表统计 |
+| `core-pay` | 支付 |
+| `core-account` | 账号管理 |
+| `core-merchant` | 商户配置 |
+| `core-customer` | 用户/员工 |
+| `core-device` | 设备管理 |
+| `core-attendance` | 考勤 |
+| `core-kitchen` / `core-backfield` | 后场厨房 |
+| `core-drp` | 供应链 |
+| `core-dorm` | 宿舍管理 |
+| `core-notice` | 通知消息 |
+| `core-open` | 开放接口 |
+| `core-nutrition` | 营养管理 |
+| `core-supermarket` | 超市 |
+| `core-common` / `core-base` | 公共基础 |
+| `core-auth` / `core-starter` | 认证/启动 |
+
+### 标准包结构（四层架构）
+
+```
+net.xnzn.core.{module}/
+├── controller/
+│   ├── web/          # Web 管理端（/api/v2/web/{module}）
+│   ├── mobile/       # 移动端（/api/v2/mobile/{module}）
+│   ├── android/      # 设备端（/api/v2/android/{module}）
+│   └── open/         # 开放接口（/api/v2/open/{module}）
+├── business/impl/    # Business 层（跨 Service 编排）
+├── service/impl/     # Service 层（单表 CRUD、事务）
+├── mapper/           # Mapper + XML（同目录！非 resources/mapper/）
+├── model/            # Entity
+├── vo/               # 响应对象
+├── dto/              # 请求参数（含 Param）
+├── constants/        # 枚举、常量
+├── mq/               # 消息队列
+└── task/             # 定时任务
+```
+
+### 参考代码位置
+
+| 需要参考 | 路径 |
+|---------|------|
+| Controller 写法 | `core-order/.../order/web/controller/OrderInfoWebController.java` |
+| Business 层写法 | `core-order/.../order/web/business/impl/OrderWebBusiness.java` |
+| Service 写法 | `core-order/.../order/common/service/impl/OrderInfoService.java` |
+| Entity 写法 | `core-order/.../order/common/model/OrderInfo.java` |
+| 枚举写法 | `core-order/.../order/common/constants/OrderStateEnum.java` |
+| 配置文件 | `core-base/src/main/resources/bootstrap.yml` |
+
+---
+
+## 前端项目
+
+**根路径**：由用户在 `CLAUDE.md` 中配置，各安装者路径不同
+
+### src/ 核心目录
+
+| 目录 | 说明 | 规模 |
+|------|------|------|
+| `api/` | 接口定义 | 63 个文件 |
+| `leniuview/` | 业务模块页面 | 33 个模块 |
+| `leniu-components/` | 业务组件库 | 12 个组件包 |
+| `components/` | 通用组件 | ~87 个 |
+| `store/` | Vuex 状态管理 | 30+ 个模块 |
+| `utils/` | 工具函数 | 37 个文件 |
+
+### 常用前端文件
+
+| 需要查找 | 路径 |
+|---------|------|
+| 主入口 | `src/main.js` |
+| 权限路由守卫 | `src/permission.js` |
+| 请求封装 | `src/utils/request.js` |
+| Token/租户工具 | `src/utils/auth.js` |
+| 全局工具 | `src/utils/index.js` |
+| Vuex 根配置 | `src/store/index.js` |
+| 构建配置 | `vue.config.js` |
+
+### 前端业务模块（leniuview 33 个）
+
+```
+accountCenter、canteenBackcourt、cost、dashboard、dataScreen、
+deviceMange、dormitory、marketing、menudish、orderCenter、
+purchase、reportCenter、stock、supplyChain、attendance、
+campus、approvalManage、noticeV2、personalV2 ...
+```
+
+---
+
+## 技能系统导航
+
+**技能路径**：`.claude/skills/{技能名}/SKILL.md`
+
+### 按开发场景选择技能
+
+| 场景 | 技能 |
+|------|------|
+| 新建 CRUD 模块 | `leniu-crud-development` |
+| API 接口设计 | `leniu-api-development` |
+| 建表/SQL | `leniu-database-ops` |
+| Entity/VO/DTO | `leniu-java-entity` |
+| MyBatis/Mapper | `leniu-java-mybatis` |
+| 异常处理 | `leniu-error-handler` |
+| 工具类使用 | `leniu-utils-toolkit` |
+| 注解使用 | `leniu-backend-annotations` |
+| 代码规范 | `leniu-code-patterns` |
+| 数据权限/双库 | `leniu-data-permission` |
+| 定制报表 | `leniu-report-customization` |
+| 标准报表 | `leniu-report-standard-customization` |
+| 金额处理 | `leniu-java-amount-handling` |
+| 并发/异步 | `leniu-java-concurrent` |
+| 导出功能 | `leniu-java-export` |
+| 定时任务 | `leniu-java-task` |
+| 消息队列 | `leniu-java-mq` |
+| Redis 缓存 | `leniu-redis-cache` |
+| 合计行查询 | `leniu-java-total-line` |
+| 报表查询入参 | `leniu-java-report-query-param` |
+| 营销计费规则 | `leniu-marketing-price-rule-customizer` |
+| 营销充值规则 | `leniu-marketing-recharge-rule-customizer` |
+| 餐次处理 | `leniu-mealtime` |
+| 定制开发位置 | `leniu-customization-location` |
+| Bug 排查 | `bug-detective`（数据问题自动联动 `mysql-debug`） |
+| 数据库查询验证 | `mysql-debug` |
+| Codex 代码审查 | `codex-code-review` |
+| 前端组件/权限 | `ui-pc` |
+| 前端 Vuex | `store-pc` |
+| 方案设计 | `leniu-brainstorm` |
+| 架构设计 | `leniu-architecture-design` |
+| 安全认证 | `leniu-security-guard` |
+
+### 快速命令
+
+| 命令 | 用途 |
+|------|------|
+| `/dev` | 开发新功能 |
+| `/crud` | 快速生成 CRUD |
+| `/check` | 代码规范检查 |
+| `/start` | 项目快速了解 |
+| `/progress` | 查看项目进度 |
+| `/next` | 下一步建议 |
+| `/add-todo` | 添加待办事项 |
+
+---
+
+## 常用搜索模式
+
+```bash
+# 查找某模块的 Controller
+Glob core-order/**/*Controller*.java
+
+# 查找 Service 实现类
+Glob core-order/**/impl/*Service*.java
+
+# 查找 Mapper XML
+Glob core-order/**/*Mapper.xml
+
+# 查找 Entity
+Glob core-order/**/model/*.java
+
+# 查找某接口路由
+Grep "/api/v2/web/order" --type java
+
+# 查找前端某页面
+Glob src/leniuview/**/index.vue
+
+# 查找前端接口定义
+Glob src/api/*.js
+```

package/src/skills/redis-cache/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: redis-cache
+description: |
+  当需要使用Redis缓存、分布式锁、限流等功能时自动使用此Skill。包含RedisUtils工具类、CacheUtils工具类、缓存注解使用规范、分布式锁实现、缓存key命名规范等。
+
+  触发场景：
+  - 使用Redis缓存数据
+  - 配置Spring Cache缓存注解
+  - 实现分布式锁
+  - 实现接口限流
+  - Redis发布订阅
+  - 缓存key设计和命名
+  - 缓存清理和刷新
+
+  触发词：Redis、缓存、Cache、@Cacheable、@CacheEvict、@CachePut、RedisUtils、CacheUtils、分布式锁、RLock、限流、RateLimiter、发布订阅、缓存key、缓存过期
+
+  核心警告：
+  - @Cacheable返回值不能使用不可变集合（List.of()、Set.of()、Map.of()）
+  - 分布式锁必须在finally中释放，且需注入RedissonClient（RedisUtils无getLock）
+  - keys()和deleteKeys()会忽略租户隔离
+---
+
+# Redis 缓存开发指南
+
+> 模块位置：`ruoyi-common/ruoyi-common-redis`
+
+## 快速索引
+
+| 功能 | 工具类/注解 | 说明 |
+|------|-------------|------|
+| 对象缓存 | `RedisUtils.setCacheObject()` | 基于 Redisson |
+| 集合缓存 | `RedisUtils.setCacheList/Set/Map()` | List/Set/Map 操作 |
+| Spring Cache | `CacheUtils.get/put/evict()` | Spring Cache 封装 |
+| 缓存注解 | `@Cacheable/@CachePut/@CacheEvict` | 声明式缓存 |
+| 分布式锁 | `redissonClient.getLock()` | 需注入 RedissonClient |
+| 限流控制 | `RedisUtils.rateLimiter()` | 基于 Redisson |
+| 原子操作 | `RedisUtils.incrAtomicValue()` | 原子递增/递减 |
+| 发布订阅 | `RedisUtils.publish/subscribe()` | 消息通信 |
+
+---
+
+## 一、RedisUtils 工具类
+
+```java
+import org.dromara.common.redis.utils.RedisUtils;
+```
+
+### 1.1 基础缓存操作
+
+```java
+RedisUtils.setCacheObject("user:123", userObj);                              // 永不过期
+RedisUtils.setCacheObject("user:123", userObj, Duration.ofMinutes(30));      // 带过期时间
+RedisUtils.setCacheObject("user:123", userObj, true);                        // 保留原有TTL（Redis 6.0+）
+boolean ok = RedisUtils.setObjectIfAbsent("user:123", userObj, Duration.ofMinutes(30));  // 不存在时设置
+boolean ok = RedisUtils.setObjectIfExists("user:123", userObj, Duration.ofMinutes(30));  // 存在时设置
+
+User user = RedisUtils.getCacheObject("user:123");          // 获取
+long ttl = RedisUtils.getTimeToLive("user:123");            // TTL毫秒（-1永不过期，-2不存在）
+boolean deleted = RedisUtils.deleteObject("user:123");      // 删除
+RedisUtils.deleteObject(Arrays.asList("user:123", "user:456"));  // 批量删除
+boolean exists = RedisUtils.isExistsObject("user:123");     // 是否存在
+RedisUtils.expire("user:123", Duration.ofMinutes(30));      // 设置过期
+```
+
+### 1.2 集合操作
+
+```java
+// List
+RedisUtils.setCacheList("myList", dataList);
+RedisUtils.addCacheList("myList", "item3");
+List<String> result = RedisUtils.getCacheList("myList");
+List<String> range = RedisUtils.getCacheListRange("myList", 0, 10);
+
+// Set
+RedisUtils.setCacheSet("mySet", dataSet);
+boolean added = RedisUtils.addCacheSet("mySet", "value3");
+Set<String> result = RedisUtils.getCacheSet("mySet");
+
+// Map
+RedisUtils.setCacheMap("myMap", dataMap);
+RedisUtils.setCacheMapValue("myMap", "key3", "value3");
+String value = RedisUtils.getCacheMapValue("myMap", "key1");
+Map<String, Object> result = RedisUtils.getCacheMap("myMap");
+Set<String> keys = RedisUtils.getCacheMapKeySet("myMap");
+RedisUtils.delCacheMapValue("myMap", "key1");
+RedisUtils.delMultiCacheMapValue("myMap", new HashSet<>(Arrays.asList("key1", "key2")));
+Map<String, Object> values = RedisUtils.getMultiCacheMapValue("myMap", keySet);
+```
+
+### 1.3 发布订阅
+
+```java
+RedisUtils.publish("notification:channel", messageObj);
+RedisUtils.publish("notification:channel", messageObj, msg -> { log.info("已发布: {}", msg); });
+RedisUtils.subscribe("notification:channel", MessageDTO.class, msg -> { /* 处理消息 */ });
+```
+
+### 1.4 限流控制
+
+```java
+import org.redisson.api.RateType;
+
+// 每10秒最多100个请求
+long remaining = RedisUtils.rateLimiter("api:limit:user:123", RateType.OVERALL, 100, 10);
+if (remaining == -1) {
+    throw new ServiceException("请求过于频繁");
+}
+
+// 带超时版本（5秒超时）
+long remaining = RedisUtils.rateLimiter("api:limit:user:123", RateType.OVERALL, 100, 10, 5);
+```
+
+### 1.5 原子操作
+
+```java
+RedisUtils.setAtomicValue("counter:view", 0L);
+long value = RedisUtils.getAtomicValue("counter:view");
+long newVal = RedisUtils.incrAtomicValue("counter:view");
+long newVal = RedisUtils.decrAtomicValue("counter:view");
+```
+
+### 1.6 Key 操作
+
+```java
+// ⚠️ keys() 和 deleteKeys() 会忽略租户隔离
+Collection<String> keys = RedisUtils.keys("user:*");
+
+KeysScanOptions options = KeysScanOptions.defaults().pattern("user:*").chunkSize(1000).limit(100);
+Collection<String> keys = RedisUtils.keys(options);
+
+RedisUtils.deleteKeys("temp:*");
+Boolean exists = RedisUtils.hasKey("user:123");
+```
+
+### 1.7 监听机制
+
+详见 [references/listeners.md](references/listeners.md)
+
+---
+
+## 二、CacheUtils 工具类
+
+```java
+import org.dromara.common.redis.utils.CacheUtils;
+
+CacheUtils.put("userCache", "user:123", userObj);       // 保存
+User user = CacheUtils.get("userCache", "user:123");     // 获取
+CacheUtils.evict("userCache", "user:123");               // 删除
+CacheUtils.clear("userCache");                           // 清空整组
+```
+
+---
+
+## 三、CacheNames 缓存名称常量
+
+> 位置：`ruoyi-common/ruoyi-common-core/.../constant/CacheNames.java`
+
+### 命名格式
+
+```
+cacheNames#ttl#maxIdleTime#maxSize#local
+- ttl: 过期时间（0=不过期，默认0）
+- maxIdleTime: 最大空闲时间（0=不检测，默认0）
+- maxSize: 最大条数（0=无限，默认0）
+- local: 本地缓存（1开启，0关闭，默认1）
+```
+
+```java
+"test#60s"                // 60秒过期
+"test#0#60s"              // 不过期，60秒空闲清理
+"test#0#1m#1000"          // 不过期，1分钟空闲，最大1000条
+"test#1h#0#500#0"         // 1小时过期，最大500条，关闭本地缓存
+```
+
+### 已定义常量
+
+```java
+public interface CacheNames {
+    String DEMO_CACHE = "demo:cache#60s#10m#20";
+    String SYS_CONFIG = "sys_config";
+    String SYS_DICT = "sys_dict";
+    String SYS_DICT_TYPE = "sys_dict_type";
+    String SYS_TENANT = GlobalConstants.GLOBAL_REDIS_KEY + "sys_tenant#30d";
+    String SYS_CLIENT = GlobalConstants.GLOBAL_REDIS_KEY + "sys_client#30d";
+    String SYS_USER_NAME = "sys_user_name#30d";
+    String SYS_NICKNAME = "sys_nickname#30d";
+    String SYS_DEPT = "sys_dept#30d";
+    String SYS_OSS = "sys_oss#30d";
+    String SYS_ROLE_CUSTOM = "sys_role_custom#30d";
+    String SYS_DEPT_AND_CHILD = "sys_dept_and_child#30d";
+    String SYS_OSS_CONFIG = GlobalConstants.GLOBAL_REDIS_KEY + "sys_oss_config";
+    String ONLINE_TOKEN = "online_tokens";
+}
+```
+
+---
+
+## 四、缓存注解使用规范
+
+### @Cacheable - 查询缓存
+
+```java
+@Cacheable(cacheNames = CacheNames.SYS_DICT, key = "#dictType")
+@Override
+public List<SysDictDataVo> listDictDataByType(String dictType) {
+    if (StringUtils.isBlank(dictType)) {
+        return Collections.emptyList();
+    }
+    List<SysDictData> dictDataList = dictDataMapper.selectByType(dictType);
+    if (CollUtil.isEmpty(dictDataList)) {
+        return Collections.emptyList();  // 返回空列表防止缓存穿透
+    }
+    return MapstructUtils.convert(dictDataList, SysDictDataVo.class);
+}
+```
+
+### @CachePut / @CacheEvict
+
+```java
+@CachePut(cacheNames = CacheNames.SYS_DICT, key = "#bo.dictType")
+public List<SysDictDataVo> insertDictType(SysDictTypeBo bo) { ... }
+
+@CacheEvict(cacheNames = CacheNames.SYS_DICT, key = "#dictType")
+public void deleteDictType(String dictType) { ... }
+
+@CacheEvict(cacheNames = CacheNames.SYS_DICT, allEntries = true)
+public void clearAllDictCache() { ... }
+```
+
+### 返回值禁止使用不可变集合
+
+```java
+// ❌ 禁止！@Cacheable 返回值序列化失败
+return List.of(data1, data2);
+return Set.of("admin", "user");
+return Map.of("key1", "value1");
+
+// ✅ 正确：使用可变集合
+List<SysDictDataVo> result = new ArrayList<>();
+result.add(data1);
+return result;
+```
+
+---
+
+## 五、分布式锁
+
+> RedisUtils **不提供** `getLock()`，需直接注入 `RedissonClient`。
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderServiceImpl implements IOrderService {
+
+    private final RedissonClient redissonClient;
+
+    public void submitOrder(OrderBo orderBo) {
+        String lockKey = "lock:submit:order:" + LoginHelper.getUserId();
+        RLock lock = redissonClient.getLock(lockKey);
+
+        try {
+            boolean locked = lock.tryLock(3, 10, TimeUnit.SECONDS);
+            if (!locked) {
+                throw new ServiceException("请勿重复提交订单");
+            }
+            try {
+                orderMapper.insert(orderBo);
+            } finally {
+                lock.unlock();  // 必须在 finally 中释放
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new ServiceException("订单提交被中断");
+        }
+    }
+}
+```
+
+---
+
+## 六、缓存 Key 命名规范
+
+```
+格式：{业务模块}:{功能}:{具体标识}
+
+示例：
+user:info:123              user:roles:123            user:permissions:123
+dict:data:sys_user_sex     order:info:20240101001    order:status:20240101001
+lock:order:20240101001     lock:stock:123            lock:submit:order:456
+limit:api:user:123         limit:sms:18888888888
+```
+
+---
+
+## 七、租户隔离注意
+
+```java
+// ⚠️ keys() 和 deleteKeys() 会忽略租户隔离，需手动拼接
+String tenantId = LoginHelper.getTenantId();
+Collection<String> keys = RedisUtils.keys(tenantId + ":user:*");
+
+// CacheUtils 会自动处理租户隔离
+CacheUtils.clear(CacheNames.SYS_USER_NAME);
+```
+
+---
+
+## 八、注意事项速查
+
+1. **@Cacheable 返回值不能使用不可变集合**（List.of()、Set.of()、Map.of()）
+2. **分布式锁必须在 finally 中释放**
+3. **keys() 和 deleteKeys() 会忽略租户隔离**
+4. **返回空列表而不是 null**，防止缓存穿透
+5. **设置随机过期时间偏移**，避免缓存雪崩
+6. **热点数据用分布式锁 + 双重检查**，防止缓存击穿
+
+---
+
+## 九、核心文件位置
+
+| 文件 | 位置 |
+|------|------|
+| RedisUtils | `ruoyi-common/ruoyi-common-redis/.../utils/RedisUtils.java` |
+| CacheUtils | `ruoyi-common/ruoyi-common-redis/.../utils/CacheUtils.java` |
+| CacheNames | `ruoyi-common/ruoyi-common-core/.../constant/CacheNames.java` |
+| GlobalConstants | `ruoyi-common/ruoyi-common-core/.../constant/GlobalConstants.java` |
+
+---
+
+## 多项目适配说明
+
+- 如果需要 leniu-tengyun-core 项目的 Redis 开发规范，请使用 `leniu-redis-cache` skill
+- leniu-tengyun-core 的 RedisUtil 工具类方法名与 RuoYi-Vue-Plus 的 RedisUtils 不同

package/src/skills/redis-cache/references/listeners.md

@@ -0,0 +1,23 @@
+# Redis 监听机制
+
+## 过期/删除监听器
+
+```java
+import org.redisson.api.listener.ExpiredObjectListener;
+import org.redisson.api.listener.DeletedObjectListener;
+
+// 注册过期监听器（需要开启Redis的notify-keyspace-events配置）
+RedisUtils.addObjectListener("user:123", (ExpiredObjectListener) name -> {
+    log.info("缓存已过期: {}", name);
+});
+
+// 注册删除监听器
+RedisUtils.addObjectListener("user:123", (DeletedObjectListener) name -> {
+    log.info("缓存已删除: {}", name);
+});
+
+// 注册List/Set/Map监听器
+RedisUtils.addListListener("myList", (ExpiredObjectListener) name -> { ... });
+RedisUtils.addSetListener("mySet", (DeletedObjectListener) name -> { ... });
+RedisUtils.addMapListener("myMap", (ExpiredObjectListener) name -> { ... });
+```