Módulo de Eventos — Documentación técnica

El corazón del módulo es src/lib/components/event/EventFormShell.svelte (2.908 líneas): un Formulario Dinámico de Eventos (FE / EventFormShell) de 4 pasos, montado por dos wrappers idénticos que solo cambian el context:

• Público (sin login): /registro-evento → context="public" registro-evento/+page.svelte:55
• Dashboard (con login): /dashboard/registro-evento → context="dashboard"; hace POST absoluto a /registro-evento?/submit dashboard/registro-evento/+page.svelte:31

Los server actions (submit y save) viven únicamente en src/routes/registro-evento/+page.server.ts y usan un cliente service-role (SUPABASE_ROLE_KEY) que bypasea RLS para el insert +page.server.ts:19. Esto importa para el scraping: la lectura pública está restringida por RLS a status='APPROVED', así que cualquier ingesta masiva debe ir con service-role.

Paso 1 · Información de contacto

Con sesión activa el email queda readonly con badge "Sesión activa". Con perfil verificado (público, contraseña OK), Nombres/Apellidos/Teléfono se autollenan y bloquean (lockedProfile).

Paso 2 · Datos clave del evento

Subpanel de ubicación (solo si presencial/híbrido/dual):

Paso 3 · Temática del evento

Paso 4 · Registro y detalles

Modalidad → eventos.modalidad

CHECK en DB: modalidad IN ('presencial','online','hibrido','dual').

Costo de inscripción → eventos.costo_inscripcion

Temáticas → eventos.tematicas (JSONB [{categoria, subcategoria, principal?}])

Se almacena el id de categoría y subcategoría. Categorías no sectoriales y sus subcategorías (eventThemes.ts):

Actividades → eventos.actividades (JSONB [{categoria, subcategoria}])

Perfil de speaker → hosts_speakers[].perfil

Speaker · Keynote Speaker / Orador central · Moderador · Panelista · Host. Centinelas (modo no-registrar): "No Aplica", "Por confirmar".

Zona horaria → eventos.zona_horaria (IANA)

Lista IANA (Bogotá, Lima, Guayaquil, Caracas, La Paz, Santiago, Buenos Aires, São Paulo, Montevideo, Asunción, México, Madrid…). Default America/Bogota. Reales top: America/Bogota 750, America/Mexico_City 80, America/Argentina/Buenos_Aires 39, America/Guayaquil 35.

País → eventos.pais_code

