Pla de programació Laravel - Geyseco

Document creat: 31/08/2026

1. Objectiu del document

Aquest document converteix la proposta funcional i tècnica de Geyseco en un pla de programació executable per fases.

No és encara un calendari tancat. És l'ordre recomanat de construcció, amb dependències, entregables, criteris d'acceptació i proves mínimes per reduir risc abans d'entrar en producció.

El criteri principal és construir una vertical completa abans d'omplir tots els CRUD:

1. Crear un congrés.
2. Assignar-hi equip.
3. Configurar inscripcions, idiomes, quotes i web.
4. Publicar una web pública.
5. Rebre una inscripció realista.
6. Generar butlletins.
7. Registrar moviments de pagament.
8. Gestionar allotjaments.
9. Validar permisos, auditoria, cues, backups i responsive.

2. Abast del MVP

Entra

• Autenticació i gestió inicial d'usuaris.
• Rols globals i equip assignat per congrés.
• Alta, edició, arxiu i gestió de congressos.
• Configuració multiidioma de backoffice i web pública.
• Configuració d'inscripcions, quotes, extres i camps.
• Formulari públic d'inscripció.
• Responsable/contacte, assistents i dades fiscals.
• Extres associats a assistents.
• Allotjaments amb disponibilitat per nit.
• Butlletins de confirmació i revisions manuals.
• Pagaments manuals com a llibre de moviments.
• Web pública del congrés.
• Textos legals globals i personalització per congrés.
• Publicació a l'agenda corporativa.
• Auditoria d'accions rellevants.
• Operacions i jobs visibles.
• Backups i restauració provada.

No entra al MVP

• Pagament amb targeta o TPV.
• Facturació.
• Comunicacions científiques.
• Avaluadors i superavaluadors.
• Estadístiques avançades.
• Constructor visual lliure de webs.

3. Arquitectura de partida

La base tècnica recomanada és:

• Laravel com a monòlit modular.
• Inertia + Vue per al backoffice.
• Blade o SSR per a webs públiques.
• PostgreSQL com a base de dades preferent.
• Redis per cues i cache.
• Laravel Queues amb workers separats.
• Outbox transaccional per correus i operacions crítiques.
• Storage privat mitjançant Laravel Flysystem.
• S3 compatible en producció si l'operativa ho permet.
• Proveïdor transaccional extern per correus.
• Desplegament i operació mitjançant Mestral.

4. Decisions prèvies a Sprint 0

Abans de començar codi productiu, cal tancar o confirmar:

• Repositori definitiu i política de branques.
• Entorns: desenvolupament, staging i producció.
• Motor de base de dades disponible al hosting final.
• Ús de PostgreSQL o alternativa si hi ha restricció operativa.
• Servidor Redis disponible per queues i cache.
• Proveïdor de correu transaccional.
• Estratègia de dominis i subdominis per webs públiques.
• Ubicació de fitxers privats.
• Política de backups i restauració.
• Idiomes inicials del backoffice.
• Idiomes inicials de webs públiques.
• Primer congrés pilot per validar la vertical completa.
• Dades legals globals de Geyseco.
• Comptes bancaris inicials.

5. Definició de fet

Una funcionalitat no es considera acabada només perquè es vegi a pantalla.

Per donar-la per feta cal:

• Migracions aplicades sense errors.
• Models, relacions i validacions coherents.
• Policies o permisos aplicats al backend.
• UI funcional al backoffice o web pública segons correspongui.
• Textos preparats per multiidioma quan siguin visibles.
• Auditoria quan hi hagi canvi funcional rellevant.
• Tests mínims de model, política o flux.
• Validació responsive en mòbil, tauleta i sobretaula.
• Sense errors de consola en la ruta afectada.
• Documentació actualitzada si canvia el criteri funcional o tècnic.

6. Sprint 0 - Arrencada tècnica

Objectiu

Crear la base real del projecte Laravel i deixar-la preparada per desenvolupar amb seguretat.

Tasques

• Crear repositori real del projecte.
• Inicialitzar Laravel.
• Configurar Inertia i Vue per al backoffice.
• Definir estructura modular interna.
• Configurar base de dades.
• Configurar Redis.
• Configurar queues.
• Configurar scheduler.
• Configurar entorn local.
• Configurar staging.
• Configurar variables d'entorn.
• Configurar logs.
• Configurar health check bàsic.
• Configurar pipeline mínim de validació.
• Afegir formatador i estàndard de codi.
• Crear layout base del backoffice.
• Preparar layout base de web pública.
• Crear primeres migracions tècniques.
• Preparar patró d'auditoria.
• Preparar patró d'outbox.
• Preparar patró d'operacions visibles.

Entregable

Aplicació Laravel arrencable en local i staging, amb login placeholder o base tècnica preparada, connexió a base de dades, cues i estructura mínima de mòduls.

Criteris d'acceptació

• El projecte arrenca en local.
• El projecte arrenca en staging.
• Les migracions s'executen sense errors.
• Es pot executar la cua.
• Es pot executar el scheduler.
• Existeix una pàgina base de backoffice.
• Existeix una pàgina base de web pública.
• Hi ha una estratègia clara de logs i configuració.

Proves mínimes

• Test de boot de l'aplicació.
• Test de connexió a base de dades.
• Test de dispatch i processament d'un job simple.
• Test de migracions en entorn net.

7. Sprint 1 - Autenticació, usuaris i permisos

Objectiu

Construir l'accés segur al backoffice i la base de permisos real.

Tasques

• Implementar login.
• Implementar logout.
• Implementar recuperació de contrasenya.
• Crear model d'usuaris.
• Crear model de rols.
• Crear assignació de rol global.
• Crear gestió d'usuaris al backoffice.
• Crear gestió de rols al backoffice.
• Crear matriu de permisos inicial.
• Incorporar el mapa de mòduls i permisos com a referència funcional.
• Crear Policies de Laravel per a mòduls inicials.
• Restringir Programació a Súperadministrador.
• Restringir documentació interna a Súperadministrador.
• Auditar canvis d'usuari i rol.
• Afegir preferència d'idioma de treball de l'usuari.

Entregable

Backoffice amb autenticació real, usuaris, rols i protecció efectiva de rutes segons permisos.

Criteris d'acceptació

• Un usuari pot entrar i sortir.
• Un usuari pot recuperar la contrasenya.
• Un administrador pot crear i modificar usuaris.
• Un administrador pot assignar rols.
• Un gestor no pot veure configuració global si no té permís.
• Un usuari no autoritzat no pot accedir a Programació.
• La documentació interna no és accessible sense permís.

Proves mínimes

• Tests d'autenticació.
• Tests de recuperació de contrasenya.
• Tests de Policies.
• Tests d'accés prohibit a rutes internes.
• Tests d'auditoria de canvis d'usuari.

8. Sprint 2 - Congressos i equip assignat

Objectiu

Crear la base operativa del congrés com a entitat mare de tota la informació.

Tasques

• Crear taula de congressos.
• Crear camps principals del congrés.
• Guardar any del congrés.
• Guardar zona horària del congrés.
• Guardar estat del congrés.
• Implementar alta de congrés.
• Implementar edició de congrés.
• Implementar llistat de congressos.
• Implementar arxiu de congrés.
• Diferenciar arxivar, eliminar, anonimitzar i purgar.
• Crear assignació d'usuaris a congressos.
• Crear pestanya Equip assignat dins del congrés.
• Aplicar permisos per congrés assignat.
• Auditar canvis principals del congrés.

Entregable

Un administrador pot crear congressos i assignar-hi gestors. Un gestor només veu i gestiona els congressos assignats.

Criteris d'acceptació

• El congrés té dades generals completes.
• L'any queda guardat de forma consultable.
• La zona horària queda definida.
• L'arxiu no elimina dades.
• L'equip assignat funciona.
• Els permisos es validen al backend.
• El llistat filtra segons el rol de l'usuari.

Proves mínimes

• Tests CRUD de congressos.
• Tests de Policies per congressos assignats.
• Tests d'arxiu.
• Tests d'auditoria de canvis de congrés.

9. Sprint 3 - Configuració d'inscripcions

Objectiu

Definir com es configurarà cada congrés abans d'obrir inscripcions.

Tasques

