多租户与 SaaS 化落地

第一层：平台级多租户
  平台自身服务多个租户
  租户 A 与租户 B 用同一个平台实例
  隔离对象：应用、元数据、用户、配额

第二层：应用级多租户
  某个租户搭建的应用，自身也可能服务多个客户
  即「租户的应用也是多租户的」
  隔离对象：业务数据

两层容易混淆：
  平台开发者的 tenant_id 是「第一层」
  应用搭建者的 tenant_id 是「第二层」
  命名必须区分，如 org_id（平台）与 tenant_id（应用）

共享库共享表：
  所有租户数据在同一张表，靠 tenant_id 区分
  优点：运维简单、成本最低、聚合统计方便
  缺点：单表膨胀、隔离靠代码保证、误查风险高

共享库独立 Schema：
  每个租户一个 schema（PG）或 database（MySQL）
  优点：隔离较强、可按租户备份
  缺点：连接数膨胀、迁移需遍历所有 schema

独立库：
  每租户一个数据库实例
  优点：隔离最强、可独立扩容
  缺点：成本高、运维复杂、跨租户统计难

CREATE TABLE app_metadata (
  app_id     varchar(36) PRIMARY KEY,
  org_id     varchar(36) NOT NULL,     -- 平台租户
  name       varchar(100) NOT NULL,
  schema     jsonb NOT NULL,
  version    int NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX idx_meta_org ON app_metadata(org_id);

元数据隔离要点：
  1. 每条元数据必须带 org_id
  2. 所有查询强制注入 org_id 条件
  3. 跨租户引用必须拒绝（如应用 A 引用应用 B 的数据源）
  4. 元数据的缓存键必须含 org_id

两种存储策略：
  A. 统一表：所有租户的业务数据存在平台预置的大表里
     （行存/列存，带 org_id + app_id + entity + data jsonb）
     优点：表数量可控、加租户零成本
     缺点：类型约束弱、查询需解析 jsonb、单表巨大

  B. 按租户建表：每个租户的业务实体建真实表
     优点：类型强、查询快、可用外键
     缺点：表数量爆炸、迁移需遍历

-- 策略 A：统一表 + JSONB
CREATE TABLE biz_record (
  id          bigserial PRIMARY KEY,
  org_id      varchar(36) NOT NULL,
  app_id      varchar(36) NOT NULL,
  entity      varchar(64) NOT NULL,
  data        jsonb NOT NULL,
  created_at  timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX idx_biz_org_entity ON biz_record(org_id, entity);
CREATE INDEX idx_biz_data ON biz_record USING GIN (data jsonb_path_ops);

-- PostgreSQL RLS：为每个租户设置会话变量
ALTER TABLE biz_record ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON biz_record
  USING (org_id = current_setting('app.current_org', true));

-- 连接建立后设置
SET app.current_org = 'org_123';

RLS 的代价与收益：
  收益：绕过应用层也隔离，防越权最后一道墙
  代价：每个连接需设会话变量、连接池要小心
        查询计划可能变差、调试更复杂

连接池陷阱：
  连接复用时会话变量可能残留
  → 每次取连接后必须重置会话变量

定制层次：
  1. 主题（Logo、颜色）→ 配置即可
  2. 字段扩展（租户特有字段）→ 元数据扩展
  3. 流程差异（不同审批链）→ 流程变体
  4. 代码差异（租户特有逻辑）→ 插件/钩子

原则：能配置就不扩展，能扩展就不分支
  → 避免为每个租户维护一份代码分支

{
  "orgId": "org_123",
  "branding": { "logo": "/assets/org123.svg", "primary": "#1a73e8" },
  "featureFlags": { "advancedReport": true, "apiAccess": false },
  "extensions": {
    "customFields": { "order": ["internal_code"] }
  }
}

配额维度：
  - 应用数、用户数、数据行数
  - API 调用次数、存储空间
  - 并发查询数、执行时长

实现：
  - 计数：Redis 计数器 + 定期落库
  - 限流：令牌桶 / 滑动窗口，按 org_id 维度
  - 隔离：单租户的慢查询不能占满连接池

async function checkQuota(orgId: string, kind: string, amount = 1) {
  const key = `quota:${orgId}:${kind}`;
  const used = await redis.incrby(key, amount);
  const limit = await getLimit(orgId, kind);
  if (used > limit) {
    await redis.decrby(key, amount);       // 回滚
    throw new QuotaExceededError(kind);
  }
}

生命周期：
  注册（开通）→ 试用 → 付费 → 续费 → 停用 → 注销（数据删除）

关键能力：
  - 开通：初始化租户元数据、配额、默认配置
  - 数据导出：租户可导出全部数据（合规要求）
  - 注销：彻底删除数据（GDPR 等要求）
  - 归档：停用但不删除，保留恢复可能

-- 注销流程（软删 → 保留窗口 → 物理删）
UPDATE org SET status = 'deleting', deleted_at = now() WHERE id = $1;
-- 保留 30 天后由定时任务物理删除
DELETE FROM biz_record WHERE org_id = $1;
DELETE FROM app_metadata WHERE org_id = $1;

分发模式：
  A. 每个客户一份实例（复制应用）
     简单，但改动需逐份同步

  B. 一份应用 + 运行时租户切换
     客户共享应用定义，数据按 tenant_id 隔离
     推荐：改一次全生效

  C. 应用市场（模板分发）
     平台提供模板，租户基于模板创建自己的应用

越权类型：
  1. 水平越权：租户 A 访问租户 B 的数据
  2. 垂直越权：普通用户执行管理员操作
  3. 上下文越权：切换租户后残留旧上下文

防护清单：
  - 所有查询强制注入 org_id（数据访问层统一注入）
  - 所有缓存键含 org_id
  - 所有会话变量在取连接时重置
  - 跨租户引用一律拒绝
  - 定期越权扫描测试（自动化）

// 数据访问层统一注入，避免各处手写
function scopedQuery(table: string, ctx: RequestContext) {
  return db(table).where('org_id', ctx.orgId);   // 强制注入，不可绕过
}