# Indice de Requerimientos Funcionales - MGN-002 Users

## Resumen del Modulo

| Campo | Valor |
|-------|-------|
| **Codigo** | MGN-002 |
| **Nombre** | Users - Gestion de Usuarios |
| **Prioridad** | P0 - Critica |
| **Total RFs** | 5 |
| **Estado** | En documentacion |
| **Fecha** | 2025-12-05 |

---

## Descripcion General

El modulo de usuarios gestiona el ciclo de vida completo de los usuarios del sistema, incluyendo:

- **CRUD de Usuarios**: Crear, listar, actualizar y eliminar usuarios (admin)
- **Perfil Personal**: Cada usuario gestiona su propia informacion
- **Cambio de Email**: Proceso seguro con verificacion
- **Cambio de Password**: Autoservicio con validaciones
- **Preferencias**: Personalizacion de la experiencia

---

## Lista de Requerimientos Funcionales

| ID | Nombre | Prioridad | Complejidad | Estado | Story Points |
|----|--------|-----------|-------------|--------|--------------|
| [RF-USER-001](./RF-USER-001.md) | CRUD de Usuarios | P0 | Media | Aprobado | 13 |
| [RF-USER-002](./RF-USER-002.md) | Perfil de Usuario | P1 | Baja | Aprobado | 7 |
| [RF-USER-003](./RF-USER-003.md) | Cambio de Email | P1 | Media | Aprobado | 6 |
| [RF-USER-004](./RF-USER-004.md) | Cambio de Password | P0 | Baja | Aprobado | 4 |
| [RF-USER-005](./RF-USER-005.md) | Preferencias de Usuario | P2 | Baja | Aprobado | 7 |

**Total Story Points:** 37

---

## Grafo de Dependencias

```
RF-AUTH-001 (Login)
       │
       ▼
RF-USER-001 (CRUD Usuarios) ─────────────────────────┐
       │                                              │
       ├──────────────────┬──────────────────┐       │
       │                  │                  │       │
       ▼                  ▼                  ▼       │
RF-USER-002          RF-USER-003       RF-USER-004  │
(Perfil)            (Cambio Email)   (Cambio Pass)  │
       │                  │                          │
       └────────┬─────────┘                          │
                │                                    │
                ▼                                    │
         RF-USER-005 ◄───────────────────────────────┘
        (Preferencias)
```

### Orden de Implementacion Recomendado

1. **RF-USER-001** - CRUD de usuarios (base)
2. **RF-USER-004** - Cambio de password (seguridad basica)
3. **RF-USER-002** - Perfil de usuario (autoservicio)
4. **RF-USER-003** - Cambio de email (proceso complejo)
5. **RF-USER-005** - Preferencias (personalizacion)

---

## Endpoints del Modulo

### Gestion de Usuarios (Admin)

| Metodo | Endpoint | RF | Descripcion | Permisos |
|--------|----------|-----|-------------|----------|
| POST | `/api/v1/users` | RF-USER-001 | Crear usuario | users:create |
| GET | `/api/v1/users` | RF-USER-001 | Listar usuarios | users:read |
| GET | `/api/v1/users/:id` | RF-USER-001 | Obtener usuario | users:read |
| PATCH | `/api/v1/users/:id` | RF-USER-001 | Actualizar usuario | users:update |
| DELETE | `/api/v1/users/:id` | RF-USER-001 | Eliminar usuario | users:delete |
| POST | `/api/v1/users/:id/activate` | RF-USER-001 | Activar usuario | users:update |
| POST | `/api/v1/users/:id/deactivate` | RF-USER-001 | Desactivar usuario | users:update |

### Perfil Personal (Self-service)

| Metodo | Endpoint | RF | Descripcion |
|--------|----------|-----|-------------|
| GET | `/api/v1/users/me` | RF-USER-002 | Obtener mi perfil |
| PATCH | `/api/v1/users/me` | RF-USER-002 | Actualizar mi perfil |
| POST | `/api/v1/users/me/avatar` | RF-USER-002 | Subir avatar |
| DELETE | `/api/v1/users/me/avatar` | RF-USER-002 | Eliminar avatar |
| POST | `/api/v1/users/me/email/request-change` | RF-USER-003 | Solicitar cambio email |
| GET | `/api/v1/users/email/verify-change` | RF-USER-003 | Verificar cambio email |
| POST | `/api/v1/users/me/password` | RF-USER-004 | Cambiar password |
| GET | `/api/v1/users/me/preferences` | RF-USER-005 | Obtener preferencias |
| PATCH | `/api/v1/users/me/preferences` | RF-USER-005 | Actualizar preferencias |
| POST | `/api/v1/users/me/preferences/reset` | RF-USER-005 | Reset preferencias |

