G Geyseco · Documentació del projecte Tornar al backoffice

Proposta funcional i arquitectura tècnica - Geyseco

Document actualitzat: 31/08/2026

1. Objectiu

Geyseco necessita una aplicació de treball per gestionar congressos mèdics de manera centralitzada. L'eina ha de servir tant per al backoffice intern com per a la publicació de webs públiques de congressos, la gestió d'inscripcions, allotjaments, pagaments manuals, pagament amb targeta/TPV, formularis d'inscripció i comunicacions transaccionals.

La proposta tècnica acordada és un monòlit modular amb Laravel, Inertia i Vue per al backoffice. La web pública es recomana renderitzar-la al servidor amb Blade/SSR, utilitzant Vue només en components puntuals quan aporti valor real.

L'objectiu del MVP no és construir tots els mòduls possibles, sinó validar una vertical completa i operativa:

  1. Crear un congrés.
  2. Assignar-hi equip de gestió.
  3. Configurar dades, idiomes, quotes, extres, allotjaments i web pública.
  4. Publicar la web.
  5. Permetre una inscripció pública.
  6. Generar formularis d'inscripció i correus.
  7. Gestionar pagaments manuals, pagament amb targeta/TPV i allotjaments des del backoffice.

2. Abast funcional del MVP

Entra al MVP

No entra al MVP inicial

Fora d'abast

L'aplicació pot recollir dades fiscals per facilitar la facturació externa de Geyseco, però no generarà factures ni ara ni en fases futures previstes.

3. Decisions funcionals consolidades

Congressos

El congrés és l'entitat mare de la informació operativa. Tota dada que pertanyi a un congrés ha de quedar identificada per congress_id o per una relació clara fins al congrés.

Cal guardar també l'any del congrés per facilitar operacions futures de consulta, arxiu, anonimització o purga.

Usuaris i permisos

El model recomanat és:

Rols inicials:

Els rols vinculats a comunicacions queden preparats per fase 2:

La UI no pot ser l'única protecció. Totes les consultes, exports, downloads, jobs i endpoints han de validar permisos al backend amb Policies de Laravel.

Documentació interna

El menú Programació queda reservat al rol superadmin. Dins d'aquest espai hi ha d'haver una pàgina Documentació del projecte amb accés als documents interns de criteri funcional, arquitectura tècnica, mapa de permisos i futurs documents de planificació.

En el prototip aquests documents poden estar enllaçats com a fitxers locals. El document funcional i tècnic es manté en Markdown com a font i s'exposa també com a HTML navegable perquè el servidor no serveix directament fitxers .md.

En l'aplicació real s'han de servir des del backend amb autenticació, autorització específica, registre d'accés i sense exposar rutes públiques directes a documentació interna.

Equip assignat

Dins de cada congrés hi ha d'haver una pestanya Equip assignat. Un administrador hi podrà indicar quins gestors poden treballar aquell congrés.

La gestió global dels rols viu fora del congrés, a Usuaris/Rols. L'assignació concreta dels gestors viu dins del congrés.

Inscripcions

Una sol·licitud d'inscripció pot tenir:

El responsable pot ser també assistent sense haver d'entrar les mateixes dades dues vegades.

Una persona pot fer la sol·licitud en nom d'altres persones, per exemple una secretària que inscriu diversos metges.

Els extres com sopars, tallers o activitats opcionals s'han d'associar sempre a un assistent concret, per saber qui hi assisteix i qui ho ha contractat.

Àrea personal

El nom públic recomanat és Àrea personal. Internament cal distingir dos perfils d'accés:

L'Àrea personal no s'ha de modelar com a usuaris interns del backoffice. Al MVP es recomana accés limitat mitjançant enllaç segur, codi temporal o validació per email.

El responsable pot consultar:

L'assistent individual pot consultar només:

L'assistent no ha de veure imports globals, dades fiscals ni dades d'altres assistents.

Si el responsable també és assistent, l'accés pot mostrar dues seccions:

Cal registrar els accessos i permetre regenerar l'enllaç o codi des del web públic amb comprovació per email i codi d'inscripció, DNI/NIE o un identificador equivalent.

Obertura d'inscripcions

Cal separar la visibilitat del mòdul i l'admissió de noves sol·licituds. El check Activar inscripciones controla si la pàgina apareix al menú públic. Amb el mòdul visible, l'obertura es configura amb tres modes: segons dates, obertes manualment o tancades manualment. Els modes manuals tenen prioritat i conserven les dates, sense aplicar-les. En mode automàtic, l'inici és inclusiu i el tancament s'aplica a l'instant de fi; una data buida significa que aquell límit no existeix. Les hores s'editen en la zona horària del congrés i es desen en UTC.

