erp-construccion/docs/02-definicion-modulos/MAI-013-administracion-seguridad/historias-usuario/US-ADM-003-gestionar-permisos.md

US-ADM-003: Gestionar Permisos Personalizados

ID: US-ADM-003
Módulo: MAI-013
Relacionado con: RF-ADM-002, ET-ADM-001
Prioridad: Media
Story Points: 5

---

📖 Historia de Usuario

Como Director General
Quiero asignar permisos personalizados a usuarios específicos que excedan o limiten su rol base
Para adaptar el acceso según necesidades especiales sin crear nuevos roles

---

✅ Criterios de Aceptación

1. Ver Permisos de Usuario

Given que soy Director General
When accedo a "Usuarios" y selecciono un usuario
And hago clic en "Permisos"
Then debo ver dos secciones:
  - "Permisos Base del Rol" (no editables, solo lectura)
  - "Permisos Personalizados" (editables)
And cada permiso debe mostrar:
  - Módulo
  - Acciones permitidas (Create, Read, Update, Delete, Approve)
  - Origen (Rol / Personalizado)

2. Agregar Permiso Personalizado

Given que estoy viendo permisos de un usuario con rol "engineer"
And su rol NO incluye permiso "approve" en módulo "budgets"
When hago clic en "+ Agregar Permiso Personalizado"
And selecciono:
  - Módulo: "Presupuestos"
  - Acción: "Aprobar"
  - Condición: "Montos < $50,000 MXN" (opcional)
And hago clic en "Guardar"
Then el sistema debe:
  - Agregar el permiso a la sección "Personalizados"
  - Marcar visualmente que es un permiso adicional (badge "Extra")
  - Registrar en audit log: "custom_permission_granted"
  - Notificar al usuario por email

3. Revocar Permiso Base

Given que un usuario con rol "resident" tiene permiso "update" en "purchases"
When quiero restringir este permiso específicamente
And hago clic en "Revocar" junto al permiso
And confirmo la acción
Then el sistema debe:
  - Crear una excepción negativa en permisos personalizados
  - Marcar el permiso con badge "Revocado"
  - El usuario pierde acceso a esa acción
  - Registrar en audit log: "permission_revoked"

4. Permisos Temporales

Given que quiero dar acceso temporal a un usuario
When agrego un permiso personalizado
And marco la opción "Temporal"
And selecciono fecha de expiración: "2025-12-31"
Then el sistema debe:
  - Guardar el permiso con fecha de expiración
  - Mostrar countdown: "Expira en 45 días"
  - Revocar automáticamente el permiso al llegar la fecha
  - Enviar notificación 3 días antes de expirar

5. Permisos Condicionales

Given que agrego un permiso personalizado
When selecciono "Con Condiciones"
And configuro reglas:
  - Campo: "monto"
  - Operador: "<="
  - Valor: "50000"
Then el sistema debe:
  - Guardar la condición en JSON
  - Validar en backend si se cumple la condición
  - Mostrar en UI: "Aprobar presupuestos ≤ $50,000"

6. Previsualización de Acceso

Given que estoy editando permisos de un usuario
When hago clic en "Previsualizar Acceso"
Then debo ver una matriz completa con:
  - Filas: Todos los módulos
  - Columnas: CREATE, READ, UPDATE, DELETE, APPROVE
  - Celdas con color:
    - Verde: Permitido por rol
    - Azul: Permitido por permiso personalizado
    - Rojo: Denegado por excepción
    - Gris: No permitido

---

🎨 Mockup / Wireframe

Panel de Permisos de Usuario

┌─────────────────────────────────────────────────────────────────┐
│ ← Usuarios / Juan Pérez                                         │
├─────────────────────────────────────────────────────────────────┤
│ [Info] [Permisos] [Actividad] [Sesiones]                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ 📋 Permisos Base del Rol: Ingeniero                    [👁️ Preview]│
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Módulo          CREATE  READ  UPDATE  DELETE  APPROVE      │ │
│ │ ──────────────────────────────────────────────────────────  │ │
│ │ Proyectos        ✓      ✓      ✓       ✗       ✗  [ROL]   │ │
│ │ Presupuestos     ✓      ✓      ✓       ✗       ✗  [ROL]   │ │
│ │ Obra             ✓      ✓      ✓       ✗       ✗  [ROL]   │ │
│ │ Compras          ✗      ✓      ✗       ✗       ✗  [ROL]   │ │
│ └─────────────────────────────────────────────────────────────┘ │
│                                                                 │
│ 🎯 Permisos Personalizados                 [+ Agregar Permiso] │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ✨ Presupuestos > Aprobar                           [Extra]  │ │
│ │    Condición: Monto ≤ $50,000 MXN                           │ │
│ │    Expira: 31 Dic 2025 (45 días restantes)                  │ │
│ │    Otorgado por: María López el 15 Nov 2025                 │ │
│ │                                    [Editar] [Revocar]        │ │
│ │                                                              │ │
│ │ 🚫 Compras > Eliminar                                [Revocado]│
│ │    Razón: Prevención de errores críticos                    │ │
│ │    Revocado por: María López el 18 Nov 2025                 │ │
│ │                                    [Restaurar]               │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Modal Agregar Permiso Personalizado

