Cada vez que node --watch reinicia el servidor, los cafés vuelven a ser dos y el pedido ped_5001 resucita en pendiente_pago. Los arrays en memoria nos han servido para construir el contrato sin distracciones, pero no son una base de datos: no sobreviven a un reinicio, no pueden garantizar que descontar stock de tres líneas ocurra de forma atómica y no escalan más allá de unos pocos miles de registros. Hoy los sustituimos por SQLite con better-sqlite3 detrás del patrón repositorio, y lo haremos cumpliendo la promesa que hicimos en 03-01: no se toca ni una línea de los controladores ni de los servicios. Por el camino veremos el esquema SQL de Tienda Aroma con el dinero en céntimos enteros, migraciones versionadas, sentencias preparadas y por qué eliminan la inyección SQL, transacciones para crear un pedido, control de concurrencia optimista, el problema N+1 y la paginación por cursor implementada de verdad.

1. Qué cambia hoy en el proyecto
2. El patrón repositorio
3. Qué base de datos y por qué SQLite en este curso
4. better-sqlite3: síncrono y sin sorpresas
5. El esquema SQL de Tienda Aroma
6. snake_case en la base de datos y camelCase en el JSON
7. Migraciones: qué son y por qué se versionan
8. El script de migración y los datos de siembra
9. La conexión: src/config/base-datos.js
10. src/repositorios/cafes-sqlite.js con sentencias preparadas
11. Por qué las sentencias preparadas evitan la inyección SQL
12. Consultas dinámicas seguras: filtros, orden y paginación
13. Transacciones: crear un pedido descontando stock
14. Concurrencia optimista y conflicto_version
15. El problema N+1 al cargar las líneas
16. Paginación por cursor de verdad
17. ORMs: cuándo compensan
18. Conexiones y cierre ordenado

Que la lista de modificaciones sea tan corta es el resultado que buscábamos. Si los controladores hubieran hablado directamente con el array, hoy tocaríamos veinte ficheros.

Un repositorio es un objeto que ofrece operaciones sobre una colección de entidades y esconde por completo dónde y cómo están guardadas. La interfaz que ya venimos usando desde 03-02:

Las tres propiedades que hacen que valga la pena:

• Sustituibilidad. cafes-memoria.js y cafes-sqlite.js cumplen la misma interfaz. Cambiar de uno a otro es cambiar un import, y en 03-08 usaremos precisamente el de memoria como doble de prueba.
• Localización del SQL. Todo el SQL de cafés está en un fichero. Cuando una consulta va lenta, sabes dónde mirar; cuando cambia una columna, sabes qué revisar.
• Vocabulario de dominio. El servicio pide buscarPorId('caf_001'), no ejecuta un SELECT. La lógica de negocio se lee sin ruido técnico.

Y el límite del patrón, dicho con honestidad: no hace que las bases de datos sean intercambiables por arte de magia. Una consulta con JSON_EXTRACT de SQLite no funciona igual en MongoDB. Lo que el repositorio garantiza es que, si hay que reescribirla, se reescribe en un sitio.

Por qué SQLite en el curso: porque no hay nada que instalar ni configurar, la base de datos es un fichero que puedes borrar y regenerar en un segundo, y el SQL que escribiremos es SQL estándar, así que lo aprendido se transfiere. Lo que aprendas de sentencias preparadas, transacciones, índices y N+1 vale exactamente igual en PostgreSQL.

Qué cambiaría con PostgreSQL. Poco en el diseño y bastante en la mecánica: se usaría el paquete pg con un pool de conexiones, las llamadas serían asíncronas (await cliente.query(...)), los marcadores de posición serían $1, $2 en vez de ?, y las transacciones se escribirían con BEGIN/COMMIT explícitos sobre una conexión reservada del pool. Los tipos ganarían precisión: TIMESTAMPTZ para las fechas, NUMERIC disponible para el dinero, JSONB con índices para las notas de cata. La estructura del repositorio, sin embargo, sería la misma; por eso empezar por SQLite no es una vía muerta.

