Cada vegada que node --watch reinicia el servidor, els cafès tornen a ser dos i la comanda com_5001 ressuscita en pendent_pagament. Els arrays en memòria ens han servit per construir el contracte sense distraccions, però no són una base de dades: no sobreviuen a un reinici, no poden garantir que descomptar estoc de tres línies passi de manera atòmica i no escalen més enllà d'uns pocs milers de registres. Avui els substituïm per SQLite amb better-sqlite3 darrere del patró repositori, i ho farem complint la promesa que vam fer a 03-01: no es toca ni una línia dels controladors ni dels serveis. Pel camí veurem l'esquema SQL de la Botiga Aroma amb els diners en cèntims enters, migracions versionades, sentències preparades i per què eliminen la injecció SQL, transaccions per crear una comanda, control de concurrència optimista, el problema N+1 i la paginació per cursor implementada de debò.

1. Què canvia avui al projecte
2. El patró repositori
3. Quina base de dades i per què SQLite en aquest curs
4. better-sqlite3: síncron i sense sorpreses
5. L'esquema SQL de la Botiga Aroma
6. snake_case a la base de dades i camelCase al JSON
7. Migracions: què són i per què es versionen
8. L'script de migració i les dades de sembra
9. La connexió: src/config/base-dades.js
10. src/repositoris/cafes-sqlite.js amb sentències preparades
11. Per què les sentències preparades eviten la injecció SQL
12. Consultes dinàmiques segures: filtres, ordre i paginació
13. Transaccions: crear una comanda descomptant estoc
14. Concurrència optimista i conflicte_versio
15. El problema N+1 en carregar les línies
16. Paginació per cursor de debò
17. ORMs: quan compensen
18. Connexions i tancament ordenat

Que la llista de modificacions sigui tan curta és el resultat que buscàvem. Si els controladors haguessin parlat directament amb l'array, avui tocaríem vint fitxers.

Un repositori és un objecte que ofereix operacions sobre una col·lecció d'entitats i amaga completament on i com estan desades. La interfície que ja fem servir des de 03-02:

Les tres propietats que fan que valgui la pena:

• Substituïbilitat. cafes-memoria.js i cafes-sqlite.js compleixen la mateixa interfície. Canviar d'un a l'altre és canviar un import, i a 03-08 farem servir precisament el de memòria com a doble de prova.
• Localització del SQL. Tot el SQL de cafès és en un fitxer. Quan una consulta va lenta, saps on mirar; quan canvia una columna, saps què revisar.
• Vocabulari de domini. El servei demana buscarPerId('caf_001'), no executa un SELECT. La lògica de negoci es llegeix sense soroll tècnic.

I el límit del patró, dit amb honestedat: no fa que les bases de dades siguin intercanviables per art de màgia. Una consulta amb JSON_EXTRACT de SQLite no funciona igual a MongoDB. El que el repositori garanteix és que, si s'ha de reescriure, es reescriu en un sol lloc.

Per què SQLite al curs: perquè no hi ha res per instal·lar ni configurar, la base de dades és un fitxer que pots esborrar i regenerar en un segon, i el SQL que escriurem és SQL estàndard, així que el que aprenguis es transfereix. El que aprenguis de sentències preparades, transaccions, índexs i N+1 val exactament igual a PostgreSQL.

Què canviaria amb PostgreSQL. Poc en el disseny i bastant en la mecànica: es faria servir el paquet pg amb un pool de connexions, les crides serien asíncrones (await client.query(...)), els marcadors de posició serien $1, $2 en comptes de ?, i les transaccions s'escriurien amb BEGIN/COMMIT explícits sobre una connexió reservada del pool. Els tipus hi guanyarien precisió: TIMESTAMPTZ per a les dates, NUMERIC disponible per als diners, JSONB amb índexs per a les notes de tast. L'estructura del repositori, però, seria la mateixa; per això començar per SQLite no és una via morta.

Què canviaria amb MongoDB. Més: desapareixen les unions, una comanda desaria les seves línies incrustades dins del mateix document —cosa que, curiosament, elimina d'arrel el problema N+1 de la secció 15— i les transaccions multidocument existeixen però es fan servir molt menys. És una elecció raonable per a catàlegs amb atributs molt variables; per a comandes, amb la seva integritat referencial i els seus totals, el model relacional encaixa millor.

La raresa de better-sqlite3 és que la seva API és síncrona: db.prepare(sql).get(id) retorna la fila directament, sense await. En un ecosistema on tot el que toca entrada/sortida és asíncron, això xoca. I és correcte:

• SQLite no és un servidor: no hi ha xarxa, no hi ha latència. La consulta és una lectura de fitxer, sovint des de la memòria cau del sistema operatiu, que triga microsegons.
• Embolcallar aquella operació en una promesa afegiria més sobrecàrrega que la consulta mateixa.
• El codi resultant és més simple i les transaccions són trivials: sense await pel mig, no hi ha risc que una altra petició s'esmunyi enmig d'una transacció.

La contrapartida: si una consulta triga 200 ms, bloqueja el bucle d'esdeveniments i cap altra petició no avança durant aquest temps. La conseqüència pràctica és que cal mantenir les consultes ràpides —amb índexs, sense escanejos complets— i no fer informes pesats al mateix procés que serveix l'API. Amb PostgreSQL i pg, tot seria asíncron i aquest problema no existiria.

Els nostres serveis ja estan escrits de manera síncrona des de 03-03, així que la migració és directa. Si demà passéssim a PostgreSQL, caldria convertir en async els mètodes del repositori, del servei i del controlador —i allà l'embolcall asincron() que veurem a 03-07 esdevé imprescindible.

Decisions de l'esquema que convé justificar una per una:

preu_centims INTEGER. És la decisió de 02-05 portada a la base de dades. Un REAL (coma flotant) seria un error de disseny: SELECT SUM(preu) FROM ... acumularia errors d'arrodoniment i el total de la comanda podria diferir en cèntims del que se li va mostrar al client. Amb enters, la suma és exacta per definició. A PostgreSQL es podria fer servir NUMERIC(10,2), que també és exacte; l'enter de cèntims funciona en qualsevol motor.

Claus primàries de text (caf_001). Trenca el costum de l'INTEGER AUTOINCREMENT, i a canvi dona el que vam decidir a 02-02: identificadors opacs que diuen de quin tipus són i que no filtren quants registres hi ha. El cost és un índex una mica més gran i comparacions de cadena en lloc d'enters, irrellevant a aquesta escala.

CHECK als enumerats. La validació de Zod (03-04) ja rebutja una torrefacció invàlida, però el CHECK protegeix davant de qualsevol via d'entrada: un script d'importació, una correcció manual amb sqlite3, un bug futur. És defensa en profunditat, i no substitueix la validació a la vora, la complementa: el CHECK produeix un error de base de dades, no un 400 amable.

notes_tast com a text JSON. SQLite no té tipus array. Desem '["cítric","floral"]' i l'analitzem en llegir. És acceptable perquè mai no filtrem per una nota concreta amb SQL; el ?q= cerca dins del text. Si demà calgués filtrar per nota, el correcte seria una taula cafes_notes amb una fila per nota. A PostgreSQL faríem servir JSONB amb un índex GIN i no hi hauria discussió.

actiu INTEGER. SQLite no té boolean: es fan servir 1 i 0. I hi ha un detall pràctic important: better-sqlite3 rebutja els booleans de JavaScript com a paràmetres; cal passar 1 o 0 explícitament. És un error que sorprèn la primera vegada.

Dates com a TEXT en ISO-8601 UTC. SQLite tampoc no té tipus data. El format ISO-8601 té una propietat valuosíssima: l'ordre alfabètic coincideix amb l'ordre cronològic, així que ORDER BY data_creacio DESC funciona correctament sobre text. Això és exactament el que fa possible la paginació per cursor de la secció 16.

versio INTEGER. És el comptador per al control de concurrència optimista de la secció 14.

Tenim tres vocabularis i cal saber on es tradueix cadascun:

I les dues fronteres:

• BD → model intern: al repositori, en una funció aModel(fila).
• Model intern → JSON: al mapejador de 03-03 (cafeARepresentacio).

Ens hauríem pogut estalviar la primera traducció fent servir camelCase també a les columnes. No ho fem perquè snake_case és la convenció universal a SQL —les eines, els bolcats i els DBA s'ho esperen— i perquè a PostgreSQL els identificadors en majúscules obliguen a posar cometes a cada consulta. Que la traducció visqui en una sola funció del repositori fa que el cost sigui negligible.

Una migració és un canvi de l'esquema escrit com un fitxer SQL, numerat, immutable i versionat a Git.

El problema que resol és aquest: tu crees la taula cafes al teu portàtil executant SQL a mà. El teu company no la té. El servidor de proves té una versió antiga sense la columna versio. Producció en té una altra de diferent. Ningú no sap quin esquema hi ha a cada lloc, i aplicar un canvi es converteix en un ritual manual amb actes.

Les regles de les migracions, que no admeten excepcions:

1. Numerades i ordenades: 001-inicial.sql, 002-afegir-descomptes.sql.
2. Immutables: una migració aplicada mai no s'edita. Si estava malament, es corregeix amb una de nova.
3. Versionades a Git, al costat del codi que les necessita.
4. Registrades: la mateixa base de dades desa quines s'han aplicat.

Aquesta quarta regla exigeix una taula més, que afegim al principi del fitxer de migracions:

I la sembra, que carrega les dades amb què treballem tot el curs:

Amb els scripts a package.json:

Sembra i migració són coses diferents. La migració canvia l'estructura i s'executa a tots els entorns, producció inclosa. La sembra hi fica dades i només té sentit en desenvolupament i en proves. Barrejar-les —un INSERT dins d'una migració— és un error clàssic que acaba ficant cafès de prova a producció.

La línia de foreign_keys = ON és la que més disgustos evita: sense ella, SQLite accepta alegrement una línia de comanda que apunta a un cafè inexistent i el problema es descobreix mesos després amb dades òrfenes.

Sobre la generació d'identificadors: seguentNumero calcula el màxim existent i hi suma un. Funciona perquè SQLite serialitza les escriptures, i l'embolcallarem en la mateixa transacció que la inserció. A PostgreSQL faríem servir una SEQUENCE, i en un sistema distribuït l'habitual seria un ULID o un UUID amb prefix (caf_01HQ...), que es genera sense consultar res i no revela el volum de negoci.

Compara aquestes dues maneres de cercar per origen:

Amb la primera, si el client envia ?origen=x' OR '1'='1, el SQL que s'executa és:

Retorna el catàleg sencer. I amb una mica més d'imaginació —x'; DROP TABLE comandes; --— destrueix dades. Aquella tècnica és al primer lloc dels riscos de seguretat des de fa vint anys i continua funcionant en aplicacions reals.

Per què la versió amb ? és immune. No és que "escapi les cometes": és que el SQL i les dades viatgen per camins separats. La sentència s'analitza i es compila abans de conèixer els valors, i produeix un pla d'execució amb forats. Quan s'executa, cada valor es col·loca al seu forat com a dada, ja al motor, sense tornar a passar per l'analitzador. Per definició, un valor no es pot convertir en instrucció: x' OR '1'='1 es cerca literalment com a origen, no troba res, i retorna zero files. El motor no hi veu una cometa especial; hi veu una cadena de vint caràcters.

Tres conseqüències pràctiques:

• Marcadors a tots els valors. Sempre. Encara que la dada "vingui de dins", encara que sigui un número, encara que n'estiguis segur.
• Els marcadors només valen per a valors, no per a noms de taula, de columna ni per a ASC/DESC. Això es resol amb llistes blanques, com veurem ara mateix.
• La validació de 03-04 no substitueix això. És defensa en profunditat: la validació filtra formes, les sentències preparades fan impossible l'atac.

buscar() ha de combinar filtres opcionals. La tècnica és construir la llista de condicions i la llista de paràmetres alhora, sense concatenar mai un valor:

Tres punts crítics:

El total surt d'una consulta a part amb el mateix WHERE. No es pot obtenir de la consulta paginada, perquè LIMIT retalla. I ha de portar exactament els mateixos filtres, o el client calcularà malament el nombre de pàgines. És un COUNT(*) extra per petició, i és el preu de la paginació per desplaçament.

ORDER BY es construeix per concatenació, però només amb valors de COLUMNES_ORDENABLES. El nom que envia el client es fa servir com a clau de cerca al mapa, mai com a text SQL. Si no és al mapa, no hi ha columna. És impossible injectar-hi res.

