Feature 控制系统

Plan Features（套餐控制）+ Feature Flags（灰度发布）· 最后更新 2026-03-28

1. 双系统总览

Celoria 有两套独立的 feature 控制系统，解决不同问题：

2. Plan Features 系统（System A）

2.1 数据模型

erDiagram
    features {
        varchar code PK "gift_cards, loyalty, marketing..."
        varchar name "显示名称"
        varchar category "core, crm, marketing, hr..."
        boolean is_active "是否启用"
    }
    plan_features {
        varchar plan_type "trial, standard, professional, enterprise"
        varchar feature_code FK "→ features.code"
        boolean is_enabled "是否包含在该 plan"
    }
    tenant_features {
        uuid tenant_id FK "→ tenants.id"
        varchar feature_code FK "→ features.code"
        boolean is_enabled "单独开关"
        timestamp expires_at "过期时间 (可选)"
    }
    tenants {
        uuid id PK
        varchar short_id "qqnails, ppnails..."
        varchar plan_type "当前套餐"
    }
    features ||--o{ plan_features : "belongs to plans"
    features ||--o{ tenant_features : "granted to tenants"
    tenants ||--o{ tenant_features : "has overrides"

2.2 套餐矩阵（当前配置）

在 Plan & Features 管理页面 可随时修改矩阵。

2.3 权限判断链路

flowchart TD
    A[租户请求 API] --> B{requireTenantFeature 中间件}
    B --> C{ENABLE_TENANT_FEATURES=false?}
    C -->|是| D[直接放行 next]
    C -->|否| E{解析 tenantId}
    E -->|无 tenantId| D
    E -->|有| F{查 plan_features 表}
    F --> G{该 plan 包含此 feature?}
    G -->|是| D
    G -->|否| H{查 tenant_features 表}
    H --> I{有单独 grant 且未过期?}
    I -->|是| D
    I -->|否| J[返回 403 FEATURE_NOT_ENABLED]

2.4 三层保护

2.5 受守卫的路由 & 任务

3. Feature Flags 系统（System B）

3.1 数据模型

feature_flags 表
┌─────────────────────┬─────────┬──────────────────┬─────────────┐
│ flag_key            │ enabled │ target_tenants   │ rollout_%   │
├─────────────────────┼─────────┼──────────────────┼─────────────┤
│ new-checkout-flow   │ true    │ {qqnails}        │ 0           │
│ dark-mode           │ true    │ {}               │ 30          │
│ experimental-ai     │ false   │ {}               │ 0           │
└─────────────────────┴─────────┴──────────────────┴─────────────┘

3.2 判断逻辑（3 层过滤）

flowchart TD
    A[isFeatureOn req, flagKey] --> B{flag 存在?}
    B -->|否| Z[return false]
    B -->|是| C{enabled = false?}
    C -->|是| Z
    C -->|否| D{target_tenants 不为空?}
    D -->|是| E{当前租户在列表中?}
    E -->|是| Y[return true]
    E -->|否| Z
    D -->|否| F{rollout_percent >= 100?}
    F -->|是| Y
    F -->|否| G{hash tenantId mod 100 < rollout?}
    G -->|是| Y
    G -->|否| Z

3.3 代码中使用

// 后端：在路由 handler 里做条件分支
const { isFeatureOn } = require('../middleware/feature-flags');

router.get('/checkout', async (req, res) => {
  if (await isFeatureOn(req, 'new-checkout-flow')) {
    return processCheckoutV2(req, res);  // 新流程
  }
  return processCheckoutV1(req, res);    // 老流程
});

3.4 灰度发布流程

1. 在 /platform/feature-flags 创建 flag: new-checkout-flow
2. 设置 target_tenants: ['qqnails']  → 只有 qqnails 能看到
3. 测试通过后，改为 rollout_percent: 10  → 10% 租户
4. 观察指标，逐步提高: 10% → 25% → 50% → 100%
5. 100% 稳定后，删掉 flag，代码里去掉 if 分支

4. 日常操作指南

4.1 新客户上线，控制他能用什么

4.2 写了新功能，想先不上线

4.3 新功能稳定了，正式发布

4.4 开发者：给新功能加守卫

// 1. 后端路由守卫 — 在 server.js 的 app.use() 加一行
app.use('/api/new-feature', requireTenantFeature('new_feature'), newFeatureRouter);

// 2. 后台任务守卫 — 在 jobs/feature-guard-map.js 加映射
const JOB_FEATURE_MAP = {
  ...
  newFeatureJob: 'new_feature',  // ← 加这行
};

// 3. 前端菜单 — 在 Sidebar.tsx 的 MENU_FEATURE_MAP 加映射
const MENU_FEATURE_MAP: Record<string, string> = {
  ...
  'new-feature': 'new_feature',  // ← 加这行
};

5. 紧急操作

-- SQL: 从所有 plan 移除
UPDATE public.plan_features SET is_enabled = false WHERE feature_code = 'voice_bot';
-- 或在管理页面取消勾选

# .env
ENABLE_TENANT_FEATURES=false
# 重启后端 — 所有 feature guard 失效，等同于没加守卫

6. 关键文件索引

7. 缓存行为

结论：管理页面操作后，后端立即生效（缓存已清除），前端需刷新页面。