El mòdul anterior va tancar el recorregut tècnic i va acabar amb una promesa: construir CicloUrbano sencer, de principi a fi, amb Vite i React Router. Aquesta lliçó és el primer pas, i és el que més gent es salta: abans d'escriure una línia de JSX cal saber què es construeix, per a qui, amb quines dades i amb quines decisions tècniques. Un projecte que comença per npm create vite sense haver respost aquestes preguntes acaba, sense excepció, refactoritzant-se a mig camí.

Faràs tres coses, en aquest ordre. Primer, definir el producte: l'abast en una frase, les dues persones usuàries, les històries amb els seus criteris d'acceptació i —tan important com l'anterior— la llista explícita del que no entra a la primera versió. Segon, fixar les decisions d'arquitectura en una acta que justifiqui cada elecció i anomeni l'alternativa descartada, perquè d'aquí a tres mesos ningú no hagi de reconstruir el raonament. I tercer, muntar el bastiment real: Vite, dependències, scripts, linter, formatador, variables d'entorn, estructura de carpetes, json-server sembrat i un primer commit que ja arrenca.

En acabar tindràs un repositori que es clona, s'instal·la i s'executa, amb l'API de desenvolupament responent i sense ni una sola pantalla escrita. Les pantalles són la lliçó següent.

1. El producte en una frase
2. Persones usuàries i els seus objectius
3. Històries d'usuari i criteris d'acceptació
4. El que queda fora de la primera versió, i per què
5. Model de dades definitiu
6. El db.json inicial complet
7. Mapa de pantalles i arbre de rutes
8. L'acta de decisions d'arquitectura
9. Crear el projecte amb Vite
10. Dependències: què s'instal·la i per què
11. El package.json complet
12. Qualitat del codi: ESLint, Prettier i .editorconfig
13. Variables d'entorn amb import.meta.env
14. Estructura de carpetes: per tipus o per funcionalitat
15. L'API de desenvolupament: json-server en marxa
16. Convencions de l'equip
17. El pla de treball: increments verticals
18. El primer commit

Si no pots descriure el que construeixes en una frase, encara no saps el que construeixes. La d'aquest projecte:

CicloUrbano és una aplicació web privada que permet a una persona client reservar bicicletes d'una xarxa urbana per estacions, i a una persona operària mantenir l'estat de la flota.

Aquesta frase carrega més informació de la que sembla:

La paraula «privada» és la que decideix l'arquitectura de renderitzat, i ho fa abans que es discuteixi cap eina. Hi tornarem a l'apartat 8.

Dues persones, ni una més. Un producte amb cinc perfils a la primera versió no en té cap ben resolt.

D'aquest quadre en surten dues conseqüències de disseny que ja no es discuteixen després:

• La pantalla d'inici és el catàleg, no un tauler de control. El client és qui més hi entra, i hi entra amb pressa.
• El taller és una pantalla a part amb accés per rol, no un mode ocult del catàleg. Barrejar els dos usos en una pantalla obligaria a amagar controls per permís a cada targeta, que és exactament el tipus de complexitat que es paga durant anys.

Una història d'usuari té una forma fixa —com a X vull Y per a Z— i només serveix si porta criteris d'acceptació comprovables. «Que el catàleg funcioni bé» no és un criteri; «en filtrar per elèctrica només apareixen les de tipus electrica» sí que ho és. A 11-04 cadascun d'aquests criteris es convertirà en una prova, i per això estan redactats així des d'avui.

La distinció no és cosmètica: si el termini s'escurça, es talla per D1-D4 sense tocar H1-H8. Tenir aquesta línia traçada abans de començar és el que impedeix que un projecte entregui deu coses a mitges en lloc de vuit acabades.

Aquesta llista és tan important com l'anterior, i convé escriure-la i compartir-la, perquè el que no està escrit s'acaba demanant a mig projecte.

Fixa't en l'última fila. Decidir que alguna cosa està fora no és decidir que mai es farà: és decidir que no competeix pel temps d'aquesta versió, i de passada deixar anotat com es faria si arriba el moment.

Quatre entitats. Les coneixes de tot el curs; aquí queden fixades amb les seves relacions.

Tres decisions del model que convé entendre abans de codificar:

1. Les relacions es guarden per identificador, mai imbricant l'objecte sencer. Una reserva guarda bicicletaId, no una còpia de la bicicleta. Si s'imbriqués, el preu de la reserva quedaria congelat en el moment de crear-la i qualsevol canvi a la bicicleta deixaria còpies desincronitzades per tota la base de dades. És la mateixa normalització que es va aplicar a l'estat de Redux a 07-04, i pel mateix motiu.
2. L'estat és una cadena d'un conjunt tancat, no un booleà. disponible | alquilada | mantenimiento admet un quart estat el dia que calgui; disponible: true/false obliga a afegir un altre booleà i a raonar sobre combinacions impossibles.
3. El camp de la reserva es diu usuari i conté un identificador. És una incoherència de nom respecte a bicicletaId, i es conserva perquè així es va fixar a tot el curs: canviar-ho ara trencaria validarReserva, les proves i els gestors de MSW. S'anota com a deute tècnic menor a l'acta, que és exactament el que es fa en un projecte real amb una incoherència innòcua ja estesa.

Aquest fitxer és la base de dades de desenvolupament i, alhora, la llavor que 11-04 restaurarà abans de cada prova d'extrem a extrem. Va a l'arrel del repositori.

El conjunt està triat perquè cada estat i cada cas límit tingui almenys un representant, que és la propietat que ha de complir qualsevol joc de dades de desenvolupament:

Aquest penúltim cas és el que més s'oblida i el que més errors produeix: si mai no veus la llista buida en desenvolupament, no la dissenyes, i l'usuari que estrena l'aplicació es troba un buit en blanc.

Les rutes van quedar fixades al mòdul 6. Aquí es comprova que cadascuna serveix una història i que cap història es queda sense pantalla.

I la taula de cobertura, que és la que es revisa per detectar buits:

Un detall que canvia respecte al mòdul 6: /reservas entra dins de la branca protegida. En el seu moment es va deixar pública per no complicar els exemples; al projecte real, veure reserves exigeix sessió, perquè són dades personals. És el tipus d'ajust que apareix just en fer aquesta taula, i per això es fa la taula.

Aquest és el document més valuós de la lliçó. Cada fila registra què es decideix, per què, i què es descarta. Es desa al repositori com a DECISIONS.md i s'actualitza quan alguna cosa canvia; mai no s'esborra una fila, s'afegeix la nova amb la seva data.

I l'assignació d'estat, que és l'aplicació literal de la taxonomia de 07-01 a aquest projecte:

Amb l'acta signada, el bastiment és mecànic.

Què ha fet cada línia:

• npm create vite@latest descarrega i executa el generador oficial. El -- separa els arguments de npm dels del generador; sense ell, npm intentaria interpretar --template com a seu.
• --template react tria la plantilla de React amb JavaScript. Existeix react-ts per a TypeScript i react-swc per usar SWC en lloc de Babel; amb React 19 i el complement oficial, la diferència de velocitat en un projecte d'aquesta mida és irrellevant.
• npm run dev aixeca el servidor de desenvolupament a http://localhost:5173.

Comprova la versió de React abans de seguir, perquè el projecte assumeix React 19:

Res no s'instal·la «perquè sí». Cada paquet respon a una fila de l'acta.

La distinció entre dependencies i devDependencies no és burocràcia: el que hi ha a dependencies pot acabar al paquet que es descarrega l'usuari. Posar json-server o Cypress allà no trencaria el build de Vite, però sí que engreixa qualsevol instal·lació de producció i dona un senyal fals sobre el que l'aplicació necessita per funcionar.

Els scripts es mereixen un comentari, perquè són la interfície del projecte per a qualsevol que arribi nou:

El --max-warnings 0 de lint és deliberat: un avís que no trenca res s'acumula fins que n'hi ha cent vint i ningú els mira. O importen i fallen, o es desactiva la regla.

Vite genera un eslint.config.js bàsic. Aquest és el del projecte, amb les dues addicions que exigeix l'acta: accessibilitat i regles de hooks.

Tres punts que cal entendre, no copiar:

• react-hooks/exhaustive-deps com a error, no com a warn. És la decisió més discutida de qualsevol configuració de React i aquí es pren a consciència: a 05-02 es va veure que una dependència omesa produeix dades obsoletes que no fallen en desenvolupament i sí en producció. Com a avís, s'ignora; com a error, obliga a resoldre'l o a justificar l'excepció amb un comentari eslint-disable-next-line que queda visible a la revisió de codi.
• jsx-a11y en mode recomanat. Caça a l'editor la imatge sense alt, l'onClick sobre un div sense rol ni teclat, i l'etiqueta sense control associat. No substitueix la revisió manual de 03-06, però elimina el 80 % dels errors habituals abans que existeixin.
• prettier va l'últim de l'array. eslint-config-prettier no afegeix regles: desactiva les d'ESLint que xoquen amb el formatat. Si es posés abans, les regles posteriors les tornarien a activar i tindries el linter i el formatador barallant-se a cada desada.

.editorconfig és el que evita el clàssic «el fitxer sencer apareix modificat al diff» quan algú treballa amb Windows: fixa els finals de línia i la indentació a nivell d'editor, abans que Prettier hi intervingui.

La URL de l'API no pot estar escrita a mà en quinze fitxers. Vite exposa les variables d'entorn a través d'import.meta.env, amb una regla estricta: només les que comencen per VITE_ arriben al codi del client.

Per què un mòdul configuracio.js en lloc de llegir import.meta.env allà on calgui:

1. Un únic punt de veritat. El dia que la variable canviï de nom, es toca un fitxer.
2. Valors per defecte en un sol lloc, amb ??, perquè clonar el repositori i oblidar-se del .env no trenqui l'arrencada.
3. Es pot substituir a les proves amb un vi.mock d'un mòdul propi; amb import.meta.env escampat, no.

I l'avís que es repetirà a 11-05 amb totes les lletres: import.meta.env és text que s'incrusta al JavaScript que es descarrega el navegador. Qualsevol persona pot llegir-lo amb dos clics. Una clau d'API privada, una contrasenya o un testimoni d'administració no hi van mai, ni tan sols «temporalment mentre provem».

Hi ha dues escoles, i totes dues tenen raó en el seu context:

CicloUrbano adopta un híbrid, que és el que fa la majoria de projectes reals d'aquesta mida: per tipus el que és compartit, per funcionalitat l'estat de domini. Aquesta última part ja venia decidida des de 07-05.

Dues regles de col·locació que eviten la majoria de les discussions:

• Un fitxer de prova viu al costat del codi que prova (TargetaBicicleta.jsx i TargetaBicicleta.test.jsx a la mateixa carpeta). Només la infraestructura de proves és a src/proves/. Així, en esborrar un component, la seva prova se'n va amb ell.
• Un component puja a components/ quan l'usa la segona pantalla, no abans. Fins llavors viu al costat de la seva pàgina. Generalitzar amb un sol cas d'ús produeix abstraccions equivocades.

Comprovació obligatòria abans de seguir. Si això no respon, cap pantalla d'11-03 funcionarà i perdràs una hora buscant l'error a React:

El que json-server dona de sèrie i el projecte aprofitarà:

I el que no dona, i cal tenir present des d'ara: no valida res, no autentica ningú i no comprova permisos. Un PATCH des de la consola del navegador canvia l'estat de qualsevol bicicleta sense sessió. És acceptable en desenvolupament i és la raó per la qual 11-05 insisteix que l'autorització de veritat es comprova sempre al servidor.

Escrites al README.md, perquè una convenció que només és al cap de qui la va inventar no és una convenció.

Noms

Exportacions: export default per a components i pàgines; exportació amb nom per a hooks, utilitats, slices i selectors. Barrejar els dos criteris en el mateix tipus de fitxer és el que produeix importacions inconsistents.

Ordre d'importacions, sempre el mateix, amb línia en blanc entre grups:

Missatges de commit, en format convencional, en català i en imperatiu:

El prefix no és decoració: permet generar el registre de canvis automàticament i, sobretot, obliga que un commit faci una sola cosa. Si dubtes entre feat i fix, probablement el commit contingui dos canvis i calgui partir-lo.

Aquí hi ha la decisió de mètode que més influeix en com se sent el projecte mentre es construeix.

Es tria vertical, amb una salvetat honesta: aquest mòdul està organitzat per capes —interfície, estat, proves, desplegament— perquè explicar requereix agrupar conceptes, mentre que construir requereix entregar valor aviat. És una diferència important i convé tenir-la clara: l'ordre del llibre no és l'ordre del taller.

Tot i així, dins de cada lliçó es treballa per històries completes. I si estiguessis fent aquest projecte en un equip real, l'ordre seria aquest:

I l'ordre de les històries, prioritzat per risc primer:

1. H4 (accés) abans que res: és la porta de tota la resta i toca sessió, formulari, redirecció i persistència. Si alguna cosa ha de sortir malament en l'arquitectura, surt malament aquí.
2. H1 + H2 (catàleg i filtre): la pantalla més visitada, i la que valida la capa de dades.
3. H5 (reservar): el camí dels diners. Toca mutació, validació, invalidació i navegació.
4. H6 (les meves reserves i cancel·lar): reutilitza gairebé tot l'anterior.
5. H3, H8 (fitxa i estacions): lectura pura, poc risc.
6. H7 (taller): el rol es prova amb tota la resta ja en peu.
7. D1-D4 si queda temps.

La regla que governa la llista: el que pot enfonsar el projecte va primer. Deixar la identificació per al final és l'error clàssic, perquè és justament la funcionalitat que travessa totes les capes i obliga a refer el que ja s'havia donat per bo.

Un commit inicial ha de complir una condició: qui el cloni, el pot arrencar.

I el README.md que l'acompanya, que és el primer que llegeix qualsevol:

npm install cp .env.example .env npm run dev:todo # Vite a :5173 i json-server a :3001

La llista de comprovació abans de donar el bastiment per acabat:

• [ ] npm install funciona en un clon net
• [ ] npm run dev serveix l'aplicació al 5173
• [ ] npm run api respon al 3001 amb els quatre recursos
• [ ] npm run lint acaba sense errors ni avisos
• [ ] .env està ignorat i .env.example versionat
• [ ] DECISIONS.md té les deu files de l'acta
• [ ] El README.md permet arrencar sense preguntar res a ningú

• Començar pel codi i planificar sobre la marxa. És l'error de fons d'aquesta lliçó. Sense històries amb criteris d'acceptació no saps quan has acabat, i sense acta de decisions cada discussió tècnica es repeteix cada dues setmanes. Mitja jornada de planificació estalvia setmanes.
• Històries sense criteris comprovables. «El catàleg ha de ser ràpid» no es pot verificar ni convertir en prova. «El catàleg mostra l'esquelet mentre carrega i la llista tan bon punt arriben les dades» sí.
• No escriure el que queda fora. L'abast que no es nega explícitament s'assumeix inclòs. La taula de l'apartat 4 és la que protegeix l'entrega.
• Imbricar objectes en el model de dades. Guardar la bicicleta sencera dins de la reserva sembla còmode el primer dia i produeix dades desincronitzades el segon. Identificadors, sempre.
• Un joc de dades de desenvolupament sense casos límit. Si totes les bicicletes estan disponibles i tots els usuaris tenen reserves, mai no veuràs l'estat buit ni el botó deshabilitat, i arribaran trencats a producció.
• Posar eines de desenvolupament a dependencies. Cypress i json-server en producció són un símptoma que ningú no ha mirat el package.json des que es va generar.
• Deixar exhaustive-deps com a avís. Amb el temps se n'acumulen desenes i deixen de llegir-se. Com a error, es resol o es justifica amb un comentari visible.
• Posar eslint-config-prettier en qualsevol posició menys l'última. Deixa de fer efecte i acabes amb el linter i el formatador en conflicte a cada desada.
• Secrets en variables VITE_. Tot el que comença per VITE_ viatja al navegador en text pla. No hi ha excepció, ni «només mentre provem».
• Consell: crea DECISIONS.md des del primer dia i afegeix una fila cada vegada que discuteixis una elecció tècnica. El valor no és al document, és a no tornar a tenir la mateixa conversa.
• Consell: verifica l'API amb curl abans d'escriure el primer fetch. Descartar la meitat del sistema en trenta segons estalvia depuracions llarguíssimes.

Exercici 1. El client demana una història nova: «com a client vull rebre un avís 10 minuts abans que acabi la meva reserva». Escriu-la amb el format de l'apartat 3, amb criteris d'acceptació comprovables. Després decideix si és imprescindible o desitjable, i si entra o no a la primera versió, justificant-ho amb l'abast de l'apartat 1 i la taula de l'apartat 4. Si decideixes deixar-la fora, redacta la fila corresponent.

Exercici 2. L'equip proposa afegir una entitat Incidencia per a la pestanya d'incidències de /estaciones/:estacionId, amb la informació d'una avaria reportada. Defineix els seus camps i les seves relacions, afegeix-la al diagrama d'entitat-relació i al db.json amb dos registres d'exemple coherents amb el cànon, i explica quins recursos nous apareixerien a json-server. Indica a més quina clau de TanStack Query li correspondria segons la fàbrica del projecte.

Exercici 3. Un company proposa tres canvis sobre l'acta: (a) usar BrowserRouter amb <Routes> perquè «és més senzill», (b) guardar la llista de bicicletes a Redux «per tenir-ho tot en un lloc», i (c) posar la clau d'un servei de mapes a VITE_CLAU_MAPES per usar-la des del client. Respon a cadascun amb l'argument tècnic corresponent i digues quina fila de l'acta ho cobreix. Per al tercer, explica a més què caldria per usar aquest servei sense exposar la clau.

Solució 1.

Classificació: desitjable (D5), fora de la primera versió. Els tres arguments:

1. No bloqueja l'objectiu principal de cap de les dues persones. Ana pot reservar i usar la bicicleta sense l'avís; Marc no el necessita en absolut.
2. L'avís realment útil és el que arriba amb l'aplicació tancada, i això són notificacions push, que estan explícitament fora d'abast per exigir servidor, permisos i service worker. Un avís que només es veu amb la pestanya oberta resol una fracció petita del problema real i pot donar una falsa sensació de cobertura.
3. Requereix un temporitzador global que reavaluï cada minut i una font de veritat de l'hora actual, cosa que complica les proves (cal fixar el rellotge) per a un benefici marginal en aquesta versió.

Fila per a la taula de l'apartat 4:

I l'anotació honesta: quan arribi l'API real, aquesta història puja a imprescindible, perquè el negoci penalitza la devolució tardana i avisar és més barat que cobrar recàrrecs.

Solució 2.

Camps i relacions. Una incidència pertany a una bicicleta (que al seu torn és en una estació) i la reporta un usuari:

Registres per a db.json, coherents amb el cànon —bici-003 és en manteniment, així que és la candidata natural a tenir una incidència oberta, i bici-002 pot tenir-ne una ja resolta:

Decisió de modelatge important: la incidència s'associa a la bicicleta, no a l'estació, encara que la pestanya que la mostra sigui la d'una estació. El motiu és que una avaria viatja amb la bicicleta: si bici-003 es trasllada a est-03, el seu historial ha d'anar amb ella. La pestanya d'incidències d'una estació s'obté llavors derivant: les bicicletes d'aquesta estació, i les incidències d'aquestes bicicletes. Modelar la relació al revés obligaria a reescriure l'estacionId de cada incidència a cada trasllat.

Recursos que apareixen a json-server:

I la clau de consulta, aprofitant que la fàbrica del projecte ja l'havia previst:

La jerarquia importa: invalidar ['estaciones', 'est-02'] invalida també ['estaciones', 'est-02', 'incidencias'], perquè TanStack Query compara les claus per prefix. És justament el comportament que es vol en resoldre una incidència.

Solució 3.

(a) BrowserRouter amb <Routes>. Cobert per la fila A2. És cert que és més senzill d'escriure, però el projecte necessita tres coses que aquest mode no dona:

• errorElement per branca: sense ell, un error en carregar la fitxa d'una bicicleta enfonsa tota l'aplicació en lloc de deixar la capçalera i el menú drets. És la diferència entre una pantalla en blanc i un error contingut.
• lazy a nivell de ruta amb l'enrutador gestionant la càrrega, que és el que fa possible la divisió de codi de 08-04 sense embolicar cada pantalla a mà.
• L'API de dades (useNavigation, useRouteError, handle per a les molles de pa), que ja s'usa a MollesDePa.

I l'argument decisiu: migrar després costa més que començar bé, perquè implica reescriure l'arbre de rutes sencer quan ja hi ha pantalles al damunt.

(b) La llista de bicicletes a Redux. Cobert per A3 i per la taula d'assignació d'estat. «Tenir-ho tot en un lloc» sona a ordre, però barreja dues coses de naturalesa diferent: les bicicletes són estat del servidor, una còpia local d'una dada que viu en una altra màquina i que pot canviar sense que l'aplicació se n'assabenti. Ficar-les a Redux obliga a escriure a mà, i a mantenir, tot això:

És exactament la feina que 07-06 va mostrar que no val la pena reescriure. Redux es queda amb el que sí que és seu: sessió, terme de cerca i ordre.

(c) La clau del servei de mapes a VITE_CLAU_MAPES. És el més greu dels tres. Tot el que comença per VITE_ se substitueix literalment al codi durant la construcció i acaba en un fitxer de dist/ que qualsevol pot obrir:

No hi ha ofuscació que ho arregli: el navegador ha de poder llegir-la per usar-la, per tant l'usuari també. Les conseqüències són consum facturat al teu compte i, segons el servei, accés a dades que no haurien de sortir.

Què fer en el seu lloc, per ordre de preferència:

1. Que la petició al servei surti del servidor. El client crida la teva API, la teva API crida el servei amb la clau i retorna el resultat. La clau mai no surt de la màquina.
2. Si el servei està pensat per al client —molts proveïdors de mapes ofereixen claus públiques—, usar aquest tipus de clau i restringir-la al tauler del proveïdor per domini d'origen, per quota i per permisos mínims. Continua sent visible, però només funciona des del teu domini i amb un sostre de despesa.
3. Mai usar una clau amb permisos d'escriptura o de facturació des del client, en cap circumstància.

I com que l'exercici parteix d'una història que està fora d'abast —el mapa geogràfic—, la resposta completa inclou recordar-ho: no cal resoldre el problema de la clau encara, perquè la funcionalitat no entra en aquesta versió.

Aquesta lliçó ha convertit una idea en un projecte que es pot començar a construir, i ho ha fet en l'ordre correcte: primer el producte, després les decisions, i només al final les eines.

Del producte queda fixat l'essencial: CicloUrbano en una frase que ja decideix l'arquitectura en declarar-se privada, dues persones usuàries amb objectius i contextos diferents que justifiquen per què l'inici és el catàleg i el taller una pantalla a part, vuit històries imprescindibles i quatre desitjables amb criteris d'acceptació comprovables —que a 11-04 es convertiran literalment en proves—, i una llista explícita del que queda fora amb el seu motiu, que és la que protegeix l'entrega quan algú proposi afegir un mapa a mig camí.

Del domini queda el model definitiu amb les seves quatre entitats i tres regles que es respecten sense excepció: relacions per identificador i mai objectes imbricats, estats com a cadena d'un conjunt tancat en lloc de booleans, i les incoherències heretades anotades com a deute en comptes d'arreglades a destemps. El db.json no és un munt de dades de farciment: cada estat, cada cas límit i l'estat buit tenen el seu representant, perquè el que no es veu en desenvolupament no es dissenya.

Del rumb tècnic queda l'acta de decisions, deu files amb la seva justificació i la seva alternativa descartada: Vite en lloc de Next.js perquè l'aplicació és privada i interactiva; React Router en mode de dades per errorElement, lazy i l'API de dades; TanStack Query per al servidor i Redux Toolkit per al client, amb context per a tema i avisos i la URL per al filtre; CSS Modules; el quartet Vitest, Testing Library, MSW i Cypress; i JavaScript ara amb la porta oberta a TypeScript. Junt amb l'acta, la taula d'assignació d'estat que respon per endavant a la pregunta que més vegades es repeteix en un projecte de React: on viu aquesta dada?

I del bastiment queda un repositori funcionant: Vite amb React 19, dependències triades una a una i ben separades entre producció i desenvolupament, un package.json amb catorze scripts que són la interfície del projecte, ESLint amb jsx-a11y i exhaustive-deps elevat a error, Prettier l'últim de la cadena, .editorconfig, .gitignore, variables d'entorn centralitzades a configuracio.js amb .env.example versionat i cap secret, una estructura de carpetes híbrida —per tipus el que és compartit, per funcionalitat l'estat de domini—, json-server sembrat i verificat amb curl, les convencions de l'equip escrites al README.md, i un pla de treball per increments verticals que ataca primer el que té més risc.