checklist/PERMISOS_CHECKLIST.md

# Sistema de Permisos por Mecánico - Checklists

## ✅ Implementación Completa

Se ha implementado un sistema completo de permisos que permite controlar qué mecánicos pueden usar cada checklist.

---

## 🎯 Características Implementadas

### **Backend**

1. **Nueva Tabla de Permisos**
   - Tabla `checklist_permissions` con relación many-to-many
   - Constraint UNIQUE para evitar duplicados
   - Índices optimizados para consultas rápidas

2. **Lógica de Acceso**
   - **Acceso Global**: Si un checklist NO tiene permisos registrados, todos los mecánicos pueden usarlo
   - **Acceso Restringido**: Si tiene permisos, solo esos mecánicos específicos pueden verlo
   - **Admins**: Siempre ven todos los checklists

3. **Endpoints Actualizados**
   - `GET /api/checklists`: Filtra automáticamente por permisos del mecánico
   - `POST /api/checklists`: Guarda permisos al crear
   - `PUT /api/checklists/{id}`: Actualiza permisos al editar
   - Incluye `allowed_mechanics` en las respuestas

### **Frontend**

1. **Creación de Checklists**
   - Selector de mecánicos con checkboxes
   - Opción "Acceso Global" (no seleccionar ninguno)
   - Interfaz clara con íconos 🔐 y 🌍

2. **Visualización**
   - Badge verde "🌍 Acceso Global" para checklists sin restricciones
   - Badge índigo "🔐 Restringido - X mecánicos" para checklists restringidos
   - Solo visible para administradores

3. **Edición de Permisos**
   - Botón "🔐 Permisos" en cada checklist (solo admins)
   - Modal dedicado para editar permisos
   - Cambios se aplican inmediatamente

4. **Mensajes Mejorados**
   - Mensaje específico para mecánicos sin checklists disponibles
   - Instrucciones claras para contactar al administrador

---

## 📋 Instrucciones de Uso

### **Para Administradores**

#### 1. Crear Checklist con Permisos

1. Ve a la pestaña "Checklists"
2. Haz clic en "+ Crear Checklist"
3. Completa los datos del checklist
4. En la sección "🔐 Mecánicos Autorizados":
   - **Para acceso global**: No selecciones ningún mecánico (deja todo sin marcar)
   - **Para acceso restringido**: Marca los mecánicos que tendrán acceso
5. Haz clic en "Crear Checklist"

#### 2. Editar Permisos de Checklist Existente

1. Ve a la pestaña "Checklists"
2. Busca el checklist que quieres modificar
3. Haz clic en el botón "🔐 Permisos"
4. Modifica la selección de mecánicos:
   - Marca "🌍 Todos los mecánicos" para acceso global
   - O selecciona mecánicos específicos
5. Haz clic en "Guardar Permisos"

**Nota**: Los cambios son inmediatos. Los mecánicos que pierdan acceso dejarán de ver el checklist instantáneamente.

#### 3. Ver Estado de Permisos

Cada tarjeta de checklist muestra:
- **🌍 Acceso Global - Todos los mecánicos**: Sin restricciones
- **🔐 Restringido - X mecánicos**: Solo esos mecánicos tienen acceso

### **Para Mecánicos**

- Solo verás los checklists donde tienes permiso
- Si no ves ningún checklist, contacta al administrador
- No puedes modificar permisos (solo el admin puede hacerlo)

---

## 🗄️ Migración de Base de Datos

### **Ejecutar SQL**

```bash
# Usando psql
psql -U tu_usuario -d tu_database -f migrations/add_checklist_permissions.sql

# O directamente
psql -U tu_usuario -d tu_database
```

Luego ejecuta:

```sql
-- Crear tabla de permisos checklist-mecánico
CREATE TABLE IF NOT EXISTS checklist_permissions (
    id SERIAL PRIMARY KEY,
    checklist_id INTEGER NOT NULL REFERENCES checklists(id) ON DELETE CASCADE,
    mechanic_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(checklist_id, mechanic_id)
);

-- Crear índices
CREATE INDEX idx_checklist_permissions_checklist ON checklist_permissions(checklist_id);
CREATE INDEX idx_checklist_permissions_mechanic ON checklist_permissions(mechanic_id);

-- Comentarios
COMMENT ON TABLE checklist_permissions IS 'Control de acceso de mecánicos a checklists. Si no hay registros para un checklist, todos los mecánicos tienen acceso.';
```

### **Reiniciar Backend**

Después de ejecutar el SQL, reinicia el backend para que los cambios en los modelos tomen efecto:

```bash
# Si usas Docker
docker-compose restart backend

# Si corres directamente
# Ctrl+C y volver a ejecutar
python -m uvicorn app.main:app --reload
```

---

## 🔍 Ejemplos de Uso

### Ejemplo 1: Checklist para Todos los Mecánicos

**Escenario**: Checklist de "Revisión Básica" que todos pueden usar

**Configuración**:
- Al crear/editar: No seleccionar ningún mecánico
- El sistema muestra: "🌍 Acceso Global - Todos los mecánicos"

**Resultado**: Todos los mecánicos ven este checklist

---

### Ejemplo 2: Checklist Especializado

**Escenario**: Checklist de "Mantenimiento Eléctrico" solo para mecánicos certificados

**Configuración**:
1. Al crear/editar: Seleccionar solo mecánicos con certificación eléctrica
2. El sistema muestra: "🔐 Restringido - 3 mecánicos"

**Resultado**: Solo esos 3 mecánicos ven este checklist

---

### Ejemplo 3: Cambio de Permisos

**Escenario**: Un mecánico nuevo se certifica en electricidad

**Pasos**:
1. Admin hace clic en "🔐 Permisos" del checklist "Mantenimiento Eléctrico"
2. Marca al nuevo mecánico en la lista
3. Guarda cambios
4. El mecánico inmediatamente ve el checklist en su lista

---

## 📊 Base de Datos

### Estructura de `checklist_permissions`

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | SERIAL | ID único de la relación |
| checklist_id | INTEGER | ID del checklist |
| mechanic_id | INTEGER | ID del mecánico autorizado |
| created_at | TIMESTAMP | Fecha de creación del permiso |

### Consultas Útiles

```sql
-- Ver permisos de un checklist específico
SELECT u.full_name, u.email 
FROM checklist_permissions cp
JOIN users u ON cp.mechanic_id = u.id
WHERE cp.checklist_id = 1;

-- Ver qué checklists puede usar un mecánico
SELECT c.name, c.description
FROM checklist_permissions cp
JOIN checklists c ON cp.checklist_id = c.id
WHERE cp.mechanic_id = 5;

-- Checklists sin restricciones (acceso global)
SELECT c.id, c.name
FROM checklists c
LEFT JOIN checklist_permissions cp ON c.id = cp.checklist_id
WHERE cp.id IS NULL;

-- Dar acceso a un mecánico a un checklist
INSERT INTO checklist_permissions (checklist_id, mechanic_id)
VALUES (1, 5)
ON CONFLICT (checklist_id, mechanic_id) DO NOTHING;

-- Quitar acceso
DELETE FROM checklist_permissions
WHERE checklist_id = 1 AND mechanic_id = 5;

-- Convertir checklist a acceso global (borrar todos los permisos)
DELETE FROM checklist_permissions WHERE checklist_id = 1;
```

---

## ⚠️ Notas Importantes

1. **Permisos Vacíos = Acceso Global**
   - Si un checklist NO tiene registros en `checklist_permissions`, TODOS los mecánicos pueden usarlo
   - Es el comportamiento por defecto

2. **Los Admins Siempre Ven Todo**
   - Los usuarios con rol `admin` ven todos los checklists sin importar los permisos
   - Útil para gestión y supervisión

3. **Cambios Inmediatos**
   - Al editar permisos, los cambios se aplican instantáneamente
   - No requiere logout/login

4. **Cascada en Borrado**
   - Si borras un checklist, sus permisos se borran automáticamente
   - Si borras un mecánico, sus permisos se borran automáticamente

5. **Inspecciones Existentes**
   - Las inspecciones ya creadas NO se ven afectadas por cambios de permisos
   - Solo afecta la creación de nuevas inspecciones

---

## 🐛 Troubleshooting

### Problema: "Mecánico no ve ningún checklist"

**Solución**:
1. Verificar que el mecánico esté activo: `SELECT is_active FROM users WHERE id = X;`
2. Verificar permisos: `SELECT * FROM checklist_permissions WHERE mechanic_id = X;`
3. Verificar si hay checklists con acceso global (sin permisos)
4. Verificar rol del usuario: debe ser `mechanic` o `mecanico`

### Problema: "Error al crear/editar permisos"

**Solución**:
1. Verificar que la tabla `checklist_permissions` existe
2. Verificar que los IDs de mecánicos son válidos
3. Revisar logs del backend para errores específicos
4. Verificar que el usuario es admin

### Problema: "Los permisos no se aplican"

**Solución**:
1. Hacer logout y login nuevamente
2. Verificar que el backend se reinició después de la migración
3. Limpiar caché del navegador (Ctrl+Shift+R)
4. Verificar en la base de datos que los permisos se guardaron correctamente

---

## 🎉 Resumen

✅ **Backend**: Filtrado automático por permisos  
✅ **Frontend**: Interfaz completa para gestionar permisos  
✅ **Base de Datos**: Migración lista para ejecutar  
✅ **Documentación**: Completa con ejemplos  

El sistema está listo para usar después de ejecutar la migración SQL y reiniciar el backend.