ai-engineering-init 1.7.0 → 1.10.0

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

@@ -1,138 +1,145 @@
 ---
 name: data-permission
 description: |
-  数据权限开发指南。实现行级数据隔离，支持部门权限、本人权限、自定义权限等 6 种权限类型。
-
+  通用行级数据权限设计指南。通过 AOP + MyBatis 拦截器模式实现数据隔离，支持部门权限、本人权限、自定义权限等多种隔离粒度。
   触发场景：
-  - 为业务模块添加数据权限过滤
-  - 配置部门级数据隔离
+  - 为业务模块添加行级数据过滤
+  - 设计部门级 / 本人级数据隔离
   - 扩展自定义数据权限类型
-  - 临时忽略数据权限查询全量数据
+  - 临时忽略数据权限查全量数据
   - 排查数据权限不生效问题
-
-  触发词：数据权限、@DataPermission、DataScope、行级权限、数据隔离、部门权限、本人权限、自定义权限、权限过滤、数据过滤、按部门过滤、按创建人过滤
-
-  注意：如果是认证授权（登录、Token、Sa-Token）或菜单/按钮权限，请使用 security-guard。
+  触发词：数据权限、行级权限、数据隔离、部门权限、本人权限、自定义权限、DataScope、DataPermission、数据过滤
+  注意：如果项目有专属技能（如 `leniu-data-permission`），优先使用专属版本。
 ---
 
-# 数据权限开发指南
+# 行级数据权限开发指南
 
-> 通过 MyBatis 拦截器自动注入 WHERE 条件，实现行级数据过滤。
+> 通用模板。如果项目有专属技能（如 `leniu-data-permission`），优先使用。
 
-## 1. 六种权限类型
+## 设计原则
 
-| 类型 | 字典值 | SQL 效果 |
-|------|--------|---------|
-| 全部数据 | 1 | 不拼接条件 |
-| 自定义权限 | 2 | `dept_id IN (角色关联的部门ID)` |
-| 本部门 | 3 | `dept_id = 100` |
-| 本部门及以下 | 4 | `dept_id IN (100,101,102)` |
-| 仅本人 | 5 | `create_by = 1` |
-| 部门及以下或本人 | 6 | `dept_id IN (...) OR create_by = 1` |
+1. **对业务透明**：数据权限通过拦截器自动注入 SQL 条件，业务代码无需感知。
+2. **声明式配置**：通过注解声明字段映射关系，框架自动拼接过滤条件。
+3. **可扩展**：权限类型（部门、本人、自定义等）可通过枚举或策略模式扩展。
+4. **安全兜底**：未配置权限范围时默认为"仅本人"，避免数据泄露。
 
 ---
 
-## 2. 快速上手
+## 权限类型设计
 
-### 步骤 1：Service 方法加注解
+| 类型 | 标识 | SQL 效果 | 适用场景 |
+|------|------|---------|---------|
+| 全部数据 | 1 | 不拼接条件 | 超管、全局数据查看 |
+| 自定义权限 | 2 | `dept_id IN (角色关联的部门ID)` | 跨部门协作 |
+| 本部门 | 3 | `dept_id = ?` | 部门经理 |
+| 本部门及以下 | 4 | `dept_id IN (当前部门及子部门)` | 上级部门 |
+| 仅本人 | 5 | `created_by = ?` | 普通员工 |
+| 部门及以下或本人 | 6 | `dept_id IN (...) OR created_by = ?` | 混合场景 |
 
-```java
-import org.dromara.common.mybatis.annotation.DataPermission;
-import org.dromara.common.mybatis.annotation.DataColumn;
+---
 
-@Service
-@RequiredArgsConstructor
-public class OrderServiceImpl implements IOrderService {
+## 实现模式
 
-    private final OrderMapper baseMapper;
+### 架构概览
 
-    @DataPermission({
-        @DataColumn(key = "deptName", value = "create_dept"),
-        @DataColumn(key = "userName", value = "create_by")
-    })
-    @Override
-    public TableDataInfo<OrderVo> pageWithPermission(OrderBo bo, PageQuery pageQuery) {
-        LambdaQueryWrapper<Order> lqw = buildQueryWrapper(bo);
-        Page<OrderVo> result = baseMapper.selectVoPage(pageQuery.build(), lqw);
-        return TableDataInfo.build(result);
-    }
-}
 ```
-
-### 步骤 2：确保表有权限字段
-
-```sql
-CREATE TABLE m_order (
-    id           BIGINT(20)   NOT NULL COMMENT '主键ID',
-    -- 业务字段 ...
-    create_dept  BIGINT(20)   DEFAULT NULL COMMENT '创建部门',  -- 必须
-    create_by    BIGINT(20)   DEFAULT NULL COMMENT '创建人',    -- 必须
-    create_time  DATETIME     DEFAULT CURRENT_TIMESTAMP,
-    PRIMARY KEY (id)
-);
+Controller -> Service (加注解) -> Mapper -> MyBatis 拦截器
+                                              |
+                                    自动注入 WHERE 条件
+                                              |
+                                   [你的权限处理器] (查询当前用户权限范围)
 ```
 