• needsLocation = presencial | hibrido | dual. Controla todo el subpanel de ubicación (país/ciudad/provincia/dirección) y la posición del selector de zona horaria. Si online: se oculta ubicación y país/ciudad/provincia no se exigen.
• provincia se exige solo si la ciudad tiene valor ({#if eventoCiudad.trim()}).
• showSessionLink = modalidad !== 'presencial': el "Link al evento" (linkSesion) aparece para online/híbrido/dual.
• useSameDate: si se marca, oculta la fecha de fin y usa la de inicio.
• Discrepancia de país (LAP-407): si el país del venue (Google Places) ≠ país seleccionado → error bloqueante (countryMismatch, val 223). La discrepancia de zona horaria es aviso no bloqueante con botón "Usar la sugerida".
• Organizador con entidad: al elegir una entidad registrada del typeahead, el rol se autollena y el select se bloquea. Si es del directorio (no registrada), el rol se rellena pero queda editable.
• Speakers: 3 modos excluyentes (registrar / confirmar / no-aplica). "no-aplica" guarda {nombres:'No Aplica'}; "confirmar" guarda {nombres:'Por confirmar'}; la validación de "completo" trata esos centinelas como vacío.
• URLs: linkRegistro y linkSesion validan /^https?:\/\/\S+\.\S+/; linkEvento no puede ser igual a linkRegistro.

• Fechas: entrada display dd-mmm-aaaa (ej. 15-jun-2026) parseada a ISO yyyy-mm-dd. Se almacenan fecha_inicio y fecha_finalizacion como DATE (CHECK fecha_finalizacion >= fecha_inicio).
• Horarios: horarios JSONB, una fila por día del rango: [{fecha:"yyyy-mm-dd", hora_inicio:"HH:MM", hora_fin:"HH:MM"}]. Duración default por modalidad: presencial/híbrido/dual 120 min, online 60 min. Máx 30 días (se trunca).
• Zona horaria: zona_horaria TEXT, default America/Bogota. Existe además zona_horaria_remota para el público remoto en híbrido, pero el form no la captura → siempre NULL.
• Distinción por modalidad (radio modalidad): online → sin ubicación, zona horaria arriba, con link de sesión. presencial → con ubicación, sin link de sesión. híbrido/dual → con ubicación y link de sesión.

LocationAutocomplete.svelte usa @googlemaps/js-api-loader (client-side, PUBLIC_GOOGLE_PLACES_API_KEY): monta google.maps.places.Autocomplete + mapa embebido con marker. El autocomplete se restringe al país seleccionado usando el ISO-2 resuelto por GET /api/country-iso2?country= (ese endpoint sí lee catalogo_pais). Al elegir un lugar autocompleta país, provincia, ciudad, dirección (ubicacion_texto) y aplica la zona horaria por país.

Tabla super_eventos con columnas id, nombre, mnemotecnia (3-5 chars), pais_code (nombre), anio_inicio, anio_finalizacion, link_url, codigo_unico (serial), fecha_inicio, fecha_finalizacion. Ejemplo real: "Colombia Tech Week 2026", mnemotecnia CTW. La FK es eventos.super_evento_id → super_eventos(id).

La asignación en el form es un SuperEventoPicker (select simple, opcional); el form no permite crear supereventos (redirige a comunidad@lpdi.co). Si un evento se asocia, su evento_codigo recibe el sufijo -MNEMOTECNIA-AA (ej. …-CTW-26).

Componente OrganizerRows.svelte. Cada fila es {nombre, rol, entityType?, entityId?}:

• Con entidad registrada: el typeahead GET /api/entidades/search devuelve entidades Startup/PyME/Scaleup/ICG. Al elegirla se fija entityId+entityType y el rol se autollena y bloquea.
• Sin entidad (raw): texto libre o sugerencia del directorio (badge "Entidad no registrada") → rol editable/obligatorio. Sin match, aparece una caja "Invitar" que llama POST /api/eventos/invitar-organizador.
• Almacenamiento: se guarda en eventos.organizadores_raw (JSONB) tras sanitizar a la whitelist {nombre, rol, entityType, entityId} (descarta filas sin nombre). Ejemplo real: [{"rol":"Startup","nombre":"La Punta del Iceberg","entityId":"…","entityType":"STARTUP"},{"rol":"Limited Partner","nombre":"Frank Prieto"}].
• Dual-write al directorio: tras el insert, syncOrganizadoresFromEvento crea/vincula filas en directorio_organizadores + evento_organizadores (best-effort, nunca bloquea el insert).

1) evento_codigo (TEXT) — la cadena legible

Patrón M-PP-TTT-AA-NNNNN, generado server-side en el submit final:

Sufijo opcional -MNEMOTECNIA-AA si hay superevento. Ejemplo real verificado: H-CO-008-26-00025 (Híbrido, Colombia, temática contexto-económico, 2026, consecutivo 25).

2) codigo_unico (entero) — correlativo interno

Un entero (ej. 245), no la cadena. Se asigna solo en el submit final (nunca en drafts) vía la RPC idempotente assign_evento_codigo_unico (hace nextval solo si es NULL). Los DRAFT quedan con codigo_unico = NULL. Ambos códigos se generan 100% en el servidor; unicidad garantizada por índice único parcial (evento_codigo) y UNIQUE (codigo_unico).

Envío: POST /registro-evento?/submit (SvelteKit form action, header x-sveltekit-action: true). Borrador/autosave: POST /registro-evento?/save (guarda DRAFT sin código). El payload es FormData con estos campos:

Índices: PK id; UNIQUE codigo_unico; único parcial uq_eventos_evento_codigo; btree en fecha_finalizacion, fecha_inicio, modalidad, status, pais_code, registered_by y parciales en deleted_at, es_prueba, publish_at; GIN en tematicas, actividades y trigram en nombre. RLS: lectura pública solo status='APPROVED' o registered_by = auth.uid().

Tablas relacionadas: super_eventos, directorio_organizadores, evento_organizadores (N:M, PK (evento_id, organizador_id)), evento_favoritos (PK (user_id, evento_id)), event_editor_privileges (vacía hoy), event_autopublish_privileges (email citext PK, vacía hoy).