• Crear configuració d'inscripcions per congrés.
• Crear idiomes actius del congrés.
• Crear idioma per defecte del congrés.
• Crear quotes d'inscripció.
• Crear edicions de quota amb dates límit.
• Crear extres associables a assistents.
• Crear camps configurables del formulari.
• Crear textos legals vinculats al formulari.
• Crear mètodes de pagament manuals actius.
• Assignar compte bancari del congrés.
• Configurar criteri de butlletins per responsable i assistents.
• Configurar text genèric de pagament pendent.
• Configurar text genèric de retorn.
• Congelar imports com a futura línia econòmica.
• Auditar canvis de configuració sensible.

Entregable

Un congrés pot deixar preparada tota la configuració necessària per rebre inscripcions públiques.

Criteris d'acceptació

• Es poden configurar quotes i extres.
• Els extres queden marcats com a associables a assistents.
• Els idiomes públics del congrés són independents de l'idioma del backoffice.
• Els mètodes de pagament manuals són configurables.
• Els textos de pagament pendent i retorn són configurables.
• La configuració queda auditada quan afecta imports o pagaments.

Proves mínimes

• Tests de configuració per congrés.
• Tests de validació d'imports.
• Tests de dates límit.
• Tests de permisos sobre configuració.

10. Sprint 4 - Formulari públic d'inscripció

Objectiu

Construir el primer flux públic complet d'inscripció.

Tasques

• Crear formulari públic SSR o Blade.
• Implementar selector d'idioma públic.
• Implementar pas de responsable.
• Permetre que el responsable sigui també assistent.
• Implementar pas d'assistents.
• Permetre diversos assistents en una sol·licitud.
• Implementar selecció de quota per assistent.
• Implementar extres per assistent.
• Implementar dades fiscals úniques per sol·licitud.
• Implementar resum final.
• Crear validacions server side.
• Crear registre de sol·licitud.
• Crear línies econòmiques congelades.
• Crear idioma de comunicació de la sol·licitud.
• Preparar esdeveniment outbox de confirmació.
• Mostrar estat inicial pendent de pagament.

Entregable

Una persona pot completar una inscripció pública amb un o diversos assistents i el sistema desa una sol·licitud coherent.

Criteris d'acceptació

• El formulari funciona en tots els idiomes actius.
• El responsable pot ser o no assistent.
• No cal entrar dues vegades les dades si el responsable és assistent.
• Cada assistent pot tenir quota i extres propis.
• Les dades fiscals són úniques per sol·licitud.
• Els imports queden congelats.
• La sol·licitud queda pendent de pagament si no hi ha pagament automàtic.

Proves mínimes

• Tests de validació del formulari.
• Tests de creació amb un assistent.
• Tests de creació amb múltiples assistents.
• Tests de responsable també assistent.
• Tests de línies econòmiques congelades.
• Tests responsive del formulari.

11. Sprint 5 - Backoffice d'inscripcions i pagaments manuals

Objectiu

Donar a Geyseco control real sobre sol·licituds, assistents, imports i moviments de pagament.

Tasques

• Crear llistat de sol·licituds.
• Crear fitxa de sol·licitud.
• Crear llistat d'assistents.
• Crear fitxa d'assistent.
• Mostrar imports contractats.
• Mostrar moviments econòmics.
• Calcular balanç.
• Derivar estat agregat de pagament.
• Afegir moviment de pagament manual.
• Afegir moviment de Bizum.
• Afegir moviment de transferència.
• Afegir ajust manual.
• Afegir devolució.
• Anul·lar o corregir moviment entrat per error.
• Auditar moviments i correccions.
• Detectar diferencial pendent.
• Detectar import a retornar.
• Crear alerta de comunicació pendent quan hi ha modificacions.

Entregable

La fitxa d'inscripció mostra clarament què s'ha contractat, què s'ha cobrat, què queda pendent i quin és l'estat agregat.

Criteris d'acceptació

• Un gestor pot veure sol·licituds del congrés assignat.
• Un gestor pot registrar un moviment manual.
• Un moviment afecta el balanç.
• L'estat de pagament es deriva del balanç.
• Un moviment incorrecte no s'esborra sense rastre.
• Les correccions queden auditades.
• La pantalla diferencia imports contractats i imports cobrats.

