Durant deu mòduls has tingut un exemple guiat: Nómada Tasques es construïa davant teu, lliçó a lliçó, i cada concepte nou arribava amb el seu tros de codi ja pensat. Això s'acaba aquí. En aquest mòdul construeixes el teu propi producte, sol, amb el mateix mètode i sense que ningú et doni el codi. Nómada Tasques no desapareix: passa a ser la referència —sis tasques, 48 hores, regles R1–R10, 124 proves, 58,3 kB en tres peticions, LCP d'1,9 s— contra la qual compararàs el que facis. I aquesta primera lliçó no escriu ni una línia de lògica de negoci a propòsit, perquè l'error més car d'un projecte propi no és un undefined inesperat: és començar a programar sense saber què s'està construint. Aquí aprendràs a convertir una idea en un pla defensable: triar el producte, retallar-lo fins a un MVP honest i escriure negre sobre blanc el que no faràs; redactar històries d'usuari amb criteris d'acceptació i prioritzar-les amb MoSCoW; dissenyar el model de dades i les regles de negoci —les noves R11 a R15— abans de tocar l'editor; decidir l'arquitectura per capes i les fronteres que no es creuen; muntar el repositori, la cadena d'eines i el flux de Git; planificar en fites amb un Gantt i una estimació que no t'enganyi; i fixar des del minut zero la Definició de Fet i el pressupost de rendiment i accessibilitat. En acabar tindràs tres lliurables reals: el document d'abast, el model de dades amb les seves regles, i un repositori inicialitzat i verd.

1. Què canvia a partir d'ara
2. El producte per defecte: Òrbita
3. Tres alternatives de domini amb el mateix mètode
4. Delimitar l'abast: el MVP
5. La llista del que NO es farà
6. Històries d'usuari amb criteris d'acceptació
7. Prioritzar amb MoSCoW
8. El model de dades, escrit abans de programar
9. Les regles de negoci noves: R11 a R15
10. L'arquitectura per capes i les fronteres que no es creuen
11. L'entorn: repositori i cadena d'eines
12. L'estructura de carpetes de partida
13. Git de debò: branques, commits i revisions
14. Fites i estimació honesta
15. La Definició de Fet
16. El pressupost de rendiment i accessibilitat
17. La plantilla de README.md
18. Errors Habituals i Consells
19. Exercicis
20. Conclusió

Fins a la lliçó 10-06, el curs funcionava així: s'explicava un concepte, s'aplicava a Nómada Tasques, i el codi apareixia. Tu el llegies, l'entenies, l'adaptaves als exercicis. És la manera correcta d'aprendre els fonaments, i és exactament el que calia fer.

Però hi ha una diferència enorme entre entendre codi aliè i produir codi propi des de zero, i no se salva llegint més. Se salva construint. Aquest mòdul és aquesta construcció.

A partir d'aquí canvien tres coses:

Aquest últim punt mereix èmfasi. L'habilitat que separa qui sap JavaScript de qui és desenvolupador no és conèixer més mètodes d'array: és acabar coses. Acabar significa que funciona, que està provat, que es pot desplegar, que una altra persona ho entén i que tu pots defensar per què està fet així. Aquest és el llistó d'aquest mòdul.

I hi ha un advertiment honest que convé llegir a poc a poc. La part difícil d'un projecte propi no és tècnica. És que ningú no et diu quan has acabat, ningú no et corregeix l'abast quan creix, i ningú no t'avisa que portes tres dies polint una animació mentre la funcionalitat principal continua a mitges. El mètode d'aquesta lliçó existeix precisament per posar aquestes baranes abans que les necessitis.

El producte per defecte d'aquest mòdul es diu Òrbita. És una aplicació de gestió de treball per a equips petits: la mateixa família que Nómada Tasques, però clarament més ambiciosa, amb sis extensions que al curs no es van implementar mai i que hauràs de resoldre pel teu compte.

Nota sobre les dades. Òrbita, els seus usuaris d'exemple i qualsevol organització que aparegui a les teves dades de prova han de ser ficticis. No facis servir noms, correus ni dades reals de companys, clients o familiars, ni tan sols «per provar»: així que això arriba a un repositori públic o a un desplegament, deixa de ser una prova i passa a ser un tractament de dades personals. A la lliçó 11-03 i a la 11-05 hi tornarem amb detall.

Les sis extensions sobre Nómada Tasques són aquestes:

Cap de les sis és decorativa. Cadascuna obliga a resoldre un problema real que Nómada Tasques esquivava:

• E1 trenca la simplificació de responsable: 'Iván'. Així que hi ha entitats referenciades, apareixen la integritat referencial (què passa amb les tasques d'un usuari que s'esborra?) i els permisos.
• E2 converteix una llista plana en un arbre. Tot el que era array.filter(...) passa a necessitar recorregut recursiu, i les hores totals deixen de ser una suma directa.
• E3 sembla trivial i no ho és: combinar N filtres amb dues semàntiques diferents i mantenir-los a la URL (06-04, encaminador) exigeix pensar l'estat.
• E4 és la primera vista que no és una llista, i per tant la primera que no pots resoldre copiant TaulerVista.
• E5 és la primera funcionalitat que produeix un fitxer, amb tot el que això implica: format, codificació, noms, i el fet que un CSV mal escapat es trenca així que un títol porta una coma.
• E6 introdueix dades immutables i creixents, que és exactament el tipus de dada que fa esclatar localStorage (lliçó 11-03).

Òrbita en una frase, que és com hauries de poder descriure qualsevol producte:

Òrbita és una aplicació web que permet a un equip petit planificar la seva feina en tasques i subtasques, veure qui està sobrecarregat i quan vencen les coses, i saber en tot moment qui va canviar què.

Si no pots escriure aquesta frase per al teu producte, encara no saps què estàs construint.

