Complemento SENCE · Documentación técnica

1. Arquitectura

No hay servicios externos fuera de SENCE (formulario del navegador), el servidor de licencias (activación una vez y version/sence.json diario) y el SMTP opcional. No hay CDN en la interfaz.

2. Flujo con SENCE

1. El bloque arma un formulario POST hacia https://sistemas.sence.cl/rce/Registro/IniciarSesion (o /rcetest/ si la OTEC está en pruebas) con RutOtec, Token, LineaCapacitacion, RunAlumno (normalizado), CodSence, CodigoCurso (ID de acción del grupo), UrlRetoma y UrlError (/blocks/sence/retorno.php) e IdSesionAlumno = token firmado userid.courseid.expira.hmac (24 h).
2. SENCE devuelve al navegador con un POST cross-site a retorno.php, que corre con NO_MOODLE_COOKIES: valida la firma, comprueba que RUN, ID de acción y código SENCE coincidan con lo esperado y que el token no haya iniciado otra sesión, escribe {block_sence} y {block_sence_intento} y redirige con GET al curso (la cookie SameSite=Lax viaja).
3. El cierre llega sin IdSesionSence; se acepta aunque el token haya vencido si su firma es válida y hay una sesión abierta con él.
4. Se mantiene el camino previo a 3.5 (POST directo a la página del curso) para sitios con SameSite=None, con las mismas comprobaciones.

3. Base de datos

Preferencias de usuario (4.0.2, solo estudiantes con franquicia): block_sence_lastactive (última actividad) y block_sence_idlecourse (curso SENCE de esa actividad); se ignoran si son anteriores al inicio de sesión actual ($USER->currentlogin).

Ajustes en config_plugins: codigo_activacion, comprobante_activacion, retornosecret, notices_*, mailtransport, smtp*, update_*. La configuración por curso no viaja en los respaldos de curso.

4. Migración 3.x → 4.0

db/upgrade.php (2026100200) crea las tablas, agrega índices y llama a \block_sence\local\migration::from_3x() (idempotente): OTEC desde el JSON otecs y testenv; por cada instancia del bloque en un curso, su configuración (otec, codigoCurso, lineaCap, grupoBecas, asistenciaObligatoria, senceTiempoCierre, muestraLogo, vnModo); grupos «SENCE-XXXXXXX». asistenciaObligatoria, muestraLogo y la renovación de 3.x se ignoran: se guardan las reglas fijas (required=1, showlogo=1, renewal=daily). db/upgrade.php 2026100401 (4.0.1) alinea las filas ya existentes con un UPDATE sin cambiar el esquema. Se eliminan conectividad_enabled, validanet_url, validanet_apikey, require_activation, otecs, testenv; una OTEC con RUT o token ilegible se respalda en otecs_3x_backup.

4.1 Reglas fijas de SENCE (4.0.1 y 4.0.2)