Quan no s'admeten noves inscripcions, la pàgina conserva el menú i mostra un avís traduït, sense el formulari: obertura prevista amb data/hora, termini finalitzat o tancament temporal manual. L'estat es calcula en cada petició, sense scheduler. El POST torna a validar l'obertura dins de la transacció, perquè un formulari obert abans del tancament no permeti enviar una sol·licitud fora de termini. No es cancel·len ni es recalculen sol·licituds existents; es mantenen les confirmacions i l'Àrea personal mentre el mòdul continua activat. El backoffice conserva l'alta manual per gestionar excepcions.

Imports

Els imports aplicats a una inscripció han de quedar congelats com a línies econòmiques. Si més endavant canvia una quota, un extra o una tarifa hotelera, les inscripcions antigues no s'han de recalcular silenciosament.

Una mateixa quota pot tenir diversos períodes de preu consecutius, amb una denominació compartida i una data límit, preu, IVA i disponibilitat online per període. Les dates límit inclouen tot el dia en la zona horària del congrés; el període següent comença l'endemà. Només l'últim pot no tenir data límit. El formulari públic mostra una sola opció per quota amb el preu vigent, i el backoffice reutilitza el mateix criteri per a nous conceptes. La línia contractada congela el període, el preu aplicat i la data de valoració. Un canvi de preu mentre el formulari públic és obert obliga a revisar el nou import abans de confirmar l'enviament. No s'aplica un període antic com a alternativa si el període actual és offline o tots han vençut.

Cal separar visualment i tècnicament:

Els diners s'han de guardar sense float:

Pagaments

Al MVP entren tres vies de pagament:

Només el pagament amb targeta/TPV pot marcar una inscripció com a pagada de manera automàtica quan el proveïdor confirma l'operació. Transferència i Bizum han de requerir sempre un moviment manual al backoffice.

El pagament no ha de ser només un camp payment_status. Ha de funcionar com un llibre de moviments i transaccions:

Els retorns o ajustos posteriors també s'han de registrar com a moviments auditables.

L'estat agregat es calcula comparant imports contractats i moviments:

Si un gestor s'equivoca en entrar un moviment, cal poder corregir-lo. La recomanació tècnica és no esborrar físicament moviments ja consolidats, sinó anul·lar-los o registrar una correcció, conservant auditoria.

La integració amb TPV ha de tenir:

Modificacions i revisions

Quan Geyseco modifica conceptes, imports o allotjaments d'una inscripció ja confirmada, el sistema ha de detectar si hi ha:

Les modificacions pendents s'han d'agrupar en una única comunicació pendent fins que el gestor revisi i enviï el nou formulari d'inscripció.

Per imports pendents o retorns:

Formularis d'inscripció i correus

Quan una sol·licitud inclou diversos assistents, el comportament ha de ser configurable per congrés.

Configuració recomanada:

El formulari d'inscripció del responsable pot incloure assistents, conceptes contractats, imports, estat de pagament i instruccions.

El formulari d'inscripció de l'assistent ha d'incloure només dades informatives personals: congrés, assistent, quota, activitats o allotjament propi si aplica, sense totals ni dades d'altres persones.

Els documents i els correus són conceptes diferents: es conserva cada document individual, però els destinats a una mateixa adreça s'agrupen en un únic correu dins de la mateixa sol·licitud i revisió, sense còpies a altres destinataris. S'aplica a les confirmacions inicials i a les revisions manuals, respectant els destinataris configurats al congrés.

Cada inscripció ha de guardar el seu idioma de comunicació. El formulari d'inscripció s'envia en aquest idioma, no necessàriament en l'idioma de treball del backoffice.

Els textos generals dels formularis d'inscripció han de venir del catàleg global de traduccions revisades. Només s'han de personalitzar per congrés si hi ha un missatge específic.

Denominacions reutilitzables

Configuració global disposa d'un catàleg ampliable de denominacions en CA, ES, EN i PT. Inicialment inclou Inscripció de soci i Inscripció de no soci, i els tipus d'habitació Individual, Doble, Triple i Quàdruple.

En configurar una quota o habitació es poden copiar les traduccions del catàleg o introduir una denominació pròpia del congrés, amb edició manual per idioma. El catàleg no defineix imports, condicions, capacitats o disponibilitat. Els canvis globals no reescriuen les còpies existents; les inscripcions conserven els conceptes contractats i els seus textos com a snapshots.

La quota Curso completo (3 jornadas) és particular del congrés SEGCD26D, no una entrada del catàleg global. Els administradors poden ampliar, editar o desactivar denominacions globals, amb auditoria. Els permisos concrets dels gestors continuen pendents de validació amb el client.

Comptes bancaris globals