-### 步骤 3：角色管理中配置数据权限范围
+### 步骤 1：定义注解
 
----
+```java
+@Target({ElementType.METHOD, ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface DataPermission {
+    DataColumn[] value();
+    String joinStr() default "AND";  // 多角色权限连接方式
+}
 
-## 3. 使用场景
+@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
-@DataPermission({
-    @DataColumn(key = "deptName", value = "create_dept")
-})
-public List<Order> listWithPermission(OrderBo bo) {
-    return list(buildQueryWrapper(bo));
+@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
-@DataPermission({
-    @DataColumn(key = "userName", value = "create_by")
-})
-public List<Task> listMyTasks(TaskBo bo) {
-    return list(buildQueryWrapper(bo));
+@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：确保数据库表有权限字段
 
-```java
-@DataPermission({
-    @DataColumn(key = "deptName", value = "create_dept"),
-    @DataColumn(key = "userName", value = "create_by")
-})
-public TableDataInfo<ProjectVo> pageWithPermission(ProjectBo bo, PageQuery pageQuery) {
-    // ...
-}
+```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 u.*, d.dept_name FROM sys_user u LEFT JOIN sys_dept d ON ...
+// SQL: SELECT o.*, u.user_name FROM biz_order o LEFT JOIN sys_user u ON ...
 @DataPermission({
-    @DataColumn(key = "deptName", value = "u.dept_id"),
-    @DataColumn(key = "userName", value = "u.user_id")
+    @DataColumn(key = "deptName", value = "o.dept_id"),
+    @DataColumn(key = "userName", value = "o.created_by")
 })
+List<OrderVo> selectWithJoin(@Param("query") OrderQuery query);
 ```
 
 ### 临时忽略数据权限
 
 ```java
-import org.dromara.common.mybatis.helper.DataPermissionHelper;
-
-// 忽略数据权限，查全量
-Long total = DataPermissionHelper.ignore(() -> orderService.count());
+// 使用工具类忽略权限过滤，查全量数据
+Long total = [你的权限工具类].ignore(() -> orderService.count());
 
 // 无返回值
-DataPermissionHelper.ignore(() -> {
-    List<Config> configs = configService.list();
+[你的权限工具类].ignore(() -> {
+    configService.refreshAll();
     return null;
 });
 ```
