Els cursos tècnics solen fallar pel mateix: cada lliçó ensenya una API aïllada amb un exemple de joguina, i en acabar saps escriure vint fragments que no has vist mai encaixar. Aquest curs funciona a l'inrevés. Tot el que aprenguis a partir d'aquí construirà una única aplicació real, mòdul a mòdul, fins a arribar a una API en producció.

Aquesta aplicació és Escena Viva. Ja n'has vist les dades a les lliçons anteriors; ara la formalitzarem: qui és, a qui serveix, quin és el seu model de domini, quines convencions adopta i —el més important— quina part d'ella construiràs a cadascun dels dotze mòduls. En acabar aquesta lliçó tindràs l'esquelet del projecte creat, el fitxer llavor dades/esdeveniments.json escrit i un mapa clar de la destinació.

1. El context de negoci
2. Els actors i el que necessita cadascun
3. El model de domini
4. El fitxer llavor dades/esdeveniments.json
5. L'estructura de carpetes del repositori
6. Full de ruta: què construeix cada mòdul
7. Convencions del projecte
8. Nota sobre dades fictícies

Escena Viva és una petita empresa que gestiona la venda d'entrades de tres espais culturals d'una ciutat de mida mitjana:

Fins ara, cada sala venia les entrades pel seu compte: una amb un full de càlcul, una altra per telèfon i la tercera amb un sistema heretat que ningú no sap mantenir. Escena Viva neix per unificar-ho tot en una sola plataforma.

Els tres esdeveniments amb què arrenquem —i que ja coneixes— són:

• Concierto de Otoño (Teatro Almendra), 2 sessions a l'octubre del 2026.
• Noche de Monólogos (Sala Bóveda), 3 sessions a l'octubre del 2026.
• Festival de Jazz de Primavera (Auditorio Ribera), 2 sessions a l'abril del 2027.

Els requisits que marquen les decisions tècniques del projecte són aquests:

1. Pics de concurrència brutals i molt curts. Quan s'obre la venda d'un festival, milers de persones hi entren alhora durant deu minuts. La resta del mes el trànsit és modest.
2. L'aforament no es pot sobrevendre. És el requisit dur: dues persones no poden comprar la mateixa butaca.
3. Els preus són diners de veritat. No admeten errors d'arrodoniment.
4. Cal integrar-se amb tercers: passarel·la de pagament, enviament de correu, i en el futur un lector de codis a la porta.
5. L'equip és petit. Dues persones desenvolupen i mantenen tot, així que la simplicitat i la reutilització de coneixement entre client i servidor tenen valor real.

Els punts 1, 4 i 5 són exactament les raons per les quals, a la primera lliçó, vam concloure que Node.js encaixa amb aquest negoci.

Aquesta separació no és decorativa: és la que justificarà el control d'accés basat en rols del Mòdul 8. Un organitzador del Teatro Almendra no ha de poder veure la recaptació de la Sala Bóveda.

Aquestes són les entitats del sistema. Els noms de la columna «identificador» són els que farem servir literalment al codi, en català i sense accents ni ç.

I així es relacionen:

Tres decisions de modelatge que convé entendre des d'ara:

• L'aforament viu a la sessió, no a l'esdeveniment. El Teatro Almendra té 420 localitats, però una sessió concreta en pot treure a la venda només 380 si hi ha una zona reservada per a premsa. La sala aporta el màxim; la sessió, la realitat.
• L'entrada és individual i té codi propi. Una comanda de 4 entrades genera 4 registres entrada, cadascun amb el seu codi únic, perquè cadascun es valida per separat a la porta.
• venudes és un comptador desnormalitzat a la sessió. En rigor es podria calcular comptant entrades, però mostrar la disponibilitat al catàleg ha de ser instantani. Al Mòdul 7 veurem com mantenir aquest comptador coherent amb transaccions.

Fins al Mòdul 7, quan aparegui la base de dades escena_viva, aquest fitxer és la font de dades de tota l'aplicació. Crea dades/esdeveniments.json amb exactament aquest contingut:

JSON no admet comentaris, així que els posem aquí:

Comprova que el fitxer és JSON vàlid abans de continuar:

Si l'ordre falla amb SyntaxError, hi ha una coma de més, una cometa sense tancar o has fet servir cometes simples. En JSON totes les claus i totes les cadenes van entre cometes dobles, i no s'admet coma després de l'últim element.

Encara no sabem llegir aquest fitxer des del codi amb fs —això és el Mòdul 3—, però ja és al seu lloc i ja és la referència. A partir d'aquí, src/cataleg-dades.js deixarà de tenir les dades incrustades.

Aquesta és l'estructura objectiu, la que tindrà el projecte al final del curs. No la creïs sencera ara: creixerà amb cada mòdul.

Principis d'organització que seguirem:

• Una responsabilitat per carpeta. Si no saps on posar un fitxer, probablement fa dues coses.
• src/ conté només codi; dades/ només dades; informes/ només resultats generats. Els resultats generats no es versionen mai.
• Noms de fitxer en minúscules i amb guions (cataleg-dades.js), mai amb espais ni majúscules. Linux distingeix majúscules i minúscules encara que el teu portàtil no ho faci, i això ha trencat més desplegaments dels que es poden comptar.

Aquesta taula és el mapa del curs. Guarda-la: cada vegada que comencis un mòdul sabràs quina peça d'Escena Viva estàs afegint.

Aquestes regles s'apliquen a tot el codi del curs. Escrites una vegada aquí, no les tornarem a discutir.

Variables, funcions, classes, propietats i noms de fitxer van en català, sense accents ni ç: preuCentims, entradesLliures, calcularOcupacio, cataleg-dades.js.

Les excepcions són les que imposa l'entorn: paraules clau del llenguatge (const, class, return), APIs de Node i del navegador (readFile, createServer, map), i noms de paquets (express, mongoose).

Per què sense accents? Perquè un identificador sessió és vàlid en JavaScript però es converteix en una font d'errors tan bon punt viatja per una URL, un nom de fitxer o una capçalera HTTP. Val més evitar-ho d'arrel.

Estil: camelCase per a variables i funcions, PascalCase per a classes, MAJUSCULES_AMB_GUIO_BAIX per a constants globals.

Tota data es desa com a cadena AAAA-MM-DDTHH:mm:ss.

Tres raons:

1. S'ordena correctament com a text, sense convertir a Date.
2. No és ambigu: 03/10/2026 és 3 d'octubre a Catalunya i 10 de març als Estats Units.
3. Sobreviu al viatge per JSON. Un objecte Date es converteix en text en serialitzar i no torna a ser Date en deserialitzar; si ja deses text, no hi ha sorpreses.

El formatatge a 03/10/2026 20:00 és responsabilitat de la capa de presentació, mai de l'emmagatzematge.

Tot import monetari es desa com a nombre enter de cèntims. 2500 significa 25,00 EUR.

El tipus number de JavaScript és un flotant de doble precisió (IEEE 754) i no pot representar exactament 0,1. Amb diners, aquest error s'acumula i acaba en un desquadrament comptable. Treballant amb enters el problema desapareix: només es divideix entre 100 en l'últim moment, per mostrar.

Convenció de noms: qualsevol camp monetari porta el sufix Centims (preuCentims, totalCentims, descompteCentims). Així és impossible confondre's.

Cada entrada té un codi amb el format:

Per què aquest format i no un identificador aleatori llarg?

• És llegible per telèfon. Algú el pot dictar a atenció al client sense errors.
• És ordenable i el seu any és visible a simple vista.
• És curt per imprimir-lo sota un codi de barres.

La contrapartida és que és predictible: si coneixes un codi pots endevinar el següent. Per això el codi no és mai la prova de propietat; la validació a la porta comprova a més l'estat de l'entrada a la base de dades. És una decisió conscient, del tipus que es pren constantment en un projecte real.

Totes les dades d'aquest curs són inventades. Les sales, els esdeveniments, els organitzadors, els correus i les comandes que apareixeran a partir del Mòdul 7 no corresponen a persones ni empreses reals.

Això no és un formalisme: és una pràctica professional que has de traslladar a la teva feina.

• No facis servir mai dades reals de clients en desenvolupament, en proves ni en demostracions. Ni tan sols «només aquesta vegada», ni tan sols una còpia de la base de dades de producció al teu portàtil.
• Les bases de dades de desenvolupament es poblen amb dades sintètiques, generades o anonimitzades. Al Mòdul 7 veurem com escriure llavors per a això.
• Les dades personals estan regulades. Noms, correus, telèfons i dades de pagament tenen obligacions legals de tractament i minimització.
• No pugis mai secrets al repositori: claus de la passarel·la de pagament, contrasenyes de base de dades o tokens. Van en variables d'entorn (Mòdul 11) i per això el .gitignore inclou .env des de la primera lliçó.

Quan al Mòdul 8 registrem l'usuari [email protected], fixa't en el domini .test: està reservat per norma per a proves i no correspondrà mai a una bústia real.

Error 1: desar els preus com a decimals «perquè és més còmode». Ho és durant dues setmanes. Després arriba el primer desquadrament d'un cèntim en un informe de 3.000 comandes i no hi ha manera de saber d'on surt.

Error 2: fer servir formats de data locals a les dades. 03/10/2026 obliga a saber qui ho va escriure per interpretar-ho. ISO 8601 a l'emmagatzematge, format local només en mostrar.

Error 3: posar l'aforament a l'esdeveniment en comptes de a la sessió. Funciona fins a la primera sessió amb aforament reduït, i llavors cal migrar dades.

Error 4: deixar el fitxer JSON amb una única línia gegant. Cada canvi apareix al control de versions com «tota la línia modificada» i les revisions es tornen impossibles. null, 2 sempre.

Error 5: barrejar idiomes als identificadors. getEsdevenimentById, llistarEvents, preuPrice. Tria'n un —en aquest curs, el català— i sigues sistemàtic.

Consell 1: torna al full de ruta en començar cada mòdul. Saber quina peça estàs construint canvia completament la manera d'estudiar una API.

Consell 2: fes servir git des del primer dia. Un git commit en acabar cada lliçó et dona un punt de retorn i un històric del teu propi aprenentatge.

Consell 3: no avancis feina. És temptador muntar ja el servidor Express. Cada mòdul introdueix els conceptes en un ordre pensat; saltar-se'l acaba sovint en codi que funciona sense entendre per què.

Consell 4: quan dubtis, mira el model de domini. Bona part de les decisions de codi es responen soles mirant la taula d'entitats.

Deixa el projecte llest per al Mòdul 2. Ha de complir:

1. La carpeta escena-viva/ conté src/, dades/ i informes/.
2. dades/esdeveniments.json existeix amb els tres esdeveniments i és JSON vàlid.
3. informes/ està sota control de versions encara que sigui buida (pista: .gitkeep).
4. .gitignore exclou node_modules/, .env, *.log i el contingut generat d'informes/ sense excloure la carpeta.
5. .nvmrc conté la versió LTS instal·lada.
6. Existeix un README.md amb el nom del projecte, els tres esdeveniments i les ordres per arrencar.
7. Un primer commit de git amb tot l'anterior.

Escriu la seqüència completa d'ordres i el contingut de cada fitxer.

Afegeix a dades/esdeveniments.json un quart esdeveniment amb aquestes característiques:

• Títol: Cuentos al Anochecer
• Sala: Teatro Almendra (organitzador org-almendra)
• Categoria: familiar, durada 55 minuts, estat publicat
• Tres sessions els dissabtes 7, 14 i 21 de novembre del 2026 a les 18:00
• Aforament 200 a cada sessió (el Teatro Almendra reserva part de la platea per a aquest format)
• Entrades venudes: 200, 145 i 30 respectivament
• Preu: 1200 cèntims les dues primeres i 900 la tercera

Respecta els formats d'id, de data i de preu del projecte. Després, verifica amb ordres node -p que:

1. El fitxer continua sent JSON vàlid i té 4 esdeveniments.
2. El catàleg té ara 10 sessions.
3. L'aforament total del Teatro Almendra (sumant tots els seus esdeveniments) és correcte.
4. Hi ha exactament una sessió exhaurida.

Un company ha escrit aquest fragment. Reescriu-lo respectant totes les convencions del projecte i explica cada canvi.

Solució 1

.gitignore (punt 4). La clau és l'excepció amb !, per ignorar el contingut però conservar la carpeta:

README.md (punt 6):

Verificació i primer commit (punts 2 i 7):

Solució 2

Bloc que cal inserir al final de l'array de dades/esdeveniments.json (recorda la coma després de la clau de tancament de l'esdeveniment anterior):

Verificacions:

Nota sobre el punt 4: ses-002-1 té 118 de 120 venudes, així que no està exhaurida. L'única exhaurida és la primera sessió de l'esdeveniment nou.

Solució 3

Canvis aplicats i el seu motiu:

Comprovació del càlcul: 118 × 1800 + 45 × 1800 = 212.400 + 81.000 = 293.400 cèntims = 2.934,00 EUR. Amb preus decimals el resultat hauria estat el mateix en aquest cas concret, però n'hi ha prou amb un preu de 18,99 i uns centenars d'operacions perquè comencin a aparèixer cèntims fantasma.

Escena Viva ja no és un decorat: és un projecte amb context, actors, model de domini, dades i regles pròpies. Has vist qui fa servir la plataforma —assistent, organitzador i administrador— i com aquesta separació anticipa el control per rols; has formalitzat les entitats esdeveniment, sessio, entrada, comanda, usuari, organitzador i sala, amb les seves relacions i els seus estats; has escrit el fitxer llavor dades/esdeveniments.json que serà la font de dades fins que aparegui la base de dades escena_viva; i has fixat les convencions que no es tornaran a discutir: identificadors en català sense accents, dates ISO 8601, preus en cèntims com a enter, codis d'entrada EV-2026-000123, JSON amb null, 2 i dades sempre fictícies.

Sobretot, tens el full de ruta. Saps que al Mòdul 3 el catàleg deixarà d'estar incrustat al codi per llegir-se de disc, que al Mòdul 4 es traurà el nas per HTTP, que al Mòdul 7 es mudarà a una base de dades amb transaccions que impedeixin sobrevendre l'aforament, i que al Mòdul 10 aprendràs a sostenir el pic de trànsit de l'obertura de venda d'un festival.

Amb això tanquem el Mòdul 1. Tens l'entorn instal·lat amb una versió LTS gestionada per .nvmrc, saps executar i depurar un script, manejes el REPL com a laboratori, domines el JavaScript modern que farem servir i tens el projecte dret amb la seva llavor de dades.

El que encara no saps és com funciona Node.js per dins, i és la peça que falta per escriure codi de servidor de debò. Al Mòdul 2: Conceptes Bàsics obrirem la caixa: l'arquitectura de Node, el bucle d'esdeveniments i les seves fases, els callbacks, les promeses i async/await, els esdeveniments amb EventEmitter i el sistema de mòduls amb require i module.exports. Allà, per fi, l'array d'esdeveniments incrustat a src/cataleg-dades.js es convertirà en un mòdul reutilitzable, naixeran les classes Esdeveniment i Sessio a src/domini/, i el cambrer que no espera de la primera lliçó deixarà de ser una analogia per convertir-se en el codi que escrius.