Configuració > Comptes bancaris permet als administradors gestionar entitat, IBAN i SWIFT/BIC. A Dades del congrés > Inscripcions, el compte se selecciona des d'un desplegable, no per text lliure. La selecció conserva una còpia de les dades bancàries del congrés i no modifica les confirmacions històriques.

Els comptes assignats no es poden modificar ni eliminar fins que se substitueixi la selecció dels congressos afectats. Les operacions són auditades. Les dades anteriors es preserven durant la transició, però els comptes de mostra del prototip no s'importen com a comptes reals; Geyseco ha d'introduir i verificar els comptes de producció.

Allotjaments

Per defecte, una reserva hotelera s'hauria de confirmar automàticament si hi ha disponibilitat. Tot i això, el comportament ha de ser configurable per congrés.

Si no hi ha disponibilitat o el congrés requereix validació manual, la inscripció ha de poder finalitzar igualment. L'allotjament pot quedar pendent i Geyseco el podrà afegir manualment més endavant.

Quan Geyseco afegeix manualment un allotjament a una inscripció ja confirmada, el sistema no ha d'enviar automàticament el formulari d'inscripció. Ha de mostrar una alerta indicant que cal revisar i enviar manualment la comunicació.

Normalment hi haurà una habitació per assistent. Si diversos assistents comparteixen habitació, n'hi ha prou amb indicar:

La disponibilitat s'ha de controlar per nit:

Web pública

La web pública ha de ser responsive i ha de mantenir l'estructura acordada al prototip:

El contingut de la web es divideix en dos orígens:

Les opcions activades des de Dades del congrés no s'han de duplicar a Web > Continguts. A Web > Continguts s'ha de veure una simulació del menú públic amb totes les possibilitats, indicant quines estan actives o inactives i on es configuren.

Al MVP, el contingut publicat pot mostrar l'última versió guardada. La recomanació tècnica és deixar preparada l'estructura per revisions i publicació versionada, encara que la gestió completa de revisions pugui quedar per una evolució.

Programa: llista o horari

A Web > Continguts > Programa es tria la vista Listado o Horario per congrés. La selecció s'aplica a la web pública i al PDF generat automàticament, reutilitzant els mateixos dies, activitats i traduccions. Els programes existents continuen en format de llista fins que es canviï i es desi aquesta selecció.

Configuració > Personalització agrupa els catàlegs generals en dos apartats interns: Cuotas y habitaciones i Tipos de actividad. Hi ha una única pestanya superior Personalización; comptes bancaris i textos legals continuen separats. Aquesta organització permet incorporar més catàlegs sense multiplicar les opcions del menú superior.

Els tipus d'activitat es gestionen a Configuració > Personalització > Tipus d'activitat, només per a administradors i súperadministradors: nom en CA/ES/EN/PT, color exacte i estat actiu/inactiu. El catàleg inclou inicialment sessió, plenària, taller, pausa i activitat social. No hi ha eliminació del catàleg; la desactivació evita noves seleccions sense afectar programes existents.

A Web > Continguts > Programa, el botó Tipos de actividad permet incorporar tipus actius del catàleg i afegir-ne de particulars. Cada congrés conserva una còpia editable de noms, color i disponibilitat, independent del catàleg global. Els canvis locals s'apliquen en desar la pàgina, amb auditoria. Els tipus utilitzats no es poden treure del programa; desactivar-los conserva les activitats existents i impedeix noves assignacions. Els tipus no utilitzats es poden retirar de la selecció del congrés. Web i PDF generat comparteixen noms traduïts i colors, amb contrast automàtic del text.

Web > Configuració

Aquesta secció ha d'incloure:

El botó Crear web ha d'estar dins del bloc Publicació, un cop configurats els punts previs.

Web > Textos legals

Els textos legals globals es mantenen a Configuració > Textos legals i han de ser multiidioma.

Dins de cada congrés, Web > Textos legals ha de permetre:

Les pàgines legals del web públic han de ser rutes reals, accessibles des del footer, però no han d'aparèixer al menú principal del congrés.

Agenda corporativa de Geyseco

Cal distingir dues opcions:

Dins d'un congrés, l'opció Publicació agenda ha de publicar:

Per tant, dins d'aquesta pantalla el camp editable principal és el cartell. La resta ha de venir de dades ja informades en altres seccions.

Multiidioma

Cal separar clarament:

Les traduccions del backoffice s'han de gestionar amb fitxers d'idioma o catàleg global de traduccions. Els continguts públics del congrés s'han de traduir dins de cada congrés.

Per als continguts públics editables, es recomana oferir un botó de proposta de traducció amb IA dins del bloc de l'idioma de destí. La traducció proposada ha de quedar visualment diferenciada fins que un usuari la revisi, modifiqui o validi.