@@ -142,151 +149,73 @@ DataPermissionHelper.ignore(() -> {
 ```java
 // 拥有 order:all 权限的角色不过滤
 @DataPermission({
-    @DataColumn(key = "deptName", value = "create_dept", permission = "order:all")
+    @DataColumn(key = "deptName", value = "dept_id", permission = "order:all")
 })
 ```
 
 ---
 
-## 4. Mapper XML 中使用
+## 选型建议
 
-```java
-// Mapper 接口
-@DataPermission({
-    @DataColumn(key = "deptName", value = "o.create_dept")
-})
-List<OrderVo> selectOrderReport(@Param("bo") OrderBo bo);
-```
-
-```xml
-<select id="selectOrderReport" resultType="OrderVo">
-    SELECT o.*, u.user_name
-    FROM m_order o
-    LEFT JOIN sys_user u ON o.create_by = u.user_id
-    WHERE o.status = #{bo.status}
-    <!-- 数据权限自动追加到这里 -->
-</select>
-```
-
----
-
-## 5. 扩展自定义权限类型
-
-> 详细步骤见 `references/custom-data-scope.md`
-
-**步骤 1**：修改 `DataScopeType` 枚举
-
-```java
-REGION("7", "按区域", "#{#regionName} IN ( #{@sdss.getUserRegions( #user.userId )} )"),
-```
-
-**步骤 2**：在 `ISysDataScopeService` 添加方法
-
-```java
-@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);
-        return CollUtil.isEmpty(regionIds) ? "-1" : StringUtils.join(regionIds, ",");
-    }
-}
-```
-
-**步骤 3**：使用
-
-```java
-@DataPermission({
-    @DataColumn(key = "regionName", value = "region_id")
-})
-```
-
-### 自定义变量
+| 方案 | 优点 | 缺点 | 适用场景 |
+|------|------|------|---------|
+| MyBatis 拦截器 | 对业务透明、自动注入 | 依赖 MyBatis | 绝大多数 Java Web 项目 |
+| AOP + SQL 改写 | 框架无关 | 需自行解析 SQL | 非 MyBatis 项目 |
+| 数据库视图 | 完全透明 | 难以动态切换 | 权限固定的场景 |
+| 应用层过滤 | 实现简单 | 性能差（全量查出再过滤） | 数据量小 |
 
-```java
-// 设置自定义变量（请求结束后自动清理）
-DataPermissionHelper.setVariable("shopId", shopId);
+### 多角色权限计算
 
-@DataPermission({
-    @DataColumn(key = "shopId", value = "shop_id")
-})
-```
+- **SELECT 查询**：多角色权限用 `OR` 连接（并集，看到更多数据）
+- **UPDATE / DELETE**：多角色权限用 `AND` 连接（交集，更安全）
 
 ---
 
-## 6. 多角色权限计算
-
-- **SELECT 查询**：多角色权限用 `OR` 连接（并集）
-- **UPDATE/DELETE**：多角色权限用 `AND` 连接（交集）
-- 可通过 `joinStr` 参数自定义：
+## 常见错误
 
 ```java
-@DataPermission(value = {
-    @DataColumn(key = "deptName", value = "create_dept")
-}, joinStr = "AND")
-```
-
----
+// 1. 注解放在 Controller 层（无效，拦截器在 Mapper 执行前生效）
+@Controller
+public class OrderController {
+    @DataPermission({...})  // 无效！应在 Service 或 Mapper 上
+    public Result<?> list() { }
+}
 
-## 7. 禁止项
+// 2. 表别名不匹配
+@DataColumn(key = "deptName", value = "user.dept_id")  // SQL 中别名是 u
+// 应为 value = "u.dept_id"
 
-```java
-// ❌ 在 ISysDataScopeService 内调用带权限的方法（死循环）
+// 3. 在权限服务内部调用带权限的方法（死循环）
 public String getDeptAndChild(Long deptId) {
-    deptService.list(wrapper);  // 如果带 @DataPermission 会死循环
-    // ✅ 直接用 Mapper 或 DataPermissionHelper.ignore()
-    deptMapper.selectList(wrapper);
+    deptService.list(wrapper);  // 如果 list 也带 @DataPermission -> 死循环
+    // 应直接用 Mapper 或 ignore() 包装
 }
 
-// ❌ 表别名不匹配
-@DataColumn(key = "deptName", value = "user.dept_id")  // SQL 别名是 u
-// ✅ @DataColumn(key = "deptName", value = "u.dept_id")
+// 4. 忘记在表中添加部门/创建人字段
+// 没有 dept_id / created_by 字段，权限 SQL 会报错
 
-// ❌ 在 Controller 层使用 @DataPermission（无效！）
-// ✅ 必须在 Service 实现类或 Mapper 接口上
+// 5. 超级管理员测试数据权限
+// 超管通常跳过权限过滤，应使用普通用户账号测试
 
-// ✅ Entity 必须继承 TenantEntity（包含 create_dept、create_by）
-// ✅ 多表查询时使用正确的表别名
+// 6. @DataPermission 注解为空
+@DataPermission  // 空注解，无 @DataColumn 映射，不会生效
 ```
 
----
-
-## 8. 问题排查
+### 问题排查
 
 | 检查项 | 可能原因 | 解决方案 |
 |--------|---------|---------|
 | 超级管理员？ | 超管自动跳过权限 | 用普通用户测试 |
-| 角色数据范围？ | 范围为"全部数据" | 修改角色数据权限 |
-| 注解位置？ | 不在 Service/Mapper 层 | 移动到 Service 实现类 |
-| 表别名？ | value 别名与 SQL 不一致 | 检查修正别名 |
-| Unknown column？ | 表别名不存在 | 检查 value 中的别名 |
-| dept_id IN ()？ | 权限服务返回空 | 检查 ISysDataScopeService |
+| 角色数据范围？ | 范围为"全部数据" | 修改角色数据权限配置 |
+| 注解位置？ | 不在 Service / Mapper 层 | 移动注解到正确位置 |
+| 表别名？ | value 别名与 SQL 不一致 | 检查并修正别名 |
+| Unknown column？ | 表中没有该字段 | 检查数据库表结构 |
 
 **调试**：开启 SQL 日志查看拼接结果
 
 ```yaml
-mybatis-plus:
-  configuration:
-    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
+# MyBatis SQL 日志
+logging:
+  level:
+    [你的Mapper包路径]: debug
 ```
-
----
-
-## 9. 核心类位置
-
-| 类 | 路径 |
-|---|------|
-| `@DataPermission` | `ruoyi-common/ruoyi-common-mybatis/.../annotation/DataPermission.java` |
-| `@DataColumn` | `ruoyi-common/ruoyi-common-mybatis/.../annotation/DataColumn.java` |
-| `DataScopeType` | `ruoyi-common/ruoyi-common-mybatis/.../enums/DataScopeType.java` |
-| `DataPermissionHelper` | `ruoyi-common/ruoyi-common-mybatis/.../helper/DataPermissionHelper.java` |
-| `PlusDataPermissionHandler` | `ruoyi-common/ruoyi-common-mybatis/.../handler/PlusDataPermissionHandler.java` |
-| 使用示例 | `ruoyi-modules/ruoyi-system/.../impl/SysUserServiceImpl.java` |
-
----
-
-## 多项目适配说明
-
-- 如果需要 leniu-tengyun-core 项目的数据权限开发规范，请使用 `leniu-data-permission` skill
-- leniu-tengyun-core 使用物理库隔离架构，与 RuoYi-Vue-Plus 的逻辑隔离方式不同