Si el domini de les tasques t'avorreix —és una raó perfectament legítima; hi passaràs setmanes—, tria'n un altre. El mètode és idèntic i el mòdul sencer funciona igual. Aquestes són les tres alternatives proposades, cadascuna amb el mapatge de les sis extensions:

Fixa't en l'última fila: cada domini té una regla dura característica que és la que dona personalitat al model i la que més proves necessitarà. A Aforament és l'encavalcament d'intervals, que és un problema clàssic i força més subtil del que sembla. A Ratxa és la unicitat per dia, que obliga a pensar zones horàries. A Prestatgeria és una invariant numèrica que cal defensar a totes les operacions.

Criteri per triar, en ordre d'importància:

1. Que t'importi. Hi dedicaràs moltes hores i ningú no t'hi obligarà. La motivació és un recurs de projecte tan real com el temps.
2. Que el puguis ensenyar a algú. Si en una entrevista pots explicar el domini en trenta segons, serveix.
3. Que tingui almenys una regla dura no trivial. Un CRUD sense regles no demostra res; és el projecte que fa tothom.
4. Que hi càpiga. Si la teva idea és «com Jira però millor», no hi cap. Retalla-la fins que hi càpiga, que és justament l'apartat següent.

A la resta del mòdul faré servir Òrbita a tots els exemples, però cada plantilla és directament reutilitzable amb qualsevol dels altres tres dominis. Quan vegis una taula o una plantilla, substitueix-ne els noms i continua.

MVP són les sigles de Minimum Viable Product: producte mínim viable. Les dues paraules importen i gairebé sempre se n'entén malament una de les dues.

• Mínim no vol dir «xusquer». Vol dir que no hi ha res que puguis treure sense que deixi de resoldre el problema.
• Viable no vol dir «una demo». Vol dir que algú el podria fer servir de debò per al que promet.

Un MVP d'Òrbita que no permetés marcar una tasca com a feta seria mínim però no viable. Un que tingués temes de color, dreceres de teclat personalitzables i notificacions per correu seria viable però no mínim.

La prova que faig servir per decidir si una cosa entra al MVP és una sola pregunta:

Si això no hi fos, el producte continuaria servint per al que diu la seva frase?

Si la resposta és «sí, incòmode però serveix», no és MVP. Va a la versió 1.1.

Aplicat a Òrbita, aquest és el tall:

De 15 candidats, 8 hi entren. Aquesta proporció (aproximadament la meitat) és normal i saludable. Si el teu MVP conté el 90 % del que se t'ha acudit, no has retallat: has fet una llista de desitjos.

Una regla pràctica de mida, contrastada: un MVP de projecte personal hauria de ser una cosa que puguis construir en 6 a 10 setmanes dedicant-hi entre 6 i 10 hores setmanals. Si la teva estimació honesta (apartat 14) dona més, retalla ara, perquè la teva estimació és optimista, no pessimista.

Aquesta és la secció del document d'abast que més gent es salta i la que més projectes salva. Un MVP definit només pel que inclou és ambigu: tot el que no s'esmenta queda en una zona grisa on, un dimarts a la tarda, et semblarà raonable afegir «només una coseta».

Escriure explícitament el que no es farà converteix cada afegit posterior en una decisió conscient en lloc d'una deriva.

La plantilla té tres columnes i s'escriu a docs/abast.md:

Tres detalls de la plantilla que no són adorn:

• La columna «Per què» et protegeix de tu mateix. D'aquí a tres setmanes no recordaràs el raonament, només la temptació.
• «Quan es reconsidera» evita el «mai» rancuniós. Ajornar no és rebutjar, i dir-ho així fa molt més fàcil acceptar la retallada.
• «No previst» és una resposta legítima i convé fer-la servir sense culpa. No tot allò ajornat ha de tornar.

Una nota específica sobre la línia d'autenticació, perquè és un error clàssic en projectes de portafoli: una pantalla d'inici de sessió sense servidor no protegeix res. Si les dades són a localStorage, qualsevol amb les eines de desenvolupament les veu. Posar-hi un formulari de contrasenya al davant és pitjor que no posar-l'hi, perquè comunica una seguretat que no existeix. Si el teu projecte necessita autenticació de debò, necessita servidor, i això és la versió 2.0 (lliçó 11-07).

Una història d'usuari descriu una necessitat des del punt de vista de qui la té, no des del de qui la implementa. El seu valor no és el format bonic: és que t'obliga a dir per a qui i per a què, i aquestes dues paraules decideixen sovint el disseny tècnic.

La plantilla clàssica:

I el que de debò fa útil una història són els seus criteris d'acceptació: condicions verificables que permeten dir «fet» sense discussió. S'escriuen en format Donat / Quan / Llavors (Given / When / Then), que té un avantatge enorme i gens casual: es tradueix gairebé literalment a una prova de les que vas aprendre a 08-03 i 08-06.

Aquí tens tres històries reals d'Òrbita, completes.

Fixa't en el criteri 2. No diu «no es pot»: diu què passa exactament, amb quin missatge i citant la regla. Aquesta precisió és la que converteix el criteri en una prova de Jest de cinc línies.

I fixa't en el criteri 3: l'accessibilitat és dins del criteri d'acceptació, no en una llista a part que es revisa al final. És l'única manera que no s'oblidi. Hi tornaré a l'apartat 16 i a la lliçó 11-02.

El criteri 3 és el que té conseqüències arquitectòniques: obliga que el filtre formi part de l'estat de l'aplicació i de l'encaminador (06-04 i l'encaminador.js de Nómada Tasques), no que sigui una variable local de la vista. Un criteri d'acceptació ben escrit decideix disseny.

El criteri 4 és el que més s'oblida en projectes de portafoli: els estats buits. Una aplicació que mostra una zona en blanc quan no hi ha resultats sembla trencada encara que funcioni perfectament.