Si falta una traducció pública, el sistema ha de fer fallback a l'idioma per defecte del congrés i marcar-ho internament com a pendent de revisió.

4. Arquitectura tècnica recomanada

Recomanació:

Laravel modular + Inertia/Vue per al backoffice + Blade/SSR per a webs públiques + MySQL/MariaDB + Redis/Queues + Outbox transaccional + jobs auditables + storage S3 compatible + proveïdor transaccional de correu + proveïdor de pagament TPV + desplegament i operació mitjançant Mestral.

Diagrama lògic

Internet
   |
   v
Nginx + TLS
   |
   +-- Backoffice: Laravel + Inertia + Vue
   +-- Web pública: Laravel Blade/SSR + components Vue puntuals
   +-- Formularis públics i portals limitats
   +-- API de webhooks i futures integracions
              |
              v
         MySQL/MariaDB
              |
        Outbox transaccional
              |
              v
       Redis + Laravel Queues
              |
      +-------+--------+
      v       v        v
   Correus  Purgues  Processos llargs
      |
      v
Proveïdor transaccional

5. Organització modular interna

Continua sent una sola aplicació i un sol desplegament. No es proposen microserveis.

Mòduls interns:

6. Base de dades

Decisió operativa: MySQL/MariaDB al servidor actual.

Motivació:

PostgreSQL continua sent una alternativa tècnica vàlida, però aprofitar MySQL/MariaDB existent redueix dependències d'infraestructura. Caldrà posar especial atenció en transaccions d'allotjaments, índexs, backups i consultes d'informes.

Taules conceptuals principals:

Regla de disseny: tota taula funcional que pengi d'un congrés ha de tenir congress_id directe o una relació inequívoca fins al congrés. Això facilita permisos, exports, auditories i purgues.

7. Jobs, cues, outbox i idempotència

Una cua tècnica no substitueix un job de negoci visible.

A més de Laravel Queues, cal una taula operations o job_runs amb:

Operacions candidates:

Per evitar perdre esdeveniments si Redis falla, es recomana patró outbox:

  1. La transacció desa la inscripció o canvi funcional.
  2. La mateixa transacció desa l'esdeveniment pendent a MySQL/MariaDB.
  3. Un worker processa l'outbox.
  4. La idempotència evita duplicats.

8. Correus

Els correus han de sortir per un proveïdor transaccional extern, no directament des de la IP del servidor web.

Cal preveure:

9. Fitxers i backups

Fitxers:

Backups:

Un backup que no s'ha restaurat mai no és encara una garantia.

10. Desplegament i operativa

Processos separats en producció:

Entorns:

El desplegament ha de contemplar:

11. Observabilitat i auditoria

Cal registrar:

L'auditoria ha de guardar com a mínim:

12. Ordre de desenvolupament recomanat

Es recomana construir primer una vertical completa, no tots els CRUD de manera horitzontal.

Aquest apartat és el resum executiu. El detall operatiu queda desenvolupat al document pla-programacio-laravel-geyseco.md.

  1. Sprint 0: base tècnica, entorns, Laravel, DB, Redis, queues, auth base, CI mínim.
  2. Sprint 1: usuaris, rols, permisos i equip assignat.
  3. Sprint 2: congressos, dades generals, idiomes, estat i arxiu.
  4. Sprint 3: configuració d'inscripcions, quotes, extres i camps.
  5. Sprint 4: formulari públic d'inscripció, responsable, assistents i dades fiscals.
  6. Sprint 5: pagaments manuals, targeta/TPV, transaccions, webhooks, moviments, estat agregat, retorns, correccions i auditoria.
  7. Sprint 6: formularis d'inscripció, Àrea personal, correus, outbox, registre i reenviaments.
  8. Sprint 7: allotjaments, inventari per nit i reserves.
  9. Sprint 8: web pública, continguts, URL, aparença, textos legals i publicació agenda.
  10. Sprint 9: QA, responsive, permisos, backups, restauració, logs i validació client.

Aquest ordre valida aviat permisos, dades, emails, imports i publicació pública, que són els punts de més risc.

13. Decisions pendents abans de programar

Decisions que cal tancar o confirmar abans de Sprint 0:

Decisions funcionals ja orientades:

14. Recomanació final

La tecnologia proposada és adequada, però el projecte ha de néixer amb arquitectura operativa completa.

La recomanació final és:

Laravel modular + Inertia/Vue per al backoffice + Blade/SSR per a webs públiques + MySQL/MariaDB + Redis/Queues + Outbox transaccional + jobs auditables + storage S3 compatible + correu transaccional extern + proveïdor de pagament TPV + desplegament i operació mitjançant Mestral.

Els punts que no s'han de deixar per més endavant són: