leniu-dev 2.0.0

package/.cursor/skills/data-permission/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: data-permission
+description: |
+  通用行级数据权限设计指南。通过 AOP + MyBatis 拦截器模式实现数据隔离，支持部门权限、本人权限、自定义权限等多种隔离粒度。
+  触发场景：
+  - 为业务模块添加行级数据过滤
+  - 设计部门级 / 本人级数据隔离
+  - 扩展自定义数据权限类型
+  - 临时忽略数据权限查全量数据
+  - 排查数据权限不生效问题
+  触发词：数据权限、行级权限、数据隔离、部门权限、本人权限、自定义权限、DataScope、DataPermission、数据过滤
+  注意：如果项目有专属技能（如 `leniu-data-permission`），优先使用专属版本。
+---
+
+# 行级数据权限开发指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-data-permission`），优先使用。
+
+## 设计原则
+
+1. **对业务透明**：数据权限通过拦截器自动注入 SQL 条件，业务代码无需感知。
+2. **声明式配置**：通过注解声明字段映射关系，框架自动拼接过滤条件。
+3. **可扩展**：权限类型（部门、本人、自定义等）可通过枚举或策略模式扩展。
+4. **安全兜底**：未配置权限范围时默认为"仅本人"，避免数据泄露。
+
+---
+
+## 权限类型设计
+
+| 类型 | 标识 | SQL 效果 | 适用场景 |
+|------|------|---------|---------|
+| 全部数据 | 1 | 不拼接条件 | 超管、全局数据查看 |
+| 自定义权限 | 2 | `dept_id IN (角色关联的部门ID)` | 跨部门协作 |
+| 本部门 | 3 | `dept_id = ?` | 部门经理 |
+| 本部门及以下 | 4 | `dept_id IN (当前部门及子部门)` | 上级部门 |
+| 仅本人 | 5 | `created_by = ?` | 普通员工 |
+| 部门及以下或本人 | 6 | `dept_id IN (...) OR created_by = ?` | 混合场景 |
+
+---
+
+## 实现模式
+
+### 架构概览
+
+```
+Controller -> Service (加注解) -> Mapper -> MyBatis 拦截器
+                                              |
+                                    自动注入 WHERE 条件
+                                              |
+                                   [你的权限处理器] (查询当前用户权限范围)
+```
+
+### 步骤 1：定义注解
+
+```java
+@Target({ElementType.METHOD, ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface DataPermission {
+    DataColumn[] value();
+    String joinStr() default "AND";  // 多角色权限连接方式
+}
+
+@Target(ElementType.ANNOTATION_TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface DataColumn {
+    String key() default "deptName";   // 占位符关键字
+    String value() default "dept_id";  // 对应的表字段名
+    String permission() default "";     // 拥有此权限则不过滤
+}
+```
+
+### 步骤 2：实现 MyBatis 拦截器
+
+```java
+@Intercepts({@Signature(type = Executor.class, method = "query", args = {...})})
+public class DataPermissionInterceptor implements Interceptor {
+
+    @Override
+    public Object intercept(Invocation invocation) throws Throwable {
+        // 1. 从线程上下文获取 @DataPermission 注解
+        // 2. 获取当前用户的角色及数据权限范围
+        // 3. 根据权限类型拼接 WHERE 条件
+        // 4. 修改原始 SQL，追加过滤条件
+        return invocation.proceed();
+    }
+}
+```
+
+### 步骤 3：在 Service / Mapper 上使用
+
+```java
+@Service
+public class OrderServiceImpl implements OrderService {
+
+    @Autowired
+    private OrderMapper orderMapper;
+
+    // 按部门 + 创建人过滤
+    @DataPermission({
+        @DataColumn(key = "deptName", value = "dept_id"),
+        @DataColumn(key = "userName", value = "created_by")
+    })
+    @Override
+    public List<OrderVo> listWithPermission(OrderQuery query) {
+        return orderMapper.selectList(buildWrapper(query));
+    }
+}
+```
+
+### 步骤 4：确保数据库表有权限字段
+
+```sql
+CREATE TABLE biz_order (
+    id           BIGINT       NOT NULL COMMENT '主键',
+    -- 业务字段 ...
+    dept_id      BIGINT       DEFAULT NULL COMMENT '所属部门',   -- 必须
+    created_by   BIGINT       DEFAULT NULL COMMENT '创建人',     -- 必须
+    created_time DATETIME     DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id)
+);
+```
+
+### 多表关联（使用表别名）
+
+```java
+// SQL: SELECT o.*, u.user_name FROM biz_order o LEFT JOIN sys_user u ON ...
+@DataPermission({
+    @DataColumn(key = "deptName", value = "o.dept_id"),
+    @DataColumn(key = "userName", value = "o.created_by")
+})
+List<OrderVo> selectWithJoin(@Param("query") OrderQuery query);
+```
+
+### 临时忽略数据权限
+
+```java
+// 使用工具类忽略权限过滤，查全量数据
+Long total = [你的权限工具类].ignore(() -> orderService.count());
+
+// 无返回值
+[你的权限工具类].ignore(() -> {
+    configService.refreshAll();
+    return null;
+});
+```
+
+### 指定权限标识跳过过滤
+
+```java
+// 拥有 order:all 权限的角色不过滤
+@DataPermission({
+    @DataColumn(key = "deptName", value = "dept_id", permission = "order:all")
+})
+```
+
+---
+
+## 选型建议
+
+| 方案 | 优点 | 缺点 | 适用场景 |
+|------|------|------|---------|
+| MyBatis 拦截器 | 对业务透明、自动注入 | 依赖 MyBatis | 绝大多数 Java Web 项目 |
+| AOP + SQL 改写 | 框架无关 | 需自行解析 SQL | 非 MyBatis 项目 |
+| 数据库视图 | 完全透明 | 难以动态切换 | 权限固定的场景 |
+| 应用层过滤 | 实现简单 | 性能差（全量查出再过滤） | 数据量小 |
+
+### 多角色权限计算
+
+- **SELECT 查询**：多角色权限用 `OR` 连接（并集，看到更多数据）
+- **UPDATE / DELETE**：多角色权限用 `AND` 连接（交集，更安全）
+
+---
+
+## 常见错误
+
+```java
+// 1. 注解放在 Controller 层（无效，拦截器在 Mapper 执行前生效）
+@Controller
+public class OrderController {
+    @DataPermission({...})  // 无效！应在 Service 或 Mapper 上
+    public Result<?> list() { }
+}
+
+// 2. 表别名不匹配
+@DataColumn(key = "deptName", value = "user.dept_id")  // SQL 中别名是 u
+// 应为 value = "u.dept_id"
+
+// 3. 在权限服务内部调用带权限的方法（死循环）
+public String getDeptAndChild(Long deptId) {
+    deptService.list(wrapper);  // 如果 list 也带 @DataPermission -> 死循环
+    // 应直接用 Mapper 或 ignore() 包装
+}
+
+// 4. 忘记在表中添加部门/创建人字段
+// 没有 dept_id / created_by 字段，权限 SQL 会报错
+
+// 5. 超级管理员测试数据权限
+// 超管通常跳过权限过滤，应使用普通用户账号测试
+
+// 6. @DataPermission 注解为空
+@DataPermission  // 空注解，无 @DataColumn 映射，不会生效
+```
+
+### 问题排查
+
+| 检查项 | 可能原因 | 解决方案 |
+|--------|---------|---------|
+| 超级管理员？ | 超管自动跳过权限 | 用普通用户测试 |
+| 角色数据范围？ | 范围为"全部数据" | 修改角色数据权限配置 |
+| 注解位置？ | 不在 Service / Mapper 层 | 移动注解到正确位置 |
+| 表别名？ | value 别名与 SQL 不一致 | 检查并修正别名 |
+| Unknown column？ | 表中没有该字段 | 检查数据库表结构 |
+
+**调试**：开启 SQL 日志查看拼接结果
+
+```yaml
+# MyBatis SQL 日志
+logging:
+  level:
+    [你的Mapper包路径]: debug
+```

