erp-construccion/docs/02-definicion-modulos/MAI-013-administracion-seguridad/historias-usuario/US-ADM-001-invitar-registrar-usuarios.md

US-ADM-001: Invitar y Registrar Usuarios

ID: US-ADM-001
Módulo: MAI-013
Relacionado con: RF-ADM-001, ET-ADM-001
Prioridad: Alta
Story Points: 8

---

📖 Historia de Usuario

Como Director General o RH de una constructora
Quiero invitar nuevos usuarios por email y que puedan registrarse con un rol específico
Para incorporar al equipo sin permitir registros públicos y mantener control sobre quién accede al sistema

---

✅ Criterios de Aceptación

1. Enviar Invitación

Given que soy Director General o RH con permisos de gestión de usuarios
When accedo a la sección "Usuarios" y hago clic en "Invitar Usuario"
And completo el formulario con:
  - Email del invitado
  - Rol a asignar (director, engineer, resident, etc.)
  - Mensaje personalizado (opcional)
And hago clic en "Enviar Invitación"
Then el sistema debe:
  - Generar un token único con expiración de 7 días
  - Enviar email con el link de registro
  - Mostrar el usuario como "Invitado (Pendiente)" en la lista
  - Registrar la acción en el audit log

2. Registro desde Invitación

Given que recibí un email de invitación válido
When hago clic en el link de registro
Then debo ser redirigido a un formulario pre-llenado con:
  - Email (no editable)
  - Nombre completo
  - Password (con validación de política)
  - Confirmar password
  - Aceptar términos y condiciones
When completo el formulario y hago clic en "Crear Cuenta"
Then el sistema debe:
  - Validar que el token no haya expirado
  - Validar que el password cumpla la política
  - Crear la cuenta con status "active"
  - Invalidar el token de invitación
  - Enviar email de bienvenida
  - Permitir login inmediato

3. Token Expirado

Given que recibí una invitación hace más de 7 días
When intento acceder al link de registro
Then debo ver un mensaje: "Esta invitación ha expirado"
And un botón "Solicitar Nueva Invitación"
When hago clic en "Solicitar Nueva Invitación"
Then se debe enviar un email al administrador notificando la solicitud

4. Validaciones de Email

Given que estoy enviando una invitación
When ingreso un email que ya está registrado
Then debo ver un error: "Este email ya tiene una cuenta activa"
And no se debe enviar la invitación

Given que un email ya tiene una invitación pendiente
When intento invitar al mismo email nuevamente
Then debo ver un mensaje: "Este usuario ya tiene una invitación pendiente"
And opciones para:
  - "Reenviar invitación"
  - "Cancelar invitación anterior y crear nueva"

5. Lista de Invitaciones

Given que soy administrador
When accedo a "Usuarios > Invitaciones Pendientes"
Then debo ver una tabla con:
  - Email invitado
  - Rol asignado
  - Enviado por
  - Fecha de envío
  - Expira en (countdown)
  - Estado (Pendiente, Expirado, Aceptado)
  - Acciones: Reenviar, Cancelar

---

🎨 Mockup / Wireframe

Formulario de Invitación

┌─────────────────────────────────────────────┐
│ Invitar Nuevo Usuario                    [X]│
├─────────────────────────────────────────────┤
│                                             │
│ Email *                                     │
│ ┌─────────────────────────────────────────┐ │
│ │ usuario@ejemplo.com                     │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ Rol *                                       │
│ ┌─────────────────────────────────────────┐ │
│ │ [v] Ingeniero                           │ │
│ └─────────────────────────────────────────┘ │
│   ▼ Director General                        │
│     Ingeniero                               │
│     Residente de Obra                       │
│     Compras                                 │
│     Finanzas                                │
│     RH                                      │
│     Post-venta                              │
│                                             │
│ Mensaje Personalizado (opcional)            │
│ ┌─────────────────────────────────────────┐ │
│ │ Te invitamos a unirte a nuestro equipo  │ │
│ │ en el sistema...                        │ │
│ │                                         │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│        [Cancelar]  [Enviar Invitación]      │
└─────────────────────────────────────────────┘

Página de Registro (desde invitación)

