# 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
```bash
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:**
```python
if current_user.role != "admin":
    raise HTTPException(status_code=403, detail="No tienes permisos")
```

**DESPUÉS:**
```python
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
```python
# Antes
if current_user.role != "admin":

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

#### Gestión de Checklists
```python
# Antes
if current_user.role != "admin":

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

#### Ver todas las Inspecciones
```python
# 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
```python
# Antes
if current_user.role != "admin":

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

### 5. Actualizar Frontend

**schemas en App.jsx:**
```javascript
// 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:**
```javascript
// 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

```bash
# 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"