leniu-dev 2.0.0

package/.cursor/skills/leniu-security-guard/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: leniu-security-guard
+description: |
+  leniu-tengyun-core / leniu-yunshitang 项目安全权限控制规范。包含认证注解体系、TokenManager API、数据权限校验、SQL注入防护。
+
+  触发场景：
+  - 配置接口认证注解（@RequiresAuthentication/@RequiresGuest/@RequiresPermissions）
+  - 使用 TokenManager 获取用户信息或校验权限
+  - 防 SQL 注入（MyBatis #{} 参数化查询）
+  - 数据归属校验（防越权）
+  - VO 敏感字段脱敏处理
+
+  适用项目：
+  - leniu-tengyun-core：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun-core
+  - leniu-yunshitang：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun/leniu-yunshitang
+
+  触发词：安全认证、权限注解、TokenManager、SQL注入防护、数据脱敏、接口安全、RequiresAuthentication
+---
+
+# leniu-security-guard
+
+## 认证注解
+
+所有注解包路径：`net.xnzn.framework.secure.filter.annotation.*`
+
+| 注解 | 用途 |
+|------|------|
+| `@RequiresAuthentication` | 需要登录认证（最常用，类/方法级） |
+| `@RequiresGuest` | 允许游客访问（公开接口） |
+| `@RequiresPermissions` | 需要指定权限码 |
+| `@RequiresRoles` | 需要指定角色 |
+| `@RequiresUser` | 需要用户登录 |
+| `@RequiresHeader` | 需要指定请求头 |
+
+### Controller 认证示例
+
+```java
+import net.xnzn.framework.secure.filter.annotation.RequiresAuthentication;
+import net.xnzn.framework.secure.filter.annotation.RequiresGuest;
+import net.xnzn.framework.secure.filter.annotation.RequiresPermissions;
+import net.xnzn.framework.secure.filter.annotation.RequiresRoles;
+
+// 类级别：整个 Controller 需要登录
+@RestController
+@RequestMapping("/api/v2/web/xxx")
+@RequiresAuthentication
+public class XxxWebController { }
+
+// 方法级别：允许游客访问
+@GetMapping("/public/info")
+@RequiresGuest
+public LeResponse<String> getPublicInfo() { }
+
+// 需要特定权限
+@GetMapping("/admin/users")
+@RequiresPermissions("system:user:list")
+public LeResponse<List<User>> listUsers() { }
+
+// AND 逻辑（默认）：需要所有权限
+@RequiresPermissions(value = {"system:user:add", "system:user:edit"}, logical = Logical.AND)
+
+// OR 逻辑：需要任一权限
+@RequiresPermissions(value = {"system:user:add", "system:user:edit"}, logical = Logical.OR)
+
+// 需要指定角色
+@RequiresRoles("admin")
+
+// 需要所有角色
+@RequiresRoles(value = {"admin", "manager"}, logical = Logical.AND)
+```
+
+> **注意**：`@RequiresPermissions` 不指定 `value` 时，自动使用 `@RequestMapping` 路径作为权限码。
+
+---
+
+## TokenManager API
+
+```java
+import net.xnzn.framework.secure.token.TokenManager;
+```
+
+### 用户信息
+
+```java
+// 登录状态
+TokenManager.isLogin();
+
+// 用户 ID
+Long userId = TokenManager.getSubjectId().orElse(null);
+
+// 用户名
+String userName = TokenManager.getSubjectName().orElse(null);
+
+// 附加数据
+Map<String, String> userData = TokenManager.getSubjectData();
+String orgId = userData.get("orgId");
+```
+
+### 权限/角色校验
+
+```java
+// 单个权限
+TokenManager.hasPermission("system:user:add");
+
+// 多个权限（AND）
+TokenManager.hasPermission("system:user:add", "system:user:edit");
+
+// 任一权限（OR）
+TokenManager.hasAnyPermission("system:user:add", "system:user:edit");
+
+// 角色
+TokenManager.hasRole("admin");
+TokenManager.hasAnyRole("admin", "manager");
+```
+
+### 附加数据管理
+
+```java
+// 添加
+TokenManager.attachData("orgId", "12345");
+
+// 批量添加
+TokenManager.attachData(Map.of("orgId", "12345", "deptId", "67890"));
+
+// 获取
+String orgId = TokenManager.getSubjectData().get("orgId");
+
+// 移除
+TokenManager.removeData("orgId", "deptId");
+```
+
+### 登出与缓存
+
+```java
+// 登出
+TokenManager.logout();
+
+// 强制下线
+TokenManager.revokeAuthenticate();
+
+// 撤销旧 Token（保留最近 N 个）
+TokenManager.revokeAuthenticate(userId, 3);
+
+// 清除权限/角色缓存
+TokenManager.clearPermission(userId);
+TokenManager.clearRole(userId);
+TokenManager.clearRoleAndPermission(userId);
+TokenManager.clearAllRoleAndPermission();
+```
+
+---
+
+## WebContext
+
+```java
+import net.xnzn.framework.secure.WebContext;
+
+HttpServletRequest request = WebContext.get().getRequest().orElse(null);
+HttpServletResponse response = WebContext.get().getResponse().orElse(null);
+Optional<AccessToken> token = WebContext.get().getAccessToken();
+
+// 属性存取
+WebContext.get().setAttribute("key", "value");
+Object value = WebContext.get().getAttribute("key");
+WebContext.reset();
+```
+
+---
+
+## 数据权限校验（防越权）
+
+```java
+@Transactional(rollbackFor = Exception.class)
+public void delete(Long id) {
+    Order order = orderMapper.selectById(id);
+    Assert.notNull(order, () -> new LeException("订单不存在"));
+
+    // 校验数据归属
+    Long currentUserId = TokenManager.getSubjectId()
+        .orElseThrow(() -> new LeException("用户未登录"));
+    if (!order.getUserId().equals(currentUserId)) {
+        throw new LeException("无权操作该订单");
+    }
+
+    orderMapper.deleteById(id);
+}
+```
+
+### 最小权限原则
+
+```java
+@RequiresAuthentication
+@RequiresPermissions("order:view")
+public PageVO<OrderVO> pageList(OrderPageParam param) {
+    Long userId = TokenManager.getSubjectId()
+        .orElseThrow(() -> new LeException("用户未登录"));
+    param.setUserId(userId);  // 限制只查自己的数据
+    return orderService.pageList(param);
+}
+```
+
+---
+
+## SQL 注入防护
+
+### MyBatis XML 必须用 `#{}`
+
+```xml
+<!-- 正确：参数化查询 -->
+<select id="selectByName" resultType="User">
+    SELECT id, name, mobile FROM user WHERE name = #{name}
+</select>
+
+<!-- 错误：${} 有注入风险 -->
+<select id="selectByName" resultType="User">
+    SELECT * FROM user WHERE name = '${name}'
+</select>
+```
+
+### 禁止 SELECT *
+
+```xml
+<!-- 错误 -->
+SELECT * FROM user WHERE status = #{status}
+
+<!-- 正确：明确指定字段 -->
+SELECT id, name, mobile, status FROM user WHERE status = #{status}
+```
+
+---
+
+## VO 敏感字段处理
+
+```java
+@Data
+public class UserVO {
+    @JsonIgnore
+    private String password;  // 密码绝不返回
+
+    @JsonSerialize(using = MobileSerializer.class)
+    private String mobile;    // 手机号脱敏
+
+    @JsonSerialize(using = IdCardSerializer.class)
+    private String idCard;    // 身份证脱敏
+}
+```
+
+### 日志脱敏
+
+```java
+// 错误：记录敏感信息
+log.info("用户登录, username:{}, password:{}", username, password);
+
+// 正确：不记录密码
+log.info("用户登录, username:{}", username);
+```
+
+---
+
+## 输入验证
+
+```java
+@Data
+public class UserParam {
+    @NotBlank(message = "用户名不能为空")
+    @Pattern(regexp = "^[a-zA-Z0-9_]{4,20}$", message = "用户名格式不正确")
+    private String username;
+
+    @NotBlank(message = "密码不能为空")
+    @Size(min = 6, max = 20, message = "密码长度必须在6-20之间")
+    private String password;
+
+    @NotBlank(message = "手机号不能为空")
+    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
+    private String mobile;
+
+    @Email(message = "邮箱格式不正确")
+    private String email;
+}
+```
+
+---
+
+## 限流防护
+
+```java
+// Redis 计数器限流
+public void checkRateLimit(Long userId, String api, int limit, int seconds) {
+    String key = String.format("rate:%d:%s", userId, api);
+    Integer count = RedisUtil.incr(key, (long) seconds);
+    if (count > limit) {
+        throw new LeException("请求过于频繁，请稍后重试");
+    }
+}
+```
+
+---
+
+## 注意事项
+
+1. 权限和角色数据自动缓存到 Redis，通过 `clearPermission/clearRole` 手动清除
+2. `TokenManager` 方法需在已登录上下文中使用
+3. `@RequiresGuest` 用于公开接口，不需要登录
+4. MyBatis XML 中必须使用 `#{}` 而非 `${}`
+5. VO 中密码字段必须 `@JsonIgnore`，手机号等用序列化脱敏
+6. 限流 key 格式：`rate:{userId}:{api}`

