checklist/ROLES_IMPLEMENTATION_GUIDE.md

Guía de Implementación del Sistema de Roles

📋 Resumen

Se implementa un sistema de roles basado en base de datos con 3 roles:

• Administrador (id=1): Acceso completo
• Asesor (id=2): Solo informes y reportes
• Mecánico (id=3): Crear y completar inspecciones

🔄 Pasos de Migración

1. Ejecutar Migración de Base de Datos

cd backend
python migrate_roles.py

Esto hará:

• ✅ Crear tabla roles
• ✅ Insertar 3 roles predefinidos
• ✅ Migrar usuarios existentes (admin -> administrador, mechanic -> mecanico)
• ✅ Eliminar columna role antigua

2. Reemplazar Verificaciones de Permisos en main.py

ANTES:

if current_user.role != "admin":
    raise HTTPException(status_code=403, detail="No tienes permisos")

DESPUÉS:

require_permission(current_user, "can_manage_users")

3. Permisos por Rol

Permiso	Administrador	Asesor	Mecánico
can_manage_users	✅	❌	❌
can_manage_roles	✅	❌	❌
can_manage_checklists	✅	❌	❌
can_create_inspections	✅	❌	✅
can_view_all_inspections	✅	✅	❌
can_view_reports	✅	✅	❌
can_deactivate_inspections	✅	❌	❌

4. Cambios en Endpoints

Gestión de Usuarios

# Antes
if current_user.role != "admin":

# Después  
require_permission(current_user, "can_manage_users")

Gestión de Checklists

# Antes
if current_user.role != "admin":

# Después
require_permission(current_user, "can_manage_checklists")

Ver todas las Inspecciones

# Antes
if current_user.role == "mechanic":
    query = query.filter(models.Inspection.mechanic_id == current_user.id)

# Después
if not has_permission(current_user, "can_view_all_inspections"):
    query = query.filter(models.Inspection.mechanic_id == current_user.id)

Desactivar Inspecciones

# Antes
if current_user.role != "admin":

# Después
require_permission(current_user, "can_deactivate_inspections")

5. Actualizar Frontend

schemas en App.jsx:

// Antes
role: 'mechanic'

// Después
role_id: 3,  // mecanico
role: {
  id: 3,
  name: 'mecanico',
  display_name: 'Mecánico',
  can_create_inspections: true,
  can_view_reports: false,
  // ...otros permisos
}

Verificación de permisos:

// Antes
if (user.role === 'admin')

// Después
if (user.role.can_manage_users)

6. Agregar Endpoints de Roles

Ver archivo role_endpoints.txt para los 5 nuevos endpoints:

• GET /api/roles - Listar roles
• GET /api/roles/{id} - Ver rol
• POST /api/roles - Crear rol
• PUT /api/roles/{id} - Actualizar rol
• DELETE /api/roles/{id} - Eliminar rol

7. Actualizar Componentes Frontend

UsersTab

• Cambiar selector de rol de texto a dropdown con roles de BD
• Mostrar role.display_name en lugar de role
• Enviar role_id en lugar de role al crear/editar

Sidebar

• Mostrar tab "Informes" solo si user.role.can_view_reports
• Mostrar tab "Usuarios" solo si user.role.can_manage_users

⚠️ Importante

1. Backup de BD: Hacer backup antes de ejecutar migración
2. Orden de deployment:
   • Backend primero (migración + código)
   • Frontend después
3. Validar: Probar login con cada tipo de usuario después de migrar

🧪 Testing

# 1. Probar login con admin
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

# 2. Verificar que el response incluye role object
# Debe tener: role: { id: 1, name: 'administrador', ... }

# 3. Probar permisos
curl -X GET http://localhost:8000/api/users \
  -H "Authorization: Bearer {token}"
# Debe funcionar para admin, fallar para mecanico

📝 Notas

• Los 3 roles predefinidos (id 1, 2, 3) no se pueden eliminar ni editar
• Nuevos roles personalizados pueden crearse con id > 3
• La migración es irreversible (elimina columna role)
• Usuarios sin role_id después de migración se asignan automáticamente a "mecanico"