El comodí del LIKE va al paràmetre. '%' || ? || '%' també seria vàlid, però posar el patró complet al paràmetre és més clar. El que no es pot fer mai és LIKE '%${q}%'.

Una nota de rendiment: LIKE '%text%' amb comodí inicial no pot fer servir un índex i obliga a recórrer la taula sencera. Amb 200 cafès és irrellevant; amb 200.000 registres caldria un índex de text complet (FTS5 a SQLite, tsvector a PostgreSQL) o un motor de cerca dedicat. És una limitació coneguda i acceptada del ?q= que vam prometre a 02-06.

Finalment, el selector d'implementació:

I a src/serveis/cafes.js canvia una línia:

Aquí hi ha la promesa complerta. Reinicia, prova curl -s http://localhost:3000/v1/cafes | jq .total i comprova que tot respon igual… i que ara sobreviu als reinicis.

Crear una comanda no és una operació: en són diverses que han de passar totes o cap.

1. Comprovar que cada cafè existeix i té estoc.
2. Inserir la fila de la comanda.
3. Inserir una línia per cafè.
4. Descomptar l'estoc de cada cafè.

Sense transacció, una fallada al pas 4 —per exemple, perquè l'estoc ja no arriba— deixaria una comanda cobrable amb l'inventari sense tocar. Això és corrupció de dades.

Una transacció garanteix les quatre propietats ACID; la que ens importa aquí és l'atomicitat: o s'apliquen tots els canvis, o cap.

Què passa si falla a mitges. Suposa que la segona línia es queda sense estoc perquè un altre client s'ha avançat per 30 mil·lisegons. L'excepció puja, better-sqlite3 executa ROLLBACK i l'estat de la base de dades torna exactament a com estava: no hi ha comanda, no hi ha línies, i l'estoc del primer cafè no s'ha descomptat. El servei tradueix aquell error a 409 estoc_insuficient i el client pot reintentar-ho. Sense transacció tindríem una comanda incompleta, una línia òrfena i estoc descomptat per una comanda que no va existir mai.

Per què l'estoc es comprova dues vegades. La primera lectura (cafePerComanda) serveix per donar un missatge d'error útil amb el nom del cafè i les unitats que queden. La segona, la condició AND estoc >= ? dins de l'UPDATE, és la que de debò protegeix: és una comprovació i una escriptura en una sola sentència atòmica, així que no hi ha finestra entre llegir i escriure. Aquest patró —comprovar al WHERE de l'actualització i mirar changes— és la manera correcta d'evitar que dues peticions simultànies venguin la mateixa darrera bossa de cafè.

Un detall de better-sqlite3 que cal respectar: dins d'una transacció no hi pot haver await. Com que la seva API és síncrona, no ens cal; però si hi barregessis una crida asíncrona, la transacció es tancaria abans d'hora. Amb PostgreSQL, en canvi, tot el bloc seria async i caldria reservar una connexió del pool per a tota la transacció.

Un altre problema de concurrència, diferent del de l'estoc: l'actualització perduda.

Sense control, el segon PATCH esclafaria el preu nou amb el que B va llegir fa un minut, i ningú no se n'assabentaria. El bloqueig optimista ho detecta: cada actualització exigeix la versió que el client va llegir.

I el servei tradueix aquell null al 409 conflicte_versio del catàleg:

Dues precisions sobre el catàleg de 02-04. Allà conflicte_versio apareixia associat a 412 Precondition Failed, que és el codi correcte quan el client envia la condició a la capçalera If-Match amb un ETag —el mecanisme estàndard d'HTTP, que veurem amb la memòria cau condicional a 04-06—. Aquí la condició viatja com un camp versio al cos, sense capçalera condicional, i llavors el codi adequat és 409 Conflict: la petició era vàlida però xoca amb l'estat actual del recurs. Mateix problema, mateix codi de catàleg, dos codis HTTP segons com s'expressi la condició. I el matís sobre el nom "optimista": es diu així perquè no bloqueja res; assumeix que els conflictes són rars i es limita a detectar-los. El pessimista (SELECT ... FOR UPDATE) bloqueja la fila, i només compensa quan els conflictes són freqüents.