Proves mínimes

• Tests de càlcul de balanç.
• Tests d'estat agregat.
• Tests de moviment positiu.
• Tests de devolució.
• Tests d'anul·lació o correcció.
• Tests de permisos per congrés.

12. Sprint 6 - Butlletins, correus i outbox

Objectiu

Enviar confirmacions i revisions sense perdre rastre ni duplicar comunicacions.

Tasques

• Crear plantilles globals multiidioma de butlletins.
• Crear variables disponibles per plantilla.
• Crear butlletí detallat de responsable.
• Crear butlletí personal d'assistent.
• Aplicar configuració per congrés.
• Enviar butlletins segons idioma de comunicació.
• Registrar cada email enviat.
• Registrar plantilla i versió utilitzada.
• Processar enviaments via outbox.
• Evitar duplicats amb idempotència.
• Crear reenviament manual.
• Agrupar modificacions en una única comunicació pendent.
• Permetre editar puntualment instruccions de pagament pendent.
• Permetre editar puntualment instruccions de retorn.
• Preparar webhooks del proveïdor de correu.

Entregable

El sistema genera i envia butlletins coherents en l'idioma correcte, amb registre d'enviament i reenviament manual.

Criteris d'acceptació

• El responsable pot rebre un butlletí detallat.
• Cada assistent pot rebre un butlletí personal sense dades econòmiques.
• L'idioma del correu és el de comunicació de la inscripció.
• Les plantilles globals estan traduïdes.
• Els reenviaments queden registrats.
• Les modificacions pendents s'agrupen en una sola comunicació fins que s'envia.
• Si falla Redis, l'esdeveniment funcional no es perd perquè existeix outbox.

Proves mínimes

• Tests de render de plantilles.
• Tests d'idioma de correu.
• Tests d'outbox.
• Tests d'idempotència.
• Tests de reenviament.
• Tests de comunicació pendent agrupada.

13. Sprint 7 - Allotjaments

Objectiu

Gestionar hotels, tipus d'habitació, disponibilitat per nit i reserves vinculades a inscripcions.

Tasques

• Crear hotels per congrés.
• Crear tipus d'habitació.
• Crear inventari per nit.
• Crear disponibilitat confirmada.
• Crear disponibilitat bloquejada.
• Crear reserves vinculades a sol·licituds.
• Permetre titular d'habitació.
• Permetre ocupants.
• Permetre habitacions compartides.
• Confirmar automàticament si hi ha disponibilitat i la configuració ho permet.
• Deixar reserva pendent si no hi ha disponibilitat o cal validació manual.
• Permetre acabar la inscripció encara que allotjament quedi pendent.
• Permetre afegir allotjament manualment a posteriori.
• Generar alerta per enviar butlletí manual quan s'afegeix allotjament.
• Controlar concurrència per nit.

Entregable

Geyseco pot gestionar allotjaments sense sobreocupació i pot afegir reserves manualment quan cal.

Criteris d'acceptació

• La disponibilitat es controla per hotel, tipus i nit.
• Dues reserves simultànies no poden sobreocupar inventari.
• La inscripció pot finalitzar amb allotjament pendent.
• L'allotjament manual actualitza imports contractats.
• L'allotjament manual crea alerta de butlletí pendent.
• Les habitacions compartides tenen titular i ocupants.

Proves mínimes

• Tests d'inventari per nit.
• Tests de concurrència.
• Tests de reserva confirmada.
• Tests de reserva pendent.
• Tests d'afegit manual.
• Tests de generació d'alerta.

14. Sprint 8 - Web pública, continguts, legals i agenda

Objectiu

Construir la publicació pública del congrés amb continguts editables, domini configurable i coherència amb el backoffice.

Tasques

