# 📚 GUÍA DE USO - Módulo de Informes para Padres v12

**Sistema PREALTUM - Versión 12 (2026-06-04)**

---

## 🚀 INICIO RÁPIDO

### Acceso al Módulo
1. Inicia sesión como **Administrador**
2. Ve a: `/admin/informes_padres.php`
3. O desde el panel, busca la opción "Informes para Padres"

### Dashboard Principal
- **5 tarjetas KPI** en la parte superior
- **7 pestañas** en la barra de navegación
- Interfaz moderna con tema oscuro

---

## 📋 LAS 5 TARJETAS KPI

### 1. 📄 Informes generados
- Total histórico de informes generados
- Número acumulativo de toda la temporada
- Clic para ir a historial

### 2. ✅ Enviados hoy
- Cantidad de informes enviados hoy específicamente
- Permite trackear actividad diaria
- Actualiza automáticamente

### 3. ⏳ Pendientes
- Informes generados pero NO enviados aún
- **CLICKEABLE** → Abre la pestaña de Pendientes
- Útil para identificar trabajos en proceso

### 4. 👥 Alumnos activos
- Cantidad total de alumnos disponibles para informes
- Necesarios en tu institución
- Varía según estado 'activo' en BD

### 5. ⚠️ Con error
- Informes que tuvieron problemas al enviar
- Correos inválidos, fallos SMTP, etc.
- Revisar logs para resolver

---

## 🎯 LAS 7 PESTAÑAS

### Pestaña 1: 📄 INDIVIDUAL

**Mejor para:** Enviar informe a un solo alumno

**Pasos:**
1. Filtra por grado, profesor o búsqueda por nombre
2. Clic en "Seleccionar" del alumno deseado
3. **Paso 2:** Elige tipo de período (Diario/Semanal/Mensual/etc.)
4. Opcional: Ajusta fechas personalizadas
5. Clic "Generar Vista Previa"
6. **Paso 3:** Visualiza el PDF en el navegador
7. Opción: "Enviar ahora" o descargar manualmente
8. Si envías, va al correo de padres automáticamente

**Notas:**
- Correos de padres se autocompletán desde perfil del alumno
- Puedes editar correos antes de enviar
- Siempre puedes cambiar de alumno regresando al Paso 1

---

### Pestaña 2: 👨‍🏫 PROFESOR

**Mejor para:** Enviar a todos los alumnos de un profesor

**Pasos:**
1. Busca el profesor en el campo "Buscar profesor..."
2. Clic en el profesor (tarjeta se resalta)
3. Se muestra cantidad de alumnos asignados
4. Clic "Cargar alumnos"
5. Se abre tabla con la lista completa
6. Opción 1: Haz clic en checkboxes individuales
7. Opción 2: Clic en checkbox "Seleccionar todos"
8. Botones:
   - **"Generar"** = Solo genera PDFs (útil para revisar primero)
   - **"Generar y Enviar"** = Genera PDFs Y envía correos

**Resultado:**
- Cada alumno recibe su PDF individual
- Cada alumno recibe su correo individual (NO grupal)
- Barra de progreso muestra: "3 de 10 generados"

**Ejemplo:**
```
Profesor: María López
Alumnos seleccionados: 10
Resultado: 10 PDFs individuales + 10 correos personalizados
```

---

### Pestaña 3: 📚 GRADO

**Mejor para:** Enviar a todos los alumnos de un grado específico

**Pasos:**
1. Botones visuales: "4°", "5°", etc. (grados disponibles)
2. Clic en el grado deseado
3. Muestra cantidad total de alumnos en ese grado
4. Clic "Cargar alumnos"
5. Tabla con todos los alumnos del grado
6. Seleccionar:
   - Alumnos individuales (checkboxes)
   - O checkbox "Seleccionar todos" para todos del grado
7. Clic "Generar y Enviar"
8. Monitorea progreso: "5 de 35 generados"

**Capacidad:**
- Soporta 35, 50, 100+ alumnos sin problemas
- Carga progresiva
- Progreso visual en tiempo real

**Ejemplo:**
```
4° Grado Secundaria
Total alumnos: 35
Generados: 35 PDFs individuales
Enviados: 35 correos individuales
Tiempo aprox: 2-5 minutos
```

---

### Pestaña 4: ☑ MÚLTIPLE

