ai-engineering-init 1.7.0 → 1.8.0

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

@@ -1,179 +1,212 @@
 ---
 name: tenant-management
 description: |
-  多租户数据隔离开发指南。基于 MyBatis-Plus 租户插件，自动 SQL/Redis/Cache 隔离。
-
+  通用多租户架构设计指南。涵盖字段隔离、Schema 隔离、物理隔离三种模式的对比与实现要点。
   触发场景：
-  - 为业务表添加租户隔离
-  - 临时忽略租户过滤查询全量数据
-  - 切换到其他租户执行操作
-  - 配置排除租户过滤的表
+  - 设计多租户 SaaS 系统架构
+  - 选择租户隔离方案
+  - 处理跨租户数据操作
   - 定时任务遍历所有租户
+  - 配置 Redis / 缓存租户隔离
+  触发词：多租户、租户隔离、SaaS、tenantId、跨租户、租户切换、数据隔离、Schema隔离、物理隔离、字段隔离
+  注意：如果项目有专属技能（如 `leniu-data-permission` 或 `leniu-tenant`），优先使用专属版本。
+---
+
+# 多租户架构设计指南
+
+> 通用模板。如果项目有专属技能，优先使用。
+
+## 设计原则
+
+1. **隔离性**：租户数据必须完全隔离，不可跨租户访问。
+2. **透明性**：业务代码尽量不感知多租户，由框架层自动处理。
+3. **可扩展**：新增租户不需要改代码，配置即可上线。
+4. **运维友好**：备份恢复、数据迁移应以租户为单位。
 
-  触发词：多租户、租户隔离、TenantEntity、TenantHelper、tenantId、跨租户、ignore租户、动态租户、租户切换、SaaS、数据隔离
 ---
 
-# 多租户开发指南
+## 三种隔离模式对比
+
+| 维度 | 字段隔离 | Schema 隔离 | 物理隔离（独立库） |
+|------|---------|------------|-----------------|
+| **实现方式** | 每张表加 `tenant_id` 字段 | 每个租户独立 Schema | 每个租户独立数据库 |
+| **隔离强度** | 低（逻辑隔离） | 中（Schema 级） | 高（物理隔离） |
+| **数据安全** | 依赖应用层正确过滤 | 数据库级隔离 | 最安全 |
+| **资源利用** | 高（共享一切） | 中（共享实例） | 低（独占资源） |
+| **扩展性** | 单库上限制约 | 单实例 Schema 数限制 | 水平扩展灵活 |
+| **运维复杂度** | 低 | 中 | 高 |
+| **备份恢复** | 复杂（需过滤） | 简单（按 Schema） | 最简单（按库） |
+| **租户定制** | 困难 | 可支持 | 完全独立 |
+| **成本** | 最低 | 中等 | 最高 |
+| **适用场景** | 中小 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
+// 1. Entity 携带 tenant_id
+public class [你的租户基类] extends [你的基础Entity] {
+    private String tenantId;
+}
 
-@Data
-@EqualsAndHashCode(callSuper = true)
 @TableName("biz_order")
-public class BizOrder extends TenantEntity {
-    @TableId(value = "id")
+public class BizOrder extends [你的租户基类] {
     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)
-);
+// 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', ...)
 ```
 
----
-
-## 二、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;
+public class [你的租户工具类] {
 
-// 1. 忽略租户（查全量数据）
-List<SysUser> allUsers = TenantHelper.ignore(() -> {
-    return userMapper.selectList(null);  // 不追加 tenant_id 条件
-});
+    // 获取当前租户ID（从请求上下文/ThreadLocal）
+    public static String getTenantId() { ... }
 
-// 2. 切换到指定租户（推荐用法）
-TenantHelper.dynamic("000001", () -> {
-    userMapper.insert(user);  // 使用租户 000001
-});
+    // 忽略租户过滤（查全量数据）
+    public static <T> T ignore(Supplier<T> supplier) {
+        // 临时关闭拦截器的租户条件追加
+        try {
+            setIgnore(true);
+            return supplier.get();
+        } finally {
+            setIgnore(false);
+        }
+    }
 
-// 3. 手动管理（复杂场景）
-TenantHelper.setDynamic("000001");
-try {
-    userMapper.insert(user);
-} finally {
-    TenantHelper.clearDynamic();  // 必须清理！
+    // 切换到指定租户执行
+    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
-# application.yml
 tenant:
   enable: true
-  excludes:        # 不追加 tenant_id 条件的表
+  excludes:
     - sys_menu
     - sys_dict_type
     - sys_dict_data
-    - sys_oss_config
     - sys_config
 ```
 
