# 跨租户操作模式（Cross-Tenant Operation Pattern）

> 来源：酒店-餐厅双租户拆分
> 时间：2026-09-30

## 业务背景

酒店点餐模块拆分为两个租户：
- **酒店租户**（如 tenant_id=8）：管理客房、订单、支付、二维码、对账
- **餐厅租户**（如 tenant_id=9）：管理菜品、分类、规格、营业时段、暂停接单

顾客通过二维码扫码下单，订单归属酒店租户（tenant_id=8）。但后续订单操作（接单、备餐、出餐、配送、完成、退单等）可能由餐厅员工在餐厅租户下执行。

## 核心问题

### TenantLineInnerInterceptor 的行为

MyBatis-Plus 的 `TenantLineInnerInterceptor` 会根据**当前登录上下文**自动追加 `tenant_id = 当前租户ID`：

- **SELECT**：`WHERE ... AND tenant_id = 当前上下文`
- **UPDATE**：`WHERE ... AND tenant_id = 当前上下文`
- **DELETE**：`WHERE ... AND tenant_id = 当前上下文`

### 关键陷阱

**传参数不能覆盖拦截器行为！**

```java
// ❌ 错误：以为传了 tenantId=8 就能查 tenant_id=8 的数据
orderMapper.selectKitchenOrderList(8, queryDate);

// 实际生成的 SQL：
SELECT ... FROM hotel_order
WHERE tenant_id = 8          -- XML 显式条件（参数传入）
  AND tenant_id = 9          -- 拦截器自动追加（当前登录上下文）
-- 两个条件矛盾 → 查不到数据！
```

## 解决方案

### 方案一：executeWithTenant — 临时切换租户上下文

用于**查询/操作另一个租户的数据**。

```java
// ✅ 正确：用 executeWithTenant 切换上下文
final Long hotelTenantId = 8L; // 从映射表解析
TenantContextHolder.executeWithTenant(hotelTenantId, new Runnable() {
    @Override
    public void run() {
        // 拦截器现在追加 tenant_id = 8
        orderMapper.selectKitchenOrderList(hotelTenantId, queryDate);
        orderMapper.updateById(order); // WHERE tenant_id = 8
    }
});
```

**关键点**：
- `executeWithTenant` 切换的是**整个上下文**，拦截器和 XML 都会使用新值
- 适用于有返回值的场景用 `Supplier<T>` 重载
- 适用于无返回值的场景用 `Runnable` 重载

### 方案二：executeIgnore — 绕过租户过滤

用于**系统级配置表**（如映射表），所有租户都需要访问。

```java
// ✅ 正确：映射表是系统级配置，用 executeIgnore 绕过
default HotelTenantMapping selectByRestaurantTenantId(Long restaurantTenantId) {
    return TenantContextHolder.executeIgnore(() -> _selectByRestaurantTenantId(restaurantTenantId));
}
```

**关键点**：
- 映射表的 `tenant_id` 应设为 `1`（系统级）
- XML 中不要写 `tenant_id = ?` 条件
- 用 `default` 方法 + `executeIgnore` 包裹实际查询方法

## 双租户映射表设计

### 表结构

```sql
CREATE TABLE hotel_tenant_mapping (
    id              BIGINT NOT NULL,
    tenant_id       BIGINT NOT NULL DEFAULT 1 COMMENT '系统级配置，固定为1',
    hotel_tenant_id BIGINT NOT NULL COMMENT '酒店租户ID',
    restaurant_tenant_id BIGINT NOT NULL COMMENT '餐厅租户ID',
    status          VARCHAR(16) NOT NULL DEFAULT 'ACTIVE',
    ...
);
```

### 查询模式

```java
// Mapper 接口：用 default 方法 + executeIgnore
default Long selectRestaurantTenantId(Long hotelTenantId) {
    return TenantContextHolder.executeIgnore(() -> _selectRestaurantTenantId(hotelTenantId));
}

// XML：不写 tenant_id 条件
<select id="_selectRestaurantTenantId" resultType="java.lang.Long">
    SELECT restaurant_tenant_id
    FROM hotel_tenant_mapping
    WHERE hotel_tenant_id = #{hotelTenantId}
      AND status = 'ACTIVE'
      AND del_flag = 0
    LIMIT 1
</select>
```

