# 🔧 CORRECCIÓN CRÍTICA: Sistema Híbrido de Roles

**Fecha**: 19 de Noviembre de 2025  
**Autor**: Alberto Granados  
**Ticket**: Coherencia id_role vs Bouncer Roles

---

## 📋 RESUMEN EJECUTIVO

### Problema Detectado

El comando `php artisan make:user-account` tenía un **bug crítico** que causaba **incoherencia entre el sistema legacy (`users.id_role`) y el sistema Bouncer (`assigned_roles`)**.

**Síntoma**:
- Usuarios web (root, admin, operative, viewer) recibían `id_role=5` (client) por defecto
- Sus roles Bouncer se asignaban correctamente (root, admin, etc.)
- **Resultado**: Incoherencia entre ambos sistemas

**Ejemplo en Producción**:
```sql
SELECT u.id, u.name, u.id_role, r.name FROM users u
JOIN roles r ON u.id_role = r.id
WHERE u.id IN (1, 3);

-- ANTES DEL FIX:
id | name               | id_role | role_name
---|--------------------|---------|-----------
1  | Alberto Granados   | 5       | Client    ❌ (debería ser 7: root)
3  | Hugo Rivera        | 5       | Client    ❌ (debería ser 7: root)
```

---

## ✅ SOLUCIÓN IMPLEMENTADA

### 1. Corrección del Comando `make:user-account`

**Archivo**: `app/Console/Commands/MakeUserAccount.php`

**Cambios Principales**:

```php
// ❌ ANTES (INCORRECTO):
$defaultRole = \App\Role::where('slug', 'client')->first();
$user->id_role = $defaultRole->id; // Siempre 5 (client)

// Solo se sobreescribía para drivers:
if ($userType === 'driver') {
    $driverRole = \App\Role::where('slug', 'driver')->firstOrFail();
    $user->id_role = $driverRole->id;
}
```

```php
// ✅ DESPUÉS (CORRECTO):
// Mapeo de tipos de usuario a slugs de roles
$roleSlugMap = [
    'driver'    => 'driver',
    'viewer'    => 'viewer',
    'admin'     => 'admin',
    'operative' => 'operative',
    'root'      => 'root'
];

$roleSlug = $roleSlugMap[$userType] ?? 'client';
$role = \App\Role::where('slug', $roleSlug)->first();
$user->id_role = $role->id; // ✅ Asignado según tipo de usuario
```

### 2. Mapeo Correcto de Roles

| Tipo Usuario | `users.id_role` | Rol Bouncer | Estado       |
|--------------|-----------------|-------------|--------------|
| `root`       | 7 (root)        | root        | ✅ Coherente  |
| `admin`      | 1 (admin)       | admin       | ✅ Coherente  |
| `operative`  | 3 (operative)   | operative   | ✅ Coherente  |
| `viewer`     | 8 (viewer)      | viewer      | ✅ Coherente  |
| `driver`     | 4 (driver)      | (N/A)       | ✅ Móvil solo |

### 3. Validación Automatizada

**Script de Tests**: `tests/test_roles_coherence.sh`

```bash
$ bash tests/test_roles_coherence.sh

🧪 TEST DE COHERENCIA: Sistema Híbrido de Roles
================================================

✅ Test 1: root creado correctamente
✅ Test 2: admin creado correctamente
✅ Test 3: operative creado correctamente
✅ Test 4: viewer creado correctamente
✅ Test 5: driver creado correctamente

📊 RESUMEN
✅ Pruebas exitosas: 5
❌ Pruebas fallidas: 0
🎉 TODAS LAS PRUEBAS PASARON
```

---

## 🔄 MIGRACIÓN EN PRODUCCIÓN

### Paso 1: Identificar Usuarios Afectados

```sql
-- Ver usuarios con incoherencia
SELECT 
    u.id,
    u.name,
    u.email,
    u.id_role,
    r.name as role_name_by_id,
    br.slug as bouncer_role
FROM users u
LEFT JOIN roles r ON u.id_role = r.id
LEFT JOIN assigned_roles ar ON u.id = ar.entity_id AND ar.entity_type = 'App\User'
LEFT JOIN roles br ON ar.role_id = br.id
WHERE r.slug != br.slug  -- Incoherentes
  AND br.slug IS NOT NULL;
```

### Paso 2: Ejecutar Script de Corrección

```bash
# En servidor de producción
psql -U [usuario] -d [database] -f database/migrations/fix_user_roles_coherence.sql
```

**Archivo**: `database/migrations/fix_user_roles_coherence.sql`

**Acciones del Script**:
1. Muestra estado ANTES de la corrección
2. Actualiza `users.id_role` según rol Bouncer asignado:
   - Bouncer 'root' → `id_role=7`
   - Bouncer 'admin' → `id_role=1`
   - Bouncer 'operative' → `id_role=3`
   - Bouncer 'viewer' → `id_role=8`