Així és com no es carreguen les comandes amb les seves línies:

Amb 20 comandes són 21 consultes. El codi sembla innocent perquè la consulta està amagada dins del bucle, i per això el problema N+1 és tan comú. A SQLite, amb la base en local, el cost és petit; amb PostgreSQL en una altra màquina i 2 ms de xarxa per consulta, aquells 21 viatges són 42 ms de latència pura per retornar una pàgina. I si la llista fos de 100 comandes, 200 ms.

La solució: una segona consulta per a totes les línies de cop.

Dues consultes, sigui quin sigui el nombre de comandes. L'alternativa seria un únic JOIN, que també funciona però retorna la comanda repetida tantes vegades com línies tingui i obliga a deduplicar. Amb dues consultes el codi queda més clar i el rendiment és equivalent.

Un avís: IN (...) té un límit de paràmetres (999 per defecte a SQLite). Com que les nostres pàgines són de 100 com a màxim, no ens afecta; en un procés per lots caldria trossejar.

A 02-06 vam decidir que /v1/comandes faria servir cursor, i ara es veu per què. Amb OFFSET, el motor ha de recórrer i descartar totes les files anteriors:

És el deep paging: la pàgina 1 és instantània i la 5.000 triga segons. I a més és inestable: si entra una comanda nova mentre el client pagina, tot es desplaça una posició i en veu una de repetida.

El cursor resol les dues coses desant el darrer element vist en lloc d'un número de posició:

La comparació de tuples (a, b) < (x, y) és SQL estàndard i significa "a < x, o bé a = x i b < y". És exactament el desempat que necessitàvem, expressat en una condició.

Tres decisions a subratllar. El cursor és opac: base64 d'un JSON intern. No és xifrat —qualsevol el pot descodificar— però sí que és explícitament "no és cosa teva": el contracte de 02-06 prohibeix construir-lo a mà, i així en podem canviar el contingut sense trencar res a ningú. Demanar limit + 1 files és el truc estàndard per saber si n'hi ha més sense un COUNT extra. I la paginació per cursor no ofereix total ni salt a la darrera pàgina: és el preu que es paga, i per això el contracte va reservar el cursor per a /v1/comandes —on l'històric és enorme i només s'avança— i va deixar el desplaçament a /v1/cafes, on el catàleg és petit i saber el total importa.

L'índex idx_comandes_client_data (client_id, data_creacio DESC, id DESC) està construït justament per a aquesta consulta: el motor localitza el punt de tall amb una cerca a l'arbre i llegeix 21 files seguides. El cost no depèn de com de lluny estigui la pàgina.

A favor: menys codi repetitiu, migracions integrades, tipatge del resultat, portabilitat entre motors, i relacions carregades sense escriure el JOIN.

En contra: una abstracció més per aprendre i depurar; consultes generades que sorprenen; el problema N+1 ocult —un .linies que sembla un accés a propietat i en realitat dispara una consulta—; i dificultat per expressar SQL avançat.

El criteri: si la teva aplicació té moltes entitats amb relacions semblants i CRUD repetitiu, un ORM t'estalvia setmanes. Si en té poques i consultes exigents, el SQL directe darrere d'un repositori —el que hem fet— és més simple i més ràpid. I amb el patró repositori, la decisió és reversible: adoptar Prisma demà significaria reescriure els fitxers de src/repositoris/, i res més.

SQLite és un fitxer i no necessita pool: una única connexió per procés, oberta en arrencar. El mode WAL permet lectures concurrents amb l'escriptura, i busy_timeout gestiona els xocs d'escriptors.

Amb PostgreSQL sí que caldria un pool: obrir una connexió TCP costa desenes de mil·lisegons, així que se'n manté un conjunt reutilitzable (new Pool({ max: 10 })). Allà apareixen problemes propis —esgotament del pool per connexions que no es tornen, transaccions que s'han d'executar sobre una connexió reservada— que aquí no tenim.

El que sí que cal fer és tancar la base de dades en apagar. Actualitzem src/servidor.js:

El close() de better-sqlite3 bolca el WAL al fitxer principal i allibera el bloqueig. Sense ell, una apagada brusca deixa fitxers -wal i -shm solts que SQLite sap recuperar, però no hi ha cap raó per dependre d'això.