┌─────────────────────────────────────────────┐
│ Agregar Permiso Personalizado            [X]│
├─────────────────────────────────────────────┤
│                                             │
│ Tipo *                                      │
│ ◉ Otorgar permiso adicional                 │
│ ○ Revocar permiso del rol                   │
│                                             │
│ Módulo *                                    │
│ [v] Presupuestos                            │
│                                             │
│ Acción *                                    │
│ [v] Aprobar                                 │
│                                             │
│ ☑️ Aplicar Condiciones                      │
│ ┌─────────────────────────────────────────┐ │
│ │ Campo    Operador     Valor             │ │
│ │ [monto] [<=]      [50000]        [+ And]│ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ ☑️ Permiso Temporal                         │
│ Expira el: [31/12/2025]  📅                │
│                                             │
│ Razón *                                     │
│ ┌─────────────────────────────────────────┐ │
│ │ Necesita aprobar presupuestos pequeños  │ │
│ │ durante ausencia del director           │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ ☑️ Notificar al usuario                     │
│                                             │
│        [Cancelar]  [Agregar Permiso]        │
└─────────────────────────────────────────────┘

Previsualización de Matriz de Permisos

┌─────────────────────────────────────────────────────────────────┐
│ Previsualización de Acceso: Juan Pérez (Ingeniero)          [X]│
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Módulo             CREATE   READ   UPDATE  DELETE  APPROVE     │
│ ──────────────────────────────────────────────────────────────  │
│ Proyectos           🟢      🟢      🟢      ⚫      ⚫         │
│ Presupuestos        🟢      🟢      🟢      ⚫      🔵<$50K    │
│ Obra                🟢      🟢      🟢      ⚫      ⚫         │
│ Compras             ⚫      🟢      ⚫      🔴      ⚫         │
│ Contratos           ⚫      🟢      ⚫      ⚫      ⚫         │
│ RH                  ⚫      ⚫      ⚫      ⚫      ⚫         │
│                                                                 │
│ Leyenda:                                                        │
│ 🟢 Permitido por rol    🔵 Permiso personalizado               │
│ 🔴 Revocado            ⚫ No permitido                          │
│                                                                 │
│                              [Cerrar]                           │
└─────────────────────────────────────────────────────────────────┘

---

🧪 Casos de Prueba

CP-001: Agregar Permiso Adicional

Precondiciones:

• Usuario "Juan" con rol "engineer"
• Director autenticado

Pasos:

1. Ir a perfil de Juan > Permisos
2. Clic en "+ Agregar Permiso Personalizado"
3. Seleccionar: Presupuestos > Aprobar
4. Agregar condición: monto <= 50000
5. Guardar

Resultado Esperado:

• ✅ Permiso aparece en "Permisos Personalizados"
• ✅ Badge "Extra" visible
• ✅ Juan puede aprobar presupuestos ≤$50K
• ✅ Juan NO puede aprobar presupuestos >$50K
• ✅ Email enviado a Juan notificando cambio

CP-002: Revocar Permiso Base

Precondiciones:

• Usuario "Ana" con rol "resident"
• Rol incluye UPDATE en "purchases"

Pasos:

1. Ir a perfil de Ana > Permisos
2. En "Permisos Base", clic en "Revocar" junto a Compras > Update
3. Confirmar revocación

Resultado Esperado:

• ✅ Permiso marcado como "Revocado" con badge rojo
• ✅ Ana pierde acceso a editar compras
• ✅ GET /api/users/me/permissions excluye ese permiso
• ✅ Audit log registra revocación

CP-003: Permiso Temporal Expira

Precondiciones:

• Usuario tiene permiso temporal que expira hoy a las 23:59

Pasos:

1. Esperar a que llegue la fecha de expiración
2. Verificar permisos del usuario

Resultado Esperado:

• ✅ Cron job revoca el permiso automáticamente
• ✅ Permiso removido de lista de personalizados
• ✅ Usuario recibe email: "Tu permiso temporal ha expirado"
• ✅ Audit log: "temporary_permission_expired"

CP-004: Validación de Condición

Precondiciones:

• Juan tiene permiso "approve budgets" con condición "monto <= 50000"

Pasos:

1. Juan intenta aprobar presupuesto de $30,000
2. Juan intenta aprobar presupuesto de $80,000

Resultado Esperado:

• ✅ Presupuesto $30K: Aprobación exitosa
• ✅ Presupuesto $80K: Error 403 "No tienes permiso para aprobar montos superiores a $50,000"

CP-005: Previsualización Correcta

Precondiciones:

• Usuario con permisos base + 2 personalizados + 1 revocado

Pasos:

1. Abrir "Previsualizar Acceso"

Resultado Esperado:

• ✅ Matriz muestra todos los módulos y acciones
• ✅ Colores correctos según origen del permiso
• ✅ Tooltips explican condiciones

---

🔗 Dependencias

Requisitos Previos:

• ET-ADM-001: Tabla custom_permissions implementada
• ET-ADM-002: Sistema RBAC base funcional
• Backend: Guard que evalúa permisos personalizados

APIs Necesarias:

• GET /api/users/:id/permissions - Permisos completos del usuario
• POST /api/users/:id/permissions/custom - Agregar permiso personalizado
• DELETE /api/users/:id/permissions/custom/:permissionId - Revocar
• PUT /api/users/:id/permissions/custom/:permissionId - Editar
• POST /api/users/:id/permissions/preview - Previsualizar matriz

---

📊 Métricas de Éxito

• Permisos personalizados activos: <10% del total de usuarios
• Tiempo de configuración: <2 minutos por permiso
• Precisión de condiciones: 100% (0 falsos positivos/negativos)
• Revocaciones automáticas: 100% al expirar

---

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