El criteri 4 és el que et costarà una tarda sencera si no l'escrius ara. La doble comptabilització d'hores en arbres és una d'aquelles errades que no trenca res visiblement: només fa que tots els números estiguin malament.

Quantes històries escriure. Per a un MVP com aquest, entre 12 i 18 històries és l'ordre de magnitud correcte. Menys de 10 acostuma a significar que les històries són massa gruixudes («com a usuari vull gestionar tasques» no és una història, és un mòdul). Més de 25 acostuma a significar que estàs descrivint la implementació en lloc de la necessitat.

Tenir històries no n'hi ha prou: cal saber en quin ordre. MoSCoW és un mètode de priorització simple i sorprenentment eficaç, el nom del qual ve de les inicials de les seves quatre categories:

La regla del 60 % és la part important i la que gairebé tothom incompleix. Si els teus Must consumeixen el 100 % del temps disponible, no tens pla: tens una aposta. Qualsevol imprevist —i sempre n'hi ha— et deixa sense lliurar. El 40 % restant en Should i Could és el teu marge: quan el temps estreny, se sacrifiquen sense dolor i el producte continua sent lliurable.

Priorització completa del MVP d'Òrbita:

Repartiment: Must 57 h (57 %), Should 26 h (26 %), Could 22 h (22 %). Total 105 h. La regla del 60 % es compleix amb folgança.

Dos advertiments sobre aquesta taula:

• La columna «Depèn de» és la que defineix l'ordre real. MoSCoW diu què és important; les dependències diuen què és possible. No pots fer H-11 abans que H-05 encara que vulguis.
• Les estimacions són de la lliçó 14, no sortides del no-res, i ja porten incorporat el factor de correcció que allà s'explica.

Aquí hi ha el consell més rendible de tota la lliçó: el model de dades s'escriu abans que el codi, en un document, i es revisa com es revisa un contracte. Canviar un camp en un document costa trenta segons. Canviar-lo quan ja és al domini, al repositori, a la vista, a les proves i a les dades desades dels usuaris costa una tarda i una migració (lliçó 11-03).

El model d'Òrbita amplia el de Nómada Tasques amb tres entitats noves.

Usuari — l'entitat nova més important, perquè canvia el tipus de dos camps que portaves deu mòduls tractant com a text.

Tasca — conserva els vuit camps de Nómada Tasques i n'hi afegeix quatre:

Canvi — l'entitat de l'historial (E6). És append-only: s'hi afegeix, mai no es modifica ni s'esborra.

Aquesta última decisió —serialitzar a text en lloc de desar el valor original— és deliberada i convé entendre'n el motiu: una entrada d'historial ha de continuar sent llegible d'aquí a dos anys, quan el model hagi canviat i prioritat potser ja no existeixi. Un historial que depèn del model actual per interpretar-se no és un historial: és una còpia parcial de l'estat.

1 · Què passa quan s'esborra un usuari amb tasques assignades?

Tres opcions, i cal triar-ne una explícitament:

L'opció triada és la tercera, i és la que es fa servir a gairebé tot el programari professional: l'esborrat real d'entitats referenciades gairebé mai no és el correcte. Aquesta decisió mereix un ADR (lliçó 11-06).

2 · Les etiquetes són una entitat o un array de textos?

A Nómada Tasques eren un array de textos normalitzats (R9). Per al MVP d'Òrbita es mantenen així, amb una funció que deriva el catàleg d'etiquetes del tauler. Convertir-les en entitat amb id propi només compensa si necessites reanomenar una etiqueta a totes les tasques alhora, i això és fora d'abast.

Anota-ho al document: una decisió que es pren explícitament i es justifica no és deute tècnic; és una decisió. El que crea deute és no adonar-se que hi havia una elecció.

3 · L'arbre es desa imbricat o pla amb referència?

La forma plana és la que fan servir les bases de dades i la que t'estalviarà problemes a la lliçó 11-03. Construir l'arbre és una funció recursiva de quinze línies (03-07); mantenir sincronitzada una estructura imbricada duplicada és un problema permanent.

Avís de protecció de dades. Així que el teu model conté nom de persones, estàs modelant dades personals. En un projecte d'aprenentatge amb dades fictícies no hi ha cap problema legal, però adquireix l'hàbit ara: anota al document d'abast quins camps són personals, per a què es fan servir i quant de temps es conserven. Si algun dia aquest producte tractés dades de persones reals, el RGPD exigeix base legal, informació a la persona interessada, minimització i terminis de conservació — i això requereix assessorament legal específic, no una lliçó de JavaScript. Hi tornarem a 11-03 i 11-05.

Les regles R1 a R10 de Nómada Tasques continuen vigents. Les repasso breument perquè són la base sobre la qual es recolzen les noves:

I aquestes són les cinc noves, que són les que donen caràcter a Òrbita:

Cinc observacions sobre aquestes regles, perquè cadascuna amaga una decisió:

R11 i la integritat referencial. «Existent i actiu» és més fort que «existent». Vol dir que en desactivar un usuari cal decidir què passa amb les seves assignacions futures: la resposta triada és que les existents es conserven (són història) però no se'n poden crear de noves. Aquesta asimetria és intencionada i mereix una prova explícita.

R12 i la suma de les fulles. És la regla que evita la doble comptabilització del criteri 4 d'H-11. La seva conseqüència pràctica: horesEstimades deixa de ser un camp editable així que una tasca té filles, i la interfície ho ha de reflectir (camp deshabilitat amb explicació, no camp que accepta un valor que s'ignora en silenci).

R13 i el tancament en cascada. Prohibir tancar una mare amb filles obertes és l'estricte; permetre-ho tancant les filles automàticament és el còmode. La regla triada fa l'estricte per defecte i ofereix la cascada com a acció explícita («Tancar també les 3 subtasques pendents»). No facis mai la cascada en silenci: esborrar o tancar coses que l'usuari no ha mirat és la recepta de la desconfiança.

R14 i la immutabilitat. «Una correcció és una entrada nova» és el principi comptable de tota la vida, i és el que fa que un historial serveixi per a alguna cosa. Així que es pot editar, deixa de ser prova de res.

R15 i la setmana ISO. Triar la setmana ISO 8601 (dilluns a diumenge, amb la regla del dijous per a la setmana 1) en lloc de «els últims set dies» és una decisió amb conseqüències: cal implementar-la bé, i és un cas de prova preciós perquè l'1 de gener cau de vegades a la setmana 52 de l'any anterior. Anota-ho: serà una de les teves proves parametritzades de la lliçó 11-04.

On viuen les regles. Totes, sense excepció, a la capa de domini. La vista les pot anticipar per donar bona informació a l'usuari (deshabilitar un botó, avisar abans d'enviar), però la vista mai no és qui decideix. Si una regla només és al formulari, no existeix: n'hi ha prou de cridar el mètode des d'un altre lloc per saltar-se-la. Això és exactament el que 06-07 explicava sobre validació de client, i el mateix que la lliçó 11-05 repetirà sobre validació de servidor.

Nómada Tasques tenia quatre carpetes —model/, dades/, vista/, util/— i aquella organització no era estètica: era una arquitectura per capes, amb regles sobre qui pot cridar qui. Òrbita la formalitza amb quatre capes i una capa transversal.

Les quatre capes, amb la seva responsabilitat i les seves prohibicions:

Les tres fronteres que no es creuen, i què et passa si les creues:

1. domini/ no sap que existeix un navegador. Ni document, ni localStorage, ni fetch, ni alert. Conseqüència pràctica immediata: el domini es prova a Node sense jsdom, en mil·lisegons, i això és el que fa possible tenir centenars de proves ràpides (11-04). Si un dia necessites Date.now() dins del domini, es passa com a paràmetre o com a rellotge injectat — mai no es crida directament, perquè llavors les proves depenen de quin dia les executis.

2. vista/ no sap d'on vénen les dades. Rep un estat i unes funcions (enCrearTasca, enCanviarEstat) i les crida. No sap si al darrere hi ha memòria, localStorage o una API. Conseqüència pràctica: canviar l'emmagatzematge a la lliçó 11-03 no tocarà ni un fitxer de vista.

3. dades/ no sap què es pinta. Retorna entitats del domini o llança errors tipats. No retorna HTML, ni missatges d'usuari, ni «cadenes llestes per mostrar». Conseqüència pràctica: la traducció d'un error a un text amable és responsabilitat de la vista, i per això el mateix ErrorDeRegla es pot mostrar de tres maneres diferents en tres pantalles.

Per què aquesta arquitectura, i no una altra. Dues referències del mateix curs:

• 05-04 (mòduls) va ensenyar que un import és una dependència declarada: en escriure'l estàs dient «això no funciona sense allò». Una arquitectura per capes és, literalment, una regla sobre quins import estan permesos. I com que és una regla mecànica, es pot automatitzar: ESLint (08-02) té regles de restricció d'importacions que trenquen la compilació si algú escriu import { desar } from '../dades/...' dins de domini/. Configurar-ho és l'exercici 3.

• 10-06 va demostrar amb dades que domini/regles.js va ser idèntic a les quatre versions de la mateixa pantalla (JavaScript pur, React, Vue i Angular). Aquest fet és l'argument definitiu: si el domini no depèn de la vista, sobreviu al canvi de vista. I les vistes canvien. Sempre.

Un apunt d'honestedat: per a un projecte de 100 hores, quatre capes poden semblar cerimònia. No ho són, per una raó molt concreta: el cost d'introduir-les al principi és d'una hora; el d'introduir-les quan ja hi ha 4.000 línies barrejades és d'una setmana. I en aquest projecte en particular les necessites, perquè la lliçó 11-03 substituirà la capa de dades sencera i la 11-04 provarà cada capa amb una tècnica diferent.

Ara sí, teclat. L'objectiu d'aquest apartat és un repositori que, en executar una sola ordre, ho verifiqui tot i surti en verd.

Cada línia, explicada:

• git init -b main crea el repositori amb la branca principal anomenada main des del principi, que és el que espera GitHub i el que farà servir el flux de desplegament de la lliçó 11-05.
• vite és el servidor de desenvolupament i l'empaquetador. Et dona recàrrega instantània en desar i, en producció, la compilació amb minificació i hashing que veuràs a 11-05. És l'eina que Nómada Tasques feia servir des del Mòdul 9.
• ESLint i Prettier separen responsabilitats com explicava 08-02: ESLint busca errors, Prettier imposa format. eslint-config-prettier desactiva les regles d'ESLint que es barallarien amb Prettier.
• Jest amb jsdom per a unitàries i integració; Testing Library per consultar el DOM per rol i per text, com una persona (08-05).
• Cypress per als tres recorreguts d'extrem a extrem (08-06).
• Husky i lint-staged executen les comprovacions abans de cada commit, sobre els fitxers que estàs confirmant. És la diferència entre «la CI ja m'avisarà» i «no puc confirmar codi trencat».

El guió clau és verificar. És el contracte del projecte en una línia: lint, format, proves amb cobertura i compilació. És exactament el que executarà la integració contínua (11-04) i el que has de poder llançar en qualsevol moment per saber si el projecte està sa. La regla associada és simple i no admet excepcions:

npm run verificar ha d'estar en verd abans de cada push. Sempre.

L'ordre dels quatre passos no és casual: van de més ràpid a més lent, perquè el primer que falli sigui el més barat de detectar.