• Crear model de web pública per congrés.
• Configurar URL final.
• Configurar subdomini temporal o definitiu.
• Configurar estat publicada o no publicada.
• Configurar aparença bàsica.
• Gestionar banner.
• Crear pàgines editorials.
• Editar continguts multiidioma.
• Proposar traduccions amb IA com a ajuda, si s'integra en fase real.
• Diferenciar continguts editorials i mòduls provinents de Dades del congrés.
• Mostrar menú públic segons configuració.
• Implementar estructura responsive.
• Crear footer amb textos legals.
• Seleccionar textos legals per web.
• Permetre personalitzar textos legals per congrés i idioma.
• Crear pàgines legals reals.
• Crear publicació a agenda corporativa.
• Mostrar dates readonly des de Dades del congrés.
• Mostrar URL readonly des de Web > Configuració.
• Permetre pujar cartell d'agenda.
• Preparar operació visible de publicació o regeneració.

Entregable

Un congrés pot tenir web pública responsive, continguts traduïts, footer legal i fitxa publicada a l'agenda corporativa.

Criteris d'acceptació

• La web pública carrega en mòbil, tauleta i sobretaula.
• El banner enllaça a home.
• El menú lateral funciona en escriptori.
• El menú hamburguesa funciona en mòbil.
• Les pàgines publicades es veuen.
• Les pàgines en esborrany no es veuen al web públic.
• Els mòduls actius depenen de Dades del congrés.
• Els textos legals del footer es poden configurar.
• Les pàgines legals són accessibles des del footer.
• La publicació agenda usa dates i URL ja informades.

Proves mínimes

• Tests de render web pública.
• Tests de selecció d'idioma.
• Tests de pàgines publicades i esborrany.
• Tests de footer legal.
• Tests responsive.
• Tests de publicació agenda.

15. Sprint 9 - QA, seguretat, operativa i validació MVP

Objectiu

Tancar el MVP amb garanties mínimes de qualitat, seguretat, recuperació i ús real.

Tasques

• Revisió completa de permisos.
• Revisió d'accés per congressos assignats.
• Revisió responsive de backoffice.
• Revisió responsive de web pública.
• Revisió de textos multiidioma.
• Revisió d'errors de consola.
• Revisió de jobs i retries.
• Revisió d'idempotència.
• Revisió d'auditoria.
• Revisió de fitxers privats.
• Revisió de backups.
• Prova real de restauració.
• Revisió de logs.
• Revisió de health checks.
• Revisió de rendiment bàsic.
• Revisió d'exports si entren al MVP.
• Correcció de bugs de validació client.
• Preparació de checklist de pas a producció.

Entregable

MVP complet validable per Geyseco en staging, amb procés de desplegament i recuperació provat.

Criteris d'acceptació

• No hi ha accessos no autoritzats a rutes sensibles.
• Els gestors no veuen congressos no assignats.
• Les cues funcionen.
• Els correus queden registrats.
• Els backups es poden restaurar.
• Les pantalles principals són funcionals en mòbil i sobretaula.
• El client pot executar la vertical completa sense intervenció tècnica.

Proves mínimes

• Suite de tests automatitzada.
• Tests de Policies globals.
• Tests de flux complet d'inscripció.
• Tests de pagaments manuals.
• Tests d'allotjaments.
• Tests de butlletins.
• Tests de web pública.
• Test de restauració documentat.

16. Entregues parcials recomanades

Entrega A - Base tècnica

Inclou Sprint 0 i Sprint 1.

Resultat: backoffice segur, usuaris, rols i base tècnica preparada.

Entrega B - Congrés gestionable

Inclou Sprint 2 i Sprint 3.

Resultat: congressos reals configurables, amb inscripcions preparades.

Entrega C - Primera vertical d'inscripció

Inclou Sprint 4, Sprint 5 i Sprint 6.

Resultat: una persona es pot inscriure, Geyseco pot gestionar la sol·licitud, registrar pagaments manuals i reenviar butlletins.

Entrega D - Allotjament i web pública

Inclou Sprint 7 i Sprint 8.

Resultat: allotjaments, web pública, textos legals i agenda corporativa.

Entrega E - Validació MVP

Inclou Sprint 9.

Resultat: MVP validable i preparat per decisió de posada en producció.

17. Ordre tècnic dins de cada sprint

Per cada sprint, l'ordre recomanat de treball és:

1. Confirmar criteri funcional.
2. Escriure migracions.
3. Crear models i relacions.
4. Crear serveis de domini quan hi hagi regles complexes.
5. Crear Policies.
6. Crear controladors o actions.
7. Crear pantalles Inertia o Blade.
8. Afegir auditoria i outbox si aplica.
9. Afegir tests.
10. Validar responsive i errors de consola.
11. Actualitzar documentació.

18. Estratègia de tests

Tests de backend

• Models i relacions.
• Validacions.
• Serveis de domini.
• Policies.
• Càlculs econòmics.
• Concurrència d'allotjaments.
• Outbox i idempotència.
• Jobs i retries.

Tests de frontend

• Render de pàgines principals.
• Formularis crítics.
• Estats buits.
• Errors de validació.
• Canvi d'idioma.
• Responsive bàsic.

Tests de flux

• Login i accés segons rol.
• Crear congrés.
• Assignar equip.
• Configurar inscripcions.
• Fer inscripció pública.
• Veure sol·licitud al backoffice.
• Registrar pagament.
• Enviar butlletí.
• Afegir allotjament.
• Publicar web.

19. Migracions i dades inicials

Cal preparar seeders inicials per:

• Rols de sistema.
• Usuari Súperadministrador inicial.
• Idiomes base.
• Traduccions de backoffice.
• Textos legals globals.
• Plantilles globals de butlletins.
• Comptes bancaris de prova.
• Congrés pilot si es vol validar amb dades demo.

Les dades demo no han de quedar barrejades amb dades productives.

20. Seguretat mínima

Cal aplicar des del principi:

• Hash segur de contrasenyes.
• Tokens temporals per recuperació.
• CSRF en formularis.
• Rate limiting en login i formularis públics.
• Validació server side sempre.
• Policies a totes les rutes sensibles.
• Fitxers privats per defecte.
• URL temporals per descàrregues.
• Registre d'accés a documentació interna.
• Registre d'accés a exports.
• Separació de permisos per congrés assignat.

21. Operativa mínima de producció

La producció ha de tenir processos separats:

• Nginx.
• PHP-FPM.
• Base de dades.
• Redis.
• Workers Laravel.
• Scheduler Laravel.
• Monitoratge.
• Backups.

El desplegament ha de contemplar:

• Migracions controlades.
• Rollback de codi.
• Reinici ordenat de workers.
• Workers executant la mateixa versió que el codi desplegat.
• Health checks.
• Logs consultables.
• Backup abans de canvis crítics.

22. Riscos principals

Permisos

Risc: confiar massa en la UI.

Mesura: Policies obligatòries i tests d'accés.

Imports

Risc: recalcular imports antics quan canvien tarifes.

Mesura: línies econòmiques congelades.

Pagaments manuals

Risc: perdre rastre de canvis manuals.

Mesura: llibre de moviments, correccions auditables i estat agregat calculat.

Allotjaments

Risc: sobreocupació per reserves simultànies.

Mesura: transaccions i bloqueig coherent d'inventari per nit.

Correus

Risc: perdre confirmacions si falla la cua.

Mesura: outbox transaccional i idempotència.

Multiidioma

Risc: barrejar idioma de backoffice, idioma públic i idioma de comunicació.

Mesura: camps separats i tests de locale.

Web pública

Risc: construir una SPA innecessària i perdre SEO o simplicitat.

Mesura: render servidor amb Blade/SSR i Vue només on aporti valor.

Documentació interna

Risc: exposar documents interns amb URL pública directa.

Mesura: servir documents des del backend amb permís de Súperadministrador.

23. Primer objectiu real de desenvolupament

El primer objectiu real no hauria de ser tenir totes les pantalles dibuixades.

El primer objectiu hauria de ser:

En staging, un Súperadministrador entra al backoffice, crea un congrés, assigna un gestor, configura una quota, publica una web mínima, completa una inscripció pública, veu la sol·licitud al backoffice, registra un pagament manual i envia un butlletí.

Quan aquesta vertical funcioni amb dades persistents, permisos, email, auditoria i responsive, la resta de mòduls es podran ampliar amb molt menys risc.

24. Documents relacionats

• Proposta funcional i arquitectura tècnica.
• Mapa de mòduls i permisos.
• Esquema de base de dades.
• Fluxos principals.