• evento_codigo y codigo_unico — compuestos/asignados en el server (§10), solo en el submit final.
• status — 'APPROVED' si el correo tiene privilegio de autopublish (RPC is_event_autopublish), si no 'PENDING'. El borrador es 'DRAFT'.
• approved_at / approved_by — solo si autopublish.
• empresa_registro — resuelto del perfil existente, no del form.
• registered_by — usuario resuelto de la sesión o del email (§14).
• created_at / updated_at — timestamp + trigger.
• ubicacion_solo_registrados / link_acceso_solo_registrados — forzados a false si la entrada es libre; hoy siempre false.
• nombre — fallback "[BORRADOR] Evento de …" si viene vacío.
• Efectos post-insert (best-effort, no bloquean): dual-write al directorio, invitación a speakers no registrados, y correos (publicacion_exitosa / registro_exitoso + nuevo_por_aprobar / actualizado / cambios_por_aprobar).

Resolución de usuario en el submit: (1) si hay sesión → safeGetSession(); (2) si no, busca el perfil por contact_email en profiles (y valida la contraseña con signInWithPassword si es público); (3) si no existe (público) → crea la cuenta con createEcosystemUser (Opción B, con ciclo de confirmación). Ese usuario queda como registered_by.

Perfil: se crea si falta; si existe, solo se completa (fill-only, nunca sobreescribe). Entidades (Startup/PyME/ICG): se enlazan a nivel organizador, no a nivel evento — el vínculo va en organizadores_raw[].entityId/entityType y el dual-write puebla directorio_organizadores + evento_organizadores. No hay FK directa evento→entidad; empresa_registro es solo el texto de la empresa del perfil del registrante.

Endpoints de apoyo: POST /api/check-email, POST /api/auth/verify-event-user, GET /api/entidades/search, GET /api/country-iso2, POST /api/eventos/invitar-organizador, /api/eventos/speaker-lookup.

Gate: RPC is_event_admin(uid); si no es admin → 403. El server trae todos los eventos (incluida la papelera), paginando de a 1000 por el tope de PostgREST. Se muestran todos los campos del form + trazabilidad (creado/aprobado/editado/eliminado por + fechas).

Pestañas

Acciones por fila (según estado y rol)

14 filtros acumulativos (modalidad, temática, país, ciudad, rango de fechas, superevento, actividad, costo, organizado/creado/aprobado/editado/eliminado por). Descargar CSV solo para super_admin. Toda la lógica de transición/validación/correos vive en PATCH /api/admin/eventos/[id]; el panel es solo UI.

• admin_roles (rol GLOBAL): vocabulario vigente super_admin, curador. Los legacy moderador/revisor/editor fueron purgados (mig 077). Prod: 1 fila (super_admin).
• module_permissions (rol POR MÓDULO, ej. eventos): admin, curador, editor_confianza, duplicador, publicador, organizadores. Prod eventos: 1 fila = admin.

Las funciones-gate vigentes (migración 080, que sobrescribe 073/077): is_super_admin, is_module_admin, has_module_permission, is_event_admin (= ver panel), has_event_role(['curador']) (= acciones de estado), can_duplicate, can_manage_organizadores.

Estados derivados (no columnas de status): Publicado = APPROVED && (publish_at null o vencida); Programado = APPROVED con publish_at futura (el catálogo lo oculta hasta esa fecha); Finalizado = (APPROVED|INACTIVO) && fecha fin < hoy (solo lectura); Papelera = deleted_at ≠ null (+ delete_scheduled_for = +30d).

Quién aprueba: las acciones de estado exigen has_event_role(['curador']) = super_admin o admin/curador del módulo eventos.

Qué se edita antes de aprobar: la acción editar tiene una whitelist de campos (todos los del form: contacto, nombre, modalidad, fechas, ubicación, temáticas, actividades, speakers, organizadores, links, costo). Están excluidos a propósito status, approved_*, rejected_*, deleted_*. Un evento finalizado es solo lectura salvo super_admin.

Autopublish / auto-aprobación (dos mecanismos, ambos vacíos en prod): event_autopublish_privileges = correos cuyo evento se publica sin curaduría; event_editor_privileges (editor de confianza) = al editar un APPROVED, como editar no toca status, el evento queda aprobado sin re-curaduría. Feedback asimétrico: al rechazar el comentario es opcional; al solicitar cambios es obligatorio (≥10 caracteres).