Aquest és el fitxer eslint.config.js, i conté la part que fa que l'arquitectura de l'apartat 10 es compleixi sola:

El que acabes de fer és important i mereix que ho vegis amb claredat: has convertit una decisió d'arquitectura en una regla automàtica. A partir d'ara, la frontera no depèn que te'n recordis un divendres a la tarda. Si algú —tu d'aquí a tres setmanes— escriu import { RepositoriLocal } from '../dades/repositori-local.js' dins de domini/tasca.js, npm run lint falla, el commit es rebutja i la CI es posa en vermell.

Les arquitectures que no es poden verificar automàticament s'erosionen sempre. No és qüestió de disciplina: és qüestió que ningú no recorda un document de fa dos mesos a les onze de la nit.

Dos passos: formatar i revisar només els fitxers que estàs confirmant (lint-staged), i executar només les proves afectades (--onlyChanged). Ràpid a propòsit: un ganxo lent és un ganxo que acabaràs saltant-te amb --no-verify, i un ganxo que se salta no serveix de res. La suite completa és responsabilitat de la CI.

Tres decisions de l'estructura, amb el seu perquè:

• src/ com a arrel del codi. Separa el codi de la configuració, que a l'arrel ja són deu fitxers. Vite ho espera així per defecte.
• docs/ versionat amb el codi. Si el document d'abast viu en una nota solta o en un servei extern, es desincronitza en dues setmanes. Dins del repositori, canvia al mateix commit que el codi que reflecteix.
• test/ fora de src/, reflectint-ne l'estructura. Existeix l'alternativa de posar les proves al costat del codi (tasca.test.js al costat de tasca.js); les dues funcionen. L'avantatge de separar-les és que el build de producció no ha d'excloure res i la cobertura per capes es llegeix d'una ullada.

Fins ara potser has fet servir Git com a còpia de seguretat: git add ., git commit -m "canvis", git push. Funciona fins que necessites respondre una d'aquestes preguntes, i llavors no funciona en absolut:

• Quan va deixar de funcionar l'informe de càrrega i quin canvi el va trencar?
• Per què està escrit així aquest tros estrany que no goso tocar?
• Puc desfer la funcionalitat de subtasques sense desfer les tres de després?
• Què va entrar exactament a la versió que vaig desplegar dimarts?

L'historial de Git és documentació que s'escriu sola si li dediques trenta segons per commit. Aquestes són les regles del projecte.

Una branca per història d'usuari. Neix de main, viu entre unes hores i tres dies, i es fusiona.

Conveni de noms, amb el mateix prefix que els commits:

Per què curtes. Una branca de tres setmanes acumula conflictes, es desincronitza de main i arriba un moment en què fusionar-la fa por. Una branca de dos dies es fusiona sense pensar. Si una història no cap en tres dies, la història és massa gran: parteix-la (H-04 es pot partir en «crear subtasca», «agregar hores» i «regla de tancament R13»).

El format de Commits Convencionals és un estàndard àmpliament adoptat:

Exemples reals d'aquest projecte, del pitjor al millor:

I un commit amb cos, que és on hi ha el valor de debò:

Ningú no escriu això per lluir-se. S'escriu perquè d'aquí a sis mesos, quan l'informe torni a donar un número estrany, aquest missatge apareix a git log i t'estalvia dues hores. És el mateix argument de l'historial de canvis de la R14, aplicat al codi en lloc de a les dades.

La regla d'or de la mida del commit: si necessites la paraula «i» per descriure el que fa, són dos commits.

Què va a la descripció i què va al cos:

El què ja és al diff. El perquè només és al teu cap, i el teu cap no es pot consultar d'aquí a sis mesos.

«Reviso el meu propi codi» sona a teatre. No ho és, si es fa amb un procediment que forci el canvi de perspectiva:

1. Obre una Pull Request contra main, sempre. Encara que l'aprovis tu.
2. Deixa passar temps. Idealment fins l'endemà; com a mínim, una hora fent una altra cosa. La revisió immediata no veu res perquè el teu cap encara omple els buits.
3. Llegeix el diff complet a la interfície web, no al teu editor. El canvi de context visual és sorprenentment eficaç: veuràs coses que al teu editor eren invisibles.
4. Aplica la llista de comprovació de l'apartat següent i escriu els comentaris a la PR, no en un paper.
5. Corregeix amb commits nous a la mateixa branca, no reescrivint. Que es vegi la correcció.