3. Muestra estado DESPUÉS de la corrección
4. Genera reporte de coherencia

**Resultado Esperado**:
```
=== DESPUÉS DE LA CORRECCIÓN ===
id | name             | role_slug | bouncer_slug | coherencia
---|------------------|-----------|--------------|------------
1  | Alberto Granados | root      | root         | ✅ COHERENTE
3  | Hugo Rivera      | root      | root         | ✅ COHERENTE

=== RESUMEN ===
total_usuarios_web: 2
coherentes: 2
incoherentes: 0
```

### Paso 3: Verificación Post-Migración

```sql
-- Verificar que NO haya incoherencias
SELECT COUNT(*) as incoherentes
FROM users u
JOIN roles r ON u.id_role = r.id
JOIN assigned_roles ar ON u.id = ar.entity_id AND ar.entity_type = 'App\User'
JOIN roles br ON ar.role_id = br.id
WHERE r.slug != br.slug;

-- Resultado esperado: 0
```

---

## 📚 DOCUMENTACIÓN ACTUALIZADA

### Archivos Modificados

1. **`app/Console/Commands/MakeUserAccount.php`**
   - Corregido mapeo de `id_role` según tipo de usuario
   - Eliminada asignación por defecto a 'client'

2. **`database/seeds/README_ROLES.md`**
   - Agregada tabla de coherencia
   - Documentado problema histórico
   - Agregados ejemplos de output del comando

3. **`DICCIONARIO_DATOS.md`**
   - Agregada entrada en historial de cambios
   - Documentado mapeo correcto vs problemático

4. **`tests/test_roles_coherence.sh`** (NUEVO)
   - Suite de 5 tests automatizados
   - Valida coherencia para cada tipo de usuario

5. **`database/migrations/fix_user_roles_coherence.sql`** (NUEVO)
   - Script transaccional de migración
   - Reportes automáticos de estado

---

## ⚠️ IMPORTANTE: USUARIOS CREADOS ANTES DEL 19-NOV-2025

**Usuarios afectados**:
- ❌ Todos los usuarios web creados con `make:user-account` antes del 19-Nov-2025
- ❌ Tienen `id_role=5` (client) independientemente de su rol Bouncer real

**Acción requerida**:
1. Identificar usuarios afectados (query del Paso 1)
2. Ejecutar script de migración (Paso 2)
3. Verificar coherencia (Paso 3)

**Usuarios NO afectados**:
- ✅ Drivers (siempre tuvieron `id_role=4` correcto)
- ✅ Usuarios creados manualmente con SQL
- ✅ Usuarios creados con `make:user-account` después del 19-Nov-2025

---

## 🎯 TESTING

### Test Manual

```bash
# Crear usuario root
php artisan make:user-account nuevo.root@empresa.com
> Nombre: Nuevo Root
> Teléfono: 4611234567
> Tipo: root  # Opción 4

# Verificar en BD
SELECT u.id_role, r.slug, br.slug 
FROM users u
JOIN roles r ON u.id_role = r.id
JOIN assigned_roles ar ON u.id = ar.entity_id
JOIN roles br ON ar.role_id = br.id
WHERE u.email = 'nuevo.root@empresa.com';

-- Resultado esperado:
-- id_role | slug | slug
-- --------+------+------
-- 7       | root | root  ✅
```

### Test Automatizado

```bash
$ bash tests/test_roles_coherence.sh
# Debe pasar 5/5 tests
```

---

## 📊 IMPACTO

### En Desarrollo
- ✅ Fix aplicado y validado
- ✅ Tests pasando 100%
- ✅ Documentación completa

### En Producción
- ⚠️ Usuarios históricos requieren migración
- ⚠️ No afecta funcionalidad actual (Bouncer funciona correctamente)
- ⚠️ Afecta reportes y queries que usan `users.id_role`

### Impacto Funcional
- **Bajo**: Sistema Bouncer siempre funcionó correctamente
- **Medio**: Queries directas a `users.id_role` mostraban rol incorrecto
- **Alto**: Reportes y auditorías basados en `id_role` eran inconsistentes

---

## ✅ CHECKLIST DE DESPLIEGUE

### Desarrollo
- [x] Código corregido en `MakeUserAccount.php`
- [x] Tests creados y pasando (5/5)
- [x] Script de migración creado
- [x] Documentación actualizada

### Producción
- [ ] Backup de BD previo a migración
- [ ] Identificar usuarios afectados
- [ ] Ejecutar script de migración
- [ ] Verificar coherencia post-migración
- [ ] Validar que nuevos usuarios se crean correctamente

---

**Autor**: Alberto Granados (granadosacosta.01@gmail.com)  
**Revisado por**: Equipo AMX  
**Estado**: ✅ Completado y validado en desarrollo  
**Próximo paso**: Aplicar migración en producción