# US-MGN-001-003-001: CRUD de Usuarios (Crear, Listar, Editar, Desactivar)

**RF Asociado:** [RF-MGN-001-003](../../02-modelado/requerimientos-funcionales/mgn-001/RF-MGN-001-003-gestion-usuarios.md)
**Módulo:** MGN-001 - Fundamentos
**Epic:** Gestión de Usuarios
**Prioridad:** P0 (MVP)
**Story Points:** 5
**Sprint:** Sprint 2
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story

**Como** administrador del sistema,
**Quiero** crear, listar, editar y desactivar usuarios,
**Para** gestionar quién tiene acceso al sistema y con qué roles.

---

## Descripción Detallada

CRUD completo de usuarios con validaciones de negocio: unicidad de email por tenant, asignación de roles, soft delete, envío de email de bienvenida.

---

## Criterios de Aceptación

### Escenario 1: Crear usuario nuevo
**Dado que** soy administrador,
**Cuando** creo usuario con email, nombre, contraseña y roles,
**Entonces** usuario se crea con password hasheado, email de bienvenida enviado.

### Escenario 2: Email duplicado
**Dado que** email ya existe en el tenant,
**Cuando** intento crear usuario,
**Entonces** retorna error 400 "Email ya registrado".

### Escenario 3: Listar usuarios con filtros
**Dado que** existen múltiples usuarios,
**Cuando** listo con filtros (nombre, email, rol, status),
**Entonces** veo resultados paginados con rol y status.

### Escenario 4: Editar usuario
**Dado que** un usuario existe,
**Cuando** edito nombre, teléfono, roles,
**Entonces** cambios se aplican inmediatamente.

### Escenario 5: Desactivar usuario (soft delete)
**Dado que** usuario está activo,
**Cuando** lo desactivo,
**Entonces** status='inactive', tokens revocados, no puede login.

---

## Reglas de Negocio

- **RN-1:** Email único por tenant
- **RN-2:** Contraseña hasheada con bcrypt (cost 12)
- **RN-3:** Soft delete (status='inactive', deleted_at)
- **RN-4:** Al desactivar: revocar tokens activos
- **RN-5:** No se puede auto-desactivar (el admin no puede desactivarse a sí mismo)

---

## Tareas Técnicas

### Backend
- [ ] POST /api/v1/auth/users - Crear usuario
- [ ] GET /api/v1/auth/users - Listar con paginación/filtros
- [ ] GET /api/v1/auth/users/:id - Detalle usuario
- [ ] PATCH /api/v1/auth/users/:id - Actualizar
- [ ] DELETE /api/v1/auth/users/:id - Soft delete
- [ ] UsersService.create/findAll/update/deactivate
- [ ] CreateUserDto, UpdateUserDto con validaciones
- [ ] Enviar email de bienvenida (SendGrid/SES)
- [ ] Unit + Integration tests (12 casos)

### Frontend
- [ ] UsersListPage con tabla paginada
- [ ] UserFormModal (crear/editar)
- [ ] Filtros: búsqueda, rol, status
- [ ] Confirmación antes de desactivar
- [ ] API client + React Query
- [ ] Component + E2E tests

### Database
- [ ] Tabla: auth.users (validar schema)
- [ ] Índice: idx_users_email_tenant (UNIQUE)
- [ ] Trigger: revocar tokens al desactivar

---

## Estimación: 5 SP (9 horas)

---

## Definition of Done

- [ ] CRUD implementado (backend + frontend)
- [ ] Tests pasando (>80% cobertura)
- [ ] Email de bienvenida funcionando
- [ ] Soft delete funcionando
- [ ] Code review aprobado
- [ ] Merge a develop

---

## Referencias

- [RF-MGN-001-003](../../02-modelado/requerimientos-funcionales/mgn-001/RF-MGN-001-003-gestion-usuarios.md)
- [ET-BACKEND-MGN-001-003](../../02-modelado/especificaciones-tecnicas/backend/mgn-001/ET-BACKEND-MGN-001-003-gestion-usuarios.md)
- [ET-FRONTEND-MGN-001-003](../../02-modelado/especificaciones-tecnicas/frontend/mgn-001/ET-FRONTEND-MGN-001-003-gestion-usuarios.md)