Qué cambiaría con MongoDB. Más: desaparecen las uniones, un pedido guardaría sus líneas incrustadas en el propio documento —lo cual, curiosamente, elimina de raíz el problema N+1 de la sección 15— y las transacciones multidocumento existen pero se usan mucho menos. Es una elección razonable para catálogos con atributos muy variables; para pedidos, con su integridad referencial y sus totales, lo relacional encaja mejor.

La rareza de better-sqlite3 es que su API es síncrona: db.prepare(sql).get(id) devuelve la fila directamente, sin await. En un ecosistema donde todo lo que toca entrada/salida es asíncrono, esto choca. Y es correcto:

• SQLite no es un servidor: no hay red, no hay latencia. La consulta es una lectura de fichero, a menudo desde la caché del sistema operativo, que tarda microsegundos.
• Envolver esa operación en una promesa añadiría más sobrecarga que la propia consulta.
• El código resultante es más simple y las transacciones son triviales: sin await de por medio, no hay riesgo de que otra petición se cuele en mitad de una transacción.

La contrapartida: si una consulta tarda 200 ms, bloquea el bucle de eventos y ninguna otra petición avanza durante ese tiempo. La consecuencia práctica es que hay que mantener las consultas rápidas —con índices, sin escaneos completos— y no hacer informes pesados en el mismo proceso que sirve la API. Con PostgreSQL y pg, todo sería asíncrono y este problema no existiría.

Nuestros servicios ya están escritos de forma síncrona desde 03-03, así que la migración es directa. Si mañana pasáramos a PostgreSQL, habría que convertir en async los métodos del repositorio, del servicio y del controlador —y ahí el envoltorio asincrono() que veremos en 03-07 se vuelve imprescindible.

Decisiones del esquema que conviene justificar una a una:

precio_centimos INTEGER. Es la decisión de 02-05 llevada a la base de datos. Un REAL (coma flotante) sería un error de diseño: SELECT SUM(precio) FROM ... acumularía errores de redondeo y el total del pedido podría diferir en céntimos del que se le mostró al cliente. Con enteros, la suma es exacta por definición. En PostgreSQL se podría usar NUMERIC(10,2), que también es exacto; el entero de céntimos funciona en cualquier motor.

Claves primarias de texto (caf_001). Rompe la costumbre del INTEGER AUTOINCREMENT, y a cambio da lo que decidimos en 02-02: identificadores opacos que dicen de qué tipo son y que no filtran cuántos registros hay. El coste es un índice algo mayor y comparaciones de cadena en lugar de enteros, irrelevante a esta escala.

CHECK en los enumerados. La validación de Zod (03-04) ya rechaza un tueste inválido, pero el CHECK protege frente a cualquier vía de entrada: un script de importación, una corrección manual con sqlite3, un bug futuro. Es defensa en profundidad, y no sustituye a la validación en el borde, la complementa: el CHECK produce un error de base de datos, no un 400 amable.

notas_cata como texto JSON. SQLite no tiene tipo array. Guardamos '["cítrico","floral"]' y lo parseamos al leer. Es aceptable porque nunca filtramos por una nota concreta con SQL; el ?q= busca dentro del texto. Si mañana hiciera falta filtrar por nota, lo correcto sería una tabla cafes_notas con una fila por nota. En PostgreSQL usaríamos JSONB con un índice GIN y no habría discusión.

activo INTEGER. SQLite no tiene booleano: se usa 1 y 0. Y hay un detalle práctico importante: better-sqlite3 rechaza los booleanos de JavaScript como parámetros; hay que pasar 1 o 0 explícitamente. Es un error que sorprende la primera vez.

Fechas como TEXT en ISO-8601 UTC. SQLite tampoco tiene tipo fecha. El formato ISO-8601 tiene una propiedad valiosísima: el orden alfabético coincide con el orden cronológico, así que ORDER BY fecha_creacion DESC funciona correctamente sobre texto. Eso es exactamente lo que hace posible la paginación por cursor de la sección 16.

version INTEGER. Es el contador para el control de concurrencia optimista de la sección 14.

Tenemos tres vocabularios y hay que saber dónde se traduce cada uno:

Y las dos fronteras:

• BD → modelo interno: en el repositorio, en una función aModelo(fila).
• Modelo interno → JSON: en el mapeador de 03-03 (cafeARepresentacion).