• Asistencia obligatoria para estudiantes con franquicia (course_config::learner() tipo sence): sin la sesión del día, attendance::content() devuelve lock=true y el AMD locker reemplaza el contenido del curso por el botón y el logo. En el servidor, block_sence_after_require_login() (callback de require_login() con $cm) redirige a /course/view.php con el aviso st_locked (o lanza moodle_exception en AJAX y servicios web): cubre /mod/*/view.php, las demás páginas del módulo y pluginfile.php de sus archivos.
• attendance::locked(): nunca para administradores ni para el equipo del curso (attendance::is_staff(): moodle/course:viewhiddensections o moodle/course:viewhiddenactivities; docente, profesor sin edición, gestor); nunca si el curso no está configurado, no pide la sesión SENCE, está fuera de vigencia o no tiene el bloque; nunca para el grupo de becarios ni (desde 4.0.2) para quien no está en un grupo SENCE: attendance::franchised() exige course_config::learner() de tipo sence; para el grupo SENCE, mientras session_valid() sea falso. La cadena st_notauthorised y el bloqueo de «sin grupo» de 4.0.1 se eliminaron.
• Estudiantes sin grupo SENCE = no franquiciados (4.0.2): tipo none se trata como becario: attendance::learner() devuelve la nota st_becas sin botón ni logo (nada si el curso no tiene grupos SENCE, course_config::has_sence_groups()), reports::without_session(), avisos e informes solo cuentan el tipo sence, el Resumen cuenta solo alumnos con franquicia y muestra el aviso informativo att_nogroup en cursos con grupos SENCE, students.php los muestra como «Sin franquicia» con el filtro type (sence/none) y no revisa su RUN. course_config::problems() ya no marca «sin grupos» como problema: un curso sin grupos SENCE se ve como «Sin grupos SENCE» y el docente recibe la nota note_nogroups. El grupo de becarios queda opcional. Equipo del curso excluido de los informes con la misma regla que is_staff().
• Cierre por inactividad a los 60 minutos (4.0.2, Res. Ex. 4027), solo con attendance::franchised(): inactivity::page() (gancho del pie, también en el recuadro de bloqueo) marca el seguimiento y carga block_sence/inactivity: mouse, teclado, rueda, desplazamiento, toque y puntero en la página y en marcos del mismo origen (reproductor SCORM, rescaneo cada 3 s), informados a ajax.php?action=active cada minuto; a los 55 minutos (warn_at()) consulta action=status (otras pestañas, seguimiento SCORM) y abre un role="alertdialog" con el foco en «Seguir conectado»; a los 60 (limit()) va a inactive.php (sesskey), que comprueba en el servidor y llama a inactivity::close(): registro en block_sence_intento, require_logout() y página de acceso con $SESSION->logininfomsg (idle_closed, en el idioma del estudiante). En el servidor, block_sence_after_require_login() llama a inactivity::on_request() en cada require_login(): si pasaron 60 minutos, cierra antes de atender (página: redirección al acceso; AJAX o servicios web: require_login_session_timeout_exception); si no, las peticiones de página (no AJAX), incluidas mod/scorm/datamodel.php y los archivos del paquete, cuentan como actividad (escritura como máximo cada 30 s). No depende de $CFG->sessiontimeout ni cierra la sesión SENCE (requiere ClaveÚnica): al volver el mismo día la sesión SENCE sigue válida. El tiempo de conexión no suma el tiempo inactivo (el contador ya se detiene a los 5 minutos sin actividad). Solo pruebas automáticas: $CFG->block_sence_idle_test (segundos) en config.php acorta el límite.
• Participantes y Calificaciones no se bloquean: el bloqueo cubre /course/view.php, /course/section.php, /course/resources.php y /mod/… (con o sin $cm).
• Una vez al día — texto del panel: «Una vez al día: el participante con franquicia inicia sesión SENCE cada día que trabaja en el curso, para que la suma de sesiones sea coherente con las horas del curso (Guía SENCE e-learning 2026). El cierre de sesión es opcional.» Fuente: «Guía de uso cursos e-learning, perfil participante» v2.0 (SENCE, 2026) (sesión = «instancia de participación efectiva»; la sumatoria de las sesiones debe ser coherente con las horas acreditadas; al menos una sesión para la Declaración Jurada; cierre opcional, «en caso de existir»). session_valid() compara el día calendario del último inicio con el de hoy en America/Santiago (course_config::TIMEZONE, independiente de la zona del servidor). Con closesession marcado, una sesión cerrada exige un nuevo inicio.
• Logo: attendance::logo() va siempre en el pie del bloque cuando el estudiante con franquicia ve el bloque (no para becarios ni estudiantes sin grupo SENCE).
• Los formularios de «Cursos y grupos» y «Bloque en cursos» muestran estas reglas con ui::fixed() (no editables); course_config::save() ignora esos campos y validate() ya no los revisa.

4.2 Auditoría de ajustes frente a SENCE (4.0.1, actualizada en 4.0.2)

Regla: el complemento viene preconfigurado con lo que SENCE exige y no ofrece opciones que SENCE pueda rechazar.

4.3 Filtro por OTEC (4.0.4)

• Solo con reports::multi_otec() (dos o más filas en block_sence_otec): parámetro otec validado por reports::otec_param() y agregado a reports::filters() como otecid; campo ui::otec_field() (select con <label for>) en ui::record_filters(), students.php e index.php.
• Pertenencia (reports::otec_map()): curso → course_config::otec_of($cfg); grupo SENCE (no becarios, con ID de acción y otecid propio) → course_config::otec_of($cfg, $g->otecid), guardado solo si difiere de la del curso. Registro (block_sence, block_sence_intento) → reports::otec_of_record($map, courseid, codigocurso): el ID de acción enviado a SENCE (CodigoCurso) identifica el grupo; si no coincide con un grupo de otra OTEC, la del curso. Estudiante → reports::learners() agrega otecid (grupo SENCE con OTEC propia, si no la del curso). Tiempo de conexión (sin ID de acción) → reports::otec_of_learner(). 0 = «Sin OTEC».
• SQL: reports::otec_sql($prefix, $f, $params) = (courseid IN cursos de la OTEC AND NOT (pares curso/ID de acción de otra OTEC)) OR (pares curso/ID de acción de la OTEC), con COALESCE(codigocurso, ''); usado por sessions(), attempts(), errors() y summary($now, $otecid). Los cursos y alumnos del Resumen y de Alumnos y RUN se filtran con otec_courses() y el otecid del estudiante.
• Columna «OTEC» (ui::otec_cell(): razón social + RUT) en records.php y students.php; exporter::data() agrega «OTEC» y «RUT OTEC» en sesiones, intentos y alumnos y devuelve la OTEC de cada fila; exporter::by_otec() arma una hoja por OTEC (+ «Sin OTEC» si hay filas) ignorando el filtro OTEC, con exporter::sheet_name() (31 caracteres, sin : \ / ? * [ ], nombres únicos). export.php?byotec=1 para exporter::BYOTEC_TYPES; mismo control de licencia que la exportación normal (exporter::allowed()). Los informes por correo siguen filtrando por OTEC a nivel de curso (mailreports::filters()).

5. Acceso, permisos y licencia

• Página Licencia (4.0.2): license::plan_box() muestra «Qué incluye la versión gratuita» solo sin plan de pago vigente (también cuando la anual vence y termina la gracia) y, con licencia, «Tu licencia incluye todas las funciones» con el vencimiento (anual) o «actualizaciones para siempre» (perpetua); license::show_buy() oculta «Comprar licencia» con licencia vigente (la anual lo muestra para renovar en sus últimos 30 días o en la gracia).
• Gratis: solo is_siteadmin(). Las filas de block_sence_puser se conservan pero se ignoran.
• Con licencia: secciones credentials (nuevo: sin acceso), courses, block, records (nuevo: solo lectura) y notices (nuevo: sin acceso). Cada página llama a panel::require_section() y cada acción vuelve a exigir «edit» en la clase. Usuarios, bitácora, licencia y cuenta SMTP: solo administrador.
• Producto sence, mayor de licencia 3: los códigos de 3.x siguen valiendo (perpetuos). Funciones de pago: varias OTEC, exportaciones (salvo la de asistencia), avisos, usuarios, bitácora. Desde 4.0.1 exporter::FREE_TYPES = ['sessions']: la exportación de la asistencia enviada es gratuita; export.php exige licencia solo si exporter::allowed() es falso y ui::export_button() muestra el candado en las demás.
• Licencia anual: aviso en el panel desde 30 días antes (NOTICE_DAYS) y correo a get_admins() (usuario noreply, SMTP de Moodle) 30, 15, 3 y 1 día antes (REMINDER_DAYS), evaluado por la tarea diaria check_updates: una vez por hito y por fecha de vencimiento (nlic_reminded_<exp>_<n> en la configuración del bloque), solo el hito más cercano si se saltaron, y de nuevo al renovar con otra exp. 15 días de gracia (GRACE_DAYS) y luego versión gratuita sin borrar datos.

6. Tareas, ganchos y eventos

• \block_sence\task\send_notices (cada hora; actúa una vez al día a la hora elegida), \block_sence\task\send_reports (cada hora; mailreports::run() envía cada informe una vez por período: due_period() da Daaaammdd, Waaaa-ss o Maaaamm en hora de Chile y se guarda en mreports_lastperiod antes de enviar) y \block_sence\task\check_updates (diaria).
• Correo: transport::send($to, $subject, $html, $attachments) (correo de Moodle con email_to_user() o SMTP propio con moodle_phpmailer; adjuntos ruta ⇒ nombre). Página mail.php (solo administrador): transporte, contraseña oculta y «Probar conexión» (registro kind=smtptest en block_sence_mail). Informes: mailreports.php, ajustes mreports_*, historial kind=report|reporttest; adjunto exporter::to_file('sessions', …) (PhpSpreadsheet a un archivo temporal que se borra tras enviar).
• Gancho before_footer_html_generation: además del contador, attendance::clock() carga block_sence/sessionclock para quien tiene franquicia y la sesión del día (tiempo restante hasta la medianoche de Chile o el fin de la vigencia, alerta a los 10 minutos).
• Tablas: block_sence/tables (30 filas por página, «Anterior»/«Siguiente», búsqueda y orden sobre todas las filas, casillas ordenables; las filas de otras páginas quedan ocultas en el DOM, así las casillas se envían con el formulario). Componente pensado para copiarse a los demás complementos (data-perpage, data-prev, data-next, data-pageof, data-results, data-pagerlabel en el contenedor).
• Gancho primary_extend: entrada «SENCE» en el menú principal solo para quien puede usar el panel. Gancho before_footer_html_generation: carga block_sence/heartbeat en páginas de cursos SENCE vigentes para alumnos matriculados; ajax.php nunca acredita más segundos que los transcurridos.
• Evento \block_sence\event\settings_changed en cada cambio de configuración.

7. Privacidad

classes/privacy/provider.php declara y exporta/borra sesiones, intentos, tiempo de conexión y avisos (contexto de curso) y usuarios del panel, bitácora y avisos recibidos (contexto de sistema). Declara también la transferencia a SENCE y al SMTP y, desde 4.0.2, las preferencias de usuario del cierre por inactividad (user_preference_provider).

8. Pruebas y simulador

• PHPUnit: vendor/bin/phpunit --testsuite block_sence_testsuite (pruebas en Moodle 4.5 y 5.0, incluidas las de las reglas fijas: bloqueo y desbloqueo del grupo SENCE, becarios nunca, logo siempre, sesión válida el mismo día y nueva el día siguiente; desde 4.0.2, estudiantes sin grupo y cursos sin grupos SENCE sin bloqueo, cierre por inactividad solo para franquiciados y caja de licencia según el plan; desde 4.0.4, filtro y descarga por OTEC: reports_test::test_otec_filter). Pruebas de extremo a extremo: dev/e2e_sence401.py (Playwright; --solo402 para lo de 4.0.2, con el reloj de inactividad acelerado a 60 segundos solo durante esa parte).
• Simulador local de SENCE (solo desarrollo, fuera del ZIP): dev/mock_sence.php. En el config.php del Moodle de pruebas: $CFG->block_sence_rce_urls = ['start' => '…/dev/mock_sence.php?op=start', 'close' => '…?op=close'];. Permite aceptar o rechazar (208, 212, 100;210) sin llamar a SENCE con datos de personas.
• Conjunto ficticio para un aula demo: php blocks/sence/dev/seed_demo.php --otecrut=<RUT de la OTEC de pruebas> (crea la categoría «Pruebas SENCE», 4 cursos más uno abierto sin grupos SENCE, 36 alumnos más 2 sin grupo y 1 comprador del curso abierto, con RUN inventados desde 30.100.001, 2 docentes y 30 días de historial; no lee el token) y --reset (borra solo lo que creó: su categoría, sus usuarios marcados con departamento SEED-SENCE y sus filas). Pruebas de extremo a extremo con Playwright sobre el simulador.
• Datos 3.x ficticios para probar la actualización: dev/seed_3x.php. Cadenas: dev/strings.py genera lang/es y lang/en ordenadas.