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, butlletins 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 butlletins i correus.
7. Gestionar pagaments manuals i allotjaments des del backoffice.

2. Abast funcional del MVP

Entra al MVP

• Autenticació, logout i recuperació de contrasenya.
• Gestió d'usuaris interns.
• Rols inicials: Súperadministrador, Administrador i Gestor de congressos.
• Assignació de gestors a congressos concrets mitjançant l'opció Equip assignat dins de cada congrés.
• Accés intern a documentació del projecte dins de Programació, només per a Súperadministradors.
• Alta, edició, arxiu i gestió de congressos.
• Multiidioma complet per backoffice, web pública, formularis i correus.
• Configuració de quotes, tarifes, extres i camps d'inscripció.
• Formulari públic d'inscripció.
• Alta manual d'inscripcions des del backoffice.
• Separació entre responsable/contacte, assistents, dades fiscals i conceptes econòmics.
• Extres associats a cada assistent.
• Línies econòmiques congelades a cada inscripció.
• Pagaments manuals per transferència bancària i Bizum com a llibre de moviments.
• Estat agregat del pagament derivat dels imports contractats i els moviments registrats.
• Moviments de devolució i correccions auditables.
• Allotjaments amb hotels, tipus d'habitació, inventari per nit i reserves vinculades a inscripcions.
• Possibilitat d'acabar una inscripció encara que l'allotjament quedi pendent.
• Butlletins multiidioma, registre d'enviament i reenviament manual.
• Web pública amb URL configurable, aparença, continguts editables, menú públic i peu legal.
• Textos legals globals multiidioma i personalització puntual per congrés.
• Publicació del congrés a l'agenda corporativa de Geyseco.
• Auditoria de canvis rellevants.
• Estructura de dades preparada per arxivar, anonimitzar i purgar per congrés o any.

No entra al MVP inicial

• Pagament amb targeta o TPV virtual.
• Comunicacions científiques, avaluadors i superavaluadors.
• Estadístiques avançades.
• Constructor visual lliure de pàgines.
• Revisions editorials completes tipus CMS avançat, si encareixen massa el MVP.

Fora d'abast

• Emissió de factures dins l'aplicació.

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:

• Rol global de l'usuari.
• Assignació per congrés quan el rol no té accés global.

Rols inicials:

• superadmin: perfil tècnic d'aTotArreu, amb accés a Programació i configuració tècnica.
• admin: accés operatiu complet a tots els congressos.
• manager: accés només als congressos assignats.

Els rols vinculats a comunicacions queden preparats per fase 2:

• reviewer
• super_reviewer
• communicator

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:

• Responsable o contacte principal.
• Un o diversos assistents.
• Dades fiscals úniques per tota la sol·licitud.
• Quotes, extres i allotjaments.
• Moviments de pagament.
• Butlletins i comunicacions associades.

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.

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.

Cal separar visualment i tècnicament:

• Imports contractats: quotes, extres, allotjaments.
• Moviments econòmics: cobraments, devolucions, ajustos.
• Balanç resultant: pendent, parcial, pagat o import a retornar.

Els diners s'han de guardar sense float:

• Imports en cèntims enters o numeric.
• Moneda ISO, inicialment EUR.
• IVA, descomptes, totals i imports pendents com a valors explícits.

Pagaments

Al MVP, transferència bancària i Bizum són pagaments manuals. El pagament amb targeta queda fora del MVP.

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

• Transferència rebuda.
• Bizum rebut.
• Ajust manual.
• Devolució.
• Correcció per error.

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

• Pendent.
• Pagat parcialment.
• Pagat.
• Import a retornar.

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.

Modificacions i revisions

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

• Import pendent.
• Import a retornar.
• Canvi informatiu sense impacte econòmic.

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

Per imports pendents o retorns:

• Hi ha d'haver un text genèric configurable per congrés.
• El gestor l'ha de poder editar puntualment abans d'enviar la revisió.
• Els retorns s'han de poder marcar com a retornats mitjançant moviment econòmic negatiu o de devolució.

Butlletins i correus

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

Configuració recomanada:

• Enviar al responsable un butlletí detallat de la sol·licitud.
• Enviar a cada assistent un butlletí personal i informatiu, sense dades econòmiques ni dades d'altres assistents.

