pagasis/IMPORTACION_ASISTENCIAS.md

# 📥 Guía de Importación/Exportación de Asistencias

## 📋 Descripción General

El sistema permite importar y exportar asistencias y estadísticas desde el admin de Django usando archivos Excel (.xlsx) o CSV.

## ✨ Características

### 1. **Asistencias (Attendance)**

#### Importar Asistencias
- ✅ Botón "Importar" disponible en `/admin/attendance/attendance/`
- ✅ Formatos soportados: Excel (.xlsx), CSV (.csv)
- ✅ **Permite importar asistencias pasadas** (fuera de ventana de tiempo)
- ✅ Valida duplicados y eventos simultáneos automáticamente
- ✅ Auto-crea permisos de Asistente si no existen

#### Exportar Asistencias
- ✅ Botón "Exportar" disponible en la lista
- ✅ Formatos: Excel (.xlsx), CSV (.csv)

### 2. **Estadísticas de Asistencia (AttendanceStats)**

#### Importar Estadísticas
- ✅ Botón "Importar" disponible en `/admin/attendance/attendancestats/`
- ✅ Permite actualizar estadísticas masivamente

#### Exportar Estadísticas
- ✅ Botón "Exportar" para todas las estadísticas
- ✅ Acción "📊 Exportar estadísticas seleccionadas"
- ✅ Acción "📊 Exportar estudiantes que cumplen requisito para constancia"
- ✅ Acción "🔄 Actualizar estadísticas seleccionadas"

---

## 📊 Formato del Archivo Excel para Importar Asistencias

### Columnas Requeridas:

| Columna | Descripción | Ejemplo | Obligatorio |
|---------|-------------|---------|-------------|
| `account_number` | Número de cuenta del estudiante (8 dígitos) | 32114471 | ✅ Sí |
| `student_name` | Nombre completo del estudiante | Lopez Martinez Valeria | ❌ No (solo referencia) |
| `event_title` | Título exacto del evento | Matemáticas Aplicadas a Medicina... | ✅ Sí |
| `registered_by_account` | Cuenta del asistente que registra | 11111111 | ❌ No (default: 11111111) |
| `timestamp` | Fecha y hora del registro | 2025-10-21 11:30:00 | ❌ No (default: ahora) |
| `registration_method` | Método de registro | manual | ❌ No (default: manual) |
| `notes` | Notas adicionales | Importado desde Excel | ❌ No |
| `is_valid` | ¿Es válida la asistencia? | True | ❌ No (default: True) |

### Ejemplo de Archivo Excel:

```
account_number | student_name              | event_title                                      | registered_by_account
32114471       | Lopez Martinez Valeria    | Matemáticas Aplicadas a Medicina...              | 11111111
31904405       | Lopez Martinez Angel      | La presión fiscal como oportunidad...            | 11111111
42510571       | Almaraz Ramirez Rafael    | Tecnologías IIoT al servicio de la Industria     | 11111111
```

---

## ⚙️ Comportamiento del Sistema

### 🔓 skip_validation=True

Cuando se importan asistencias, el sistema usa `skip_validation=True` que:

✅ **PERMITE:**
- Importar asistencias fuera de la ventana de tiempo del evento
- Importar asistencias de eventos pasados
- Procesar importaciones masivas históricas

✅ **MANTIENE VALIDACIÓN DE:**
- ❌ **Duplicados**: No permite crear dos asistencias del mismo estudiante al mismo evento
- ❌ **Eventos simultáneos**: No permite asistencia a dos eventos que ocurren al mismo tiempo

### 🔐 Permisos de Asistente

El sistema **automáticamente**:
1. Busca el asistente por `registered_by_account`
2. Si no existe, usa el asistente por defecto (11111111)
3. Verifica si tiene permisos en la tabla `Asistente`
4. Si no tiene permisos, los crea automáticamente con `can_manage_events=True`

---

## 🚀 Cómo Usar

### Importar Asistencias desde Admin

1. Ve a `/admin/attendance/attendance/`
2. Click en botón **"IMPORTAR"** (arriba a la derecha)
3. Selecciona tu archivo Excel o CSV
4. El sistema muestra una **vista previa** de los cambios
5. Revisa los errores si los hay
6. Click en **"Confirmar importación"**
7. ✅ Listo! Las asistencias se importaron

### Exportar Asistencias

1. Ve a `/admin/attendance/attendance/`
2. Click en botón **"EXPORTAR"**
3. Selecciona formato (Excel o CSV)
4. Se descarga el archivo automáticamente

### Exportar Estudiantes con Constancia

1. Ve a `/admin/attendance/attendancestats/`
2. Selecciona estudiantes (o déjalos todos)
3. En "Acción": selecciona **"📊 Exportar estudiantes que cumplen requisito para constancia"**
4. Click en **"Ir"**
5. Se descarga Excel con estudiantes que cumplen el % mínimo

---

## ⚠️ Errores Comunes y Soluciones

### Error: "Estudiante con cuenta XXXXX no encontrado"
**Causa:** El número de cuenta no existe en la base de datos
**Solución:** Verifica que el estudiante esté registrado en el sistema

### Error: "Evento 'XXXXX' no encontrado"
**Causa:** El título del evento no coincide exactamente
**Solución:** Copia el título exacto desde `/admin/events/event/`

### Error: "Este estudiante ya tiene asistencia registrada para este evento"
**Causa:** Ya existe una asistencia para ese estudiante en ese evento
**Solución:** Es un duplicado, omítelo o elimina el existente primero

### Error: "El estudiante ya tiene asistencia registrada en un evento simultáneo"
**Causa:** El estudiante tiene asistencia en otro evento que ocurre al mismo tiempo
**Solución:** El estudiante no puede estar en dos lugares a la vez. Elige uno solo.

---

## 🔄 Actualizar Estadísticas después de Importar

Las estadísticas se actualizan **automáticamente** después de cada importación.

Si necesitas actualizar manualmente:
1. Ve a `/admin/attendance/attendancestats/`
2. Selecciona los estudiantes
3. Acción: **"🔄 Actualizar estadísticas seleccionadas"**
4. Click en **"Ir"**

---

## 📝 Notas Importantes

1. **Solo superusuarios** pueden importar asistencias
2. El sistema **normaliza automáticamente** números de cuenta (elimina espacios, guiones)
3. Los **certificados SSL** pueden variar entre máquinas (regenerar con `./docker/generate_ssl_certs.sh`)
4. La **base de datos NO se sincroniza con Git**, solo el código
5. Para sincronizar datos entre máquinas, usa **backup/restore de PostgreSQL**

---

## 🛠️ Desarrollo

### Archivos Modificados:
- `backend/attendance/admin.py` - Admin con ImportExportMixin
- `backend/attendance/models.py` - Modelo con skip_validation

### Dependencias:
- `django-import-export` - Manejo de importación/exportación
- `openpyxl` - Lectura de archivos Excel
- `pandas` - Procesamiento de datos (opcional)

---

## 📚 Referencias

- Django Import-Export: https://django-import-export.readthedocs.io/
- Admin de Django: https://docs.djangoproject.com/en/5.0/ref/contrib/admin/