package/.cursor/skills/leniu-utils-toolkit/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: leniu-utils-toolkit
+description: |
+  leniu-yunshitang-core 项目工具类使用指南。包含 BeanUtil、CollUtil、ObjectUtil、StrUtil、RedisUtil、JacksonUtil、LeBeanUtil 等核心工具类。
+
+  触发场景：
+  - 对象转换（DTO/VO/Entity）
+  - 字符串处理
+  - 集合操作
+  - 日期时间处理
+  - Redis 缓存操作
+  - JSON 序列化
+  - 模糊查询处理
+
+  适用项目：
+  - leniu-tengyun-core：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun-core
+  - leniu-yunshitang：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun/leniu-yunshitang
+
+  触发词：工具类、BeanUtil、StrUtil、CollUtil、ObjectUtil、RedisUtil、JacksonUtil、LeBeanUtil
+
+---
+
+# leniu-yunshitang-core 工具类大全
+
+> 本文档专注于 leniu-tengyun-core 项目的 Java 后端工具类。
+
+## 快速索引
+
+| 功能 | 工具类 | 包路径 | 常用方法 |
+|------|--------|--------|---------|
+| **对象转换** | `BeanUtil` | `cn.hutool.core.bean` | `copyProperties()`, `copyToList()` |
+| 字符串 | `StrUtil` | `cn.hutool.core.util` | `isBlank()`, `format()` |
+| 集合 | `CollUtil` | `cn.hutool.core.collection` | `isEmpty()`, `newArrayList()` |
+| 对象 | `ObjectUtil` | `cn.hutool.core.util` | `isNull()`, `isEmpty()` |
+| Redis缓存 | `RedisUtil` | `net.xnzn.core.base.redis` | `setString()`, `getString()` |
+| JSON | `JacksonUtil` | `net.xnzn.core.common.utils` | `writeValueAsString()`, `readValue()` |
+| 模糊查询 | `LeBeanUtil` | `net.xnzn.core.common.utils` | `fieldLikeHandle()` |
+| 租户上下文 | `TenantContextHolder` | `net.xnzn.framework.data.tenant` | `getTenantId()` |
+
+---
+
+## 1. 对象转换 - BeanUtil（Hutool）
+
+> ⚠️ **强制规范**: leniu 项目使用 Hutool 的 `BeanUtil`，不是 MapstructUtils
+
+```java
+import cn.hutool.core.bean.BeanUtil;
+
+// ✅ 单个对象转换
+XxxVO vo = BeanUtil.copyProperties(entity, XxxVO.class);
+XxxEntity entity = BeanUtil.copyProperties(dto, XxxEntity.class);
+
+// ✅ 集合转换
+List<XxxVO> voList = BeanUtil.copyToList(entityList, XxxVO.class);
+List<XxxEntity> entityList = BeanUtil.copyToList(dtoList, XxxEntity.class);
+```
+
+---
+
+## 2. 字符串操作 - StrUtil（Hutool）
+
+```java
+import cn.hutool.core.util.StrUtil;
+
+// 判空
+StrUtil.isBlank(str);      // null / "" / 空白 都返回 true
+StrUtil.isNotBlank(str);
+StrUtil.isEmpty(str);      // null / "" 返回 true
+StrUtil.isNotEmpty(str);
+
+// 字符串拼接
+String str = StrUtil.join(",", list);       // "1,2,3"
+
+// 常量
+StrUtil.COMMA  // ","
+StrUtil.DOT    // "."
+StrUtil.SLASH  // "/"
+
+// 截取
+String str = StrUtil.sub(s, 0, 10);
+
+// 去除前后缀
+StrUtil.removePrefix(str, "prefix_");
+StrUtil.removeSuffix(str, "_suffix");
+
+// 判断前后缀
+StrUtil.startWith(str, "prefix_");
+StrUtil.endWith(str, "_suffix");
+
+// 大小写转换
+StrUtil.upperCase(str);
+StrUtil.lowerCase(str);
+```
+
+---
+
+## 3. 集合操作 - CollUtil（Hutool）
+
+```java
+import cn.hutool.core.collection.CollUtil;
+
+// 判空
+CollUtil.isEmpty(list);
+CollUtil.isNotEmpty(list);
+
+// 创建集合
+CollUtil.newArrayList(1, 2, 3);
+CollUtil.newHashSet("a", "b");
+
+// 集合转数组
+String[] array = CollUtil.toArray(list, String.class);
+
+// 集合转字符串
+String str = CollUtil.join(list, ",");
+
+// 分割
+List<String> list = CollUtil.split("1,2,3", ",");
+```
+
+---
+
+## 4. 对象操作 - ObjectUtil（Hutool）
+
+```java
+import cn.hutool.core.util.ObjectUtil;
+
+// 判空
+ObjectUtil.isNull(obj);
+ObjectUtil.isNotNull(obj);
+ObjectUtil.isEmpty(obj);      // null / 空字符串 / 空集合
+ObjectUtil.isNotEmpty(obj);
+
+// 默认值
+ObjectUtil.defaultIfNull(obj, defaultValue);
+
+// 相等比较
+ObjectUtil.equal(a, b);
+
+// 克隆
+ObjectUtil.clone(obj);
+```
+
+---
+
+## 5. Redis 缓存 - RedisUtil
+
+```java
+import net.xnzn.core.base.redis.RedisUtil;
+import org.redisson.api.RLock;
+
+// ========== String 操作 ==========
+RedisUtil.setString(key, value);                    // 存字符串
+RedisUtil.setString(key, value, timeout);           // 存字符串（秒）
+RedisUtil.getString(key);                           // 取字符串
+
+// ========== Object 操作 ==========
+RedisUtil.setObj(key, obj);                         // 存对象
+RedisUtil.setObj(key, obj, timeout);                // 存对象（秒）
+RedisUtil.getObj(key);                              // 取对象
+RedisUtil.getObjOrNull(key);                        // 取对象（异常返回null）
+
+// ========== 删除操作 ==========
+RedisUtil.delete(key);                              // 删除单个key
+RedisUtil.delete(keys);                             // 批量删除
+RedisUtil.deleteByPattern("cache:user:*");          // 模式匹配删除
+RedisUtil.deleteKeysInPipeline(keys);               // 管道批量删除
+
+// ========== 分布式锁 ==========
+RLock lock = RedisUtil.getLock(key);                // 获取普通锁
+RLock lock = RedisUtil.getFairLock(key);            // 获取公平锁
+RedisUtil.safeUnLock(lock);                         // 安全解锁
+RedisUtil.isLock(key);                              // 检查是否锁定
+
+// ========== 其他操作 ==========
+RedisUtil.setNx(key, value, expireTime);            // SETNX
+RedisUtil.hasKey(key);                              // 判断key存在
+RedisUtil.incr(key, liveTime);                      // 自增
+RedisUtil.decr(key, liveTime);                      // 自减
+```
+
+---
+
+## 6. JSON 操作 - JacksonUtil
+
+```java
+import net.xnzn.core.common.utils.JacksonUtil;
+
+// 序列化
+String json = JacksonUtil.writeValueAsString(obj);                // 对象->JSON字符串
+String json = JacksonUtil.writeValueAsStringIgnoreNull(obj);      // 忽略null字段
+
+// 反序列化
+User user = JacksonUtil.readValue(json, User.class);           // JSON->对象
+List<User> list = JacksonUtil.readList(json, User.class);     // JSON->List
+Map<String, Object> map = JacksonUtil.readValue(json, Map.class);
+
+// JsonNode 操作
+JsonNode node = JacksonUtil.readTree(json);                        // JSON->JsonNode
+User user = JacksonUtil.treeToValue(node, User.class);            // JsonNode->对象
+String value = JacksonUtil.getByPath(node, "data.user.name");     // 路径获取
+String str = JacksonUtil.getString(node, "key");                   // 取String
+Integer num = JacksonUtil.getInt(node, "key");                     // 取Integer
+
+// 节点创建
+ObjectNode objectNode = JacksonUtil.objectNode();                     // 创建ObjectNode
+ArrayNode arrayNode = JacksonUtil.arrayNode();                        // 创建ArrayNode
+```
+
+---
+
+## 7. 模糊查询处理 - LeBeanUtil
+
+```java
+import net.xnzn.core.common.utils.LeBeanUtil;
+
+// 字段模糊查询处理（自动添加 %前后缀）
+param.setName(LeBeanUtil.fieldLikeHandle(param.getName()));
+// 效果: "张" -> "%张%"
+
+// 常用于 Service 层查询条件处理
+param.setCanteenName(LeBeanUtil.fieldLikeHandle(param.getCanteenName()));
+param.setStallName(LeBeanUtil.fieldLikeHandle(param.getStallName()));
+param.setDishName(LeBeanUtil.fieldLikeHandle(param.getDishName()));
+```
+
+---
+
+## 8. 租户上下文 - TenantContextHolder
+
+```java
+import net.xnzn.framework.data.tenant.TenantContextHolder;
+
+// 获取当前租户ID
+Long tenantId = TenantContextHolder.getTenantId();
+
+// 常用于 Redis key 构建
+String key = "cache:" + TenantContextHolder.getTenantId() + ":data";
+```
+
+---
+
+## 9. 日期时间工具
+
+```java
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+
+// 当前时间
+LocalDateTime now = LocalDateTime.now();
+
+// 格式化
+String format = now.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
+
+// 解析
+LocalDateTime time = LocalDateTime.parse(str, DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
+```
+
+---
+
+## 10. 常用正则表达式
+
+```java
+// 手机号
+String phoneReg = "^1[3-9]\\d{9}$";
+
+// 邮箱
+String emailReg = "^[\\w-]+(\\.[\\w-]+)*@[\\w-]+(\\.[\\w-]+)+$";
+
+// 身份证
+String idCardReg = "^[1-9]\\d{5}(19|20)\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])\\d{3}[\\dXx]$";
+```
+
+---
+
+## 工具类选择速查
+
+| 需求 | 推荐工具 | 说明 |
+|------|---------|------|
+| 对象转换 | `BeanUtil.copyProperties()` | **leniu 必用** |
+| 集合判空 | `CollUtil.isEmpty()` | Hutool |
+| 对象判空 | `ObjectUtil.isNull()` | Hutool |
+| 字符串判空 | `StrUtil.isBlank()` | Hutool |
+| JSON序列化 | `JacksonUtil.writeValueAsString()` | leniu |
+| Redis缓存 | `RedisUtil.setString()` | leniu |
+| 模糊查询 | `LeBeanUtil.fieldLikeHandle()` | leniu |
+| 租户ID | `TenantContextHolder.getTenantId()` | leniu |
+| 字符串拼接 | `StrUtil.join()` | Hutool |
+| 日期格式化 | `DateTimeFormatter` | JDK 8 |
+| ID 生成 | `IdUtil.getSnowflakeNextId()` | Hutool |
+
+---
+
+## 禁止事项
+
+```java
+// ❌ 禁止使用 MapstructUtils（leniu 使用 BeanUtil）
+// MapstructUtils.convert(source, Target.class);  // 禁止！
+
+// ❌ 禁止使用 Map 传递业务数据
+public Map<String, Object> getXxx() { ... }  // 禁止！
+
+// ❌ 禁止手写 stream 转换（应使用 BeanUtil.copyToList）
+list.stream().map(item -> BeanUtil.copyProperties(item, XxxVO.class)).collect(Collectors.toList());
+// ✅ 推荐
+BeanUtil.copyToList(list, XxxVO.class);
+
+// ❌ 禁止使用完整类型引用
+public net.xnzn.core.common.util.LeResponse<XxxVo> getXxx()  // 禁止！
+// ✅ 正确：先 import，再使用短类名
+import net.xnzn.core.common.util.LeResponse;
+public LeResponse<XxxVo> getXxx()
+```
+
+---
+
+## 常见错误对比
+
+### ❌ 错误写法
+
+```java
+// 错误 1: 使用 RuoYi 的 MapstructUtils
+MapstructUtils.convert(source, Target.class);  // ❌ leniu 用 BeanUtil
+
+// 错误 2: 使用 RuoYi 的 StringUtils
+StringUtils.isBlank(str);  // ❌ leniu 用 StrUtil
+
+// 错误 3: 使用 RuoYi 的 RedisUtils
+RedisUtils.setCacheObject(key, value);  // ❌ leniu 用 RedisUtil
+
+// 错误 4: 使用 RuoYi 的 JsonUtils
+JsonUtils.toJsonString(obj);  // ❌ leniu 用 JacksonUtil
+
+// 错误 5: 使用 RuoYi 的 TenantHelper
+TenantHelper.getTenantId();  // ❌ leniu 用 TenantContextHolder
+```
+
+### ✅ 正确写法
+
+```java
+// 正确 1: 使用 leniu 的 BeanUtil
+BeanUtil.copyProperties(source, Target.class);  // ✅
+
+// 正确 2: 使用 Hutool 的 StrUtil
+StrUtil.isBlank(str);  // ✅
+
+// 正确 3: 使用 leniu 的 RedisUtil
+RedisUtil.setString(key, value);  // ✅
+
+// 正确 4: 使用 leniu 的 JacksonUtil
+JacksonUtil.writeValueAsString(obj);  // ✅
+
+// 正确 5: 使用 leniu 的 TenantContextHolder
+TenantContextHolder.getTenantId();  // ✅
+```
+
+---
+
+## 工具类选择决策
+
+| 场景 | RuoYi-Vue-Plus | leniu-tengyun-core |
+|------|----------------|-------------------|
+| 对象转换 | `MapstructUtils.convert()` | `BeanUtil.copyProperties()` |
+| 集合判空 | `CollUtil.isEmpty()` | `CollUtil.isEmpty()` |
+| 对象判空 | `ObjectUtil.isNull()` | `ObjectUtil.isNull()` |
+| 字符串判空 | `StringUtils.isBlank()` | `StrUtil.isBlank()` |
+| JSON序列化 | `JsonUtils.toJsonString()` | `JacksonUtil.writeValueAsString()` |
+| Redis缓存 | `RedisUtils.setCacheObject()` | `RedisUtil.setString()` |
+| 模糊查询 | `"%" + keyword + "%"` | `LeBeanUtil.fieldLikeHandle()` |
+| 租户ID | `LoginHelper.getTenantId()` | `TenantContextHolder.getTenantId()` |
+
+---
+
+## 相关技能
+
+| 需要了解 | 激活 Skill |
+|---------|-----------|
+| Entity/VO/DTO 设计 | `leniu-java-entity` |
+| MyBatis 使用 | `leniu-java-mybatis` |
+| 异常处理 | `leniu-error-handler` |
+| 数据库设计 | `leniu-database-ops` |