# RF-MGN-001-003: Gestión de Usuarios

**Módulo:** MGN-001 - Fundamentos
**Prioridad:** P0 (MVP)
**Story Points:** 8
**Estado:** Definido
**Fecha:** 2025-11-23

## Descripción

El sistema debe permitir la creación, lectura, actualización y desactivación (soft delete) de usuarios. Incluye gestión de perfiles, asignación de roles y control de estado (activo/inactivo).

## Actores

- **Actor Principal:** Administrador de Sistema
- **Actores Secundarios:** Usuario (gestiona su propio perfil)

## Precondiciones

1. Usuario administrador debe estar autenticado
2. Sistema debe tener roles disponibles para asignar
3. Tenant debe estar activo

## Flujo Principal

1. Administrador accede a módulo de Gestión de Usuarios
2. Administrador crea nuevo usuario con datos: nombre, email, teléfono
3. Sistema valida que email sea único dentro del tenant
4. Sistema genera contraseña temporal o permite definir contraseña
5. Administrador asigna uno o más roles al usuario
6. Sistema hashea contraseña con bcrypt (cost factor 12)
7. Sistema crea registro en auth.users con status='active'
8. Sistema envía email de bienvenida con credenciales (opcional)
9. Usuario recibe notificación y puede iniciar sesión

## Flujos Alternativos

### FA-1: Email Duplicado
1. Si email ya existe en el tenant
2. Sistema retorna error 400: "Email ya está registrado"

### FA-2: Actualización de Perfil Propio
1. Usuario autenticado accede a su perfil
2. Usuario actualiza nombre, teléfono, foto, idioma preferido
3. Sistema valida cambios
4. Sistema actualiza auth.users
5. Usuario NO puede cambiar su propio email ni roles

### FA-3: Cambio de Contraseña
1. Usuario autenticado solicita cambio de contraseña
2. Sistema valida contraseña actual
3. Usuario ingresa nueva contraseña (debe cumplir política de seguridad)
4. Sistema valida nueva contraseña (8+ chars, mayúscula, número, símbolo)
5. Sistema hashea nueva contraseña
6. Sistema actualiza auth.users.password_hash
7. Sistema invalida refresh tokens existentes (logout forzado en otros dispositivos)

### FA-4: Desactivación de Usuario
1. Administrador selecciona usuario activo
2. Administrador desactiva usuario (soft delete: status='inactive')
3. Sistema invalida tokens activos del usuario
4. Usuario NO puede volver a iniciar sesión
5. Datos del usuario se conservan (no se elimina de DB)

### FA-5: Reactivación de Usuario
1. Administrador selecciona usuario inactivo
2. Administrador reactiva usuario (status='active')
3. Usuario puede volver a iniciar sesión

## Reglas de Negocio

- **RN-1:** Email debe ser único por tenant (no globalmente)
- **RN-2:** Contraseña debe cumplir política: 8+ chars, 1 mayúscula, 1 número, 1 símbolo
- **RN-3:** Usuario inactivo no puede autenticarse
- **RN-4:** Usuarios eliminados son soft delete (status='inactive', deleted_at!=null)
- **RN-5:** Usuario puede actualizar su propio perfil, pero NO sus roles
- **RN-6:** Solo administradores pueden crear/desactivar usuarios
- **RN-7:** Cambio de contraseña invalida refresh tokens existentes

## Criterios de Aceptación

- [ ] Administrador puede crear nuevos usuarios con email, nombre, roles
- [ ] Sistema valida unicidad de email dentro del tenant
- [ ] Contraseña se almacena hasheada con bcrypt
- [ ] Usuario puede actualizar su propio perfil (nombre, foto, idioma)
- [ ] Usuario puede cambiar su propia contraseña
- [ ] Administrador puede desactivar usuarios (soft delete)
- [ ] Administrador puede reactivar usuarios desactivados
- [ ] Usuario inactivo no puede iniciar sesión
- [ ] Cambio de contraseña invalida sesiones activas en otros dispositivos
- [ ] Sistema envía email de bienvenida a nuevos usuarios

## Entidades Involucradas

- **Principales:**
  - auth.users (email, password_hash, name, phone, avatar, status, language)
  - auth.user_roles (asignación roles a usuarios)
- **Relacionadas:**
  - auth.roles (roles disponibles)
  - auth.tenants (tenant del usuario)

## Referencias

- [ALCANCE-POR-MODULO.md - MGN-001](../../01-definicion-modulos/ALCANCE-POR-MODULO.md#mgn-001-fundamentos)
- [Auth Domain Model](../domain-models/auth-domain.md)
- [Auth Schema DDL](../database-design/schemas/auth-schema-ddl.sql)
- [Gap Analysis MGN-001](../../01-definicion-modulos/gaps/GAP-ANALYSIS-MGN-001.md)

## Notas Técnicas

- **Patrón Odoo:** Similar a res.users en odoo/base
- **Patrón Gamilit:** CRUD usuarios con soft delete
- **Seguridad:** Nunca retornar password_hash en APIs
- **Backend:** NestJS UsersService + bcrypt para hashing
- **Frontend:** Formulario de creación/edición con validación client-side
- **Email:** Integrar con servicio de email (SendGrid, AWS SES) para bienvenida

## Dependencias

- **RF Dependientes:**
  - RF-MGN-001-001 (Autenticación)
  - RF-MGN-001-002 (Roles)
- **Bloqueante para:** RF-MGN-002-003 (Asignación usuarios a empresas)
