Generador de Formatos Académicos — Caso de Estudio

1. Descripción General

Cliente: Director de Secundaria del Deporte, Tlacuaches Marching Band. Para los Eventos escolares que requieren generación masiva de constancias de participación con datos variables (nombre, escuela, director, género) para cientos de alumnos.

Problema: El proceso manual requería abrir una plantilla en Google Docs, modificar campos uno por uno, exportar a PDF, y organizar los archivos resultantes. Para eventos con +100 participantes, esto consumía horas. Además, los errores de tipeo o duplicación eran frecuentes y no existía un registro centralizado de documentos emitidos.

Propuesta técnica: Frontend progresivo en React + MUI (dark theme corporativo) que se comunica con Google Apps Script vía JSONP para esquivar restricciones CORS. El script de Google funciona como backend: recibe datos del formulario, clona una plantilla de Google Docs, reemplaza variables con nombres y fechas reales, exporta a PDF en Google Drive, y envía el PDF por correo electrónico al estudiante. Las configuraciones del evento viven en Google Sheets y se cachean en sessionStorage para minimizar peticiones.

2. Arquitectura del Sistema

Visión General

Arquitectura serverless pura sobre Google Workspace. No hay servidor tradicional, base de datos administrada ni infraestructura cloud más allá del alojamiento estático en GitHub Pages. Todo el cómputo ocurre en el runtime de Google Apps Script, que opera como orchestrator entre los servicios de Google Workspace (Sheets, Docs, Drive, Gmail).

┌─ Cliente (GitHub Pages) ───────────────────────┐
│  React SPA (Vite + MUI)                          │
│  ┌─────────────┐  ┌──────────────┐               │
│  │ StudentForm  │  │ AdminPanel   │               │
│  │ (público)    │  │ (login GAS)  │               │
│  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                       │
└─────────┼─────────────────┼───────────────────────┘
          │ JSONP (cross-origin)
          ▼