1. Concatenar valors al SQL. Injecció garantida. Marcadors de posició sempre, sense excepcions ni "és que aquest valor ve de dins".

2. Oblidar PRAGMA foreign_keys = ON. SQLite les ignora per defecte i acabes amb línies que apunten a comandes inexistents.

3. Passar un boolean de JavaScript com a paràmetre. better-sqlite3 el rebutja. Converteix-lo a 1 / 0.

4. Desar diners en REAL. L'error més car de la llista. INTEGER de cèntims, o NUMERIC on existeixi.

5. Editar una migració ja aplicada. La teva base s'actualitza, la dels teus companys no, i el registre de migracions menteix. Corregeix sempre amb una migració nova.

6. Barrejar sembra i migració. Les dades de prova acaben a producció.

7. Consultar dins d'un bucle. És l'N+1. Si veus un prepare dins d'un for, atura't: gairebé sempre hi ha una versió amb IN (...).

8. Calcular el total sobre la consulta paginada. El COUNT va amb els mateixos filtres i sense LIMIT.

9. Preparar sentències dins del gestor. db.prepare() a cada petició malbarata l'anàlisi del SQL. Prepara en carregar el mòdul i reutilitza.

Consell: quan una consulta vagi lenta, demana el pla abans de tocar res: EXPLAIN QUERY PLAN SELECT .... Si apareix SCAN TABLE, falta un índex; si apareix SEARCH TABLE ... USING INDEX, va bé.

Escriu la migració 002-afegir-descomptes.sql, que afegeix a cafes una columna descompte_percentatge (enter, entre 0 i 50, per defecte 0). Explica per què aquesta migració és un canvi retrocompatible per als consumidors de l'API (02-07) i què caldria fer a més perquè el camp aparegui al JSON.

Implementa buscarRessenyesDeCafe(cafeId, { estat, limit, desplacament }) en un nou src/repositoris/ressenyes-sqlite.js. Ha de retornar { elements, total }, filtrar per estat si s'indica, ordenar per data_creacio DESC amb desempat per id, i no retornar ressenyes d'un cafè inexistent sense distingir-ho d'un cafè sense ressenyes. Indica quin índex de l'esquema la sosté.

Dos empleats obren alhora la fitxa de caf_001 (versio: 7). El primer canvia el preu a 15,90 € i el segon, trenta segons després, canvia l'estoc a 200 fent servir la versió 7 que va llegir. Descriu què passa pas a pas amb actualitzarCafeAmbVersio, què respon l'API al segon, i compara-ho amb el que passaria sense control de versió. Després explica per què aquest mecanisme no serviria per al descompte d'estoc de la comanda i què es fa servir al seu lloc.

Solució 1

Per què és retrocompatible: la columna té DEFAULT 0 i NOT NULL, així que les files existents s'omplen soles i cap inserció anterior no deixa de funcionar. Des del punt de vista de l'API, afegir un camp a una representació és un canvi additiu (02-07): un consumidor que ignori descomptePercentatge continua funcionant igual, perquè un client JSON ben escrit ignora els camps que no coneix. No caldria una v2.

Què falta perquè aparegui al JSON: tres coses, i cap a la base de dades. Afegir descomptePercentatge: fila.descompte_percentatge a aModel() del repositori; afegir-lo a cafeARepresentacio() al mapejador; i afegir-lo a openapi.yaml amb la seva descripció. Que calguin exactament aquests tres llocs, i que siguin sempre els mateixos, és el senyal que l'arquitectura per capes està ben posada.

Solució 2

Índex que la sosté: idx_ressenyes_cafe ON ressenyes (cafe_id, estat). Cobreix el filtre obligatori per cafe_id i, quan s'hi afegeix estat, també el segon. L'ordenació per data_creacio DESC no queda coberta, així que el motor ordena en memòria el subconjunt de ressenyes d'aquell cafè —acceptable, perquè en són poques—. Si un cafè arribés a tenir-ne milers, l'índex ideal seria (cafe_id, estat, data_creacio DESC, id DESC), que serviria filtre i ordre alhora. Comprova-ho amb EXPLAIN QUERY PLAN.

Solució 3

Pas a pas:

