leniu-dev 2.0.0

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

@@ -0,0 +1,272 @@
+---
+name: tenant-management
+description: |
+  通用多租户架构设计指南。涵盖字段隔离、Schema 隔离、物理隔离三种模式的对比与实现要点。
+  触发场景：
+  - 设计多租户 SaaS 系统架构
+  - 选择租户隔离方案
+  - 处理跨租户数据操作
+  - 定时任务遍历所有租户
+  - 配置 Redis / 缓存租户隔离
+  触发词：多租户、租户隔离、SaaS、tenantId、跨租户、租户切换、数据隔离、Schema隔离、物理隔离、字段隔离
+  注意：如果项目有专属技能（如 `leniu-data-permission` 或 `leniu-tenant`），优先使用专属版本。
+---
+
+# 多租户架构设计指南
+
+> 通用模板。如果项目有专属技能，优先使用。
+
+## 设计原则
+
+1. **隔离性**：租户数据必须完全隔离，不可跨租户访问。
+2. **透明性**：业务代码尽量不感知多租户，由框架层自动处理。
+3. **可扩展**：新增租户不需要改代码，配置即可上线。
+4. **运维友好**：备份恢复、数据迁移应以租户为单位。
+
+---
+
+## 三种隔离模式对比
+
+| 维度 | 字段隔离 | Schema 隔离 | 物理隔离（独立库） |
+|------|---------|------------|-----------------|
+| **实现方式** | 每张表加 `tenant_id` 字段 | 每个租户独立 Schema | 每个租户独立数据库 |
+| **隔离强度** | 低（逻辑隔离） | 中（Schema 级） | 高（物理隔离） |
+| **数据安全** | 依赖应用层正确过滤 | 数据库级隔离 | 最安全 |
+| **资源利用** | 高（共享一切） | 中（共享实例） | 低（独占资源） |
+| **扩展性** | 单库上限制约 | 单实例 Schema 数限制 | 水平扩展灵活 |
+| **运维复杂度** | 低 | 中 | 高 |
+| **备份恢复** | 复杂（需过滤） | 简单（按 Schema） | 最简单（按库） |
+| **租户定制** | 困难 | 可支持 | 完全独立 |
+| **成本** | 最低 | 中等 | 最高 |
+| **适用场景** | 中小 SaaS、租户量大 | 中等规模、需一定隔离 | 大客户、强合规需求 |
+
+---
+
+## 实现模式
+
+### 模式一：字段隔离（最常见）
+
+```java
+// 1. Entity 携带 tenant_id
+public class [你的租户基类] extends [你的基础Entity] {
+    private String tenantId;
+}
+
+@TableName("biz_order")
+public class BizOrder extends [你的租户基类] {
+    private Long id;
+    private String orderNo;
+}
+
+// 2. 数据库表必须含 tenant_id
+// CREATE TABLE biz_order (
+//     id         BIGINT NOT NULL,
+//     tenant_id  VARCHAR(20) DEFAULT '000000' COMMENT '租户ID',
+//     order_no   VARCHAR(64) NOT NULL,
+//     PRIMARY KEY (id),
+//     KEY idx_tenant_id (tenant_id)
+// );
+
+// 3. MyBatis 拦截器自动追加条件
+// SELECT * FROM biz_order WHERE tenant_id = '000001' AND ...
+// INSERT INTO biz_order (tenant_id, ...) VALUES ('000001', ...)
+```
+
+**核心工具类模式**：
+
+```java
+public class [你的租户工具类] {
+
+    // 获取当前租户ID（从请求上下文/ThreadLocal）
+    public static String getTenantId() { ... }
+
+    // 忽略租户过滤（查全量数据）
+    public static <T> T ignore(Supplier<T> supplier) {
+        // 临时关闭拦截器的租户条件追加
+        try {
+            setIgnore(true);
+            return supplier.get();
+        } finally {
+            setIgnore(false);
+        }
+    }
+
+    // 切换到指定租户执行
+    public static void dynamic(String tenantId, Runnable runnable) {
+        String original = getTenantId();
+        try {
+            setTenantId(tenantId);
+            runnable.run();
+        } finally {
+            setTenantId(original);
+        }
+    }
+
+    // 带返回值的租户切换
+    public static <T> T dynamic(String tenantId, Supplier<T> supplier) {
+        String original = getTenantId();
+        try {
+            setTenantId(tenantId);
+            return supplier.get();
+        } finally {
+            setTenantId(original);
+        }
+    }
+}
+```
+
+**配置排除表**（不需要租户过滤的共享表）：
+
+```yaml
+tenant:
+  enable: true
+  excludes:
+    - sys_menu
+    - sys_dict_type
+    - sys_dict_data
+    - sys_config
+```
+
+### 模式二：Schema 隔离
+
+```java
+// 动态数据源 / 动态 Schema 切换
+public class TenantSchemaResolver {
+    public String resolveSchema(String tenantId) {
+        return "tenant_" + tenantId;  // tenant_000001, tenant_000002
+    }
+}
+
+// 通过 AbstractRoutingDataSource 或 MyBatis 拦截器切换 Schema
+// SET search_path TO tenant_000001;  (PostgreSQL)
+// USE tenant_000001;                 (MySQL)
+```
+
+### 模式三：物理隔离（独立库）
+
+```java
+// 每个租户对应独立的数据源配置
+// 通过 AbstractRoutingDataSource 或动态数据源框架切换
+
+public class TenantDataSourceRouter extends AbstractRoutingDataSource {
+    @Override
+    protected Object determineCurrentLookupKey() {
+        return [你的租户工具类].getTenantId();
+    }
+}
+
+// 典型用法
+[你的租户工具类].doInTenant(tenantId, () -> {
+    // 自动路由到该租户的数据库
+    orderMapper.insert(order);
+});
+
+[你的租户工具类].doInSystem(() -> {
+    // 路由到系统公共库
+    configMapper.selectList(null);
+});
+```
+
+---
+
+## 常见场景
+
+### 场景 1：管理员查看所有租户数据
+
+```java
+public List<UserVo> listAllTenantUsers() {
+    return [你的租户工具类].ignore(() -> userMapper.selectVoList(null));
+}
+```
+
+### 场景 2：跨租户数据同步
+
+```java
+public void syncConfigToAllTenants(Config config) {
+    List<String> tenantIds = [你的租户工具类].ignore(() ->
+        tenantMapper.selectList(null).stream()
+            .map(Tenant::getTenantId).collect(Collectors.toList())
+    );
+    for (String tenantId : tenantIds) {
+        [你的租户工具类].dynamic(tenantId, () -> {
+            configMapper.insertOrUpdate(config);
+        });
+    }
+}
+```
+
+### 场景 3：定时任务遍历所有租户
+
+```java
+@Scheduled(cron = "0 0 2 * * ?")
+public void cleanupExpiredOrders() {
+    List<Tenant> tenants = [你的租户工具类].ignore(() ->
+        tenantMapper.selectByStatus("ACTIVE")
+    );
+    for (Tenant tenant : tenants) {
+        try {
+            [你的租户工具类].dynamic(tenant.getTenantId(), () -> {
+                orderMapper.deleteExpired(30);
+            });
+        } catch (Exception e) {
+            log.error("清理租户 {} 订单失败: {}", tenant.getTenantId(), e.getMessage());
+        }
+    }
+}
+```
+
+### 场景 4：Redis 缓存隔离
+
+```
+原始 Key: user:info:1001
+实际 Key: 000000:user:info:1001  （租户 000000）
+实际 Key: 000001:user:info:1001  （租户 000001）
+```
+
+全局缓存（不隔离）：使用特定前缀标识全局 Key。
+
+---
+
+## 选型建议
+
+| 维度 | 字段隔离 | Schema 隔离 | 物理隔离 |
+|------|---------|------------|---------|
+| 租户数量 | 大量（100+） | 中等（10-100） | 少量（<20） |
+| 数据量级 | 单租户数据量小 | 中等 | 大 |
+| 合规要求 | 一般 | 中等 | 严格（金融、政务） |
+| 预算 | 有限 | 中等 | 充足 |
+| 定制化 | 几乎不需要 | 少量 | 高度定制 |
+
+---
+
+## 常见错误
+
+```java
+// 1. Entity 忘记继承租户基类 / 表缺少 tenant_id（字段隔离模式）
+public class BizOrder extends BaseEntity { }  // 缺少 tenantId
+// 表中也没有 tenant_id 字段 -> 数据不隔离
+
+// 2. 手动设置租户后忘记清理
+[你的租户工具类].setTenantId("000001");
+userMapper.insert(user);
+// 忘记恢复原租户ID -> 后续请求使用错误租户
+// 应使用 dynamic() 方法（自动恢复）
+
+// 3. 事务中切换租户（字段隔离模式下可能数据错乱）
+@Transactional
+public void wrongMethod() {
+    orderMapper.insert(order);                                // 租户 A
+    [你的租户工具类].dynamic("B", () -> logMapper.insert(log)); // 租户 B
+    // 如果回滚，租户 B 的数据不会回滚（不同事务）
+}
+// 应使用独立事务
+@Transactional(propagation = Propagation.REQUIRES_NEW)
+public void saveToOtherTenant(String tenantId, Log log) { ... }
+
+// 4. 共享表未排除租户过滤
+// sys_dict_type 等共享表被加上 tenant_id 条件 -> 查不到数据
+// 应在配置中排除这些表
+
+// 5. 物理隔离模式下使用 tenant_id 字段（画蛇添足）
+// 物理隔离已通过数据源区分租户，表中不需要 tenant_id
+```

package/.cursor/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/.cursor/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` | 加上防止污染数据库 |