ai-engineering-init 1.4.3 → 1.6.0

package/src/skills/tenant-management/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: tenant-management
+description: |
+  多租户数据隔离开发指南。基于 MyBatis-Plus 租户插件，自动 SQL/Redis/Cache 隔离。
+
+  触发场景：
+  - 为业务表添加租户隔离
+  - 临时忽略租户过滤查询全量数据
+  - 切换到其他租户执行操作
+  - 配置排除租户过滤的表
+  - 定时任务遍历所有租户
+
+  触发词：多租户、租户隔离、TenantEntity、TenantHelper、tenantId、跨租户、ignore租户、动态租户、租户切换、SaaS、数据隔离
+---
+
+# 多租户开发指南
+
+> **模块**：`ruoyi-common-tenant` | **核心类**：`TenantHelper`、`TenantEntity`
+
+## 一、Entity 规范
+
+### 继承 TenantEntity
+
+```java
+import org.dromara.common.tenant.core.TenantEntity;
+
+// TenantEntity 继承关系：TenantEntity → BaseEntity
+// TenantEntity 额外字段：tenantId
+// BaseEntity 字段：createDept, createBy, createTime, updateBy, updateTime, params
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("biz_order")
+public class BizOrder extends TenantEntity {
+    @TableId(value = "id")
+    private Long id;
+    private String orderNo;
+    private String status;
+}
+```
+
+### 数据库表必须含 tenant_id
+
+```sql
+CREATE TABLE biz_order (
+    id           BIGINT(20)   NOT NULL COMMENT '主键ID',
+    tenant_id    VARCHAR(20)  DEFAULT '000000' COMMENT '租户ID',  -- 必须有
+    order_no     VARCHAR(64)  NOT NULL COMMENT '订单号',
+    status       CHAR(1)      DEFAULT '0' COMMENT '状态',
+    create_dept  BIGINT(20)   DEFAULT NULL COMMENT '创建部门',
+    create_by    BIGINT(20)   DEFAULT NULL COMMENT '创建人',
+    create_time  DATETIME     DEFAULT CURRENT_TIMESTAMP,
+    update_by    BIGINT(20)   DEFAULT NULL COMMENT '更新人',
+    update_time  DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    del_flag     CHAR(1)      DEFAULT '0' COMMENT '删除标志',
+    PRIMARY KEY (id),
+    KEY idx_tenant_id (tenant_id)
+);
+```
+
+---
+
+## 二、TenantHelper 工具类
+
+**位置**：`org.dromara.common.tenant.helper.TenantHelper`
+
+### API 速查
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `isEnable()` | 租户功能是否启用 | boolean |
+| `getTenantId()` | 获取当前租户ID（优先动态租户） | String |
+| `ignore(Runnable)` | 忽略租户执行（无返回值） | void |
+| `ignore(Supplier<T>)` | 忽略租户执行（有返回值） | T |
+| `dynamic(tenantId, Runnable)` | 切换租户执行（无返回值） | void |
+| `dynamic(tenantId, Supplier<T>)` | 切换租户执行（有返回值） | T |
+| `setDynamic(tenantId)` | 手动设置动态租户（需配合 clearDynamic） | void |
+| `setDynamic(tenantId, true)` | 设置全局动态租户（跨请求，存 Redis） | void |
+| `clearDynamic()` | 清除动态租户 | void |
+
+### 核心用法
+
+```java
+import org.dromara.common.tenant.helper.TenantHelper;
+
+// 1. 忽略租户（查全量数据）
+List<SysUser> allUsers = TenantHelper.ignore(() -> {
+    return userMapper.selectList(null);  // 不追加 tenant_id 条件
+});
+
+// 2. 切换到指定租户（推荐用法）
+TenantHelper.dynamic("000001", () -> {
+    userMapper.insert(user);  // 使用租户 000001
+});
+
+// 3. 手动管理（复杂场景）
+TenantHelper.setDynamic("000001");
+try {
+    userMapper.insert(user);
+} finally {
+    TenantHelper.clearDynamic();  // 必须清理！
+}
+```
+
+---
+
+## 三、配置
+
+```yaml
+# application.yml
+tenant:
+  enable: true
+  excludes:        # 不追加 tenant_id 条件的表
+    - sys_menu
+    - sys_dict_type
+    - sys_dict_data
+    - sys_oss_config
+    - sys_config
+```
+
+**自动配置组件**（`tenant.enable=true` 时生效）：
+
+| 组件 | 功能 |
+|------|------|
+| `TenantLineInnerInterceptor` | SQL 自动追加租户条件 |
+| `TenantKeyPrefixHandler` | Redis Key 自动添加租户前缀 |
+| `TenantSpringCacheManager` | Spring Cache 租户隔离 |
+| `TenantSaTokenDao` | Sa-Token 会话租户隔离 |
+
+---
+
+## 四、常见场景
+
+### 场景 1：管理员查看所有租户数据
+
+```java
+@SaCheckRole("superadmin")
+public List<SysUserVo> listAllTenantUsers() {
+    return TenantHelper.ignore(() -> userMapper.selectVoList(null));
+}
+```
+
+### 场景 2：跨租户数据同步
+
+```java
+public void syncConfigToAllTenants(SysConfig config) {
+    List<String> tenantIds = TenantHelper.ignore(() ->
+        tenantMapper.selectList(null).stream()
+            .map(SysTenant::getTenantId).collect(Collectors.toList())
+    );
+    for (String tenantId : tenantIds) {
+        TenantHelper.dynamic(tenantId, () -> {
+            SysConfig existing = configMapper.selectByKey(config.getConfigKey());
+            if (existing == null) configMapper.insert(config);
+            else configMapper.updateById(config);
+        });
+    }
+}
+```
+
+### 场景 3：定时任务处理所有租户
+
+> 详细示例见 `references/tenant-scenarios.md`
+
+```java
+@Scheduled(cron = "0 0 2 * * ?")
+public void cleanupExpiredOrders() {
+    List<SysTenant> tenants = TenantHelper.ignore(() ->
+        tenantMapper.selectList(Wrappers.<SysTenant>lambdaQuery().eq(SysTenant::getStatus, "0"))
+    );
+    for (SysTenant tenant : tenants) {
+        try {
+            TenantHelper.dynamic(tenant.getTenantId(), () -> {
+                orderMapper.delete(Wrappers.<Order>lambdaQuery()
+                    .eq(Order::getStatus, "CANCELLED")
+                    .lt(Order::getCreateTime, DateUtils.addDays(new Date(), -30)));
+            });
+        } catch (Exception e) {
+            log.error("清理租户 {} 订单失败: {}", tenant.getTenantId(), e.getMessage());
+        }
+    }
+}
+```
+
+---
+
+## 五、Redis 缓存隔离
+
+```
+原始 Key: user:info:1001
+实际 Key: 000000:user:info:1001  （租户 000000）
+实际 Key: 000001:user:info:1001  （租户 000001）
+```
+
+**全局 Key（不隔离）**：使用 `GlobalConstants.GLOBAL_REDIS_KEY` 前缀
+
+```java
+import org.dromara.common.core.constant.GlobalConstants;
+
+// 全局缓存（所有租户共享）
+String globalKey = GlobalConstants.GLOBAL_REDIS_KEY + "config:site_name";
+RedisUtils.setCacheObject(globalKey, "网站名称");
+
+// 租户隔离缓存（自动添加前缀）
+RedisUtils.setCacheObject("user:info:" + userId, userInfo);
+```
+
+> `TenantHelper.ignore()` 中的 Redis 操作不添加租户前缀。
+
+---
+
+## 六、常见错误
+
+### 1. 忘记继承 TenantEntity
+
+```java
+// ❌ 继承 BaseEntity，没有 tenantId
+public class BizOrder extends BaseEntity { }
+
+// ✅ 继承 TenantEntity
+public class BizOrder extends TenantEntity { }
+```
+
+### 2. 数据库表缺少 tenant_id
+
+```sql
+-- ❌ 表没有 tenant_id
+CREATE TABLE biz_order (id BIGINT NOT NULL, order_no VARCHAR(64));
+
+-- ✅ 添加 tenant_id
+CREATE TABLE biz_order (id BIGINT NOT NULL, tenant_id VARCHAR(20) DEFAULT '000000', order_no VARCHAR(64));
+```
+
+### 3. setDynamic 后忘记 clearDynamic
+
+```java
+// ❌ 租户ID泄漏到其他请求
+TenantHelper.setDynamic("000001");
+userMapper.insert(user);
+// 忘记 clearDynamic()
+
+// ✅ 推荐使用 dynamic() 方法（自动清理）
+TenantHelper.dynamic("000001", () -> userMapper.insert(user));
+```
+
+### 4. 事务中切换租户
+
+```java
+// ❌ 事务内切换租户导致数据错乱
+@Transactional
+public void wrongMethod() {
+    orderMapper.insert(order);
+    TenantHelper.dynamic("000001", () -> logMapper.insert(log));
+}
+
+// ✅ 使用独立事务
+@Transactional(propagation = Propagation.REQUIRES_NEW)
+public void saveLogToOtherTenant(String tenantId, Log log) {
+    TenantHelper.dynamic(tenantId, () -> logMapper.insert(log));
+}
+```
+
+### 5. 排除表配置不当
+
+```yaml
+# ❌ 业务表不应排除
+tenant:
+  excludes:
+    - biz_order
+
+# ✅ 只排除共享的系统表
+tenant:
+  excludes:
+    - sys_menu
+    - sys_dict_type
+```
+
+---
+
+## 七、参考代码位置
+
+| 类型 | 位置 |
+|------|------|
+| 租户基类 | `ruoyi-common/ruoyi-common-tenant/.../core/TenantEntity.java` |
+| 租户助手 | `ruoyi-common/ruoyi-common-tenant/.../helper/TenantHelper.java` |
+| 租户处理器 | `ruoyi-common/ruoyi-common-tenant/.../handle/PlusTenantLineHandler.java` |
+| Redis Key 处理 | `ruoyi-common/ruoyi-common-tenant/.../handle/TenantKeyPrefixHandler.java` |
+| 配置文件 | `ruoyi-admin/src/main/resources/application.yml` |