Podríamos habernos ahorrado la primera traducción usando camelCase también en las columnas. No lo hacemos porque snake_case es la convención universal en SQL —las herramientas, los volcados y los DBA lo esperan— y porque en PostgreSQL los identificadores en mayúsculas obligan a entrecomillar en cada consulta. Que la traducción viva en una sola función del repositorio hace el coste despreciable.

Una migración es un cambio del esquema escrito como un fichero SQL, numerado, inmutable y versionado en Git.

El problema que resuelve es este: tú creas la tabla cafes en tu portátil ejecutando SQL a mano. Tu compañero no la tiene. El servidor de pruebas tiene una versión antigua sin la columna version. Producción tiene otra distinta. Nadie sabe qué esquema hay en cada sitio, y aplicar un cambio se convierte en un ritual manual con actas.

Las reglas de las migraciones, que no admiten excepciones:

1. Numeradas y ordenadas: 001-inicial.sql, 002-anadir-descuentos.sql.
2. Inmutables: una migración aplicada jamás se edita. Si estaba mal, se corrige con otra nueva.
3. Versionadas en Git, junto al código que las necesita.
4. Registradas: la propia base de datos guarda cuáles se han aplicado.

Esa cuarta regla exige una tabla más, que añadimos al principio del fichero de migraciones:

Y la siembra, que carga los datos con los que trabajamos todo el curso:

Con los scripts en package.json:

Siembra y migración son cosas distintas. La migración cambia la estructura y se ejecuta en todos los entornos, producción incluida. La siembra mete datos y solo tiene sentido en desarrollo y en pruebas. Mezclarlas —INSERT dentro de una migración— es un error clásico que acaba metiendo cafés de prueba en producción.

La línea de foreign_keys = ON es la que más disgustos evita: sin ella, SQLite acepta alegremente una línea de pedido que apunta a un café inexistente y el problema se descubre meses después con datos huérfanos.

Sobre la generación de identificadores: siguienteNumero calcula el máximo existente y suma uno. Funciona porque SQLite serializa las escrituras, y lo envolveremos en la misma transacción que la inserción. En PostgreSQL usaríamos una SEQUENCE, y en un sistema distribuido lo habitual sería un ULID o un UUID con prefijo (caf_01HQ...), que se genera sin consultar nada y no revela el volumen de negocio.

Compara estas dos formas de buscar por origen:

Con la primera, si el cliente envía ?origen=x' OR '1'='1, el SQL que se ejecuta es:

Devuelve el catálogo entero. Y con un poco más de imaginación —x'; DROP TABLE pedidos; --— destruye datos. Esa técnica está en el primer puesto de los riesgos de seguridad desde hace veinte años y sigue funcionando en aplicaciones reales.

Por qué la versión con ? es inmune. No es que "escape las comillas": es que el SQL y los datos viajan por caminos separados. La sentencia se analiza y se compila antes de conocer los valores, produciendo un plan de ejecución con huecos. Cuando se ejecuta, cada valor se coloca en su hueco como dato, ya en el motor, sin volver a pasar por el analizador. Por definición, un valor no puede convertirse en instrucción: x' OR '1'='1 se busca literalmente como origen, no encuentra nada, y devuelve cero filas. El motor no ve una comilla especial; ve una cadena de veinte caracteres.

Tres consecuencias prácticas:

• Marcadores en todos los valores. Siempre. Aunque el dato "venga de dentro", aunque sea un número, aunque estés seguro.
• Los marcadores solo valen para valores, no para nombres de tabla, de columna ni para ASC/DESC. Eso se resuelve con listas blancas, como veremos ahora mismo.
• La validación de 03-04 no sustituye a esto. Es defensa en profundidad: la validación filtra formas, las sentencias preparadas hacen imposible el ataque.

buscar() tiene que combinar filtros opcionales. La técnica es construir la lista de condiciones y la lista de parámetros a la vez, sin concatenar nunca un valor:

Tres puntos críticos:

El total sale de una consulta aparte con el mismo WHERE. No se puede obtener de la consulta paginada, porque LIMIT recorta. Y tiene que llevar exactamente los mismos filtros, o el cliente calculará mal el número de páginas. Es un COUNT(*) extra por petición, y es el precio de la paginación por offset.