-**自动配置组件**（`tenant.enable=true` 时生效）：
+### 模式二：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);
+});
 
-| 组件 | 功能 |
-|------|------|
-| `TenantLineInnerInterceptor` | SQL 自动追加租户条件 |
-| `TenantKeyPrefixHandler` | Redis Key 自动添加租户前缀 |
-| `TenantSpringCacheManager` | Spring Cache 租户隔离 |
-| `TenantSaTokenDao` | Sa-Token 会话租户隔离 |
+[你的租户工具类].doInSystem(() -> {
+    // 路由到系统公共库
+    configMapper.selectList(null);
+});
+```
 
 ---
 
-## 四、常见场景
+## 常见场景
 
 ### 场景 1：管理员查看所有租户数据
 
 ```java
-@SaCheckRole("superadmin")
-public List<SysUserVo> listAllTenantUsers() {
-    return TenantHelper.ignore(() -> userMapper.selectVoList(null));
+public List<UserVo> listAllTenantUsers() {
+    return [你的租户工具类].ignore(() -> userMapper.selectVoList(null));
 }
 ```
 
 ### 场景 2：跨租户数据同步
 
 ```java
-public void syncConfigToAllTenants(SysConfig config) {
-    List<String> tenantIds = TenantHelper.ignore(() ->
+public void syncConfigToAllTenants(Config config) {
+    List<String> tenantIds = [你的租户工具类].ignore(() ->
         tenantMapper.selectList(null).stream()
-            .map(SysTenant::getTenantId).collect(Collectors.toList())
+            .map(Tenant::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);
+        [你的租户工具类].dynamic(tenantId, () -> {
+            configMapper.insertOrUpdate(config);
         });
     }
 }
 ```
 
-### 场景 3：定时任务处理所有租户
-
-> 详细示例见 `references/tenant-scenarios.md`
+### 场景 3：定时任务遍历所有租户
 
 ```java
 @Scheduled(cron = "0 0 2 * * ?")
 public void cleanupExpiredOrders() {
-    List<SysTenant> tenants = TenantHelper.ignore(() ->
-        tenantMapper.selectList(Wrappers.<SysTenant>lambdaQuery().eq(SysTenant::getStatus, "0"))
+    List<Tenant> tenants = [你的租户工具类].ignore(() ->
+        tenantMapper.selectByStatus("ACTIVE")
     );
-    for (SysTenant tenant : tenants) {
+    for (Tenant tenant : tenants) {
         try {
-            TenantHelper.dynamic(tenant.getTenantId(), () -> {
-                orderMapper.delete(Wrappers.<Order>lambdaQuery()
-                    .eq(Order::getStatus, "CANCELLED")
-                    .lt(Order::getCreateTime, DateUtils.addDays(new Date(), -30)));
+            [你的租户工具类].dynamic(tenant.getTenantId(), () -> {
+                orderMapper.deleteExpired(30);
             });
         } catch (Exception e) {
             log.error("清理租户 {} 订单失败: {}", tenant.getTenantId(), e.getMessage());
@@ -182,9 +215,7 @@ public void cleanupExpiredOrders() {
 }
 ```
 
----
-
-## 五、Redis 缓存隔离
+### 场景 4：Redis 缓存隔离
 
 ```
 原始 Key: user:info:1001
@@ -192,97 +223,50 @@ public void cleanupExpiredOrders() {
 实际 Key: 000001:user:info:1001  （租户 000001）
 ```
 
-**全局 Key（不隔离）**：使用 `GlobalConstants.GLOBAL_REDIS_KEY` 前缀
-
-```java
-import org.dromara.common.core.constant.GlobalConstants;
+全局缓存（不隔离）：使用特定前缀标识全局 Key。
 
-// 全局缓存（所有租户共享）
-String globalKey = GlobalConstants.GLOBAL_REDIS_KEY + "config:site_name";
-RedisUtils.setCacheObject(globalKey, "网站名称");
+---
 
-// 租户隔离缓存（自动添加前缀）
-RedisUtils.setCacheObject("user:info:" + userId, userInfo);
-```
+## 选型建议
 
-> `TenantHelper.ignore()` 中的 Redis 操作不添加租户前缀。
+| 维度 | 字段隔离 | Schema 隔离 | 物理隔离 |
+|------|---------|------------|---------|
+| 租户数量 | 大量（100+） | 中等（10-100） | 少量（<20） |
+| 数据量级 | 单租户数据量小 | 中等 | 大 |
+| 合规要求 | 一般 | 中等 | 严格（金融、政务） |
+| 预算 | 有限 | 中等 | 充足 |
+| 定制化 | 几乎不需要 | 少量 | 高度定制 |
 
 ---
 
-## 六、常见错误
-
-### 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
+// 1. Entity 忘记继承租户基类 / 表缺少 tenant_id（字段隔离模式）
+public class BizOrder extends BaseEntity { }  // 缺少 tenantId
+// 表中也没有 tenant_id 字段 -> 数据不隔离
 
-```java
-// ❌ 租户ID泄漏到其他请求
-TenantHelper.setDynamic("000001");
+// 2. 手动设置租户后忘记清理
+[你的租户工具类].setTenantId("000001");
 userMapper.insert(user);
-// 忘记 clearDynamic()
-
-// ✅ 推荐使用 dynamic() 方法（自动清理）
-TenantHelper.dynamic("000001", () -> userMapper.insert(user));
-```
+// 忘记恢复原租户ID -> 后续请求使用错误租户
+// 应使用 dynamic() 方法（自动恢复）
 
-### 4. 事务中切换租户
-
-```java
-// ❌ 事务内切换租户导致数据错乱
+// 3. 事务中切换租户（字段隔离模式下可能数据错乱）
 @Transactional
 public void wrongMethod() {
-    orderMapper.insert(order);
-    TenantHelper.dynamic("000001", () -> logMapper.insert(log));
+    orderMapper.insert(order);                                // 租户 A
+    [你的租户工具类].dynamic("B", () -> logMapper.insert(log)); // 租户 B
+    // 如果回滚，租户 B 的数据不会回滚（不同事务）
 }
-
-// ✅ 使用独立事务
+// 应使用独立事务
 @Transactional(propagation = Propagation.REQUIRES_NEW)
-public void saveLogToOtherTenant(String tenantId, Log log) {
-    TenantHelper.dynamic(tenantId, () -> logMapper.insert(log));
-}
-```
+public void saveToOtherTenant(String tenantId, Log log) { ... }
 
-### 5. 排除表配置不当
+// 4. 共享表未排除租户过滤
+// sys_dict_type 等共享表被加上 tenant_id 条件 -> 查不到数据
+// 应在配置中排除这些表
 
-```yaml
-# ❌ 业务表不应排除
-tenant:
-  excludes:
-    - biz_order
-
-# ✅ 只排除共享的系统表
-tenant:
-  excludes:
-    - sys_menu
-    - sys_dict_type
+// 5. 物理隔离模式下使用 tenant_id 字段（画蛇添足）
+// 物理隔离已通过数据源区分租户，表中不需要 tenant_id
 ```
-
----
-
-## 七、参考代码位置
-
-| 类型 | 位置 |
-|------|------|
-| 租户基类 | `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` |