El butlletí del responsable pot incloure assistents, conceptes contractats, imports, estat de pagament i instruccions.

El butlletí 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.

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

Els textos generals dels butlletins 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.

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 butlletí. 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:

• Titular de l'habitació.
• Ocupants.
• Nits.
• Hotel i tipus d'habitació.

La disponibilitat s'ha de controlar per nit:

• Hotel.
• Tipus d'habitació.
• Data/nit.
• Estoc total.
• Bloquejades.
• Confirmades.
• Pendents.

Web pública

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

• Banner superior a tota l'amplada.
• Menú lateral esquerre en escriptori.
• Menú hamburguesa en mòbil i tauleta.
• Àrea principal de contingut.
• Footer amb textos legals.

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

• Dades del congrés: dates, seu, URL, idiomes, inscripcions, allotjaments, comunicacions i secretaria tècnica.
• Web > Continguts: pàgines editorials com Presentació, Comitès, Programa, Ponents, Informació general i Crèdits.

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ó.

Web > Configuració

Aquesta secció ha d'incloure:

• Domini i contacte.
• Tecnologia del web: web pròpia o WordPress si en algun cas es decideix així.
• Aparença: banner, colors, tipografia, menú i comportament responsive.
• Publicació: crear web, estat publicada/en manteniment, preview i enllaç públic.

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:

• Triar quins enllaços apareixen al footer.
• Configurar l'etiqueta de cada enllaç per idioma.
• Assignar un text global base.
• Personalitzar puntualment el text legal per aquell congrés i idioma.
• Previsualitzar el footer públic.

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:

• Agenda general del backoffice: llistat cronològic de congressos, filtrable per mes i any.
• Publicació agenda del congrés: dades que es publiquen a https://www.grupogeyseco.com/agenda/.

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

• Cartell del congrés.
• Dates del congrés, provinents de Dades del congrés i preferentment readonly.
• URL del web públic, provinent de Web > Configuració > Domini i contacte.
• Estat de publicació a l'agenda corporativa.

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:

• Idioma de treball del backoffice: preferència de cada usuari.
• Idiomes actius del congrés: idiomes disponibles al web públic, formulari i correus.
• Idioma de comunicació de cada inscripció: idioma en què rebrà butlletins i comunicacions.

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 + PostgreSQL + Redis/Queues + Outbox transaccional + jobs auditables + storage S3 compatible + proveïdor transaccional de correu + 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
         PostgreSQL
              |
        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:

• Identitat i permisos.
• Congressos.
• Equip assignat.
• Publicació web i dominis.
• Continguts web.
• Textos legals.
• Agenda corporativa.
• Inscripcions i assistents.
• Catàleg, quotes, tarifes i extres.
• Allotjaments.
• Pagaments.
• Butlletins i correus.
• Fitxers.
• Documentació interna.
• Auditoria i retenció.
• Operacions i jobs.
• Comunicacions, fase 2.

6. Base de dades

Preferència tècnica: PostgreSQL.

Motivació:

• Integritat i restriccions.
• Concurrència de reserves hoteleres.
• Consultes i informes futurs.
• JSONB per blocs configurables validats.
• Millor evolució cap a comunicacions, avaluacions i auditoria.

Si el hosting final obliga a MySQL/MariaDB, el model es pot adaptar, però caldrà revisar especialment concurrència d'allotjaments, JSON i consultes futures.

Taules conceptuals principals:

• users
• roles
• user_roles
• congresses
• congress_user_assignments
• congress_languages
• congress_translations
• bank_accounts
• congress_payment_settings
• registration_fees
• registration_extras
• registration_form_fields
• registration_form_field_translations
• registrations
• registration_contacts
• registration_attendees
• registration_tax_data
• registration_items
• registration_revisions
• payment_movements
• payment_movement_audit_logs
• hotels
• hotel_room_types
• hotel_room_inventory
• hotel_reservations
• hotel_reservation_occupants
• websites
• website_domains
• website_theme
• website_pages
• website_page_translations
• website_legal_links
• legal_texts
• legal_text_translations
• agenda_publications
• email_templates
• email_template_translations
• email_logs
• outbox_events
• operations
• files
• audit_events
• purge_jobs

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:

• Tipus d'operació.
• Congrés.
• Usuari que l'ha iniciada.
• Estat.
• Progrés.
• Resultat.
• Error.
• Dates d'inici i finalització.
• Clau d'idempotència.

Operacions candidates:

• Enviaments de correus.
• Reenviaments de butlletins.
• Exports.
• Purgues.
• Publicació o regeneració de webs.
• Publicació a l'agenda corporativa.

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 PostgreSQL.
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:

• Plantilles multiidioma.
• Locale utilitzat.
• Registre de cada missatge.
• Relació amb inscripció, assistent i congrés.
• Webhooks de lliurament, rebot i queixa.
• Idempotència per evitar dobles confirmacions.
• Reenviament manual auditable.

9. Fitxers i backups

Fitxers:

• Laravel Flysystem des del principi.
• Disc local només en desenvolupament o storage privat del servidor.
• S3 compatible en producció si l'operativa ho permet.
• Fitxers privats per defecte.
• URL temporal per descàrregues privades.
• Metadades a base de dades.
• Validació de tipus i mida.

Backups:

• Backup diari de PostgreSQL.
• Backup de fitxers/object storage.
• Còpia fora del servidor.
• Retenció definida.
• Prova real de restauració.
• RPO i RTO acordats.

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

10. Desplegament i operativa

Processos separats en producció:

• Nginx.
• PHP-FPM.
• PostgreSQL.
• Redis.
• Workers Laravel.
• Scheduler Laravel.
• Monitoratge i health checks.

Entorns:

• Desenvolupament.
• Staging.
• Producció.

El desplegament ha de contemplar:

• Migracions controlades.
• Rollback de codi.
• Workers amb la mateixa versió que l'aplicació.
• Reinici ordenat de workers.
• Releases sense processos antics executant jobs nous.
• Logs centralitzats o consultables.
• Backups i restauració provada.

11. Observabilitat i auditoria

Cal registrar:

• Login i canvis d'usuari rellevants.
• Assignacions d'equip a congressos.
• Canvis funcionals del congrés.
• Canvis d'estat i moviments de pagament.
• Modificacions de conceptes i revisions pendents.
• Publicacions de web.
• Canvis en textos legals.
• Publicacions a l'agenda corporativa.
• Enviaments i reenviaments de correu.
• Exports.
• Purgues i anonimitzacions.
• Errors de jobs.

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

• Usuari.
• Congrés.
• Acció.
• Entitat afectada.
• Data i hora.
• Valors rellevants abans/després quan tingui sentit.
• IP o context si aplica.

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, moviments, estat agregat, retorns, correccions i auditoria.
7. Sprint 6: butlletins, 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:

• Hosting final: servidor actual, VPS nou o entorn gestionat.
• Motor de base de dades: recomanat PostgreSQL; confirmar viabilitat operativa.
• Proveïdor transaccional de correu.
• Comptes bancaris i instruccions de transferència.
• Operativa exacta de Bizum.
• Idiomes inicials per al primer congrés real.
• Textos legals definitius globals.
• Política de backups, retenció i restauració.
• Criteri final de dominis: subdominis, dominis propis o ambdues opcions.

Decisions funcionals ja orientades:

• Laravel + Inertia + Vue per al backoffice.
• Blade/SSR per a webs públiques.
• Rols globals + assignació per congrés.
• Comunicacions en fase 2.
• Factures fora d'abast.
• Web amb blocs controlats, no constructor lliure.
• Textos legals globals amb personalització per congrés.

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 + PostgreSQL + Redis/Queues + Outbox transaccional + jobs auditables + storage S3 compatible + correu transaccional extern + desplegament i operació mitjançant Mestral.

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

• Integritat del model econòmic.
• Imports congelats per inscripció.
• Concurrència d'allotjaments.
• Moviments de pagament auditables.
• Jobs visibles i idempotents.
• Auditoria.
• Multiidioma real.
• Textos legals globals i per web.
• Publicació web coherent.
• Dominis i SSL.
• Observabilitat.
• Backups restaurables.
• Seguretat i retenció de dades.