ORDER BY se construye por concatenación, pero solo con valores de COLUMNAS_ORDENABLES. El nombre que envía el cliente se usa como clave de búsqueda en el mapa, nunca como texto SQL. Si no está en el mapa, no hay columna. Es imposible inyectar nada por ahí.

El comodín del LIKE va en el parámetro. '%' || ? || '%' también sería válido, pero poner el patrón completo en el parámetro es más claro. Lo que nunca puede hacerse es LIKE '%${q}%'.

Una nota de rendimiento: LIKE '%texto%' con comodín inicial no puede usar un índice y obliga a recorrer la tabla entera. Con 200 cafés es irrelevante; con 200.000 registros haría falta un índice de texto completo (FTS5 en SQLite, tsvector en PostgreSQL) o un motor de búsqueda dedicado. Es una limitación conocida y aceptada del ?q= que prometimos en 02-06.

Finalmente, el selector de implementación:

Y en src/servicios/cafes.js cambia una línea:

Ahí está la promesa cumplida. Reinicia, prueba curl -s http://localhost:3000/v1/cafes | jq .total y comprueba que todo responde igual… y que ahora sobrevive a los reinicios.

Crear un pedido no es una operación: son varias que deben ocurrir todas o ninguna.

1. Comprobar que cada café existe y tiene stock.
2. Insertar la fila del pedido.
3. Insertar una línea por café.
4. Descontar el stock de cada café.

Sin transacción, un fallo en el paso 4 —por ejemplo, porque el stock ya no alcanza— dejaría un pedido cobrable con el inventario sin tocar. Eso es corrupción de datos.

Una transacción garantiza las cuatro propiedades ACID; la que nos importa aquí es la atomicidad: o se aplican todos los cambios, o ninguno.

Qué pasa si falla a mitad. Supón que la segunda línea se queda sin stock porque otro cliente se adelantó por 30 milisegundos. La excepción sube, better-sqlite3 ejecuta ROLLBACK y el estado de la base de datos vuelve exactamente a como estaba: no hay pedido, no hay líneas, y el stock del primer café no se ha descontado. El servicio traduce ese error a 409 stock_insuficiente y el cliente puede reintentar. Sin transacción tendríamos un pedido incompleto, una línea huérfana y stock descontado por un pedido que nunca existió.

Por qué el stock se comprueba dos veces. La primera lectura (cafeParaPedido) sirve para dar un mensaje de error útil con el nombre del café y las unidades que quedan. La segunda, la condición AND stock >= ? dentro del UPDATE, es la que de verdad protege: es una comprobación y una escritura en una sola sentencia atómica, así que no hay ventana entre leer y escribir. Este patrón —comprobar en el WHERE de la actualización y mirar changes— es la forma correcta de evitar que dos peticiones simultáneas vendan la misma última bolsa de café.

Un detalle de better-sqlite3 que hay que respetar: dentro de una transacción no puede haber await. Como su API es síncrona, no lo necesitamos; pero si mezclaras una llamada asíncrona ahí dentro, la transacción se cerraría antes de tiempo. Con PostgreSQL, en cambio, todo el bloque sería async y habría que reservar una conexión del pool para toda la transacción.

Otro problema de concurrencia, distinto del stock: la actualización perdida.

Sin control, el segundo PATCH machacaría el precio nuevo con el que B leyó hace un minuto, y nadie se enteraría. El bloqueo optimista lo detecta: cada actualización exige la versión que el cliente leyó.

Y el servicio traduce ese null al 409 conflicto_version del catálogo:

Dos precisiones sobre el catálogo de 02-04. Allí conflicto_version aparecía asociado a 412 Precondition Failed, que es el código correcto cuando el cliente envía la condición en la cabecera If-Match con un ETag —el mecanismo estándar de HTTP, que veremos con el caché condicional en 04-06—. Aquí la condición viaja como un campo version en el cuerpo, sin cabecera condicional, y entonces el código adecuado es 409 Conflict: la petición era válida pero choca con el estado actual del recurso. Mismo problema, mismo código de catálogo, dos códigos HTTP según cómo se exprese la condición. Y el matiz sobre el nombre "optimista": se llama así porque no bloquea nada; asume que los conflictos son raros y se limita a detectarlos. El pesimista (SELECT ... FOR UPDATE) bloquea la fila, y solo compensa cuando los conflictos son frecuentes.

