# US-MGN006-003: Gestionar Preferencias de Usuario

## Identificacion

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

---

## Historia de Usuario

**Como** usuario del sistema
**Quiero** personalizar mis preferencias personales
**Para** adaptar la experiencia del sistema a mis gustos y necesidades

---

## Descripcion

Cada usuario puede configurar preferencias personales que afectan solo su experiencia. Estas preferencias incluyen idioma, zona horaria, tema visual, notificaciones y opciones de UI. Se sincronizan entre dispositivos.

### Contexto

- Preferencias a nivel de usuario individual
- Se aplican sobre configuraciones de tenant
- Sincronizacion entre dispositivos
- Persistencia en base de datos

---

## Criterios de Aceptacion

### Escenario 1: Ver mis preferencias

```gherkin
Given un usuario autenticado
When accede a GET /api/v1/settings/user
Then el sistema responde con status 200
  And retorna objeto con preferencias agrupadas:
    | locale | { language, timezone, dateFormat } |
    | theme | { mode, primaryColor } |
    | notifications | { email, push, inApp } |
    | ui | { sidebarCollapsed, tablePageSize } |
```

### Escenario 2: Actualizar preferencias

```gherkin
Given un usuario autenticado
When envia PATCH /api/v1/settings/user
  | locale.language | "es-MX" |
  | locale.timezone | "America/Mexico_City" |
Then el sistema responde con status 200
  And las preferencias se actualizan
  And syncedAt se actualiza a la fecha actual
```

### Escenario 3: Cambiar tema oscuro/claro

```gherkin
Given usuario con theme.mode = "light"
When envia PATCH con theme.mode = "dark"
Then la preferencia se guarda
  And el frontend aplica el tema oscuro
```

### Escenario 4: Resetear preferencias a defaults

```gherkin
Given usuario con preferencias personalizadas
When envia POST /api/v1/settings/user/reset
Then todas las preferencias se eliminan
  And el usuario usa los valores por defecto del tenant
```

### Escenario 5: Resetear categoria especifica

```gherkin
Given usuario con preferencias personalizadas
When envia POST /api/v1/settings/user/reset
  | keys | ["theme.mode", "theme.primaryColor"] |
Then solo esas preferencias se resetean
  And las demas permanecen
```

### Escenario 6: Obtener preferencias efectivas

```gherkin
Given usuario sin preferencia de idioma definida
  And tenant con idioma "es-ES"
When accede a GET /api/v1/settings/user/effective
Then retorna:
  | locale.language | "es-ES" |
  | source | "tenant" |
```

### Escenario 7: Sincronizacion entre dispositivos

```gherkin
Given usuario cambia preferencia en navegador A
When abre sesion en navegador B
  And accede a sus preferencias
Then obtiene las preferencias actualizadas
  And syncedAt indica cuando se sincronizo
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  MIS PREFERENCIAS                                                 |
+------------------------------------------------------------------+

REGIONAL
+------------------------------------------------------------------+
| Idioma                   | [Español (Mexico) v]                  |
| Zona Horaria             | [America/Mexico_City v]               |
| Formato de Fecha         | [DD/MM/YYYY v]                        |
| Formato de Hora          | [24 horas v]                          |
| Primer dia de semana     | [Lunes v]                             |
+------------------------------------------------------------------+

APARIENCIA
+------------------------------------------------------------------+
| Tema                     | ( ) Claro  (•) Oscuro  ( ) Sistema    |
| Barra lateral            | [Expandida v]                          |
| Densidad                 | ( ) Compacta  (•) Normal  ( ) Comoda  |
+------------------------------------------------------------------+

NOTIFICACIONES
+------------------------------------------------------------------+
| □ Recibir emails de notificaciones                               |
| □ Recibir notificaciones push                                    |
| ✓ Mostrar notificaciones in-app                                  |
| Frecuencia de resumen    | [Diario v]                            |
+------------------------------------------------------------------+

TABLAS Y LISTAS
+------------------------------------------------------------------+
| Elementos por pagina     | [25 v]                                 |
| Mostrar acciones         | [Al pasar mouse v]                    |
+------------------------------------------------------------------+

                     [Restaurar Defaults]  [=== Guardar ===]

Ultima sincronizacion: hace 5 minutos
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /settings/user | Mis preferencias |
| GET | /settings/user/effective | Con herencia |
| PATCH | /settings/user | Actualizar parcial |
| POST | /settings/user/reset | Resetear |

### Preferencias Disponibles

| Categoria | Clave | Tipo | Default |
|-----------|-------|------|---------|
| locale | language | string | "en-US" |
| locale | timezone | string | "UTC" |
| locale | dateFormat | string | "YYYY-MM-DD" |
| locale | timeFormat | string | "24h" |
| theme | mode | enum | "system" |
| theme | primaryColor | string | null |
| ui | sidebarCollapsed | boolean | false |
| ui | tablePageSize | number | 20 |
| notifications | email | boolean | true |
| notifications | push | boolean | true |
| notifications | inApp | boolean | true |
| notifications | digestFrequency | enum | "daily" |

---

## Definicion de Done

- [ ] CRUD preferencias de usuario
- [ ] Merge con defaults de tenant
- [ ] Reset parcial y total
- [ ] Campo syncedAt actualizado
- [ ] UI de preferencias completa
- [ ] Componente ThemeToggle
- [ ] Persistencia en localStorage + DB
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| US-MGN006-002 | Configuraciones de tenant (defaults) |
| Tabla user_preferences | Storage |
| Zustand store | Estado local |

### Bloquea

| Item | Descripcion |
|------|-------------|
| UI global | Tema, idioma, formato |
| Notificaciones | Preferencias de canales |

---

## Historial

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