Informe Técnico de Integración

1. Introducción y Objetivo

El presente informe tiene como objetivo principal delinear la estrategia técnica y el plan de acción para desarrollar una integración robusta y automatizada entre la plataforma de e-learning existente y el Sistema Integrado de Calidad (SIC) de SENCE.

La integración se realizará a través del "API Gestor Intermedio", un middleware provisto por SENCE para centralizar la recepción de datos de avance de los alumnos, comúnmente conocido como el Libro de Clases Electrónico (LCE).

El objetivo final es crear un agente de software automatizado que, diariamente y sin intervención manual, recopile, formatee y transmita la información de progreso de los alumnos desde nuestra base de datos hacia SENCE, garantizando el cumplimiento normativo y la correcta trazabilidad de la actividad formativa.

2. Arquitectura de la Solución Propuesta

La solución se basará en un script de backend (preferiblemente PHP) que actuará como un "Agente de Sincronización SENCE". Este agente será ejecutado automáticamente a través de una tarea programada (Cron Job) en el servidor.

Flujo Operacional del Agente:

1. Activación Programada: El agente se activará automáticamente todos los días en la ventana horaria definida por SENCE (entre las 22:00 y 00:00 hrs).
2. Identificación de Cursos Activos: El agente consultará la base de datos para identificar todos los cursos activos que deben ser reportados a SENCE.
3. Recopilación y Mapeo de Datos: Por cada curso, el agente iterará sobre la lista de alumnos inscritos y recopilará toda la información requerida, realizando los cálculos necesarios (tiempo de conexión, porcentaje de avance).
4. Construcción del Payload JSON: La información recopilada se ensamblará en una estructura JSON que cumpla estrictamente con el formato exigido por la API de SENCE.
5. Transmisión de Datos: El agente realizará una llamada POST a la API de SENCE, enviando el payload JSON.
6. Registro y Manejo de Respuesta: El agente recibirá la respuesta de SENCE, la interpretará y registrará el resultado (exitoso o con errores) en tablas de log dedicadas en nuestra base de datos para auditoría y depuración.

3. Mapeo Detallado de Datos: De su Base de Datos al JSON de SENCE

Esta es la fase más crítica. A continuación se detalla cómo se obtendrá cada parámetro del JSON de la API a partir de las tablas de su base de datos.

3.1. Estructura Raíz (Nivel Curso)

Para cada curso a reportar, se ensamblará el siguiente objeto raíz.

Parámetro API SENCE	Tabla de Origen	Campo de Origen	Lógica y Observaciones
rutOtec	cursos_sence	rut_otec_sence	Dato estático por curso. Debe ser el RUT de la OTEC.
idSistema	cursos_sence	id_sistema_sence	Valor fijo 1350, según el instructivo.
token	cursos_sence	token_sence	Token de autenticación único de la OTEC, debe ser obtenido desde el portal de SENCE.
codigoOferta	cursos_sence	codigo_oferta_sence	Código de la oferta del curso entregado por SENCE.
codigoGrupo	cursos_sence	codigo_grupo_sence	Código del grupo/sección del curso entregado por SENCE.
codigoEnvio	-	-	Opcional. Se puede generar un ID único para cada envío (ej. CURSOID-YYYYMMDD).
cantActividadSincronica	subtemas_curso	tipo_actividad_sence	SELECT COUNT(*) FROM subtemas_curso WHERE curso_id = [ID_CURSO] AND tipo_actividad_sence = 'sincronica'.
cantActividadAsincronica	subtemas_curso	tipo_actividad_sence	SELECT COUNT(*) FROM subtemas_curso WHERE curso_id = [ID_CURSO] AND tipo_actividad_sence = 'asincronica'.
listaAlumnos	Múltiple	-	Arreglo de objetos Alumno que se construirá a continuación.

3.2. Estructura Anidada (listaAlumnos)

Por cada alumno inscrito en el curso (inscripciones_curso), se creará un objeto Alumno.

Parámetro API SENCE	Tabla de Origen	Campo de Origen	Lógica y Observaciones
rutAlumno / dvAlumno	alumnos	rut	Obtener el RUT completo (ej. '12345678-9'). Separar el número (12345678) y el dígito verificador (9).
tiempoConectividad	accesos_aula_virtual	duracion_segundos	Cálculo crítico: SELECT SUM(duracion_segundos) FROM accesos_aula_virtual WHERE alumno_id = [ID_ALUMNO] AND curso_id = [ID_CURSO] AND DATE(fecha_acceso) = CURDATE(). Suma de todas las sesiones del día actual.
porcentajeAvance	subtemas_curso, subtemas_alumno	-	Cálculo crítico: 1. TotalObligatorias = SELECT COUNT(*) FROM subtemas_curso WHERE curso_id = [ID_CURSO] AND es_obligatorio_sence = 1. 2. Completadas = SELECT COUNT(*) FROM subtemas_alumno WHERE alumno_id = [ID_ALUMNO] AND curso_id = [ID_CURSO] AND modo = 'completado'. 3. (Completadas / TotalObligatorias) * 100.
estado	inscripciones_curso	modo	Mapeo de valores: en_curso → 1, aprobado → 2, reprobado → 3.
fechaInicio / fechaFin	inscripciones_curso	fecha_inicio_clases / fecha_termino	Formatear a YYYY-MM-DD.
fechaEjecucion	-	-	Fecha actual del reporte, generada dinámicamente (date('Y-m-d')).
evaluacionFinal	inscripciones_curso	nota_final	Nota final del curso para el alumno.
listaModulos	Múltiple	-	Arreglo de objetos Módulo que se construirá a continuación.

