# US-MGN006-002: Gestionar Configuraciones del Tenant

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN006-002 |
| **Modulo** | MGN-006 Settings |
| **Sprint** | Sprint 4 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 8 |
| **Estado** | Ready |
| **RF Relacionado** | RF-SETTINGS-002 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** administrador de tenant
**Quiero** personalizar las configuraciones de mi organizacion
**Para** adaptar el sistema a las necesidades especificas de mi empresa

---

## Descripcion

Los tenants pueden sobrescribir configuraciones heredadas del sistema o del plan de suscripcion. El sistema aplica una jerarquia: system < plan < tenant, donde el tenant tiene la ultima palabra en configuraciones permitidas.

### Contexto

- Herencia de configuraciones
- Override por tenant
- Limites segun plan de suscripcion
- Configuraciones especificas de negocio

---

## Criterios de Aceptacion

### Escenario 1: Ver configuraciones efectivas

```gherkin
Given un administrador de tenant
When accede a GET /api/v1/settings/tenant
Then retorna configuraciones efectivas del tenant
  And cada setting indica su origen: "system", "plan", o "custom"
  And muestra valor actual y si esta sobrescrito
```

### Escenario 2: Herencia de configuraciones

```gherkin
Given configuracion "branding.logo_url" no definida en tenant
  And configuracion definida en plan con valor "default-logo.png"
When consulta el valor efectivo
Then retorna "default-logo.png"
  And inheritedFrom = "plan"
```

### Escenario 3: Sobrescribir configuracion

```gherkin
Given configuracion "branding.logo_url" heredada del plan
  And usuario con permiso "settings.tenant.update"
When envia PUT /api/v1/settings/tenant/branding.logo_url
  | value | "my-company-logo.png" |
Then la configuracion se guarda para el tenant
  And inheritedFrom = "custom"
  And isOverridden = true
```

### Escenario 4: Eliminar override (volver a herencia)

```gherkin
Given configuracion "branding.logo_url" sobrescrita por tenant
When envia DELETE /api/v1/settings/tenant/branding.logo_url
Then se elimina el override
  And el valor vuelve al heredado del plan
```

### Escenario 5: Limite por plan de suscripcion

```gherkin
Given tenant con plan "Basic"
  And configuracion "limits.max_users" tiene limite en plan = 10
When intenta establecer valor 50
Then el sistema responde con status 400
  And el mensaje indica "El plan Basic permite maximo 10 usuarios"
```

### Escenario 6: Configuracion no permitida en plan

```gherkin
Given tenant con plan "Basic"
  And configuracion "feature.advanced_reports" solo disponible en plan "Premium"
When intenta habilitar esa configuracion
Then el sistema responde con status 403
  And el mensaje indica "Caracteristica no disponible en tu plan"
```

### Escenario 7: Consultar por categoria

```gherkin
Given un administrador de tenant
When accede a GET /api/v1/settings/tenant?category=branding
Then retorna solo configuraciones de branding
  And incluye: logo_url, primary_color, company_name, etc.
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  CONFIGURACION DE LA EMPRESA                                      |
+------------------------------------------------------------------+

BRANDING
+------------------------------------------------------------------+
| Configuracion          | Valor           | Origen  | Acciones   |
+------------------------------------------------------------------+
| company_name           | Mi Empresa SA   | Custom  | [Editar]   |
| logo_url               | logo.png        | Plan    | [Override] |
| primary_color          | #3498db         | Custom  | [Editar][↺]|
| secondary_color        | #2ecc71         | System  | [Override] |
+------------------------------------------------------------------+

LIMITES (Plan: Professional)
+------------------------------------------------------------------+
| max_users              | 50 / 50         | Plan    | [🔒]       |
| max_storage_gb         | 80 / 100        | Plan    | [🔒]       |
| max_api_calls_day      | 8000 / 10000    | Plan    | [🔒]       |
+------------------------------------------------------------------+
[Actualizar plan para aumentar limites]

NOTIFICACIONES
+------------------------------------------------------------------+
| email_notifications    | Habilitado      | Custom  | [Editar]   |
| digest_frequency       | daily           | Custom  | [Editar]   |
+------------------------------------------------------------------+

Leyenda:
[🔒] = Controlado por plan
[↺] = Restaurar valor heredado
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /settings/tenant | Listar efectivas |
| GET | /settings/tenant/effective | Con herencia |
| PUT | /settings/tenant/:key | Sobrescribir |
| DELETE | /settings/tenant/:key | Eliminar override |

### Logica de Herencia

```typescript
function getEffectiveValue(key: string, tenantId: string): any {
  // 1. Buscar en tenant_settings (override)
  const tenantValue = await getTenantSetting(tenantId, key);
  if (tenantValue && tenantValue.isOverridden) {
    return { value: tenantValue.value, source: 'custom' };
  }

  // 2. Buscar en plan_settings
  const planId = await getTenantPlan(tenantId);
  const planValue = await getPlanSetting(planId, key);
  if (planValue) {
    return { value: planValue.value, source: 'plan' };
  }

  // 3. Fallback a system_settings
  const systemValue = await getSystemSetting(key);
  return { value: systemValue?.value || null, source: 'system' };
}
```

---

## Definicion de Done

- [ ] CRUD configuraciones de tenant
- [ ] Logica de herencia system < plan < tenant
- [ ] Validacion de limites por plan
- [ ] Eliminar override (volver a herencia)
- [ ] Indicador de origen en UI
- [ ] Cache con invalidacion
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| US-MGN006-001 | Configuraciones del sistema |
| Tabla plan_settings | Configuraciones por plan |
| Tabla tenant_settings | Overrides |
| MGN-004 Tenants | Suscripcion y plan |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN006-003 | Preferencias de usuario |

---

## Historial

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