Tablas (no existe una tabla organizadores a secas): directorio_organizadores (una fila viva por nombre normalizado; estados PENDIENTE_COMPLETAR / COMPLETO), evento_organizadores (puente, 2.513 vínculos) y eventos.organizadores_raw (lo que digita el form, fuente de las páginas públicas). Ruta: /dashboard/eventos/organizadores, gate can_manage_organizadores.

• Crear — (1) manual vía POST /api/admin/organizadores: si es entidad registrada, el server re-lee su perfil y deriva nombre/rol/países (ignora esos campos del cliente); si no, exige rol estructurado + url_consulta. (2) Dual-write automático desde el submit/edición de un evento (syncOrganizadoresFromEvento): normaliza por lower(trim(nombre)), inserta como PENDIENTE_COMPLETAR, crea el vínculo con ON CONFLICT DO NOTHING. Idempotente.
• Actualizar — PATCH …/[id] con dos modos: datos (URL, regiones, y para no-registrados rol + correo; en registrados el nombre y rol vienen de la entidad y están bloqueados) y evaluacion (5 criterios manuales + 1 automático = calidad ponderada).
• Fusionar (merge de duplicados) — POST …/fusionar. Zona de alto riesgo, irreversible, solo super_admin, con doble confirmación por nombre exacto. La entidad registrada siempre impone su nombre oficial. Lógica en SQL merge_organizadores (idempotente). Prod: 3 fusionados.
• Eliminar — soft-delete (deleted_at/deleted_by); nunca toca la entidad registrada. Prod: 3 eliminados.
• Detección de duplicados — RPC directorio_posibles_duplicados (índice trigram): dos vivos son posibles duplicados si sus nombres normalizados son iguales o su similitud trigram ≥ 0.6. Solo detecta, nunca fusiona automáticamente.

1. pais_code no es un código: guarda el nombre en español, y el histórico mezcla inglés ("Brazil") y español ("Brasil"). Si el scraper mete "Brazil", getIsoAlpha2 devuelve 00 y rompe el segmento país del evento_codigo. Normalizar el catálogo de país es el primer paso.
2. Georreferencia siempre NULL desde el form: ubicacion_lat/lng no se persisten; hay que cargarlos por otra vía si el mapa del catálogo los necesita.
3. Dos códigos distintos: evento_codigo (cadena M-PP-TTT-AA-NNNNN) vs codigo_unico (entero). No confundirlos; el NNNNN es el consecutivo anual, independiente del entero.
4. Sin unicidad natural: no hay constraint sobre (nombre, fecha_inicio) ni sobre link_registro. Una reingesta puede duplicar eventos; los códigos se generan al insertar, así que no sirven para deduplicar contra una fuente externa. Hay que diseñar la clave de deduplicación.
5. Insert bloqueado por RLS para anon: toda ingesta masiva debe usar service-role. El status inicial normal es PENDING (curaduría); solo correos en event_autopublish_privileges (hoy vacía) entran APPROVED.
6. horarios es autogenerado por rango de fechas (una fila por día, máx 30). Respetar la forma [{fecha,hora_inicio,hora_fin}] con hora_fin > hora_inicio.
7. Temáticas sectoriales: sus ids salen de las sub-industrias (>130); un id fuera del mapa cae a código 999. La "temática principal" (para el TTT) es la marcada con principal:true.
8. Catálogos hardcodeados = espejos de tablas: si se cambia la tabla en DB sin correr regen-event-catalogs.py, el form y el generador de código se desalinean.
9. Checkboxes de visibilidad restringida (ubicacion_solo_registrados / link_acceso_solo_registrados) existen en DB pero el form no los renderiza ni envía → siempre false.
10. Drift de roles: la UI de "Permisos" escribe en admin_roles, pero los gates vigentes (mig 080) leen module_permissions. Un curador asignado por esa UI no obtiene acceso bajo las funciones actuales; los roles reales de módulo se asignan por /api/admin/module-permissions.
11. Tope PostgREST 1000 filas: cualquier consulta directa al REST corta a 1000 salvo que se pagine con Range/Prefer: count.
12. La cola de curaduría está vacía y solo 2 personas administran: hoy no hay eventos PENDING; casi todo el histórico entró como APPROVED por importación.