Así es como no se cargan los pedidos con sus líneas:

Con 20 pedidos son 21 consultas. El código parece inocente porque la consulta está escondida dentro del bucle, y por eso el problema N+1 es tan común. En SQLite, con la base en local, el coste es pequeño; con PostgreSQL en otra máquina y 2 ms de red por consulta, esos 21 viajes son 42 ms de latencia pura para devolver una página. Y si la lista fueran 100 pedidos, 200 ms.

La solución: una segunda consulta para todas las líneas de golpe.

Dos consultas, sea cual sea el número de pedidos. La alternativa sería un único JOIN, que también funciona pero devuelve el pedido repetido tantas veces como líneas tenga y obliga a deduplicar. Con dos consultas el código queda más claro y el rendimiento es equivalente.

Un aviso: IN (...) tiene un límite de parámetros (999 por defecto en SQLite). Como nuestras páginas son de 100 como máximo, no nos afecta; en un proceso por lotes habría que trocear.

En 02-06 decidimos que /v1/pedidos usaría cursor, y ahora se ve por qué. Con OFFSET, el motor tiene que recorrer y descartar todas las filas anteriores:

Es el deep paging: la página 1 es instantánea y la 5.000 tarda segundos. Y además es inestable: si entra un pedido nuevo mientras el cliente pagina, todo se desplaza una posición y ve un pedido repetido.

El cursor resuelve las dos cosas guardando el último elemento visto en lugar de un número de posición:

La comparación de tuplas (a, b) < (x, y) es SQL estándar y significa "a < x, o bien a = x y b < y". Es exactamente el desempate que necesitábamos, expresado en una condición.

Tres decisiones a subrayar. El cursor es opaco: base64 de un JSON interno. No es cifrado —cualquiera puede descodificarlo— pero sí es explícitamente "no es asunto tuyo": el contrato de 02-06 prohíbe construirlo a mano, y así podemos cambiar su contenido sin romper a nadie. Pedir limite + 1 filas es el truco estándar para saber si hay más sin un COUNT extra. Y la paginación por cursor no ofrece total ni salto a la última página: es el precio que se paga, y por eso el contrato reservó el cursor para /v1/pedidos —donde el histórico es enorme y solo se avanza— y dejó el offset en /v1/cafes, donde el catálogo es pequeño y saber el total importa.

El índice idx_pedidos_cliente_fecha (cliente_id, fecha_creacion DESC, id DESC) está construido justo para esta consulta: el motor localiza el punto de corte con una búsqueda en el árbol y lee 21 filas seguidas. El coste no depende de lo lejos que esté la página.

A favor: menos código repetitivo, migraciones integradas, tipado del resultado, portabilidad entre motores, y relaciones cargadas sin escribir el JOIN.

En contra: una abstracción más que aprender y depurar; consultas generadas que sorprenden; el problema N+1 oculto —un .lineas que parece un acceso a propiedad y en realidad dispara una consulta—; y dificultad para expresar SQL avanzado.

El criterio: si tu aplicación tiene muchas entidades con relaciones parecidas y CRUD repetitivo, un ORM ahorra semanas. Si tiene pocas entidades y consultas exigentes, el SQL directo tras un repositorio —lo que hemos hecho— es más simple y más rápido. Y con el patrón repositorio, la decisión es reversible: adoptar Prisma mañana significaría reescribir los ficheros de src/repositorios/, y nada más.

SQLite es un fichero y no necesita pool: una única conexión por proceso, abierta al arrancar. El modo WAL permite lecturas concurrentes con la escritura, y busy_timeout gestiona los choques de escritores.

Con PostgreSQL sí haría falta un pool: abrir una conexión TCP cuesta decenas de milisegundos, así que se mantiene un conjunto reutilizable (new Pool({ max: 10 })). Ahí aparecen problemas propios —agotamiento del pool por conexiones que no se devuelven, transacciones que hay que ejecutar sobre una conexión reservada— que no tenemos aquí.

Lo que sí hay que hacer es cerrar la base de datos al apagar. Actualizamos src/servidor.js:

close() de better-sqlite3 vuelca el WAL al fichero principal y libera el bloqueo. Sin él, un apagado brusco deja ficheros -wal y -shm sueltos que SQLite sabe recuperar, pero no hay razón para depender de eso.

1. Concatenar valores en el SQL. Inyección garantizada. Marcadores de posición siempre, sin excepciones ni "es que este valor viene de dentro".

2. Olvidar PRAGMA foreign_keys = ON. SQLite las ignora por defecto y acabas con líneas que apuntan a pedidos inexistentes.

3. Pasar un booleano de JavaScript como parámetro. better-sqlite3 lo rechaza. Convierte a 1 / 0.

4. Guardar dinero en REAL. El error más caro de la lista. INTEGER de céntimos, o NUMERIC donde exista.

5. Editar una migración ya aplicada. Tu base se actualiza, la de tus compañeros no, y el registro de migraciones miente. Corrige siempre con una migración nueva.

6. Mezclar siembra y migración. Los datos de prueba acaban en producción.

7. Consultar dentro de un bucle. Es el N+1. Si ves un prepare dentro de un for, párate: casi siempre hay una versión con IN (...).

8. Calcular el total sobre la consulta paginada. El COUNT va con los mismos filtros y sin LIMIT.

9. Prepared statements dentro del manejador. db.prepare() en cada petición desperdicia el análisis del SQL. Prepara al cargar el módulo y reutiliza.

Consejo: cuando una consulta vaya lenta, pide el plan antes de tocar nada: EXPLAIN QUERY PLAN SELECT .... Si aparece SCAN TABLE, falta un índice; si aparece SEARCH TABLE ... USING INDEX, va bien.

Escribe la migración 002-anadir-descuentos.sql, que añade a cafes una columna descuento_porcentaje (entero, entre 0 y 50, por defecto 0). Explica por qué esta migración es un cambio retrocompatible para los consumidores de la API (02-07) y qué habría que hacer además para que el campo aparezca en el JSON.

Implementa buscarResenasDeCafe(cafeId, { estado, limite, desplazamiento }) en un nuevo src/repositorios/resenas-sqlite.js. Debe devolver { elementos, total }, filtrar por estado si se indica, ordenar por fecha_creacion DESC con desempate por id, y no devolver reseñas de un café inexistente sin distinguirlo de un café sin reseñas. Indica qué índice del esquema la sostiene.

Dos empleados abren a la vez la ficha de caf_001 (version: 7). El primero cambia el precio a 15,90 € y el segundo, treinta segundos después, cambia el stock a 200 usando la versión 7 que leyó. Describe qué ocurre paso a paso con actualizarCafeConVersion, qué responde la API al segundo, y compáralo con lo que pasaría sin control de versión. Después explica por qué este mecanismo no serviría para el descuento de stock del pedido y qué se usa en su lugar.

Solución 1

Por qué es retrocompatible: la columna tiene DEFAULT 0 y NOT NULL, así que las filas existentes se rellenan solas y ninguna inserción anterior deja de funcionar. Desde el punto de vista de la API, añadir un campo a una representación es un cambio aditivo (02-07): un consumidor que ignore descuentoPorcentaje sigue funcionando igual, porque un cliente JSON bien escrito ignora los campos que no conoce. No haría falta una v2.

Qué falta para que aparezca en el JSON: tres cosas, y ninguna en la base de datos. Añadir descuentoPorcentaje: fila.descuento_porcentaje en aModelo() del repositorio; añadirlo a cafeARepresentacion() en el mapeador; y añadirlo a openapi.yaml con su descripción. Que hagan falta exactamente esos tres sitios, y que sean siempre los mismos, es la señal de que la arquitectura por capas está bien puesta.

Solución 2

Índice que la sostiene: idx_resenas_cafe ON resenas (cafe_id, estado). Cubre el filtro obligatorio por cafe_id y, cuando se añade estado, también el segundo. La ordenación por fecha_creacion DESC no está cubierta, así que el motor ordena en memoria el subconjunto de reseñas de ese café —aceptable, porque son pocas—. Si un café llegara a tener miles, el índice ideal sería (cafe_id, estado, fecha_creacion DESC, id DESC), que serviría filtro y orden de una vez. Compruébalo con EXPLAIN QUERY PLAN.