**Mejor para:** Enviar a alumnos específicos sin patrón definido

**Pasos:**
1. Filtra combinando:
   - Grado (ej: 4°)
   - Profesor (ej: María)
   - Búsqueda (ej: "Juan")
2. Tabla se actualiza en tiempo real
3. Selecciona checkboxes de los alumnos que deseas
4. O clic en checkbox de cabecera para "Seleccionar todos"
5. Muestra cantidad: "(5 seleccionados)"
6. Botones de acción igual que otras pestañas
7. Clic "Generar y Enviar"

**Casos de Uso:**
- 2 alumnos de diferentes grados
- 5 alumnos de diferentes profesores
- Alumnos específicos con bajo rendimiento
- Selecciones personalizadas

---

### Pestaña 5: ⏳ PENDIENTES

**Mejor para:** Enviar informes que ya fueron generados pero no enviados

**Pasos:**
1. Se abre automáticamente mostrando lista de pendientes
2. Cada fila = 1 informe generado sin enviar
3. Información: Fecha, Alumno, Tipo, Estado
4. Opción 1: Selecciona algunos con checkboxes
   - Clic "Enviar Seleccionados"
5. Opción 2: Clic "Enviar Todos"
   - Envía todos los pendientes de una vez
6. Progreso visual: "5 de 17 enviados"

**Por qué es útil:**
- A veces generas sin enviar (revisión previa)
- Fallos de conexión → reportes quedan pendientes
- Solucionar problemas SMTP y reintentar después

**Tarjeta KPI "Pendientes":**
- Es CLICKEABLE desde el dashboard
- Te lleva directamente a esta pestaña

---

### Pestaña 6: 🤖 AUTO (Automatización)

**Mejor para:** Configurar envíos automáticos programados

**Características:**
1. **Toggle ON/OFF** - Activa/desactiva automatización
2. **Frecuencia:**
   - Diario (7:00 AM)
   - Semanal (Lunes 8:00 AM)
   - Mensual (Día 1, 9:00 AM)
3. **Filtro de grados** (opcional):
   - Dejar vacío = todos los grados
   - Ejemplo: "4,5" = solo 4° y 5°
4. **Tipo de informe:**
   - Semanal / Mensual / Completo
5. **Alertas de bajo rendimiento:**
   - Activadas/Desactivadas
6. Clic "Guardar configuración"

**Cómo funciona:**
- Una vez configurado, el sistema automáticamente:
  - Genera informes según frecuencia
  - Envía a los padres automáticamente
  - Sin intervención manual
  - Registra todo en historial

**Ejemplo:**
```
Config: Mensual, Diarios 4° y 5°, Con alertas
Resultado: Cada día 1 del mes a las 9 AM:
  - Genera informes de alumnos de 4° y 5°
  - Envía a correos de padres
  - Registra en historial
```

---

### Pestaña 7: 📋 HISTORIAL

**Mejor para:** Revisar, filtrar y analizar todos los informes generados

**Filtros disponibles (combinables):**
1. **Fecha desde** - Ej: 2026-01-01
2. **Fecha hasta** - Ej: 2026-06-04
3. **Estado** - Enviado / Generado / Error
4. **Profesor** - Filtra por profesor asignado

**Información mostrada:**
- Fecha de creación
- Nombre del alumno
- Profesor asignado
- Grado del alumno
- Tipo de informe
- Estado actual (badge coloreado)
- Enlace para descargar PDF

**Badges de estado:**
- 🟢 **ENVIADO** - Correo fue enviado exitosamente
- 🔵 **GENERADO** - PDF generado pero no enviado
- 🔴 **ERROR** - Hubo un error en la generación o envío

**Acciones:**
- Clic en "📥 PDF" → Descarga el PDF directamente
- Filtra múltiples criterios simultáneamente
- Búsqueda en tiempo real
- Paginación automática

**Ejemplo:**
```
Filtros:
- Fecha: 01/06/2026 a 04/06/2026
- Estado: Enviado
- Profesor: María López

Resultado: 8 informes enviados por María en estos 3 días
```

---

## 💡 FLUJOS DE TRABAJO COMUNES

### Flujo A: "Generar y enviar informe a un alumno"
1. Pestaña INDIVIDUAL
2. Paso 1: Busca y selecciona alumno
3. Paso 2: Configura parámetros
4. Paso 3: Genera vista previa y envía