## Service 层租户解析模式

### 解析酒店租户（管理端查询/操作订单）

```java
private Long resolveHotelTenantForAdmin() {
    Long currentTenantId = resolveTenantId();
    // 尝试从映射表反查：restaurant_tenant_id -> hotel_tenant_id
    HotelTenantMapping mapping = tenantMappingMapper.selectByRestaurantTenantId(currentTenantId);
    if (mapping != null && mapping.getHotelTenantId() != null) {
        return mapping.getHotelTenantId();
    }
    // 未找到映射，说明当前就是酒店租户或未配置双租户
    return currentTenantId;
}
```

### 解析餐厅租户（顾客端查菜品）

```java
private Long resolveRestaurantTenantId(Long hotelTenantId) {
    Long restaurantTenantId = tenantMappingMapper.selectRestaurantTenantId(hotelTenantId);
    return restaurantTenantId != null ? restaurantTenantId : hotelTenantId;
}
```

## 完整方法包裹模式

### 查询方法

```java
@Override
public List<HotelOrderVO> kitchenOrderList(final Date queryDate) {
    final Long hotelTenantId = resolveHotelTenantForAdmin();
    return TenantContextHolder.executeWithTenant(hotelTenantId, new java.util.function.Supplier<List<HotelOrderVO>>() {
        @Override
        public List<HotelOrderVO> get() {
            List<HotelOrderVO> list = orderMapper.selectKitchenOrderList(hotelTenantId, queryDate);
            for (HotelOrderVO vo : list) {
                fillOrderItems(vo);
            }
            return list;
        }
    });
}
```

### 操作方法

```java
@Override
@Transactional(rollbackFor = Exception.class)
public void orderAccept(final Long id) {
    final Long hotelTenantId = resolveHotelTenantForAdmin();
    TenantContextHolder.executeWithTenant(hotelTenantId, new Runnable() {
        @Override
        public void run() {
            HotelOrder order = requireOrder(id);
            if (order.getStatus() != HotelOrderConstants.STATUS_PLACED) {
                throw new BusinessException("只有待接单的订单才能接单");
            }
            order.setStatus(HotelOrderConstants.STATUS_ACCEPTED);
            order.setAcceptTime(new Date());
            orderMapper.updateById(order); // WHERE tenant_id = hotelTenantId
        }
    });
}
```

### 混合租户上下文（订单 + 营业时段）

```java
@Override
public DashboardVO dashboard() {
    final Long hotelTenantId = resolveHotelTenantForAdmin();
    final DashboardVO vo = new DashboardVO();

    // 订单查询：切换到酒店租户
    TenantContextHolder.executeWithTenant(hotelTenantId, new Runnable() {
        @Override
        public void run() {
            // 订单相关查询...
        }
    });

    // 营业时段：用当前上下文（餐厅租户）
    List<HotelBusinessHours> hoursList = businessHoursMapper.selectEnabled(resolveTenantId());

    // 餐段订单统计：切回酒店租户
    TenantContextHolder.executeWithTenant(hotelTenantId, new Runnable() {
        @Override
        public void run() {
            // 订单统计查询...
        }
    });

    return vo;
}
```

## 跨租户方法调用注意事项

### 问题场景

```java
// orderComplete 在 executeWithTenant(8, ...) 内调用 incrementDishSales
public void orderComplete(Long id) {
    executeWithTenant(8, () -> {
        // ... 订单操作 ...
        incrementDishSales(id); // ❌ 内部 resolveTenantId() 返回 8（酒店租户）
    });
}

private void incrementDishSales(Long orderId) {
    // resolveTenantId() 返回 8（因为外层已切换到酒店租户）
    Long restaurantTenantId = resolveRestaurantTenantId(resolveTenantId());
    // resolveRestaurantTenantId(8) → 查映射表 → 返回 9 ✅ 碰巧正确
    // 但如果映射表查询失败，回退返回 8 → executeWithTenant(8) → 查不到菜品数据 ❌
}
```

