erp-core/docs/02-fase-core-business/MGN-006-settings/requerimientos/RF-SETTINGS-004.md

RF-SETTINGS-004: Feature Flags

Identificacion

Campo	Valor
ID	RF-SETTINGS-004
Modulo	MGN-006 Settings
Titulo	Feature Flags
Prioridad	P1 - Alta
Estado	Draft
Fecha	2025-12-05

---

Descripcion

El sistema debe permitir habilitar o deshabilitar funcionalidades mediante feature flags, tanto a nivel global como por tenant o usuario, permitiendo rollouts graduales y A/B testing.

---

Requisitos Funcionales

RF-SETTINGS-004.1: Estructura de Feature Flag

Campo	Tipo	Descripcion
id	UUID	Identificador unico
key	VARCHAR(100)	Clave unica del flag
name	VARCHAR(255)	Nombre descriptivo
description	TEXT	Descripcion detallada
flag_type	ENUM	boolean, percentage, variant
default_value	JSONB	Valor por defecto
is_active	BOOLEAN	Flag activo en sistema
created_at	TIMESTAMPTZ	Fecha creacion
expires_at	TIMESTAMPTZ	Fecha expiracion (opcional)

RF-SETTINGS-004.2: Tipos de Feature Flags

enum FeatureFlagType {
  BOOLEAN = 'boolean',       // On/Off simple
  PERCENTAGE = 'percentage', // % de usuarios/tenants
  VARIANT = 'variant'        // A/B/C testing
}

RF-SETTINGS-004.3: Niveles de Aplicacion

Los flags pueden aplicarse en diferentes niveles:

Nivel	Descripcion	Override
global	Todos los tenants	Base
plan	Por plan de suscripcion	Override global
tenant	Por tenant especifico	Override plan
user	Por usuario especifico	Override tenant

RF-SETTINGS-004.4: Feature Flags Predefinidos

const FEATURE_FLAGS = [
  {
    key: 'feature.oauth_login',
    name: 'Login con OAuth',
    type: 'boolean',
    default: true
  },
  {
    key: 'feature.dark_mode',
    name: 'Modo Oscuro',
    type: 'boolean',
    default: true
  },
  {
    key: 'feature.export_excel',
    name: 'Exportar a Excel',
    type: 'boolean',
    default: true
  },
  {
    key: 'feature.new_dashboard',
    name: 'Nuevo Dashboard',
    type: 'percentage',
    default: 0  // 0% = deshabilitado
  },
  {
    key: 'feature.checkout_flow',
    name: 'Flujo de Checkout',
    type: 'variant',
    default: 'control'  // control, variant_a, variant_b
  }
];

RF-SETTINGS-004.5: Overrides por Nivel

// Tabla: feature_flag_overrides
interface FeatureFlagOverride {
  id: UUID;
  feature_flag_id: UUID;
  level: 'plan' | 'tenant' | 'user';
  level_id: UUID;  // ID del plan/tenant/user
  value: JSONB;
  is_active: boolean;
  created_at: TIMESTAMPTZ;
  created_by: UUID;
}

RF-SETTINGS-004.6: Rollout Gradual

Para flags tipo percentage:

interface RolloutConfig {
  percentage: number;        // 0-100
  sticky: boolean;          // Mismo usuario siempre igual
  seed?: string;            // Seed para determinismo
  exclude_tenants?: UUID[]; // Tenants excluidos
  include_tenants?: UUID[]; // Tenants incluidos siempre
}

Algoritmo:

1. Si tenant esta en include_tenants -> habilitado
2. Si tenant esta en exclude_tenants -> deshabilitado
3. Hash(user_id + seed) % 100 < percentage -> habilitado

RF-SETTINGS-004.7: Variantes para A/B Testing

Para flags tipo variant:

interface VariantConfig {
  variants: {
    name: string;
    weight: number;  // Peso relativo
  }[];
  sticky: boolean;
}

// Ejemplo:
{
  variants: [
    { name: 'control', weight: 50 },
    { name: 'variant_a', weight: 25 },
    { name: 'variant_b', weight: 25 }
  ],
  sticky: true
}

---

Operaciones

Verificar Feature Flag

GET /api/v1/features/:key

Response:
{
  "key": "feature.new_dashboard",
  "enabled": true,
  "variant": null,  // o nombre de variante
  "source": "tenant_override"
}

Verificar Multiples Flags

POST /api/v1/features/evaluate
{
  "keys": ["feature.new_dashboard", "feature.dark_mode"]
}

Response:
{
  "feature.new_dashboard": { "enabled": true },
  "feature.dark_mode": { "enabled": true }
}

Listar Feature Flags (Admin)

GET /api/v1/admin/features

Response:
{
  "data": [
    {
      "key": "feature.new_dashboard",
      "name": "Nuevo Dashboard",
      "type": "percentage",
      "globalValue": 25,
      "overrides": [
        { "level": "tenant", "count": 3 }
      ]
    }
  ]
}

Crear Override

POST /api/v1/admin/features/:key/overrides
{
  "level": "tenant",
  "levelId": "tenant-uuid",
  "value": true
}

Actualizar Rollout

PATCH /api/v1/admin/features/:key
{
  "percentage": 50  // Incrementar rollout al 50%
}

---

Reglas de Negocio

ID	Regla	Severidad
BR-001	Solo admin puede crear/modificar feature flags	Error
BR-002	Flags expirados se evaluan como default	Info
BR-003	Evaluacion debe ser < 5ms	Performance
BR-004	Sticky flags usan hash determinista	Info
BR-005	Cambios se propagan a cache en < 1s	Info

---

Criterios de Aceptacion

• Tres tipos de flags (boolean, percentage, variant)
• Override en cuatro niveles
• Rollout gradual funcional
• A/B testing con variantes
• Evaluacion rapida con cache
• UI de administracion de flags
• Expiracion automatica

---

Historial

Version	Fecha	Autor	Cambios
1.0	2025-12-05	Requirements-Analyst	Creacion inicial