Solución 3

Paso a paso:

1. Ambos leen caf_001 con version: 7.
2. El primero envía su cambio con version: 7. El UPDATE ... WHERE id = 'caf_001' AND version = 7 encuentra la fila, aplica el precio y sube la versión a 8. changes === 1, y la API responde 200 con la representación actualizada.
3. El segundo envía su cambio con version: 7. El WHERE ... AND version = 7 no encuentra ninguna fila, porque ahora vale 8. changes === 0 y el café sí existe → conflicto.
4. La API responde 409 conflicto_version con el mensaje que le pide recargar y repetir.

Sin control de versión: el segundo UPDATE habría escrito su copia completa del café, incluido el precio_centimos de 1450 que leyó hace medio minuto. El cambio de precio del primero desaparece sin dejar rastro: ningún error, ningún log, ningún indicio. Es la actualización perdida, y su gravedad está en que es silenciosa: el primer empleado ve su 200 OK, se va tranquilo, y el precio antiguo reaparece.

Por qué no sirve para el stock del pedido. Son dos problemas distintos. El bloqueo optimista exige que el cliente haya leído el recurso y devuelva su versión, y protege una sustitución completa del recurso. El descuento de stock, en cambio, es una operación relativa —"resta 2 a lo que haya"— que nadie ha leído previamente: el comprador no envía la versión del café ni tiene por qué conocerla. Si lo hiciera, dos compras simultáneas de cafés distintos del mismo pedido darían 409 constantemente y la tienda sería inusable.

Lo que se usa en su lugar es la condición dentro del propio UPDATE:

Aquí la lectura y la escritura ocurren en la misma sentencia atómica, así que no hay ventana entre comprobar y actualizar. Si dos peticiones intentan comprar la última bolsa, una obtiene changes === 1 y la otra changes === 0, y esta última recibe 409 stock_insuficiente. La regla general: el bloqueo optimista para actualizaciones absolutas; la condición en el WHERE para las relativas.

Los datos de Tienda Aroma ya viven en una base de datos de verdad, y el cambio ha costado tres líneas de import fuera de la carpeta repositorios/. Eso es lo que compra el patrón repositorio: el resto de la aplicación nunca supo dónde estaban los cafés. El esquema SQL traduce las decisiones de contrato a estructura —precio_centimos entero porque el dinero nunca es coma flotante, claves primarias de texto con prefijo, CHECK en los enumerados como defensa en profundidad, fechas ISO-8601 cuyo orden alfabético es el cronológico, e índices puestos exactamente donde 02-06 dijo que habría filtros y ordenaciones—. Las migraciones numeradas e inmutables convierten "el esquema" en algo que se despliega, se revisa en un pull request y se reproduce en cualquier máquina con npm run migrar.

Y has visto los cuatro problemas que separan una capa de datos ingenua de una profesional. Las sentencias preparadas, que no escapan comillas sino que mandan el SQL y los datos por caminos distintos, con la lista blanca para lo único que no admite marcadores, el ORDER BY. Las transacciones, que hacen que crear un pedido descontando stock de varias líneas sea todo o nada, con la condición AND stock >= ? en el UPDATE como verdadera protección frente a dos compradores simultáneos. El control de concurrencia optimista con version, que convierte una actualización perdida silenciosa en un 409 conflicto_version visible. Y el N+1, junto con la paginación por cursor que hace que la página cinco mil cueste lo mismo que la primera.

Queda una puerta abierta de par en par: cualquiera puede crear, modificar y borrar cafés, y GET /v1/pedidos devuelve los pedidos de todos los clientes a quien pregunte. En 03-06, Autenticación y autorización, la cerramos: distinguiremos autenticación de autorización —el 401 del 403 que el contrato separa desde 02-04—, registraremos clientes con la contraseña protegida con bcrypt, emitiremos y verificaremos JWT firmados con el secreto que ya vive en .env, escribiremos el middleware que distingue token ausente de token caducado y devuelve WWW-Authenticate, y aplicaremos los roles cliente, empleado, administrador y socio con una matriz de permisos por endpoint y comprobación de propiedad a nivel de recurso.