workspace/projects/gamilit/docs/01-fase-alcance-inicial/EAI-006-configuracion-sistema/requerimientos/RF-SYS-002-feature-flags.md

RF-SYS-002: Feature Flags (Banderas de Funcionalidad)

ID: RF-SYS-002 Título: Sistema de Feature Flags Prioridad: Alta Estado: ✅ Implementado Fase: 1 - Alcance Inicial Épica: EAI-006 - Configuración del Sistema

---

📋 Descripción

Sistema de feature flags para activar/desactivar funcionalidades de forma dinámica sin necesidad de redesplegar código, permitiendo rollouts graduales y A/B testing.

---

🎯 Objetivos

1. Habilitar/deshabilitar features sin redesplegar
2. Rollouts graduales (porcentaje de usuarios)
3. Targeting por roles, usuarios específicos o condiciones
4. Programar activación/desactivación de features
5. Soportar multi-tenancy

---

📊 Requerimientos Funcionales

REQ-001: Activación/Desactivación Dinámica

Como Product Owner Quiero activar/desactivar features sin redesplegar Para controlar el lanzamiento de funcionalidades

Criterios:

• ✅ Flag is_enabled controla si feature está activa
• ✅ Cambios se aplican inmediatamente (sin reinicio)
• ✅ API para consultar estado de feature

REQ-002: Rollout Gradual

Como Product Owner Quiero activar features para un porcentaje de usuarios Para hacer lanzamientos graduales y seguros

Criterios:

• ✅ rollout_percentage (0-100%)
• ✅ Distribución aleatoria consistente por usuario
• ✅ Incremento gradual del porcentaje

REQ-003: Targeting por Usuarios/Roles

Como Product Owner Quiero activar features para usuarios o roles específicos Para hacer beta testing o features exclusivas

Criterios:

• ✅ target_users - Array de UUIDs de usuarios
• ✅ target_roles - Array de roles (student, admin_teacher, super_admin)
• ✅ target_conditions - JSONB para condiciones complejas

REQ-004: Programación Temporal

Como Product Owner Quiero programar cuándo se activa/desactiva una feature Para lanzamientos coordinados

Criterios:

• ✅ starts_at - Fecha de inicio
• ✅ ends_at - Fecha de fin
• ✅ Feature solo activa entre estas fechas

---

🔧 Tabla: system_configuration.feature_flags

Columnas:

• id - UUID (PK)
• tenant_id - UUID (nullable)
• feature_name - TEXT (nombre descriptivo)
• feature_key - TEXT (UNIQUE, clave técnica)
• description - TEXT
• is_enabled - BOOLEAN
• rollout_percentage - INTEGER (0-100)
• target_users - UUID[]
• target_roles - gamilit_role[]
• target_conditions - JSONB
• starts_at - TIMESTAMPTZ
• ends_at - TIMESTAMPTZ

---

📝 Ejemplo de Uso

{
  "feature_key": "new_exercise_mechanic_matching",
  "feature_name": "Nueva Mecánica: Matching Avanzado",
  "description": "Mecánica de ejercicios de matching con drag & drop mejorado",
  "is_enabled": true,
  "rollout_percentage": 25,
  "target_roles": ["admin_teacher"],
  "starts_at": "2025-11-15T00:00:00Z",
  "ends_at": null
}

---

🔗 Referencias

• Especificación Técnica: ET-SYS-001
• Implementación: apps/database/ddl/schemas/system_configuration/tables/02-feature_flags.sql

---

Creado: 2025-11-08 Estado: ✅ Implementado