# Feature Flags Module

## Descripcion

Sistema de feature flags/toggles para control de funcionalidades. Permite habilitar/deshabilitar features globalmente o por tenant, con soporte para rollout gradual basado en porcentajes y overrides temporales con expiracion.

## Entidades

| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `Flag` | feature_flags.flags | Definicion de feature flags con estado global y porcentaje de rollout |
| `TenantOverride` | feature_flags.tenant_overrides | Overrides por tenant con razon y fecha de expiracion |
| `FlagEvaluation` | feature_flags.flag_evaluations | Log de evaluaciones para auditoria |

## Servicios

| Servicio | Responsabilidades |
|----------|-------------------|
| `FeatureFlagsService` | CRUD de flags y overrides; evaluacion de flags; rollout deterministico; limpieza de expirados |

## Endpoints

| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/flags` | Lista flags activos |
| GET | `/flags/all` | Lista todos los flags (incluyendo inactivos) |
| GET | `/flags/tags/:tags` | Lista flags por tags |
| GET | `/flags/:id` | Obtiene flag por ID |
| GET | `/flags/code/:code` | Obtiene flag por codigo |
| POST | `/flags` | Crea nuevo flag |
| PATCH | `/flags/:id` | Actualiza flag |
| DELETE | `/flags/:id` | Elimina flag (soft/hard) |
| PATCH | `/flags/:id/toggle` | Activa/desactiva flag |
| GET | `/flags/:id/stats` | Estadisticas de overrides del flag |
| GET | `/flags/:flagId/overrides` | Lista overrides de un flag |
| GET | `/tenants/:tenantId/overrides` | Lista overrides de un tenant |
| GET | `/overrides/:id` | Obtiene override por ID |
| POST | `/overrides` | Crea override |
| PATCH | `/overrides/:id` | Actualiza override |
| DELETE | `/overrides/:id` | Elimina override |
| GET | `/evaluate/:code` | Evalua un flag para tenant |
| POST | `/evaluate` | Evalua multiples flags |
| GET | `/is-enabled/:code` | Check rapido de flag habilitado |
| POST | `/maintenance/cleanup` | Limpia overrides expirados |

## Dependencias

- `common` - Utilidades compartidas (crypto para hash)

## Configuracion

No requiere configuracion de ambiente.

## Prioridad de Evaluacion

1. **Tenant Override** (si existe y no ha expirado)
2. **Estado Global** del flag (enabled/disabled)
3. **Rollout Percentage** (si el flag esta habilitado)
4. **Default** (false si el flag no existe)

## Rollout Deterministico

El rollout por porcentaje usa un hash MD5 de `flagCode:tenantId` para asegurar que:
- El mismo tenant siempre obtiene el mismo resultado
- La distribucion es uniforme entre tenants
- No hay necesidad de almacenar el resultado

```typescript
// Ejemplo: 30% rollout
// Tenants con bucket 0-29 = habilitado
// Tenants con bucket 30-99 = deshabilitado
bucket = MD5(flagCode + tenantId) % 100
enabled = bucket < rolloutPercentage
```

## Fuentes de Evaluacion

| Fuente | Descripcion |
|--------|-------------|
| `default` | Flag no existe, retorna false |
| `global` | Valor global del flag |
| `override` | Override especifico del tenant |
| `rollout` | Resultado del calculo de rollout |

## Mantenimiento

Se recomienda ejecutar `POST /maintenance/cleanup` periodicamente (cron diario) para eliminar overrides expirados.