University management SaaS
UNERMB · Sistema de Gestión de Prácticas y Pasantías Dashboard web para la Coordinación de Prácticas y Pasantías Profesionales de la Universidad Nacional Experimental Rafael María Baralt (UNERMB). Centraliza la verificación de elegibilidad del estudiante, la asignación y reasignación de empresas, el seguimiento de cada práctica y la generación de reportes oficiales en CSV y PDF. Módulo Descripción Resumen general KPIs, gráficos (Recharts) y actividad reciente Estudiantes Listado paginado, filtros, ficha con requisitos y materias aprobadas, alta/edición Carreras Catálogo académico con alta de carreras y creación de unidades curriculares provisionales Empresas Cartera con cupos ocupados/disponibles, localidad oficial y convenios Asignaciones Flujo guiado de 3 pasos, validación de cupos y reasignación Seguimiento Tabla de prácticas, detalle con trazabilidad y cambio de estado Reportes Vista previa institucional y descarga CSV (BOM UTF-8) / PDF (PDFKit) Configuración institucional Logo, RIF, localidad y período leídos desde app_settings El diseño visual y los prototipos provienen del proyecto Stitch UNERMB · Gestión de Pasantías; los HTML y capturas de referencia están en docs/design/. Reglas de negocio Un estudiante es elegible solo si cumple todas las condiciones: Requisito Regla Materias aprobadas Al menos el 50 % de las unidades curriculares de su carrera Promedio general ≥ 12 puntos (escala 0–20) Servicio comunitario Fase I y Fase II aprobadas Exoneración Aprobada si proviene de otra universidad; no aplica a estudiantes UNERMB Ubicación y modalidad Residencia en la localidad oficial (Cabimas, configurable) y modalidad presencial Además: Una empresa solo puede recibir pasantes si está activa y ubicada en la localidad oficial. Los cupos consumen al pasar a pendiente, asignado o en_curso; al rechazar o finalizar se liberan. Un estudiante solo puede tener una práctica activa a la vez. Las transiciones de estado válidas son pendiente → asignado → en_curso → finalizado, con rechazado disponible desde cualquier estado activo. El tutor académico solo puede iniciar (en_curso) y finalizar prácticas que tutora. La lógica canónica vive en PostgreSQL (vista v_student_eligibility, funciones fn_assign_student, fn_reassign_student, fn_change_placement_status), y la API la refuerza con Zod y validaciones de rol. Ver docs/architecture.md. Stack Frontend: React 18 + TypeScript + Vite, React Router, TanStack Query, React Hook Form + Zod, Recharts, Lucide, date-fns, CSS con design tokens (claro/oscuro). Backend: Node.js 20+ + Express 5 + TypeScript, Supabase JS (service role), Zod, Pino, PDFKit, tsup para compilar. Datos: Supabase Cloud (PostgreSQL 15+, Auth, RLS) con migraciones SQL versionadas. Compartido: packages/shared con tipos, constantes, formateadores y esquemas Zod usados por API y frontend.
UNERMB · Sistema de Gestión de Prácticas y Pasantías Dashboard web para la Coordinación de Prácticas y Pasantías Profesionales de la Universidad Nacional Experimental Rafael María Baralt (UNERMB). Centraliza la verificación de elegibilidad del estudiante, la asignación y reasignación de empresas, el seguimiento de cada práctica y la generación de reportes oficiales en CSV y PDF.
Módulo Descripción Resumen general KPIs, gráficos (Recharts) y actividad reciente Estudiantes Listado paginado, filtros, ficha con requisitos y materias aprobadas, alta/edición Carreras Catálogo académico con alta de carreras y creación de unidades curriculares provisionales Empresas Cartera con cupos ocupados/disponibles, localidad oficial y convenios Asignaciones Flujo guiado de 3 pasos, validación de cupos y reasignación Seguimiento Tabla de prácticas, detalle con trazabilidad y cambio de estado Reportes Vista previa institucional y descarga CSV (BOM UTF-8) / PDF (PDFKit) Configuración institucional Logo, RIF, localidad y período leídos desde app_settings El diseño visual y los prototipos provienen del proyecto Stitch UNERMB · Gestión de Pasantías; los HTML y capturas de referencia están en docs/design/.
Reglas de negocio Un estudiante es elegible solo si cumple todas las condiciones:
Requisito Regla Materias aprobadas Al menos el 50 % de las unidades curriculares de su carrera Promedio general ≥ 12 puntos (escala 0–20) Servicio comunitario Fase I y Fase II aprobadas Exoneración Aprobada si proviene de otra universidad; no aplica a estudiantes UNERMB Ubicación y modalidad Residencia en la localidad oficial (Cabimas, configurable) y modalidad presencial Además:
Una empresa solo puede recibir pasantes si está activa y ubicada en la localidad oficial. Los cupos consumen al pasar a pendiente, asignado o en_curso; al rechazar o finalizar se liberan. Un estudiante solo puede tener una práctica activa a la vez. Las transiciones de estado válidas son pendiente → asignado → en_curso → finalizado, con rechazado disponible desde cualquier estado activo. El tutor académico solo puede iniciar (en_curso) y finalizar prácticas que tutora. La lógica canónica vive en PostgreSQL (vista v_student_eligibility, funciones fn_assign_student, fn_reassign_student, fn_change_placement_status), y la API la refuerza con Zod y validaciones de rol. Ver docs/architecture.md.
Stack Frontend: React 18 + TypeScript + Vite, React Router, TanStack Query, React Hook Form + Zod, Recharts, Lucide, date-fns, CSS con design tokens (claro/oscuro). Backend: Node.js 20+ + Express 5 + TypeScript, Supabase JS (service role), Zod, Pino, PDFKit, tsup para compilar. Datos: Supabase Cloud (PostgreSQL 15+, Auth, RLS) con migraciones SQL versionadas. Compartido: packages/shared con tipos, constantes, formateadores y esquemas Zod usados por API y frontend. Estructura del repositorio . ├── apps │ ├── api # API REST (Express + TypeScript) │ │ └── src │ │ ├── lib # utilidades, mappers, PDF, Supabase, settings │ │ ├── middleware # autenticación, roles, errores │ │ ├── routes # endpoints por módulo │ │ └── services # acceso a Supabase y reglas de negocio │ └── web # SPA (React + Vite) │ ├── public/branding # logo institucional (placeholder) │ └── src │ ├── components # UI, layout, placements │ ├── context # auth, tema, toasts │ ├── hooks # queries y mutaciones (TanStack Query) │ ├── lib # cliente API, Supabase, fechas, query client │ ├── pages # login, dashboard, estudiantes, empresas, asignaciones, seguimiento, reportes │ └── styles # tokens, estilos globales y de componentes ├── docs │ ├── architecture.md # arquitectura, modelo de datos y reglas │ ├── api.md # referencia de endpoints y contratos │ ├── deployment.md # puesta en marcha y despliegue │ └── design/ # DESIGN.md, HTML y capturas de Stitch ├── packages/shared # tipos, constantes, formateadores y esquemas Zod ├── scripts │ ├── create-demo-users.ts │ └── verify-seed.sql ├── supabase │ ├── migrations # esquema · funciones/RLS · alta de carreras │ └── seed.sql # datos ficticios realistas del período I-2026 └── .env.example # plantilla única de configuración Requisitos Node.js 20 o superior y npm 10+. Un proyecto de Supabase Cloud (plan gratuito suficiente para la demo). Opcional: npx supabase si prefieres aplicar migraciones por CLI. Instalación rápida
Copy-Item .env.example .env cp .env.example .env Edita .env con:
Variable Uso SUPABASE_URL URL del proyecto (Settings → API) SUPABASE_ANON_KEY Clave pública; la usa el frontend SUPABASE_SERVICE_ROLE_KEY Clave secreta; solo API y scripts PORT Puerto de la API (por defecto 4000) CORS_ORIGIN Origen(es) permitidos, separados por coma UNERMB_LOCALITY Localidad oficial por defecto (la de app_settings manda) VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY Mismas credenciales para el navegador VITE_API_URL /api en desarrollo (proxy de Vite); URL pública en producción VITE_SHOW_DEMO_CREDENTIALS true/false para mostrar las cuentas demo DEMO_PASSWORD Contraseña de las cuentas demo (por defecto Unermb2026*) La API y Vite leen el mismo .env de la raíz (envDir configurado en apps/web/vite.config.ts y carga explícita en apps/api/src/env.ts).
supabase/migrations/20261105000100_schema.sql supabase/migrations/20261105000200_functions_rls.sql supabase/migrations/20261105000300_career_catalog.sql — alta atómica de carreras y materias provisionales supabase/seed.sql — datos ficticios de demostración También puedes usar Supabase CLI si ya inicializaste y configuraste el proyecto CLI (incluyendo supabase/config.toml) en este repositorio:
npx supabase link --project-ref TU_PROJECT_REF npx supabase db push
psql "$DATABASE_URL" -f supabase/seed.sql 4. Crear usuarios demo npm run seed:users Crea (o actualiza) las cuentas en Supabase Auth y sus perfiles con rol. El usuario tutor queda vinculado al registro lmendez@unermb.edu.ve del seed.
Correo Rol Contraseña admin@unermb.edu.ve Administrador Unermb2026* coordinador@unermb.edu.ve Coordinador de pasantías Unermb2026* tutor@unermb.edu.ve Tutor académico Unermb2026* 5. Arrancar en desarrollo npm run dev Frontend: http://localhost:5173 API: http://localhost:4000/api (salud en /api/health) Scripts disponibles Comando Acción npm run dev API y frontend en paralelo npm run dev:api / npm run dev:web Ejecutar solo un servicio npm run build Compila API (tsup) y frontend (vite build) npm run typecheck Verifica tipos en shared, API y web npm test Pruebas unitarias (Vitest) npm run seed:users Crea/actualiza usuarios demo npm run format Formatea con Prettier Verificación de datos Después de aplicar el seed puedes ejecutar scripts/verify-seed.sql en el SQL Editor. Incluye consultas que comprueban:
Conteo de estudiantes elegibles/no elegibles y prácticas activas. KPIs y gráficos del dashboard (fn_dashboard_kpis, fn_dashboard_charts). Que no haya sobrecupos ni estudiantes con más de una práctica activa. Que no existan asignaciones activas fuera de la localidad oficial. Que todas las asignaciones activas correspondan a estudiantes elegibles. Que cada estudiante tenga registradas las dos fases del servicio comunitario. Historial de eventos por asignación. Los datos demo esperados son 48 estudiantes (29 elegibles y 19 no elegibles, cubriendo todos los motivos de rechazo), 14 empresas y 19 asignaciones (15 activas y 4 finalizadas) con 23 cupos libres en Cabimas.
Reportes oficiales POST /api/careers permite que administradores y coordinadores registren carreras y genera unidades curriculares provisionales numeradas a partir del total indicado. Reemplaza esos nombres por las unidades del plan curricular oficial cuando estén disponibles. El endpoint de lectura GET /api/careers está disponible para usuarios autenticados.
Los endpoints /api/reports/students.csv|pdf y /api/reports/placements.csv|pdf (administrador y coordinador) aceptan careerId, status, eligibility y period. period personaliza el período mostrado en el PDF; no filtra las filas por período. El PDF incluye encabezado institucional (logo, nombre, RIF, localidad, período, fecha de emisión), filtros aplicados, tabla paginada, firma y numeración; el CSV se exporta con BOM UTF-8 para Excel. La descarga se hace por fetch autenticado (JWT de Supabase) y se guarda con nombre reporte-*.AAAA-MM-DD.csv|pdf.
Seguridad La API usa la service role key solo en el servidor y nunca la expone al navegador. Express valida el JWT de Supabase, exige perfil activo y aplica roles: las mutaciones y los reportes son exclusivos de administrador/coordinador; el tutor solo ve y actualiza sus prácticas. RLS queda habilitado en todas las tablas con políticas de lectura por rol y escritura para staff como defensa en profundidad. El frontend guarda la sesión con Supabase Auth; el token viaja en Authorization: Bearer y los reportes se descargan como blob autenticado. Revisa docs/deployment.md antes de publicar (CORS, secretos, backups). Solución de problemas Síntoma Causa probable Solución “Falta configurar Supabase” en el login .env ausente o sin VITE_* Copia .env.example a .env, completa claves y reinicia npm run dev La API no arranca y reporta variables inválidas SUPABASE_URL o SUPABASE_SERVICE_ROLE_KEY vacías Revisa el .env de la raíz 401 en todas las llamadas Sesión expirada o perfil inactivo Vuelve a iniciar sesión; verifica profiles.active 403 profile_missing Usuario sin fila en profiles Ejecuta npm run seed:users o crea el perfil “El estudiante no cumple los requisitos de elegibilidad” Datos académicos incompletos Completa materias, promedio, fases y exoneración en la ficha “La empresa no tiene cupos disponibles” Cupos consumidos por prácticas activas Amplía total_slots o reasigna a otra empresa El PDF/CSV no descarga VITE_API_URL incorrecto o CORS Ajusta la URL pública y CORS_ORIGIN Documentación docs/architecture.md — capas, modelo de datos, reglas y API. docs/api.md — referencia de endpoints con ejemplos. docs/deployment.md — Supabase, Vercel Services, API y frontend en producción. docs/design/DESIGN.md — sistema de diseño institucional. Datos y cuentas ficticios con fines académicos y de demostración.