┌─────────────────────────────────────────────┐
│            🏢 Logo Constructora             │
│                                             │
│   Bienvenido a [Nombre Constructora]        │
│   Has sido invitado como: Ingeniero         │
│                                             │
├─────────────────────────────────────────────┤
│                                             │
│ Email                                       │
│ ┌─────────────────────────────────────────┐ │
│ │ usuario@ejemplo.com          [bloqueado]│ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ Nombre Completo *                           │
│ ┌─────────────────────────────────────────┐ │
│ │ Juan Pérez                              │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ Crear Password *                            │
│ ┌─────────────────────────────────────────┐ │
│ │ ••••••••••••                     [👁️]   │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ ┌─────────────────────────────────────────┐ │
│ │ Fuerza: ████████░░ Buena                │ │
│ │ ✓ Al menos 12 caracteres                │ │
│ │ ✓ Contiene mayúscula                    │ │
│ │ ✓ Contiene minúscula                    │ │
│ │ ✓ Contiene número                       │ │
│ │ ✗ Contiene carácter especial            │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ Confirmar Password *                        │
│ ┌─────────────────────────────────────────┐ │
│ │ ••••••••••••                     [👁️]   │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ ☑️ Acepto los términos y condiciones       │
│ ☑️ Acepto el aviso de privacidad           │
│                                             │
│         [Crear Mi Cuenta]                   │
│                                             │
│   La invitación expira en: 5 días 3 horas  │
└─────────────────────────────────────────────┘

Lista de Invitaciones Pendientes

┌───────────────────────────────────────────────────────────┐
│ Invitaciones Pendientes                [+ Invitar Usuario]│
├───────────────────────────────────────────────────────────┤
│                                                           │
│ Email                Rol        Enviado por    Expira en │
│ ─────────────────────────────────────────────────────────│
│ juan@mail.com       Ingeniero   María López    2 días    │
│                                              [Reenviar][X]│
│                                                           │
│ ana@mail.com        Residente   María López    5 días    │
│                                              [Reenviar][X]│
│                                                           │
│ pedro@mail.com      Compras     María López    Expirado  │
│                                         [Nueva Invitación]│
└───────────────────────────────────────────────────────────┘

---

🧪 Casos de Prueba

CP-001: Invitación Exitosa

Precondiciones:

• Usuario autenticado con rol "director" o "hr"
• Email no existe en el sistema

Pasos:

1. Navegar a "Usuarios > Invitar Usuario"
2. Ingresar email: "nuevo@test.com"
3. Seleccionar rol: "engineer"
4. Ingresar mensaje: "Bienvenido al equipo"
5. Clic en "Enviar Invitación"

Resultado Esperado:

• ✅ Mensaje: "Invitación enviada exitosamente"
• ✅ Email recibido en "nuevo@test.com" con link válido
• ✅ Usuario aparece en lista de invitaciones pendientes
• ✅ Audit log registra: "invitation_sent"

CP-002: Registro con Invitación Válida

Precondiciones:

• Invitación enviada y no expirada
• Token válido en URL

Pasos:

1. Abrir link de invitación desde email
2. Ingresar nombre: "Juan Pérez"
3. Ingresar password: "SecurePass123!@#"
4. Confirmar password: "SecurePass123!@#"
5. Aceptar términos
6. Clic en "Crear Mi Cuenta"

Resultado Esperado:

• ✅ Cuenta creada con status "active"
• ✅ Invitación marcada como "aceptada"
• ✅ Email de bienvenida enviado
• ✅ Redirige a login o dashboard
• ✅ Puede iniciar sesión inmediatamente

CP-003: Token Expirado

Precondiciones:

• Invitación enviada hace más de 7 días

Pasos:

1. Abrir link de invitación expirada

Resultado Esperado:

• ✅ Muestra mensaje: "Esta invitación ha expirado"
• ✅ Botón para solicitar nueva invitación visible
• ✅ No permite completar registro

CP-004: Email Duplicado

Precondiciones:

• Usuario con email "existente@test.com" ya registrado

Pasos:

1. Intentar invitar a "existente@test.com"

Resultado Esperado:

• ✅ Error: "Este email ya tiene una cuenta activa"
• ✅ No se envía email
• ✅ No se crea invitación

CP-005: Password Débil

Precondiciones:

• En página de registro desde invitación

Pasos:

1. Ingresar password: "12345"
2. Intentar crear cuenta

Resultado Esperado:

• ✅ Errores de validación mostrados:
  • "Password debe tener al menos 12 caracteres"
  • "Debe contener mayúscula, minúscula, número y carácter especial"
• ✅ Botón "Crear Cuenta" deshabilitado
• ✅ No se crea la cuenta

---

🔗 Dependencias

Requisitos Previos:

• ET-ADM-001: Modelo de base de datos implementado
• ET-ADM-005: Políticas de password configuradas
• Servicio de email configurado (SendGrid/SES)

APIs Necesarias:

• POST /api/admin/users/invite
• POST /api/auth/register-from-invitation
• GET /api/admin/invitations
• POST /api/admin/invitations/:id/resend
• DELETE /api/admin/invitations/:id

Componentes Frontend:

• InviteUserModal
• RegisterFromInvitation
• InvitationsList
• PasswordStrengthMeter

---

📊 Métricas de Éxito

• Tasa de conversión: >80% de invitaciones aceptadas dentro de 7 días
• Tiempo promedio de registro: <3 minutos desde apertura del link
• Tasa de error en registro: <5%
• Passwords que cumplen política: 100%

---

Generado: 2025-11-20
Estado: ✅ Listo para desarrollo