### Flujo B: "Enviar a todos los alumnos de un profesor"
1. Pestaña PROFESOR
2. Busca profesor
3. Clic "Cargar alumnos"
4. Clic "Seleccionar todos"
5. Clic "Generar y Enviar"
6. Espera progreso

### Flujo C: "Enviar informes pendientes"
1. KPI "Pendientes" o Pestaña PENDIENTES
2. Clic "Enviar Todos" o selecciona algunos
3. Clic "Enviar Seleccionados"
4. Espera progreso

### Flujo D: "Revisar qué se envió ayer"
1. Pestaña HISTORIAL
2. Filtro Fecha: Ayer (03/06/2026)
3. Estado: Enviado
4. Revisa lista y descargas si necesitas

---

## ⚙️ CONFIGURACIÓN IMPORTANTE

### Correos de Padres
**¿Dónde se guardan?**
- Perfil del alumno → emails de padre/madre
- Sistema automáticamente los usa
- Puedes editarlos antes de enviar

**¿Qué pasa si no hay correo?**
- No se envía correo (PDF se genera igual)
- Aparece como "Generado" en lugar de "Enviado"
- Puedes agregarlo manualmente después

### SMTP (Servidor de Correos)
**Configurado en:**
- File: `config/config.php` o `src/config.php`
- Settings: Host, puerto, usuario, contraseña
- Si falla: Revisar logs de error

### Automatización
**Base de datos:**
- Tabla: `config_reportes_ia`
- Se guarda configuración
- Campos: frecuencia, filtros_grado, activo, etc.

---

## 🆘 SOLUCIÓN DE PROBLEMAS

### "No se envía correo"
1. Verifica correos de padres en BD
2. Revisa configuración SMTP en config
3. Busca errores en logs
4. Intenta "Reenviar" desde PENDIENTES

### "Progreso se congeló"
- Es normal, espera 30-60 seg
- Sistema está procesando en background
- No recargues la página

### "No aparecen alumnos"
- Verifica que status = 'activo' en BD
- Verifica que colegio_id sea correcto
- Filtra por grado específico

### "PDF se ve vacío"
- Revisa que datos de alumno estén completos
- Verifica tabla de calificaciones existe
- Revisa permisos de carpeta uploads/

### "Error al guardar configuración automatización"
- Verifica permisos BD
- Revisa tabla `config_reportes_ia` existe
- Intenta nuevamente

---

## 📊 MEJORES PRÁCTICAS

### ✅ RECOMENDADO
- Generar primero, enviar después (revisa PDFs antes)
- Usar "Pendientes" para reintentos
- Configurar automatización para envíos regulares
- Revisar historial regularmente
- Mantener correos de padres actualizados

### ❌ EVITAR
- Enviar masivo sin vista previa
- Usar correos inválidos
- Generar informes de alumnos inactivos
- Olvidar revisar historial
- No respaldar configuración

---

## 📈 ESTADÍSTICAS Y MONITOREO

### Dashboard KPIs
- Verificar números diarios
- Identificar patrones
- Detectar problemas temprano

### Historial
- Permite auditoría completa
- Filtros para análisis
- Descarga PDFs según necesidad

### Automatización
- Reduce trabajo manual 80%
- Envíos consistentes
- Menos errores humanos

---

## 🎓 CAPACITACIÓN RECOMENDADA

1. **Administrador:**
   - Todas las pestañas
   - Configuración automatización
   - Troubleshooting

2. **Director/Coordinador:**
   - Individual
   - Historial
   - Estadísticas KPI

3. **Secretaria:**
   - Individual
   - Pendientes
   - Descargas PDF

---

## 📞 SOPORTE

**Problemas técnicos:**
- Revisa documentación: `IMPLEMENTACION_INFORMES_v12.md`
- Archivo de logs: `LOGS/`
- Contacta al administrador del sistema

**Sugerencias:**
- Comunica mejoras deseadas
- Propón nuevas funcionalidades
- Reporta bugs/errores

---

## ✨ PRÓXIMAS ACTUALIZACIONES

- Descargar múltiples PDFs en ZIP
- Templates personalizables
- Estadísticas de open rate
- Integración Google Drive
- SMS como alternativa

---

**¡Listo para usar!** 🚀

Para cualquier duda, revisa `IMPLEMENTACION_INFORMES_v12.md` o contacta al equipo técnico.