1. Tots dos llegeixen caf_001 amb versio: 7.
2. El primer envia el seu canvi amb versio: 7. L'UPDATE ... WHERE id = 'caf_001' AND versio = 7 troba la fila, aplica el preu i puja la versió a 8. changes === 1, i l'API respon 200 amb la representació actualitzada.
3. El segon envia el seu canvi amb versio: 7. El WHERE ... AND versio = 7 no troba cap fila, perquè ara val 8. changes === 0 i el cafè sí que existeix → conflicte.
4. L'API respon 409 conflicte_versio amb el missatge que li demana tornar a carregar i repetir.

Sense control de versió: el segon UPDATE hauria escrit la seva còpia completa del cafè, inclòs el preu_centims de 1450 que va llegir fa mig minut. El canvi de preu del primer desapareix sense deixar rastre: cap error, cap log, cap indici. És l'actualització perduda, i la seva gravetat rau en el fet que és silenciosa: el primer empleat veu el seu 200 OK, se'n va tranquil, i el preu antic reapareix.

Per què no serveix per a l'estoc de la comanda. Són dos problemes diferents. El bloqueig optimista exigeix que el client hagi llegit el recurs i en retorni la versió, i protegeix una substitució completa del recurs. El descompte d'estoc, en canvi, és una operació relativa —"resta 2 al que hi hagi"— que ningú no ha llegit prèviament: el comprador no envia la versió del cafè ni té per què conèixer-la. Si ho fes, dues compres simultànies de cafès diferents de la mateixa comanda donarien 409 constantment i la botiga seria inusable.

El que es fa servir al seu lloc és la condició dins del mateix UPDATE:

Aquí la lectura i l'escriptura passen a la mateixa sentència atòmica, així que no hi ha finestra entre comprovar i actualitzar. Si dues peticions intenten comprar la darrera bossa, una obté changes === 1 i l'altra changes === 0, i aquesta darrera rep 409 estoc_insuficient. La regla general: el bloqueig optimista per a actualitzacions absolutes; la condició al WHERE per a les relatives.

Les dades de la Botiga Aroma ja viuen en una base de dades de debò, i el canvi ha costat tres línies d'import fora de la carpeta repositoris/. Això és el que compra el patró repositori: la resta de l'aplicació no va saber mai on eren els cafès. L'esquema SQL tradueix les decisions de contracte a estructura —preu_centims enter perquè els diners no són mai coma flotant, claus primàries de text amb prefix, CHECK als enumerats com a defensa en profunditat, dates ISO-8601 l'ordre alfabètic de les quals és el cronològic, i índexs posats exactament on 02-06 va dir que hi hauria filtres i ordenacions—. Les migracions numerades i immutables converteixen "l'esquema" en una cosa que es desplega, es revisa en un pull request i es reprodueix a qualsevol màquina amb npm run migrar.

I has vist els quatre problemes que separen una capa de dades ingènua d'una de professional. Les sentències preparades, que no escapen cometes sinó que envien el SQL i les dades per camins diferents, amb la llista blanca per a l'única cosa que no admet marcadors, l'ORDER BY. Les transaccions, que fan que crear una comanda descomptant estoc de diverses línies sigui tot o res, amb la condició AND estoc >= ? a l'UPDATE com a protecció veritable davant de dos compradors simultanis. El control de concurrència optimista amb versio, que converteix una actualització perduda silenciosa en un 409 conflicte_versio visible. I l'N+1, juntament amb la paginació per cursor que fa que la pàgina cinc mil costi el mateix que la primera.

Queda una porta oberta de bat a bat: qualsevol pot crear, modificar i esborrar cafès, i GET /v1/comandes retorna les comandes de tots els clients a qui ho pregunti. A 03-06, Autenticació i autorització, la tanquem: distingirem autenticació d'autorització —el 401 del 403 que el contracte separa des de 02-04—, registrarem clients amb la contrasenya protegida amb bcrypt, emetrem i verificarem JWT signats amb el secret que ja viu a .env, escriurem el middleware que distingeix token absent de token caducat i retorna WWW-Authenticate, i aplicarem els rols client, empleat, administrador i soci amb una matriu de permisos per endpoint i comprovació de propietat a nivell de recurs.