---

## Tablas de Base de Datos

| Tabla | Schema | RF | Descripcion |
|-------|--------|-----|-------------|
| `users` | core_users | RF-USER-001 | Tabla principal de usuarios |
| `user_avatars` | core_users | RF-USER-002 | Historial de avatares |
| `email_change_requests` | core_users | RF-USER-003 | Solicitudes de cambio email |
| `password_history` | core_auth | RF-USER-004 | Historial de passwords |
| `user_preferences` | core_users | RF-USER-005 | Preferencias por usuario |

---

## Modelo de Datos Principal

```mermaid
erDiagram
    users ||--o| user_preferences : "has"
    users ||--o{ user_avatars : "has"
    users ||--o{ email_change_requests : "requests"
    users ||--o{ password_history : "has"
    users }o--|| tenants : "belongs to"

    users {
        uuid id PK
        uuid tenant_id FK
        varchar email
        varchar password_hash
        varchar first_name
        varchar last_name
        varchar phone
        varchar avatar_url
        enum status
        boolean is_active
        timestamptz email_verified_at
        timestamptz last_login_at
        integer failed_login_attempts
        timestamptz locked_until
        jsonb metadata
        timestamptz created_at
        uuid created_by
        timestamptz updated_at
        uuid updated_by
        timestamptz deleted_at
        uuid deleted_by
    }

    user_preferences {
        uuid id PK
        uuid user_id FK
        uuid tenant_id FK
        varchar language
        varchar timezone
        varchar date_format
        varchar time_format
        varchar theme
        jsonb notifications
        jsonb dashboard
        timestamptz updated_at
    }
```

---

## Estados de Usuario

| Estado | Descripcion | Puede Login |
|--------|-------------|-------------|
| `pending_activation` | Recien creado, esperando activacion | No |
| `active` | Usuario activo y funcional | Si |
| `inactive` | Desactivado por admin | No |
| `locked` | Bloqueado por intentos fallidos | No |
| `deleted` | Soft deleted | No |

---

## Criterios de Aceptacion Consolidados

### Seguridad

- [ ] Soft delete en lugar de hard delete
- [ ] Solo admins gestionan otros usuarios
- [ ] Email verificado antes de cambio efectivo
- [ ] Password actual requerido para cambios sensibles
- [ ] Historial de passwords para evitar reuso
- [ ] Rate limiting en operaciones sensibles

### Funcionalidad

- [ ] CRUD completo con paginacion y filtros
- [ ] Perfil autoservicio funcional
- [ ] Avatar upload con resize automatico
- [ ] Cambio de email con doble verificacion
- [ ] Cambio de password con politica de complejidad
- [ ] Preferencias persistentes y aplicadas

### Auditoria

- [ ] created_by/updated_by en todas las operaciones
- [ ] deleted_by en soft deletes
- [ ] Historial de cambios de email
- [ ] Historial de passwords

---

## Estimacion Total

| Capa | Story Points |
|------|--------------|
| Database | 6 |
| Backend | 15 |
| Frontend | 16 |
| **Total** | **37** |

---

## Riesgos Identificados

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Spam de cambio de email | Media | Bajo | Rate limiting 3/dia |
| Storage de avatares lleno | Baja | Medio | Cleanup job, limites |
| Performance en listados | Media | Medio | Paginacion, indices |
| Enumeracion de usuarios | Baja | Alto | Permisos estrictos |

---

## Referencias

### Documentacion Relacionada

- [DDL-SPEC-core_users.md](../../02-modelado/database-design/DDL-SPEC-core_users.md) - Especificacion de base de datos
- [ET-users-backend.md](../../02-modelado/especificaciones-tecnicas/ET-users-backend.md) - Especificacion tecnica backend
- [TP-users.md](../../04-test-plans/TP-users.md) - Plan de pruebas

### Dependencias con Otros Modulos

- **MGN-001 (Auth)**: Autenticacion y tokens
- **MGN-003 (Roles)**: Asignacion de roles a usuarios
- **MGN-004 (Tenants)**: Aislamiento multi-tenant

---

## Historial de Cambios

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | 2025-12-05 | System | Creacion inicial con 5 RFs |

---

## Aprobaciones

| Rol | Nombre | Fecha | Firma |
|-----|--------|-------|-------|
| Analista | System | 2025-12-05 | [x] |
| Tech Lead | - | - | [ ] |
| Product Owner | - | - | [ ] |