┌─ Google Apps Script (https://script.google.com/macros/...) ─┐
│  ┌──────────────────────────────────────────────────────┐    │
│  │  Router (action= getInfo|getTemplate|login|           │    │
│  │           updateInfo|submit)                           │    │
│  └──┬─────────┬──────────┬──────────┬──────────┬─────────┘    │
│     ▼         ▼          ▼          ▼          ▼              │
│  ┌──────┐ ┌──────┐ ┌────────┐ ┌──────────┐ ┌──────────────┐  │
│  │Sheets│ │ Docs │ │ Drive  │ │  Gmail   │ │Session Cache │  │
│  │Event │ │Plant.│ │(PDFs)  │ │(Envío)   │ │(Info Evento) │  │
│  │Config│ │Var.  │ │        │ │          │ │              │  │
│  └──────┘ └──────┘ └────────┘ └──────────┘ └──────────────┘  │
└────────────────────────────────────────────────────────────────┘

Flujo de Generación de Constancia

1. Usuario llena formulario: nombre, escuela, director, sexo, correo (opcional)
2. Frontend → JSONP → action=submit → Google Apps Script
3. Apps Script:
   ├── Recibe parámetros por URL (query string, límite ~8KB)
   ├── Clona plantilla de Google Docs (por ID preconfigurado)
   ├── Reemplaza variables: {{NOMBRE_ALUMNO}}, {{T_ALUMNO}}, {{ESCUELA}},
   │   {{DIRECTOR}}, {{TITULO}}, {{SALUDO}}, {{FECHAEVENTO}}, {{EVENTO}},
   │   {{ORGANIZADOREVENTO}}, {{LUGAREVENTO}}, {{FECHA}}, {{CORREO}}
   ├── Exporta documento → PDF (Drive API)
   └── (Opcional) Envía PDF por Gmail al correo del alumno
4. Respuesta JSONP al frontend: { status: "success", pdfUrl: "..." }
5. Frontend muestra botón de descarga directa desde Google Drive
6. Usuario descarga o recibe correo con el PDF adjunto

Separación de Responsabilidades

3. Tecnologías y Justificación

Frontend

• React 19 + Vite: SPA con HMR para desarrollo rápido, compilación TypeScript integrada, y output optimizado para hosting estático. Vite reemplaza a CRA con tiempos de build ~10x menores.
• Material UI 7: Sistema de diseño completo con dark theme corporativo incluido. Componentes de formulario, diálogos, tabs, Snackbars y selectores listos para producción sin escribir CSS de componentes. El tema oscuro reduce la fatiga visual del personal administrativo que usa el panel por periodos prolongados.
• Sin routing (SPA monocromo): No se usa React Router. El estado de la aplicación — vista pública, panel admin, about — se controla con `useState`. La autenticación admin es vía flag en localStorage (no persistente entre navegadores). Esto mantiene el bundle mínimo en 248 KB — un 15% menos que con React Router.

Backend (Google Apps Script)

• Google Apps Script como backend serverless: Ejecuta JavaScript del lado del servidor en infraestructura de Google, con acceso nativo a los APIs de Sheets, Docs, Drive y Gmail. Costo de operación es $0/mes. El límite de tiempo de ejecución de 6 minutos es suficiente para generar un PDF (~45 segundos promedio por documento).
• JSONP sobre fetch/XHR: Google Apps Script no soporta CORS para dominios externos. El patrón JSONP — inyectar un tag de script solo con un callback global — permite comunicación cross-origin. Aunque JSONP es un patrón considerado obsoleto para APIs públicas, en este contexto controlado — tráfico entre un frontend conocido y un script de Google con un solo usuario administrativo — es el mecanismo más simple y funcional.
• Google Sheets como DB de configuración: En lugar de un servidor de base de datos, las configuraciones del evento (nombre, fecha, lugar, Entidad) se almacenan en una hoja de Sheets con una fila. El administrador puede editar estas celdas directamente con Excel o desde el panel web. No requiere migraciones, esquema de datos, ni backups — Google Sheets maneja el historial de revisiones por defecto.

Generación de PDF

• Google Docs como motor de plantillas: La plantilla se escribe como documento normal de Docs con marcadores de variables en formato {{ VARIABLE }}. Google Apps Script reemplaza los marcadores con los datos del formulario, y Drive API exporta el documento a PDF. Esto permite al administrador — sin conocimientos técnicos — modificar el diseño del documento directamente en Docs.
• Variables sensibles al género: La plantilla usa variables como {{ T_ALUMNO }} (alumno/alumna),{{ TITULO }} (DIRECTOR/DIRECTORA DE), y{{ SALUDO }} (Apreciable director/directora). El script resuelve el valor correcto según el sexo ingresado en el formulario, garantizando gramática correcta sin requerir dos plantillas separadas.

Cache y Rendimiento

• Cache de dos capas: El endpoint getEventInfo cachea los datos del evento en memoria (variable en módulo) y en sessionStorage. Esto reduce las peticiones JSONP de cada carga de página a 1 llamada inicial, y habilita la funcionalidad del formulario incluso si el backend temporalmente retorna slow (cold start de hasta 10s en Google Script). El evento se actualiza en el cliente solo si hay fuerza de refresh explícita.
• Timeout adaptativo: Cada tipo de acción tiene un timeout diferente: getInfo (20s), login (30s), updateInfo y getTemplate (45s), submit (90s). Estos valores se calibraron experimentalmente para los cold starts de Google Apps Script que pueden oscilar entre 3 y 15 segundos.

4. Capturas de Pantalla

El Generador de Constancias Tlacuaches en funcionamiento: formulario público con datos del evento, panel de administración, vista previa dinámica del PDF, y experiencia de carga humorística.

Formulario Público

Login — Panel Admin

Panel Admin — Configuración

5. Problemas Encontrados

6. Decisiones Técnicas Clave

7. Aprendizajes

• Google Apps Script es un backend viable para herramientas internas escolares. Aunque el cold start puede llegar a 15 segundos, el costo $0/mes y la integración nativa con Workspace lo convierten en una opción poderosa donde un VPS tradicional sería sobreinversión. Para una escuela con presupuesto limitado, esta arquitectura elimina la barrera de infraestructura — solo necesitan una cuenta Google (creada en 2 minutos, gratis).
• JSONP + Google Script es un antipattern para sistemas públicos pero aceptable para herramientas de confianza limitada. El tráfico ocurre de GitHub Pages (dominio confiable) a Google Scripts (servicio de Google). No hay tokens de autenticidad vulnerables en tránsito. Si alguien interceptara el flujo, lo peor que obtiene es un PDF del documento generado para un estudiante individual. Las credenciales admin se transmiten como parte de una URL y cada script se asigna solo a la cuenta administrativa del evento.
• El tiempo percibido es más importante que el tiempo real.Los 90 segundos técnicos son largos, pero con mensajes humorísticos que rotan cada 2 segundos, el usuario siente que la solución está trabajando. Es un patrón transferible a cualquier herramienta con procesamiento largo: background jobs, batch processing, sync de datos desde APIs externas. La experiencia de carga no es un speed problem — es un emotion problem.
• Separar género del estudiante del género del director deja. fijar la data que entra. Inicialmente ambos campos estaban fusionados (si el alumno es masculino, el director se asumía masculino). Esto fallaba en casos reales: una directora mujer que firma constancias de un alumno varón. Explicitar ambos géneros en el formulario y tratarlos como variables independientes en el script aplica en todas las generaciones — proyectos con interlocutores múltiples, sistemas de permisos, firmas con roles.
• Cachear información que no cambia es la mitad de la batalla de UX para APIs lentas. Con el cache de getEventInfo evitando 3-5 llamadas JSONP por sesión, la sensación de carga en el formulario pasó de ~9 segundos promedio a ~2 segundos después del primer acceso. El patrón de doble cache (memoria + sessionStorage) es replicable para cualquier API con cold starts impredecibles.
• Un solo formulario no necesita react router. El enrutamiento por estado (useState) fue más que suficiente para las 3 vistas: formulario, loading, success. El bundle size se mantuvo 20% más chico sin React Router, y el SEO es irrelevante porque la app siempre está autenticada después de la carga. No usar router where not needed es un patrón de simplicidad subestimado.

8. Documentación Técnica del Proyecto

Repositorio público con código completo del frontend y el script de Google Apps Script. El README incluye instrucciones de setup, configuración pasando la URL del script, y guía de deploy vía npm run deploy.