3.3. Estructura Anidada (listaModulos)

Para cada tema (temas_curso) asociado al curso, se creará un objeto Módulo.

Parámetro API SENCE	Tabla de Origen	Campo de Origen	Lógica y Observaciones
codigoModulo	temas_curso	codigo_modulo_sence	Código del módulo (tema) entregado por SENCE.
tiempoConectividad	video_progreso_alumno	segundos_vistos	Sumar el tiempo de visualización de todos los videos (subtemas) que pertenecen a este módulo (tema). SELECT SUM(vpa.segundos_vistos) FROM video_progreso_alumno vpa JOIN subtemas_curso sc ON vpa.subtema_id = sc.id WHERE vpa.alumno_id = [ID_ALUMNO] AND sc.tema_id = [ID_TEMA].
porcentajeAvance	subtemas_curso, subtemas_alumno	-	Similar al del curso, pero acotado al módulo: ...WHERE tema_id = [ID_TEMA].
estado	temas_curso	-	Lógica a definir. Se puede basar en si todas las actividades del módulo están completadas y la nota promedio.
notaModulo	notas_alumno	nota	Calcular el promedio de las notas de las evaluaciones asociadas a este módulo (tema).
cantActividad...	subtemas_curso	tipo_actividad_sence	Similar al del curso, pero acotado al módulo: ...WHERE tema_id = [ID_TEMA].
listaActividades	subtemas_curso	-	Arreglo de objetos Actividad que se construirá a continuación.

3.4. Estructura Anidada (listaActividades)

Para cada subtema (subtemas_curso) asociado al módulo (tema), se creará un objeto Actividad.

Parámetro API SENCE	Tabla de Origen	Campo de Origen	Lógica y Observaciones
codigoActividad	subtemas_curso	codigo_actividad_sence	Usar este campo. Si no existe, se puede usar titulo, pero debe ser truncado a 50 caracteres.

4. Proceso de Ejecución y Logging

4.1. Tarea Programada (Cron Job)

Se configurará una tarea programada en el servidor para ejecutar el script del agente diariamente.

Ejemplo de configuración de Cron:

0 22 * * * /usr/bin/php /ruta/a/su/proyecto/agente_sence.php

Esta línea ejecutará agente_sence.php todos los días a las 22:00 horas.

4.2. Lógica del Agente (PHP)

El script agente_sence.php contendrá la lógica principal:

1. Conexión a BD: Establecer conexión segura a la base de datos cursosla_cursos.
2. Consulta de Cursos: Obtener los id de los cursos a reportar.
3. Bucle Principal: foreach ($cursos as $curso) { ... }
4. Construcción del JSON: Dentro del bucle, ejecutar las consultas detalladas en la sección 3 para construir el array de datos completo.
5. Envío con cURL:
   • Inicializar cURL.
   • Establecer la URL del endpoint: https://auladigital.sence.cl/gestor/API/avance-sic/enviarAvance.
   • Configurar como POST, Content-Type: application/json.
   • Enviar el JSON (json_encode($datos_curso)).
   • Importante: Configurar un timeout generoso para evitar interrupciones (ej. 600 segundos).
6. Logging:
   • Crear una tabla log_sence_envios (id, fecha_envio, curso_id, id_proceso_sence, estado_envio, request_payload, response_payload).
   • Crear una tabla log_sence_errores (id, id_log_envio, rut_alumno, codigo_modulo, codigo_error, mensaje_error).
   • Al recibir la respuesta, decodificarla (json_decode).
   • Insertar un registro en log_sence_envios.
   • Si la respuesta contiene el array datosError, iterar sobre él y registrar cada error en log_sence_errores, vinculándolo al envío principal.

5. Recomendaciones y Próximos Pasos

• Seguridad: El token_sence es información sensible. Debe ser almacenado de forma segura en la base de datos y la conexión a la API debe realizarse exclusivamente a través de HTTPS.
• Entorno de Pruebas: Antes de apuntar al endpoint de producción, es mandatorio realizar todas las pruebas utilizando los datos y el curso de prueba proporcionados por SENCE en su documentación. La API de SENCE no permite eliminar datos una vez enviados al entorno productivo.
• Gestión de Errores: La implementación de las tablas de log es fundamental. Permitirá diagnosticar rápidamente problemas comunes como un alumno no registrado en SENCE (Error 012), un token inválido (Error 001) o un porcentaje de avance menor al reportado previamente (Error 025).
• Atomicidad: Se recomienda enviar la información de un curso por cada llamada a la API para facilitar la depuración, tal como lo sugiere el instructivo.

---

Este informe constituye la Fase 1: Planteamiento y Estrategia de nuestro flujo de trabajo. Contiene el plan de acción completo y el mapeo de datos necesario para proceder.

Quedo a la espera de su revisión y autorización explícita para comenzar con la Fase 2: Desarrollo y Codificación del agente de software descrito.