package/src/skills/tenant-management/references/tenant-scenarios.md

@@ -0,0 +1,91 @@
+# 多租户扩展场景
+
+## 统计所有租户数据
+
+```java
+public List<TenantOrderStats> getTenantOrderStats() {
+    return TenantHelper.ignore(() -> {
+        return orderMapper.selectMaps(
+            new QueryWrapper<Order>()
+                .select("tenant_id", "COUNT(*) as order_count", "SUM(amount) as total_amount")
+                .groupBy("tenant_id")
+        ).stream().map(map -> {
+            TenantOrderStats stats = new TenantOrderStats();
+            stats.setTenantId((String) map.get("tenant_id"));
+            stats.setOrderCount(((Number) map.get("order_count")).longValue());
+            stats.setTotalAmount((BigDecimal) map.get("total_amount"));
+            return stats;
+        }).collect(Collectors.toList());
+    });
+}
+```
+
+## 定时任务完整模板
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OrderCleanupJob {
+
+    private final OrderMapper orderMapper;
+    private final SysTenantMapper tenantMapper;
+
+    @Scheduled(cron = "0 0 2 * * ?")
+    public void cleanupExpiredOrders() {
+        // 1. 获取所有启用的租户
+        List<SysTenant> tenants = TenantHelper.ignore(() -> {
+            return tenantMapper.selectList(
+                Wrappers.<SysTenant>lambdaQuery()
+                    .eq(SysTenant::getStatus, "0")
+            );
+        });
+
+        // 2. 逐个租户处理
+        for (SysTenant tenant : tenants) {
+            try {
+                TenantHelper.dynamic(tenant.getTenantId(), () -> {
+                    orderMapper.delete(
+                        Wrappers.<Order>lambdaQuery()
+                            .eq(Order::getStatus, "CANCELLED")
+                            .lt(Order::getCreateTime, DateUtils.addDays(new Date(), -30))
+                    );
+                });
+            } catch (Exception e) {
+                log.error("清理租户 {} 订单失败: {}", tenant.getTenantId(), e.getMessage());
+            }
+        }
+    }
+}
+```
+
+## 跨租户数据同步完整模板
+
+```java
+@Service
+@RequiredArgsConstructor
+public class DataSyncServiceImpl implements IDataSyncService {
+
+    private final SysConfigMapper configMapper;
+    private final SysTenantMapper tenantMapper;
+
+    public void syncConfigToAllTenants(SysConfig config) {
+        List<String> tenantIds = TenantHelper.ignore(() -> {
+            return tenantMapper.selectList(null)
+                .stream()
+                .map(SysTenant::getTenantId)
+                .collect(Collectors.toList());
+        });
+
+        for (String tenantId : tenantIds) {
+            TenantHelper.dynamic(tenantId, () -> {
+                SysConfig existing = configMapper.selectByKey(config.getConfigKey());
+                if (existing == null) {
+                    configMapper.insert(config);
+                } else {
+                    configMapper.updateById(config);
+                }
+            });
+        }
+    }
+}
+```

package/src/skills/test-development/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: test-development
+description: |
+  测试开发技能，编写单元测试、集成测试、Controller测试。基于 JUnit5 + Spring Boot Test + Mockito 标准测试框架。
+
+  触发场景：
+  - 编写单元测试（工具类、枚举、POJO）
+  - 编写 Spring 集成测试（Service、Controller、Mapper）
+  - Mock 外部依赖
+  - 参数化测试
+  - 测试数据构造
+  - 测试覆盖率提升
+
+  触发词：测试、单元测试、集成测试、@Test、JUnit5、JUnit、Mockito、Mock、断言、test、测试用例、测试覆盖率、测试数据、@SpringBootTest、@Mock、@MockBean、Assertions、测试类、测试方法、@ParameterizedTest、参数化测试、@BeforeEach、@AfterEach、@DisplayName
+
+  注意：本项目使用标准的 JUnit5 + Spring Boot Test，没有自定义测试基类。
+---
+
+# 测试开发规范
+
+## 测试分层策略
+
+| 层次 | 测试类型 | 启动 Spring | 执行速度 |
+|------|---------|------------|---------|
+| 单元测试 | 工具类/枚举/POJO | 否 | < 1s |
+| 集成测试 | Service/Controller/Mapper | 是（`@SpringBootTest`） | 5-10s |
+
+## 测试文件位置
+
+```
+src/test/java/org/dromara/test/     # 通用测试
+src/test/java/org/dromara/{模块}/   # 模块测试（与源码包路径一致）
+```
+
+**重要**：`@SpringBootTest` 只能在 SpringBoot 主包下使用（需包含 main 方法和 yml 配置）。
+
+---
+
+## 1. 单元测试（纯 JUnit5，无 Spring）
+
+```java
+package org.dromara.test;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+@DisplayName("StringUtils 测试")
+public class StringUtilsTest {
+
+    @Test
+    @DisplayName("测试 isBlank 方法")
+    public void testIsBlank() {
+        Assertions.assertTrue(StringUtils.isBlank(null));
+        Assertions.assertTrue(StringUtils.isBlank(""));
+        Assertions.assertFalse(StringUtils.isBlank("hello"));
+    }
+
+    @Test
+    @DisplayName("测试异常抛出")
+    public void testThrowsException() {
+        Assertions.assertThrows(NullPointerException.class, () -> {
+            String str = null;
+            str.length();
+        });
+    }
+}
+```
+
+---
+
+## 2. Service 集成测试
+
+```java
+@SpringBootTest
+@Transactional  // 测试后自动回滚，不污染数据库
+@DisplayName("TestDemo Service 测试")
+public class TestDemoServiceTest {
+
+    @Autowired
+    private ITestDemoService testDemoService;
+
+    @Test
+    @DisplayName("测试添加数据")
+    public void testAdd() {
+        // Arrange
+        TestDemoBo bo = new TestDemoBo();
+        bo.setDeptId(103L);
+        bo.setUserId(1L);
+        bo.setTestKey("测试数据");
+        bo.setValue("test_value");
+
+        // Act
+        Boolean result = testDemoService.insertByBo(bo);
+
+        // Assert
+        Assertions.assertTrue(result);
+    }
+
+    @Test
+    @DisplayName("测试查询详情")
+    public void testGetById() {
+        TestDemoBo bo = new TestDemoBo();
+        bo.setTestKey("测试查询");
+        bo.setValue("test_query");
+        testDemoService.insertByBo(bo);
+
+        TestDemoVo vo = testDemoService.queryById(bo.getId());
+        Assertions.assertNotNull(vo);
+        Assertions.assertEquals("测试查询", vo.getTestKey());
+    }
+}
+```
+
+### Mock 外部依赖
+
+```java
+@SpringBootTest
+@DisplayName("订单服务测试")
+public class OrderServiceTest {
+
+    @Autowired
+    private IOrderService orderService;
+
+    @MockBean
+    private IPaymentService paymentService;
+
+    @Test
+    @DisplayName("测试订单支付（Mock 支付服务）")
+    public void testPayOrder() {
+        Long orderId = 123L;
+        Mockito.when(paymentService.pay(orderId)).thenReturn(true);
+
+        Boolean success = orderService.payOrder(orderId);
+
+        Assertions.assertTrue(success);
+        Mockito.verify(paymentService, Mockito.times(1)).pay(orderId);
+    }
+}
+```
+
+---
+
+## 3. Controller 测试
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+@DisplayName("TestDemo Controller 测试")
+public class TestDemoControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Test
+    @DisplayName("测试分页查询")
+    public void testPageList() throws Exception {
+        mockMvc.perform(get("/demo/demo/list")
+                .param("pageNum", "1")
+                .param("pageSize", "10"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.code").value(200));
+    }
+
+    @Test
+    @DisplayName("测试添加数据")
+    public void testAdd() throws Exception {
+        String requestBody = """
+            {
+                "deptId": 103,
+                "userId": 1,
+                "testKey": "测试数据",
+                "value": "test_value"
+            }
+            """;
+
+        mockMvc.perform(post("/demo/demo")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(requestBody))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.code").value(200));
+    }
+}
+```
+
+---
+
+## 4. 参数化测试
+
+```java
+@DisplayName("参数化测试")
+public class ParamUnitTest {
+
+    @ParameterizedTest
+    @ValueSource(strings = {"t1", "t2", "t3"})
+    public void testValueSource(String str) {
+        Assertions.assertNotNull(str);
+    }
+
+    @ParameterizedTest
+    @EnumSource(UserType.class)
+    public void testEnumSource(UserType type) {
+        Assertions.assertNotNull(type);
+    }
+
+    @ParameterizedTest
+    @CsvSource({"1, Banner, 横幅广告", "2, Popup, 弹窗广告"})
+    public void testCsvData(String code, String name, String desc) {
+        Assertions.assertNotNull(code);
+    }
+
+    @ParameterizedTest
+    @MethodSource("getParam")
+    public void testMethodSource(String str) {
+        Assertions.assertNotNull(str);
+    }
+
+    public static Stream<String> getParam() {
+        return Stream.of("t1", "t2", "t3");
+    }
+}
+```
+
+> 更多参数化测试示例详见 `references/parameterized-examples.md`
+
+---
+
+## 5. 异常测试
+
+```java
+@Test
+@DisplayName("测试 key 为空抛出异常")
+public void testAdd_ThrowsException() {
+    TestDemoBo bo = new TestDemoBo();
+    // 不设置必填字段
+
+    ServiceException exception = Assertions.assertThrows(
+        ServiceException.class,
+        () -> testDemoService.insertByBo(bo)
+    );
+    Assertions.assertTrue(exception.getMessage().contains("key键不能为空"));
+}
+```
+
+---
+
+## 6. 测试标签（@Tag）
+
+```java
+@Test @Tag("dev")   public void testDev() { }
+@Test @Tag("prod")  public void testProd() { }
+```
+
+```bash
+mvn test -Dgroups=dev           # 运行 dev 标签
+mvn test -DexcludedGroups=prod  # 排除 prod 标签
+```
+
+---
+
+## 运行测试
+
+```bash
+mvn test                                  # 运行所有测试
+mvn test -Dtest=AdServiceTest             # 运行单个测试类
+mvn test -Dtest=AdServiceTest#testAddAd   # 运行单个方法
+mvn clean install -DskipTests             # 跳过测试
+```
+
+---
+
+## 开发检查清单
+
+### 命名规范
+
+- [ ] 测试类：`{被测试类名}Test`
+- [ ] 测试方法：`test{功能}`
+- [ ] 使用 `@DisplayName` 添加中文描述
+- [ ] 位于 `src/test/java`，包路径与源码一致
+
+### 注解选择
+
+| 场景 | 注解组合 |
+|------|---------|
+| 工具类/枚举/POJO | 不加 `@SpringBootTest` |
+| Service 测试 | `@SpringBootTest` + `@Transactional` |
+| Controller 测试 | `@SpringBootTest` + `@AutoConfigureMockMvc` |
+| Mock Spring Bean | `@MockBean` |
+| Mock（纯单元测试） | `@Mock` + `@InjectMocks` |
+
+### 常见错误
+
+| 错误 | 正确做法 |
+|------|---------|
+| 测试在 `src/main/java` | 放到 `src/test/java` |
+| 缺少 `@DisplayName` | 必须添加描述 |
+| 需要注入但没加 `@SpringBootTest` | 加上注解 |
+| `@SpringBootTest` 在非主包下 | 确保在主类同包或子包 |
+| Mock 后不验证调用 | `Mockito.verify()` |
+| 测试方法相互依赖 | 每个测试独立 |
+| Service 测试不加 `@Transactional` | 加上防止污染数据库 |