Llista de comprovació de revisió (l'ampliarem a 11-02 i 11-06):

I una regla que val or quan algú altre revisa el teu codi o tu revises el d'altres: critica el codi, mai la persona. «Aquesta funció fa tres coses» en lloc de «has fet un embolic». Aplica-ho també amb tu mateix: l'objectiu és un producte millor, no un judici.

Tothom estima malament i sempre en la mateixa direcció: per defecte. La causa està ben estudiada i es diu fal·làcia de la planificació: en estimar imaginem el camí en què tot surt bé, perquè és l'únic que podem imaginar amb detall. Els imprevistos, per definició, no es poden enumerar.

El mètode honest té tres passos:

1. Estima cada història en hores de treball efectiu, suposant que no hi ha interrupcions i que en saps.
2. Multiplica per un factor de correcció segons com de conegut et resulti el problema.
3. Afegeix un 20 % de reserva al total del projecte per al que no és a cap història (configurar coses, arreglar el desplegament, una errada rara de Jest).

Un exemple complet, la història H-04:

Les 10 hores de la taula de l'apartat 7 surten d'aquí, no d'una intuïció.

Total d'Òrbita: 105 h d'històries + 21 h de reserva (20 %) = 126 hores. A 8 hores setmanals, unes 16 setmanes. Si això et sembla molt, tens dues sortides legítimes: dedicar-hi més hores per setmana, o retallar els Could (22 h) i quedar-te en 13 setmanes. El que no és una sortida és decidir que en realitat seran 60 hores.

Una fita no és una data: és un estat del producte que es pot ensenyar. Cadascuna acaba amb alguna cosa demostrable.

Dues observacions sobre el Gantt:

• La reserva apareix al diagrama. Si la reserva no està dibuixada, no existeix: se la menjarà el primer imprevist i donaràs el pla per perdut. Dibuixada, és una part del pla que s'està consumint, i ho veus.
• Les fites no s'encavalquen. És temptador dibuixar tasques en paral·lel, però treballes sol: el paral·lelisme és una il·lusió que només serveix perquè el pla sembli més curt.

Com es fa servir el pla. No com una promesa, sinó com un instrument de mesura. Al final de cada setmana anota hores dedicades i històries tancades. Si en acabar H2 portes un 40 % més de temps del previst, el teu factor de correcció és baix: puja'l per a la resta del pla en comptes d'esperar recuperar-lo. Recuperar temps perdut gairebé mai no passa; ajustar el model, sí.

La Definició de Fet (Definition of Done) respon una pregunta que sembla tonta i no ho és: quan està acabada una història? Sense una resposta escrita, «fet» significa «funciona a la meva màquina quan faig el que espero», i aquest és l'origen del 80 % del deute d'un projecte personal.

S'escriu una vegada, al principi, i s'aplica a totes les històries sense excepció:

Sí, és llarga. I sí, es compleix, per dos motius:

1. La majoria de les caselles les verifica una màquina: npm run verificar en cobreix set. Només unes poques exigeixen que tu facis alguna cosa a mà.
2. És més barata que l'alternativa. Cada casella d'aquesta llista representa un problema real que apareix si no es comprova, i tots són més cars d'arreglar després.

Un consell pràctic: desa-la com a plantilla de Pull Request a .github/pull_request_template.md. Així apareix sola, marcada com a llista de tasques, cada vegada que obres una PR. El que no apareix sol, no es fa.

La lliçó 09-01 va deixar una idea que cal aplicar ara, no al final: mesurar abans d'optimitzar. I el seu corol·lari, que és el que fa aquest apartat: un objectiu sense número no és un objectiu.

Nómada Tasques va mesurar la seva línia base al final, amb l'aplicació ja construïda, i va trobar deu problemes de cop. Tu ho faràs al revés: fixes el pressupost ara, amb l'aplicació buida, i la CI el vigila des del primer dia. La diferència és enorme: un pressupost fixat al principi s'incompleix el dia que es trenca, amb un sol canvi sospitós; fixat al final, s'incompleix per l'acumulació de trenta canvis i ningú no sap quin va ser.

La columna de referència són els números mesurats de Nómada Tasques a la lliçó 09-01 (línia base amb 600 tasques, després de les optimitzacions de tot el Mòdul 9):

Els pressupostos són una mica més laxos que els números de Nómada Tasques, i això és deliberat: Òrbita té més pantalles i més funcionalitat. Un pressupost impossible s'ignora a la primera setmana; un d'assolible però exigent es respecta.

La regla del pressupost: si un canvi l'incompleix, hi ha tres sortides legítimes — optimitzar el canvi, renunciar a la funcionalitat, o pujar el pressupost conscientment i anotar per què. La quarta sortida, «ja ho miraré més endavant», és la que produeix aplicacions de 2 MB.

El criteri 9 té una conseqüència immediata a Òrbita i convé veure-la ara: la tasca vençuda de la R10 no es pot destacar només en vermell, i la cel·la sobrecarregada de la R7 no es pot destacar només en ambre. Totes dues necessiten text o icona amb text alternatiu. Si ho saps ara, ho dissenyes bé; si ho descobreixes a la revisió d'accessibilitat, ho refaràs.

Els llindars 1, 2, 5 i 6 els verifica la màquina. La resta són manuals i van a la Definició de Fet. La lliçó 11-04 munta l'automatització completa.

El README.md és el primer que veu qualsevol que arribi al teu repositori: un revisor, un reclutador, o tu mateix d'aquí a un any. Es crea ara, amb buits, i s'omple a mesura que el projecte avança. Un README que s'escriu l'últim dia es nota, i no es nota bé.

git clone https://github.com//orbita.git cd orbita npm install npm run dev # http://localhost:5173

npm test # unitàries i integració npm run test:cov # amb informe de cobertura npm run e2e # recorreguts d'extrem a extrem npm run verificar # tot l'anterior + lint + build

src/domini/ Regles R1-R15. Sense dependències. Es prova a Node. src/dades/ Persistència i xarxa. Una interfície, tres implementacions. src/vista/ DOM, esdeveniments i accessibilitat. No sap d'on vénen les dades. src/aplicacio/ Casos d'ús i estat. Uneix les tres anteriors.

Les seccions que gairebé ningú no escriu i que més impressionen qui revisa són «Decisions tècniques» i «Limitacions conegudes». La primera demostra criteri; la segona demostra honestedat i consciència dels límits de la pròpia feina, que és exactament el que es busca en algú amb qui treballaràs. La lliçó 11-06 desenvolupa el README a fons.

Començar a programar abans de tenir el model de dades escrit. És l'error més car de tots, perquè no fa mal al principi: fa mal a la setmana quatre, quan descobreixes que responsable havia de ser una referència i ja és en vint llocs. Mitja hora de document estalvia dos dies de refactorització. Escriu el model, llegeix-lo en veu alta, i només llavors obre l'editor.

Confondre MVP amb «versió xusquera». Un MVP té menys funcionalitats, no menys qualitat. Les que hi són, hi són acabades: provades, accessibles i amb els seus estats buit i d'error. Una aplicació amb tres funcionalitats impecables demostra moltíssim més que una amb dotze a mitges — i en una entrevista, la segona juga en contra teva.

No escriure la llista del que NO es farà. Sense aquesta llista, cada idea nova sembla raonable perquè res no diu el contrari. Amb la llista, afegir alguna cosa exigeix ratllar-la explícitament, i aquest petit acte de fricció filtra el 90 % de les idees de dimarts a la tarda.

Estimar en el millor cas. La teva estimació ingènua és el temps que trigaries si tot sortís bé i ja en sabessis. Multiplica pel factor de la taula de l'apartat 14 sense negociar amb tu mateix, i afegeix la reserva del 20 %. Un pla que es compleix motiva; un que s'incompleix des de la segona setmana s'abandona.

Deixar l'arquitectura com una intenció. «Ja aniré amb compte de no importar dades/ des de domini/» és una frase que caduca en dues setmanes. Configura la regla d'ESLint de l'apartat 11.3 el primer dia: converteix la teva bona intenció en un error de compilació, que és l'única cosa que no s'oblida.

Ajornar l'accessibilitat a «quan funcioni». Afegir accessibilitat al final és refer la meitat de la vista: els <div> clicables cal convertir-los en <button>, el focus cal gestionar-lo, els anuncis cal introduir-los. Fet des del principi no costa pràcticament res, perquè gairebé tot es redueix a fer servir l'element HTML correcte.

Un README buit durant mesos. Escriu avui la primera versió, encara que la meitat siguin buits. Cada vegada que prenguis una decisió, afegeix una fila a la taula de decisions tècniques. Reconstruir el perquè de vint decisions l'últim dia és impossible: no les recordaràs.

Branques llargues. Una branca de tres setmanes és un projecte paral·lel que un dia hauràs de reconciliar. Si una història no cap en tres dies, parteix-la. Si no saps com partir-la, és senyal que encara no l'entens bé — i això també és informació valuosa.

Consell · Escriu el document d'abast per «al tu d'aquí a tres mesos». Aquest lector no recorda res, no té context i només té deu minuts. Si el document li serveix, et serveix a tu i li servirà a qualsevol.

Consell · Fixa un dia i una hora de treball, i protegeix-los. La causa número u d'abandonament de projectes personals no és la dificultat tècnica: és la pèrdua de ritme. Dues sessions setmanals fixes de tres hores rendeixen moltíssim més que «quan pugui».

Consell · Fes el primer desplegament amb l'aplicació buida. A la fita H1, abans d'escriure lògica. Descobriràs els problemes de configuració quan no costen res, en lloc de l'última setmana amb tot en joc. És el mateix principi que la fase pilot de les migracions de 10-06.

Aquests tres exercicis són la fita H1 del teu projecte. En acabar-los tindràs el document d'abast, el model de dades i un repositori verd: tot el necessari per començar a construir a la lliçó següent.

Exercici 1 — El document d'abast.

Crea docs/abast.md al teu repositori amb aquestes set seccions:

1. El producte en una frase (format de l'apartat 2): qui el fa servir, què fa, quin problema resol.
2. El MVP: la taula de funcionalitats amb la columna «MVP?» i la seva raó. Mínim 12 candidates, i almenys 5 amb «No».
3. Fora d'abast: la taula de tres columnes de l'apartat 5, amb almenys 8 files.
4. Històries d'usuari: entre 12 i 18, amb la plantilla Com a / vull / per. Almenys quatre desenvolupades completament amb criteris Donat / Quan / Llavors (mínim 3 criteris cadascuna), incloent-hi almenys un criteri d'accessibilitat.
5. Priorització MoSCoW: la taula de l'apartat 7 amb estimació, fita i dependències. Verifica la regla del 60 %.
6. Pla de fites: les sis fites amb el seu lliurable demostrable i el seu diagrama de Gantt en Mermaid, amb la reserva dibuixada.
7. Definició de Fet: adaptada al teu projecte, amb almenys 18 caselles repartides entre les sis categories.

Exercici 2 — El model de dades i les regles.

Crea docs/model-dades.md amb:

1. Un diagrama d'entitats en Mermaid (erDiagram) amb totes les teves entitats i les seves relacions.
2. Una taula per entitat amb camp, tipus, si admet null, regles i una nota justificant el tipus triat.
3. La taula de regles R1–R15 (o les que corresponguin al teu domini, si n'has triat un altre) amb: descripció, capa on s'aplica i error que llança.
4. Les tres decisions de modelatge de l'apartat 8.3 aplicades al teu domini, cadascuna amb les seves alternatives descartades i el perquè.
5. Un exemple complet de dades fictícies en JSON amb almenys 8 entitats, incloent-hi un cas límit de cada regla nova.
6. Una secció «Dades personals» que enumeri quins camps ho són, per a què es fan servir i quant es conserven.

Exercici 3 — El repositori verd.

Deixa el repositori en l'estat exacte del qual parteix la lliçó 11-02:

1. Repositori amb main, primer commit convencional i .gitignore correcte (node_modules, dist, .env, coverage, cypress/videos).
2. package.json amb els deu guions de l'apartat 11.2, inclòs verificar.
3. eslint.config.js amb les dues fronteres d'arquitectura configurades i comprovades.
4. .prettierrc, jest.config.js (amb testEnvironment: 'jsdom' i llindars de cobertura) i vite.config.js.
5. Ganxo de pre-commit amb Husky i lint-staged, verificat amb un commit real.
6. L'estructura de carpetes de l'apartat 12, amb un .gitkeep a les buides.
7. Una prova que demostri que les fronteres funcionen: escriu src/domini/prova-frontera.js amb import ... from '../dades/repositori.js', comprova que npm run lint falla amb el teu missatge personalitzat, i esborra'l. Documenta el resultat a l'ADR-0001.
8. README.md amb la plantilla de l'apartat 17 (els buits s'omplen després).
9. npm run verificar en verd.

No hi ha solucions en forma de codi, perquè el projecte és teu. Aquestes són les rúbriques amb les quals s'avalua cada lliurable. Puntua't honestament: l'objectiu no és la nota, és detectar el que falta abans que et surti car.

Rúbrica de l'exercici 1 — Document d'abast (30 punts)

Llindar d'aprovació: 20/30, amb almenys 2 punts a «Retallada del MVP» i a «Històries». Si hi falles, tota la resta es construeix sobre sorra.

Rúbrica de l'exercici 2 — Model de dades (24 punts)

Senyal d'alarma inequívoc: si la teva taula de regles té menys de cinc regles noves pròpies del domini, el teu producte és un CRUD. Afegeix-hi regles dures — són el que fa interessant el domini, el que dona sentit a les proves de 11-04 i el que s'explica bé en una entrevista.

Rúbrica de l'exercici 3 — Repositori (verificació binària)

Aquí no hi ha grisos: cada punt es compleix o no es compleix.

El punt 10 és el que de debò importa i el que gairebé ningú no comprova. Una regla d'ESLint mal configurada no falla: simplement no fa res, i tu et creus que estàs protegit durant tres mesos. Provoca l'error a propòsit, comprova el missatge, i només llavors esborra'l.

Autoavaluació final de la fita H1. Respon amb sinceritat abans de passar a la lliçó següent:

Sis «sí» i pots continuar. Un sol «no» i val la pena tornar enrere abans d'escriure codi, perquè cadascun d'aquests «no» es multiplica per setmanes de feina més endavant.

Has fet el que gairebé ningú no fa en un projecte personal: planificar abans de programar. I no amb un pla decoratiu, sinó amb instruments que es faran servir cada setmana del mòdul.

Saps que a partir d'aquí el codi l'escrius tu: Nómada Tasques deixa de ser l'exemple que se't dona resolt i passa a ser la referència contra la qual comparar, amb les seves sis tasques, les seves 48 hores, les seves regles R1–R10 i els seus números mesurats. Tens un producte per defecte —Òrbita— amb sis extensions que obliguen a resoldre problemes que el curs esquivava: usuaris com a entitats, un arbre de subtasques, filtre múltiple, una vista que no és una llista, un informe que produeix un fitxer i un historial immutable que creix sense parar. I tens tres alternatives de domini —Aforament, Ratxa, Prestatgeria— amb el mapatge complet de les sis extensions, perquè el mètode és el mateix i el que importa és que t'importi.

Saps retallar: el MVP és el que no es pot treure sense trencar la frase del producte, i la prova és una sola pregunta. De quinze candidates n'hi van entrar vuit. I saps que la meitat que es queda fora cal escriure-la, amb el seu perquè i el seu quan es reconsidera, perquè una funcionalitat que no és a cap llista és una funcionalitat que apareixerà un dimarts a la tarda.

Saps escriure històries d'usuari que diuen per a qui i per a què, amb criteris Donat / Quan / Llavors tan precisos que es tradueixen en proves gairebé paraula per paraula — inclosos els criteris d'accessibilitat, que van dins de la història i no en una llista a part que es revisa al final. I saps prioritzar-les amb MoSCoW respectant la regla del 60 %, que és la que converteix un pla en un pla i no en una aposta.

Tens el model de dades escrit abans que el codi, amb el seu diagrama d'entitats, els seus tipus justificats i les tres decisions que calia prendre explícitament: desactivar usuaris en lloc d'esborrar-los, etiquetes com a text normalitzat, i arbre pla amb tascaMareId en comptes d'imbricat. I tens les regles noves R11 a R15 —integritat referencial amb usuaris actius, arbre sense cicles amb hores per fulles, tancament bloquejat per subtasques obertes, historial immutable, i permisos amb càrrega per setmana ISO— vivint totes al domini, perquè una regla que només és al formulari no existeix.

Tens una arquitectura per capes amb tres fronteres que no es creuen —el domini no sap que hi ha navegador, la vista no sap d'on vénen les dades, les dades no saben què es pinta— i, el que és més important, les tens verificades per ESLint: has convertit una intenció en un error de compilació, que és l'única cosa que no s'erosiona. L'argument no és teòric: a 10-06, domini/regles.js va ser idèntic a les quatre versions de la mateixa pantalla.

Tens l'entorn muntat: Vite, ESLint i Prettier, Jest amb jsdom i Testing Library, Cypress, Husky i lint-staged, amb un guió verificar que resumeix el contracte del projecte en una línia i una regla sense excepcions. Tens Git de debò: branques curtes per història, commits convencionals el cos dels quals explica el perquè —l'única cosa que el diff no et pot explicar d'aquí a sis mesos— i revisions del teu propi codi amb distància, a la interfície web i amb llista de comprovació.

Tens un pla honest: 105 hores d'històries, factor de correcció per familiaritat, 20 % de reserva dibuixat al Gantt, sis fites que acaben cadascuna en alguna cosa que es pot ensenyar. Tens una Definició de Fet de la qual la majoria de caselles les verifica una màquina, desada com a plantilla de Pull Request perquè aparegui sola. I tens el pressupost de rendiment i accessibilitat fixat al principi, amb els números de Nómada Tasques com a referència: ≤ 60 kB, LCP ≤ 2,5 s, ≤ 1.500 nodes, 0 incidències greus d'axe, contrast 4,5:1 i res comunicat només per color.

La fita H1 està tancada: document d'abast, model de dades amb les seves regles, i un repositori que respon en verd. La pàgina és buida, i això és exactament el correcte, perquè ara saps què hi posaràs i per què.

El següent és posar-ho. I hi ha una manera de fer-ho que no és la intuïtiva —de dins cap a fora, començant per les regles i acabant pels píxels, i una funcionalitat completa abans que totes a mitges—: és Construcció del Projecte.