package/.cursor/skills/data-permission/references/custom-data-scope.md

@@ -0,0 +1,90 @@
+# 扩展自定义数据权限类型 - 完整指南
+
+## 步骤 1：修改 DataScopeType 枚举
+
+位置：`ruoyi-common-mybatis/.../enums/DataScopeType.java`
+
+```java
+public enum DataScopeType {
+
+    // ... 现有类型 ...
+
+    /**
+     * 按区域过滤（自定义类型示例）
+     */
+    REGION("7", "按区域", "#{#regionName} IN ( #{@sdss.getUserRegions( #user.userId )} )"),
+    ;
+
+    // ... 其他代码 ...
+}
+```
+
+## 步骤 2：在 ISysDataScopeService 中添加方法
+
+```java
+// 接口
+public interface ISysDataScopeService {
+    // ... 现有方法 ...
+
+    /**
+     * 获取用户关联的区域ID列表
+     */
+    String getUserRegions(Long userId);
+}
+
+// 实现
+@Service("sdss")
+public class SysDataScopeServiceImpl implements ISysDataScopeService {
+
+    @Override
+    @Cacheable(cacheNames = CacheNames.SYS_USER_REGIONS, key = "#userId")
+    public String getUserRegions(Long userId) {
+        List<Long> regionIds = userRegionMapper.selectRegionIdsByUserId(userId);
+        if (CollUtil.isEmpty(regionIds)) {
+            return "-1";  // 返回 -1 表示无权限
+        }
+        return StringUtils.join(regionIds, ",");
+    }
+}
+```
+
+## 步骤 3：使用新权限类型
+
+```java
+@DataPermission({
+    @DataColumn(key = "regionName", value = "region_id")
+})
+@Override
+public List<Store> listByRegion(StoreBo bo) {
+    return list(buildQueryWrapper(bo));
+}
+```
+
+## 添加自定义变量
+
+通过 `DataPermissionHelper` 设置自定义变量供 SpEL 表达式使用。
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderServiceImpl implements IOrderService {
+
+    private final OrderMapper baseMapper;
+
+    @Override
+    public TableDataInfo<OrderVo> pageByShop(Long shopId, OrderBo bo, PageQuery pageQuery) {
+        // 设置自定义变量（请求结束后 SaStorage 自动清理，无需手动移除）
+        DataPermissionHelper.setVariable("shopId", shopId);
+        return pageWithPermission(bo, pageQuery);
+    }
+
+    @DataPermission({
+        @DataColumn(key = "shopId", value = "shop_id")
+    })
+    private TableDataInfo<OrderVo> pageWithPermission(OrderBo bo, PageQuery pageQuery) {
+        LambdaQueryWrapper<Order> lqw = buildQueryWrapper(bo);
+        Page<OrderVo> result = baseMapper.selectVoPage(pageQuery.build(), lqw);
+        return TableDataInfo.build(result);
+    }
+}
+```

package/.cursor/skills/database-ops/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: database-ops
+description: |
+  通用数据库操作指南。涵盖建表规范、审计字段、逻辑删除、索引设计等。
+  触发场景：建表、数据库设计、SQL 编写、数据迁移。
+  触发词：建表、数据库、SQL、DDL、数据迁移、索引。
+  注意：如果项目有专属技能（如 `leniu-database`），优先使用专属版本。
+---
+
+# 数据库操作指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-database`），优先使用。
+
+## 核心规范
+
+### 建表标准模板
+
+```sql
+CREATE TABLE t_order (
+    id          BIGINT       NOT NULL                COMMENT '主键',
+    order_no    VARCHAR(64)  NOT NULL                COMMENT '订单编号',
+    status      TINYINT      NOT NULL DEFAULT 0      COMMENT '状态(0-待处理,1-已完成,2-已取消)',
+    amount      BIGINT       NOT NULL DEFAULT 0      COMMENT '金额(单位:分)',
+    remark      VARCHAR(500)          DEFAULT NULL   COMMENT '备注',
+    create_by   VARCHAR(64)           DEFAULT NULL   COMMENT '创建人',
+    create_time DATETIME              DEFAULT NULL   COMMENT '创建时间',
+    update_by   VARCHAR(64)           DEFAULT NULL   COMMENT '更新人',
+    update_time DATETIME              DEFAULT NULL   COMMENT '更新时间',
+    deleted     TINYINT      NOT NULL DEFAULT 0      COMMENT '删除标识(0-正常,1-删除)',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_order_no (order_no),
+    KEY idx_status (status),
+    KEY idx_create_time (create_time)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单表';
+```
+
+### 审计字段规范
+
+| 字段 | 类型 | 说明 | 填充时机 |
+|------|------|------|---------|
+| `create_by` | VARCHAR(64) | 创建人 | INSERT |
+| `create_time` | DATETIME | 创建时间 | INSERT |
+| `update_by` | VARCHAR(64) | 更新人 | INSERT / UPDATE |
+| `update_time` | DATETIME | 更新时间 | INSERT / UPDATE |
+| `deleted` | TINYINT | 逻辑删除 | 手动 / 框架自动 |
+
+> 审计字段自动填充可通过 MyBatis-Plus 的 `MetaObjectHandler` 实现。
+
+### 逻辑删除
+
+- `deleted = 0` 表示正常
+- `deleted = 1` 表示已删除
+- MyBatis-Plus 配置：
+
+```yaml
+mybatis-plus:
+  global-config:
+    db-config:
+      logic-delete-field: deleted
+      logic-delete-value: 1
+      logic-not-delete-value: 0
+```
+
+### 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 表名 | 小写下划线，建议加前缀 | `t_order`, `sys_user` |
+| 字段名 | 小写下划线 | `order_no`, `create_time` |
+| 主键 | `id` | `id BIGINT NOT NULL` |
+| 外键字段 | `关联表_id` | `user_id`, `order_id` |
+| 唯一索引 | `uk_字段名` | `uk_order_no` |
+| 普通索引 | `idx_字段名` | `idx_status` |
+| 联合索引 | `idx_字段1_字段2` | `idx_user_id_status` |
+
+## 代码示例
+
+### 审计字段自动填充
+
+```java
+@Component
+public class MyMetaObjectHandler implements MetaObjectHandler {
+
+    @Override
+    public void insertFill(MetaObject metaObject) {
+        this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
+        this.strictInsertFill(metaObject, "createBy", String.class, getCurrentUser());
+        this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
+        this.strictInsertFill(metaObject, "updateBy", String.class, getCurrentUser());
+    }
+
+    @Override
+    public void updateFill(MetaObject metaObject) {
+        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
+        this.strictUpdateFill(metaObject, "updateBy", String.class, getCurrentUser());
+    }
+
+    private String getCurrentUser() {
+        // 从安全上下文获取当前用户，按项目实际实现
+        return [你的用户上下文工具].getCurrentUsername();
+    }
+}
+```
+
+### 常见数据库设计模式
+
+#### 模式一：树结构 - 祖先路径法
+
+```sql
+CREATE TABLE t_org (
+    id          BIGINT       NOT NULL              COMMENT '主键',
+    parent_id   BIGINT                DEFAULT NULL COMMENT '父节点ID',
+    ancestors   VARCHAR(500)          DEFAULT NULL COMMENT '祖先路径(逗号分隔)',
+    name        VARCHAR(100) NOT NULL              COMMENT '节点名称',
+    sort        INT          NOT NULL DEFAULT 0    COMMENT '排序',
+    create_by   VARCHAR(64)           DEFAULT NULL COMMENT '创建人',
+    create_time DATETIME              DEFAULT NULL COMMENT '创建时间',
+    update_by   VARCHAR(64)           DEFAULT NULL COMMENT '更新人',
+    update_time DATETIME              DEFAULT NULL COMMENT '更新时间',
+    deleted     TINYINT      NOT NULL DEFAULT 0    COMMENT '删除标识(0-正常,1-删除)',
+    PRIMARY KEY (id),
+    KEY idx_parent_id (parent_id),
+    KEY idx_ancestors (ancestors(255))
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='组织树';
+```
+
+#### 模式二：关联表（多对多）
+
+```sql
+CREATE TABLE t_user_role (
+    id      BIGINT NOT NULL              COMMENT '主键',
+    user_id BIGINT NOT NULL              COMMENT '用户ID',
+    role_id BIGINT NOT NULL              COMMENT '角色ID',
+    create_time DATETIME DEFAULT NULL    COMMENT '创建时间',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_user_role (user_id, role_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户角色关联';
+```
+
+#### 模式三：状态字段（枚举驱动）
+
+```java
+@Getter
+@AllArgsConstructor
+public enum OrderStatusEnum {
+
+    PENDING(0, "待处理"),
+    COMPLETED(1, "已完成"),
+    CANCELLED(2, "已取消");
+
+    private final int code;
+    private final String desc;
+}
+
+// SQL 字段
+// status TINYINT NOT NULL DEFAULT 0 COMMENT '状态(0-待处理,1-已完成,2-已取消)'
+```
+
+### 常见查询模式
+
+```sql
+-- 分页查询（配合 MyBatis-Plus Page）
+SELECT id, order_no, status, amount, create_time
+FROM t_order
+WHERE deleted = 0
+  AND status = #{status}
+ORDER BY create_time DESC;
+
+-- 批量插入
+INSERT INTO t_order (id, order_no, status, amount, create_by, create_time, deleted)
+VALUES
+    (#{id1}, #{orderNo1}, 0, #{amount1}, #{createBy}, NOW(), 0),
+    (#{id2}, #{orderNo2}, 0, #{amount2}, #{createBy}, NOW(), 0);
+
+-- 逻辑删除
+UPDATE t_order SET deleted = 1, update_by = #{updateBy}, update_time = NOW()
+WHERE id = #{id} AND deleted = 0;
+```
+
+### 索引设计原则
+
+1. **必须有主键**：推荐 BIGINT 雪花 ID 或自增
+2. **高频查询字段建索引**：WHERE、JOIN、ORDER BY 中的字段
+3. **联合索引遵循最左前缀**：把区分度高的字段放前面
+4. **避免在大文本字段上建索引**：TEXT、BLOB 等
+5. **控制单表索引数量**：建议不超过 5-6 个
+
+### 数据迁移脚本规范
+
+```sql
+-- V1.0.1__add_order_remark.sql
+-- 描述：订单表新增备注字段
+-- 作者：xxx
+-- 日期：2024-01-01
+
+ALTER TABLE t_order ADD COLUMN remark VARCHAR(500) DEFAULT NULL COMMENT '备注' AFTER amount;
+```
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|---------|
+| 用 VARCHAR 存金额 | 用 BIGINT 存分，或 DECIMAL(10,2) |
+| 字段不加 COMMENT | 所有字段必须有注释 |
+| 表没有主键 | 每张表必须有主键 |
+| 用 UUID 做主键 | 推荐 BIGINT（索引友好） |
+| 逻辑删除值搞反 | 确认项目约定（通用：0=正常, 1=删除） |
+| 大表无索引 | 根据查询模式建立合适索引 |
+| 字段允许 NULL 但业务不允许 | 加 NOT NULL 约束 + DEFAULT 值 |
+| 直接物理删除数据 | 使用逻辑删除，保留数据可追溯 |