### 正确做法：显式传递租户 ID

```java
// 在切换租户前保存原始餐厅租户ID
public void orderComplete(final Long id) {
    final Long hotelTenantId = resolveHotelTenantForAdmin();
    final Long originalRestaurantTenantId = resolveRestaurantTenantId(resolveTenantId());
    TenantContextHolder.executeWithTenant(hotelTenantId, new Runnable() {
        @Override
        public void run() {
            // ... 订单操作 ...
            incrementDishSales(id, originalRestaurantTenantId); // ✅ 显式传递
        }
    });
}

private void incrementDishSales(Long orderId, Long restaurantTenantId) {
    List<HotelOrderItem> items = orderItemMapper.selectByOrderId(orderId);
    TenantContextHolder.executeWithTenant(restaurantTenantId, new Runnable() {
        @Override
        public void run() {
            for (HotelOrderItem item : items) {
                dishMapper.incrementSales(item.getDishId(), item.getQuantity());
            }
        }
    });
}
```

## tenant_id 是否会被意外修改？

### updateById(entity)

```sql
UPDATE hotel_order
SET status = 2, ..., tenant_id = 8  -- 实体内存中的值（加载时是 8，未改动）
WHERE id = ? AND tenant_id = 8      -- 拦截器追加
```

**结论**：`tenant_id` 保持原值，不会变。

### UpdateWrapper

```sql
UPDATE hotel_order
SET status = 7, reject_reason = ?   -- 只 SET 显式指定的字段
WHERE id = ? AND tenant_id = 8      -- 拦截器追加
```

**结论**：没有 `.set("tenant_id", ...)` → `tenant_id` 不会被修改。

### deleteById

```sql
UPDATE hotel_order SET del_flag = id WHERE id = ? AND tenant_id = 8
```

**结论**：逻辑删除只改 `del_flag`，`tenant_id` 不变。

## 影响范围分析

### 对酒店租户（8）登录无影响

- `resolveHotelTenantForAdmin()` 查映射表 → 未找到（8 是 hotel_tenant_id，不是 restaurant_tenant_id）→ 回退返回 8
- `executeWithTenant(8, ...)` → 当前上下文已经是 8 → **no-op，无变化**

### 对餐厅租户（9）登录的影响

- `resolveHotelTenantForAdmin()` 查映射表 → 找到 `hotel_tenant_id = 8` → 返回 8
- `executeWithTenant(8, ...)` → 从 9 切换到 8 → **订单相关操作正确执行**

### 不受影响的模块

菜品管理、菜品分类、规格管理、营业时段、房间管理、入住管理、二维码管理、支付回调、对账管理等模块完全不涉及跨租户，不受影响。

## 最佳实践总结

1. **传参数不能覆盖拦截器**：必须用 `executeWithTenant` 切换上下文
2. **系统级配置表用 `executeIgnore`**：映射表等跨租户共享数据，`tenant_id = 1`
3. **整个操作包裹**：`requireOrder` + `updateById` 必须在同一个 `executeWithTenant` 内
4. **显式传递租户 ID**：跨租户方法调用时，在切换前保存原始租户 ID，显式传递
5. **对当前租户无影响**：`executeWithTenant(当前租户, ...)` 是 no-op，不会改变现有行为
6. **tenant_id 不会被意外修改**：`updateById` 的 SET 来自实体内存值，`UpdateWrapper` 只 SET 显式字段

## 相关文件

- 映射表：`hotel_tenant_mapping`（Flyway V1.0.144）
- Mapper：`HotelTenantMappingMapper.java` / `HotelTenantMappingMapper.xml`
- Service：`HotelOrderServiceImpl.java`（所有订单操作方法）
- 租户上下文：`TenantContextHolder.executeWithTenant()` / `executeIgnore()`