# US-MGN006-001: Gestionar Configuraciones del Sistema

## Identificacion

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

---

## Historia de Usuario

**Como** super administrador del sistema
**Quiero** gestionar las configuraciones globales del sistema
**Para** ajustar parametros que afectan a todos los tenants

---

## Descripcion

Las configuraciones del sistema son parametros globales que afectan el comportamiento de la plataforma. Solo pueden ser modificadas por super administradores y algunas son visibles para administradores de tenant.

### Contexto

- Configuraciones a nivel de plataforma
- Afectan a todos los tenants
- Algunas son publicas, otras privadas
- Incluyen validaciones por tipo de dato

---

## Criterios de Aceptacion

### Escenario 1: Listar configuraciones por categoria

```gherkin
Given un super administrador autenticado
When accede a GET /api/v1/settings/system
Then el sistema responde con status 200
  And retorna configuraciones agrupadas por categoria
  And cada setting incluye: key, value, dataType, category, isEditable

When accede con query ?category=security
Then retorna solo configuraciones de seguridad
```

### Escenario 2: Ver configuraciones publicas

```gherkin
Given un administrador de tenant (no super admin)
When accede a GET /api/v1/settings/system?public=true
Then retorna solo configuraciones donde isPublic = true
  And no retorna configuraciones sensibles
```

### Escenario 3: Obtener configuracion especifica

```gherkin
Given configuracion "security.max_login_attempts" existe
When accede a GET /api/v1/settings/system/security.max_login_attempts
Then retorna:
  | key | "security.max_login_attempts" |
  | value | 5 |
  | dataType | "number" |
  | description | "Intentos maximos de login" |
  | isEditable | true |
```

### Escenario 4: Actualizar configuracion

```gherkin
Given un super administrador
  And configuracion "security.max_login_attempts" con isEditable = true
When envia PUT /api/v1/settings/system/security.max_login_attempts
  | value | 3 |
Then el sistema responde con status 200
  And el valor se actualiza a 3
  And se invalida el cache de esta configuracion
```

### Escenario 5: Actualizar configuracion no editable

```gherkin
Given configuracion "system.version" con isEditable = false
When intenta actualizar el valor
Then el sistema responde con status 403
  And el mensaje indica "Configuracion no es editable"
```

### Escenario 6: Validacion de tipo de dato

```gherkin
Given configuracion "security.max_login_attempts" de tipo "number"
When envia valor "abc" (no numerico)
Then el sistema responde con status 400
  And el mensaje indica "El valor debe ser un numero"

Given configuracion con validationRules: { min: 1, max: 10 }
When envia valor 15
Then el sistema responde con status 400
  And el mensaje indica "El valor debe estar entre 1 y 10"
```

### Escenario 7: Resetear a valor por defecto

```gherkin
Given configuracion modificada con valor diferente al default
When envia POST /api/v1/settings/system/security.max_login_attempts/reset
Then el valor se restaura al defaultValue
  And se invalida el cache
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  CONFIGURACION DEL SISTEMA                                        |
+------------------------------------------------------------------+
| [Categoria: Todas v]  [Solo editables ✓]  [Buscar...]            |
+------------------------------------------------------------------+

SEGURIDAD
+------------------------------------------------------------------+
| Clave                        | Valor    | Tipo   | Acciones     |
+------------------------------------------------------------------+
| security.max_login_attempts  | 5        | number | [Editar] [↺] |
| security.lockout_minutes     | 30       | number | [Editar] [↺] |
| security.token_expiry_hours  | 24       | number | [Editar] [↺] |
| security.password_min_length | 8        | number | [Editar] [↺] |
+------------------------------------------------------------------+

EMAIL
+------------------------------------------------------------------+
| email.smtp_host              | smtp...  | string | [Editar] [↺] |
| email.smtp_port              | 587      | number | [Editar] [↺] |
+------------------------------------------------------------------+

ALMACENAMIENTO
+------------------------------------------------------------------+
| storage.max_file_size_mb     | 10       | number | [Editar] [↺] |
| storage.allowed_extensions   | [pdf,..] | array  | [Editar] [↺] |
+------------------------------------------------------------------+

Modal: Editar Configuracion
+------------------------------------------------------------------+
| EDITAR CONFIGURACION                                        [X]  |
+------------------------------------------------------------------+
| Clave: security.max_login_attempts                               |
| Descripcion: Intentos maximos de login antes de bloqueo          |
|                                                                  |
| Tipo: number                                                     |
| Valor actual: 5                                                  |
| Valor por defecto: 5                                             |
|                                                                  |
| Nuevo Valor*                                                     |
| [3                    ]                                          |
| Minimo: 1 | Maximo: 10                                          |
|                                                                  |
|                               [Cancelar]  [=== Guardar ===]     |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /settings/system | Listar todas |
| GET | /settings/system/:key | Obtener una |
| PUT | /settings/system/:key | Actualizar |
| POST | /settings/system/:key/reset | Resetear |

### Tipos de Dato Soportados

| Tipo | Ejemplo | Validaciones |
|------|---------|--------------|
| string | "smtp.example.com" | minLength, maxLength, pattern |
| number | 5 | min, max |
| boolean | true | - |
| json | {...} | jsonSchema |
| array | ["pdf","jpg"] | minItems, maxItems |
| secret | "***" | Se enmascara en lectura |

---

## Definicion de Done

- [ ] CRUD configuraciones del sistema
- [ ] Validacion por tipo de dato
- [ ] Filtro por categoria
- [ ] Filtro publicas/privadas
- [ ] Reset a valor por defecto
- [ ] Invalidacion de cache
- [ ] UI de administracion
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Tabla system_settings | Con seed inicial |
| Cache Redis | Para performance |
| Super admin role | Permiso especial |

### Bloquea

| Item | Descripcion |
|------|-------------|
| US-MGN006-002 | Settings de tenant heredan de sistema |

---

## Historial

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