7.1 ASR, transacciones, concurrencia e idempotencia

Al terminar esta lección

• Distinguir un ASR de un NFR común o de una decisión de implementación, y registrarlo con su origen y su prueba.
• Derivar la frontera transaccional de un caso de uso a partir de su garantía mínima, y justificar qué efectos quedan afuera.
• Formular una invariante concurrente, detectar una carrera read-then-write y elegir el mecanismo mínimo que la protege en PostgreSQL.
• Diseñar la semántica de idempotencia (mismo requestId con mismo payload y con payload distinto) y el patrón outbox para efectos posteriores al commit.
• Leer y redactar un ADR completo con contexto, alternativas, consecuencias y disparador de revisión.

7. Cuando el negocio empieza a empujar la arquitectura

La arquitectura no empieza con "¿microservicios o monolito?". Empieza cuando un requisito o un riesgo obliga a tomar una decisión estructural que será costosa de cambiar después.

Hasta el módulo 6 trabajaste con evidencia, reglas y especificación. Ahora cada una de esas piezas se vuelve una pregunta técnica concreta: la regla RN-05 (disponible = onHand - reserved, nunca negativo) pregunta dónde se decide la disponibilidad; la RN-06 (una intención de pedido no genera dos pedidos) pregunta cómo se reconoce un reintento; el NFR-04 (una falla fiscal después del commit no duplica pedido ni comprobante) pregunta qué pasa después de la transacción.

7.1 Requisitos arquitectónicamente significativos

El problema. Un equipo que trata todo NFR como decisión de arquitectura termina con un diagrama enorme; uno que no trata ninguno descubre en producción que la estructura no soporta lo que el negocio necesitaba. Hace falta un criterio para separar lo que cambia la forma del sistema de lo que se resuelve dentro de la forma elegida.

Definición operativa. No todos los NFR merecen una decisión arquitectónica explícita. Un ASR es una restricción o cualidad que, si cambia, puede modificar la estructura de la solución. Para decidir si algo es ASR hacé tres preguntas:

1. Si este requisito cambiara de valor, ¿tendríamos que mover una frontera (de módulo, de transacción, de proceso, de base)?
2. ¿Revertir la decisión después de tener datos y usuarios es caro?
3. ¿Hay evidencia de que el riesgo existe en Nexo, o lo estamos trayendo de otro sistema?

Ejemplos de la bibliografía general: multi-depósito con reserva concurrente, integración fiscal obligatoria, operación offline en depósito, auditoría legal, picos de cientos de pedidos concurrentes. Identificar ASR evita diseñar arquitectura por moda.

Ejemplo en Nexo. Nexo tiene alrededor de decenas de usuarios internos (en el caso ficticio: unos treinta, con picos de unos treinta concurrentes) y cientos de clientes B2B, no millones de usuarios públicos. Eso importa: una arquitectura distribuida por prestigio añadiría coordinación, observabilidad y fallos sin que exista una necesidad de escala que la justifique. La reserva concurrente, la integración fiscal y la autoridad de precios sí son ASR porque pueden romper dinero o integridad. El equipo los deja en un registro versionado en el repositorio:

1asr:
2  - id: ASR-01
3    titulo: Reserva concurrente sin sobreventa por depósito y SKU
4    origen: [RN-05, AC-06, EV-05]
5    escenario: >
6      Dos vendedores confirman pedidos distintos por la última unidad de un SKU
7      en el mismo depósito. Exactamente uno obtiene la reserva y el
8      disponible final nunca es negativo.
9    por_que_es_estructural: >
10      La decisión de disponibilidad tiene que tomarse en la misma fuente
11      que la actualiza, de forma atómica. No se puede resolver en la UI ni en un cache.
12    decisiones: [ADR-002]
13    prueba: T06
14​
15  - id: ASR-02
16    titulo: La misma intención de pedido no produce dos pedidos
17    origen: [RN-06, AC-07]
18    escenario: >
19      El cliente reintenta un POST porque la red cortó después de que el
20      servidor confirmó. Mismo requestId y mismo payload devuelven el mismo
21      pedido. Mismo requestId con payload distinto devuelve conflicto.
22    por_que_es_estructural: >
23      Exige persistir la intención en la misma transacción que el pedido.
24    decisiones: [ADR-005, ADR-006]
25    prueba: [T07, T08]
26​
27  - id: ASR-03
28    titulo: Los efectos externos se entregan después del commit y sobreviven a caídas
29    origen: [NFR-04, AC-11, AC-12]
30    escenario: >
31      El pedido se confirma, el sistema de preparación o el proveedor fiscal
32      no responde. El pedido sigue siendo válido, la entrega queda
33      pendiente, es observable y se reintenta sin duplicar.
34    por_que_es_estructural: >
35      Obliga a un mecanismo de entrega durable y a un proceso que no es el request.
36    decisiones: [ADR-003, ADR-004]
37    prueba: [T12]
38​
39  - id: ASR-04
40    titulo: El servidor es la autoridad de precio, crédito, estado y permisos
41    origen: [RN-01, RN-03, NFR-03]
42    escenario: >
43      Un cliente web manipulado envía unitPrice, creditApproved o reserved=true.
44      El servidor los ignora y decide desde fuentes autoritativas.
45    por_que_es_estructural: >
46      Define qué datos viven en Nexo y cuáles se leen del ERP en cada request.
47    decisiones: [ADR-001]
48    prueba: [T10]
49​
50  - id: ASR-05
51    titulo: Toda autorización de crédito es reconstruible
52    origen: [NFR-02]
53    escenario: >
54      Seis meses después alguien pregunta quién autorizó un sobregiro, con qué
55      regla y por qué motivo. La respuesta está en la base, no en un audio de WhatsApp.
56    por_que_es_estructural: >
57      La escritura de auditoría comparte transacción con la decisión.
58    decisiones: [ADR-001]
59    prueba: [T04]
60​
61restricciones:
62  - id: RES-01
63    titulo: Equipo pequeño y operación simple
64    detalle: >
65      Cada componente adicional necesita despliegue, backup, alerta y guardia.
66      El costo operativo cuenta como requisito.
67​
68no_son_asr:
69  - id: NFR-01
70    motivo: >
71      p95 < 800 ms para registrar un pedido con 30 usuarios concurrentes se cumple
72      con índices y consultas razonables dentro de la estructura elegida. Pasaría
73      a ser ASR solo si una medición mostrara que la estructura no puede alcanzarlo.

El registro tiene una virtud poco glamorosa: obliga a escribir, junto a cada ASR, qué prueba lo defiende. Un ASR sin prueba es un deseo.

Contraejemplo. "Necesitamos escalar" sin número ni escenario. En Nexo, el único número que existe es el de usuarios internos y es chico. Que no haya ASR de escala independiente es un hallazgo tan importante como los ASR que sí hay: es lo que va a sostener el ADR-001.

Cómo se verifica. Para cada fila del registro: ¿tiene origen (RN, NFR, EV)? ¿Tiene escenario con condiciones observables? ¿Tiene decisión asociada y prueba? ¿Hay algún componente del diagrama que no apunte a ningún ASR o restricción?

7.2 Diseñar transacciones desde la garantía mínima

El problema. El reflejo habitual es envolver "todo el método" en una transacción por seguridad. Eso alarga la transacción, retiene locks mientras se espera a terceros y no garantiza nada sobre lo que realmente importa.

Definición operativa. Las clases de control a menudo encapsulan transacciones; en Eje Z la frontera transaccional se deriva de la garantía mínima del CU. Si "pedido + reserva + movimiento de crédito" deben ser atómicos, la transacción debe contener las mutaciones que hacen verdadera esa garantía, no simplemente "todo el método por seguridad".

La garantía mínima de CU-01 dice: no existe pedido confirmado con precio no autorizado, reserva negativa o decisión de crédito ausente, y ante cualquier fallo antes del commit no queda pedido parcial, débito ficticio ni reserva huérfana. De ahí sale la lista de lo que comparte transacción.

Ejemplo en Nexo. El orden canónico de CU-01 es validar → calcular precio → evaluar crédito → reservar stock, todo en la misma transacción. Para CU-01, una unidad transaccional razonable incluye pedido, líneas con su snapshot de precio, reservas, decisión de crédito, registro de idempotencia y el evento de outbox, dentro de la misma base autoritativa. No incluimos una llamada HTTP al proveedor fiscal ni al sistema de preparación: una red externa puede tardar, caer o responder después de que la base ya decidió. Separar el commit local del efecto externo nos obliga a diseñar el "después" con idempotencia y reintentos.

Antipatrón. La llamada externa dentro de la transacción. Parece inofensiva porque el código queda "en orden", pero la conexión y los locks de stock_level quedan retenidos mientras el proveedor decide cuánto tarda:

1 await db.transaction(async tx => {
2   const reserved = await stock.reserve(tx, input);
3   const order = await orders.insert(tx, input, reserved);
4-  await fiscalClient.requestInvoice(order.id); // 30 s de timeout con la fila de stock bloqueada
5+  await outbox.enqueue(tx, "order.confirmed", { orderId: order.id });
6   return order;
7 });

Si el proveedor responde después de 30 segundos, esa fila de stock_level estuvo 30 segundos bloqueada para los otros 29 vendedores. Y si el proveedor facturó pero la transacción después falla, tenés un comprobante de un pedido que no existe.

Cómo se verifica. Para cada mutación del caso de uso, preguntá: "si esto falla, ¿la garantía mínima deja de ser cierta?". Si la respuesta es sí, va adentro. Para cada efecto externo, preguntá: "si esto falla, ¿hay que deshacer el pedido?". Si la respuesta es no, va afuera y necesita un mecanismo de entrega durable.

7.3 Concurrencia: primero la invariante, después el mecanismo

El problema. "¿Usamos locks?" es una pregunta prematura. Sin una propiedad escrita, cualquier mecanismo parece razonable y ninguno se puede probar.

Definición operativa. Primero se define qué condición debe seguir siendo verdadera cuando dos operaciones ocurren al mismo tiempo. Para la última unidad de stock, la invariante puede ser reservado <= disponible; en columnas de Nexo, on_hand - reserved >= 0 por depósito y SKU. Luego se elige el mecanismo mínimo que pueda demostrarla bajo la carga y topología acordadas.

Una invariante bien escrita se puede leer en voz alta sin mencionar tecnología: para cualquier depósito y SKU, la suma de unidades reservadas nunca supera las unidades físicas registradas. Después se arma el escenario A/B que podría romperla.

Ejemplo en Nexo: la carrera. Dos vendedores, una unidad de COR-118 en el depósito Centro (CEN). Cada request, por separado, es correcto. El defecto vive en el entrelazado:

Para encontrarlo en código, leelo como lo haría un revisor: ¿en qué línea se decide y en qué línea se escribe? Si entre ambas hay un await, otro request puede colarse.

Los mecanismos candidatos. La invariante on_hand - reserved >= 0 puede protegerse de varias maneras. La elección depende del patrón de acceso y del motor de persistencia.

Redis no "resuelve carreras" por existir, y una cola tampoco reemplaza una transacción si dos consumidores pueden observar la misma disponibilidad. Para Nexo, PostgreSQL y una operación condicional o bloqueo focal son suficientes.

El mecanismo elegido, en SQL. La condición viaja dentro de la sentencia, y como defensa en profundidad la base también la declara como CHECK:

1CREATE TABLE stock_level (
2  product_id    uuid   NOT NULL REFERENCES product(id),
3  warehouse_id  text   NOT NULL REFERENCES warehouse(id),   -- 'CBA' | 'CEN'
4  on_hand       integer NOT NULL CHECK (on_hand >= 0),
5  reserved      integer NOT NULL DEFAULT 0 CHECK (reserved >= 0),
6  PRIMARY KEY (product_id, warehouse_id),
7  CONSTRAINT disponible_no_negativo CHECK (reserved <= on_hand)   -- RN-05
8);
9​
10-- Reserva atómica: la decisión y la escritura son la misma sentencia.
11UPDATE stock_level
12   SET reserved = reserved + $3
13 WHERE product_id   = $1
14   AND warehouse_id = $2
15   AND on_hand - reserved >= $3
16RETURNING on_hand - reserved AS available_after;
17-- 1 fila  → Reserved
18-- 0 filas → InsufficientStock (o el SKU no existe en ese depósito)

¿Por qué funciona bajo el nivel de aislamiento por defecto de PostgreSQL (READ COMMITTED)? Cuando dos UPDATE apuntan a la misma fila, el segundo espera a que el primero termine; al despertar, PostgreSQL vuelve a evaluar el WHERE contra la versión nueva de la fila. En el escenario de la última unidad, el segundo request ve on_hand - reserved = 0, la condición deja de cumplirse y no actualiza nada. Dos cosas para recordar: la protección depende de que condición y escritura estén en la misma sentencia; y el CHECK es la red de seguridad si alguien escribe un UPDATE manual sin la condición, porque la base rechaza el estado inválido en vez de aceptarlo.

Quedan dos detalles que separan una solución de ejemplo de una solución operable. Primero, un pedido de varias líneas toma varios locks: si dos pedidos piden los mismos SKU en orden distinto pueden quedar esperándose mutuamente (deadlock). La convención es reservar siempre en orden determinista (por ejemplo, ordenando las líneas por SKU). Segundo, la prueba tiene que ejecutar la carrera real: dos transacciones concurrentes sobre una unidad, no dos llamadas secuenciales. Ese test se escribe en el módulo 10 (T06, AC-06).

7.4 Idempotencia: diseñar para que los reintentos sean normales

El problema. Clientes móviles, proxies y agentes pueden reintentar sin saber si el request anterior llegó. Si crear pedido no es idempotente, un timeout puede convertirse en venta duplicada, con su doble reserva y su doble deuda.

Definición operativa. El comando debe llevar una clave de intención (requestId); el sistema la asocia a una semántica y devuelve el mismo resultado ante el mismo payload. Reutilizar la clave con un payload distinto debe producir conflicto, no una segunda operación silenciosa. Eso es la RN-06 escrita como contrato:

Ejemplo en Nexo, y lo que sale mal con la versión ingenua. Guardar la clave sin pensar el segundo caso deja ambigüedad. Esta es la comparación entre el diseño que la mayoría escribe primero y el que se defiende:

La huella (request_hash) resume el contenido que identifica la intención. Qué entra en ella es una decisión de contrato: cliente, depósito y líneas normalizadas por SKU y cantidad entran; la metadata de tracing (cabeceras, timestamps del cliente) no. Esa definición es la del ADR-006, que vas a ver completo en 7.2. Una advertencia: un hash de "todo el JSON" es una trampa, porque el orden de las propiedades o un campo de tracing convertirían un reintento legítimo en un falso conflicto.

Cómo se verifica. Dos tests de integración (T07, mismo requestId y payload; T08, mismo requestId y payload distinto) y uno concurrente: dos requests con el mismo requestId a la vez producen un solo pedido.

7.5 Fallos externos: qué ocurre después del commit

El problema. Una transacción local no vuelve atómica una llamada a un sistema externo. Si el pedido se confirma en PostgreSQL y luego falla la notificación a logística, revertir la base puede ser imposible o incorrecto. Si en cambio la notificación se envía antes del commit y el commit falla, avisaste de un pedido que no existe. Es el problema de la doble escritura: dos sistemas, ninguna transacción que los abarque.

Definición operativa. El diseño debe separar la consistencia del negocio local de la entrega de efectos externos. El patrón estándar se llama outbox transaccional: en la misma transacción que cambia el estado de negocio se inserta una fila en una tabla de eventos pendientes; un proceso aparte (el worker) lee esas filas y las entrega al sistema externo, marcándolas como entregadas. La entrega es at-least-once: puede repetirse, así que el receptor (o la clave que le mandamos) debe tolerar duplicados.

Ejemplo en Nexo. El primer release tiene que entregar el pedido confirmado a preparación, y deja la intención fiscal registrada: la emisión real del comprobante es una integración posterior, pero el contrato de fallo (NFR-04) se diseña y se prueba ahora contra un fake. En ambos casos, la aplicación confirma el pedido y registra el evento en la misma transacción local. Un worker lo reclama, llama al destino con una clave idempotente (el id del evento) y registra el resultado. Si la red falla, reintenta sin volver a confirmar el pedido. Si el destino dice "ya recibido", reconcilia en lugar de duplicar.

Contraejemplo. Un try/catch alrededor del fetch posterior al commit que "reintenta tres veces" en memoria. Si el proceso se reinicia entre el commit y el fetch, el evento se pierde sin dejar rastro. La durabilidad tiene que estar en la base, no en la memoria del request.

Cómo se verifica. Se inyecta una falla en el destino (timeout antes de procesar, timeout después de procesar, error permanente) y se comprueba que: el pedido sigue válido, el evento queda pendiente y visible, el reintento no duplica el efecto y, tras un error permanente, el evento queda en un estado que alguien ve (no se reintenta infinitamente en silencio).

7.6 Seguridad como autoridad contextual, no como login

Autenticación responde quién sos. Autorización responde qué podés hacer en este contexto. Que exista login y un middleware que verifique JWT no resuelve la política de negocio. En Nexo, un vendedor autenticado no debería poder registrar pedidos para cualquier cliente ni autorizar su propio sobregiro. La decisión depende de cartera asignada, rol, monto, estado del pedido y, si corresponde, sucursal. Esas reglas deben evaluarse del lado servidor y poder probarse. Ocultar un botón no es una política de autorización.

1if (!user.isAdmin && req.method !== "GET") {
2  return res.status(403).end();
3}
4// ...cualquier usuario no admin que pase acá
5// puede crear pedidos para cualquier clientId

1export function canCreateOrder(actor: Actor, client: ClientRef): Decision {
2  if (!actor.roles.includes("seller")) return deny("role");
3  if (!actor.portfolio.includes(client.id) && !actor.permissions.has("orders:any-client"))
4    return deny("client_not_in_portfolio"); // T10: forbidden sin filtrar datos
5  return allow();
6}

La seguridad también incluye qué queda auditado y qué deliberadamente no se registra. Una autorización crítica debería conservar actor, momento, pedido, regla aplicada y motivo (NFR-02). Pero auditar no significa volcar cualquier payload: tokens, secretos, contraseñas, documentos sensibles e información innecesaria no deberían terminar en logs por comodidad. Observabilidad y privacidad se diseñan juntas. El cliente nunca es autoridad de precio, crédito, estado ni permisos: el frontend puede enviar clientId, items y un requestId; no impone unitPrice, creditApproved ni reserved=true.

7.7 Arquitectura mínima propuesta para Nexo

Con los riesgos ya explicitados, el dibujo sirve para responder una pregunta concreta: qué piezas necesitamos separar hoy y cuáles conviene mantener juntas para preservar consistencia, operación simple y trazabilidad.

La figura muestra la forma general. Este diagrama de componentes agrega lo que la figura no dice: qué módulo habla con qué puerto y quién toca la base.

La elección concreta podría ser Next.js para el portal, una API TypeScript modular, PostgreSQL y un worker para integraciones. Lo importante no es el stack. Es la cadena de justificación: volumen moderado + reglas fuertemente transaccionales + equipo pequeño → mantener un único límite de consistencia local; integraciones lentas o fallables → sacar efectos externos del request crítico; necesidad de trazabilidad → outbox, audit log y estados observables.

Un monolito modular no es "todo mezclado en una carpeta". Los módulos exponen puertos (interfaces) y la regla es verificable en CI: orders puede depender del puerto StockPort, pero no importar tablas de stock ni sus funciones internas. Eso es lo que hace barata una separación futura si algún ADR lo exige.

7.8 Estado: cuando un enum deja de ser suficiente

El problema. Un campo status con strings libres permite cualquier transición: un pedido DESPACHADO puede volver a CONFIRMADO por un UPDATE descuidado, y nadie lo nota hasta que depósito imprime dos veces.

Definición operativa. Pedido merece una máquina de estados porque las operaciones válidas dependen de su ciclo de vida. Cada transición corresponde a un evento de negocio o de aplicación. Los guards expresan condiciones de la transición y las acciones muestran efectos asociados. La expiración automática de reservas no aparece todavía porque la política TTL (RN-07) continúa BLOCKED; dibujarla como transición sería convertir un unknown en comportamiento.

La misma máquina, redibujada para ver el camino de autorización de crédito (CU-02) junto al camino feliz. Nota que no hay flecha de expiración:

Dos aclaraciones. En el camino feliz, BORRADOR → RESERVADO → CONFIRMADO ocurre dentro de una sola transacción: el vendedor nunca observa RESERVADO. Y la reserva blanda de un pedido pendiente de autorización es una decisión de política: la RN-07 dice que expira "pasado un tiempo todavía no definido", y mientras ese tiempo no exista, no hay transición automática que dibujar.

En código, la máquina es una tabla de transiciones permitidas, no un if disperso:

1export type OrderStatus =
2  | "BORRADOR" | "RESERVADO" | "PENDIENTE_AUTORIZACION" | "CONFIRMADO"
3  | "EN_PREPARACION" | "LISTO_PARA_FACTURAR" | "FACTURADO" | "DESPACHADO" | "CANCELADO";
4​
5const allowed: Record<OrderStatus, readonly OrderStatus[]> = {
6  BORRADOR: ["RESERVADO", "PENDIENTE_AUTORIZACION", "CANCELADO"],
7  PENDIENTE_AUTORIZACION: ["RESERVADO", "CANCELADO"],
8  RESERVADO: ["CONFIRMADO", "CANCELADO"],
9  CONFIRMADO: ["EN_PREPARACION", "CANCELADO"],
10  EN_PREPARACION: ["LISTO_PARA_FACTURAR"],
11  LISTO_PARA_FACTURAR: ["FACTURADO"],
12  FACTURADO: ["DESPACHADO"],
13  DESPACHADO: [],
14  CANCELADO: [],
15};
16​
17export function assertTransition(from: OrderStatus, to: OrderStatus): void {
18  if (!allowed[from].includes(to)) {
19    throw new IllegalTransition(from, to); // T11: rechazo, datos intactos
20  }
21}

Y la base lo respalda con una actualización condicional: UPDATE orders SET status = $2 WHERE id = $1 AND status = $3 (el estado de origen forma parte del WHERE). Si 0 filas cambian, otro proceso movió el pedido antes y el caso de uso lo informa en vez de pisarlo: es la misma idea de la reserva, aplicada al estado.

7.9 ADR: conservar por qué elegimos algo

El problema. Seis meses después, nadie recuerda por qué el stock se reserva con un UPDATE condicional ni por qué no hay colas. Un desarrollador nuevo (o un agente) "mejora" la decisión sin saber qué alternativa ya se descartó y por qué.

Definición operativa. Un ADR (Architecture Decision Record, formato popularizado por Michael Nygard) es un documento corto, versionado junto al código, que registra una decisión: su contexto (qué fuerzas la empujan), la decisión en una oración activa, las alternativas consideradas y por qué se descartaron, las consecuencias (positivas y negativas) y un disparador de revisión (la evidencia que haría cambiarla). Un ADR no se edita para reescribir la historia: si la decisión cambia, se acepta un ADR nuevo que reemplaza al anterior.

En Nexo el primer release queda gobernado por seis ADR. Esta lección presenta ADR-001, ADR-002 y ADR-003, los que definen la forma del sistema y la protección del stock. ADR-004, ADR-005 y ADR-006 nacen de los incidentes de 7.2 y los vas a ver completos ahí.

1# ADR-001 · Monolito modular con worker como estilo de despliegue
2​
3Estado: aceptada
4Decide: Responsable del Desarrollo. Revisan: Sergio (depósito) y Laura (crédito) por impacto operativo.
5Relacionada: ADR-003 (worker), ADR-002 (PostgreSQL como fuente de stock).
6​
7## Contexto
8- Equipo de desarrollo pequeño y operación a cargo del mismo equipo (RES-01).
9- Volumen moderado: unos treinta usuarios internos con picos de unos treinta
10  concurrentes y cientos de clientes B2B. Son cifras de ficción del caso, no un
11  requisito medido. Ningún ASR pide escala independiente por componente.
12- Las operaciones críticas cruzan pedidos, stock y crédito y exigen una garantía
13  transaccional única: nada de pedido parcial, reserva huérfana ni decisión
14  de crédito ausente (ASR-01, ASR-04, ASR-05).
15- El ERP legacy sigue siendo maestro de productos, clientes y listas base en la
16  etapa 1. Nexo es autoridad de pedidos, reservas, estados y auditoría.
17​
18## Decisión
19Construimos una aplicación modular en un único deploy lógico para request y base
20de datos, más un proceso worker desplegado desde el mismo repositorio. Los módulos
21(catalog, pricing, credit, orders, stock, authorization, audit) se comunican por
22puertos en proceso. Un módulo no importa tablas ni funciones internas de otro, y
23esa regla se verifica con una regla de lint de imports en CI. Qué trabajo sale del
24request hacia el worker lo decide ADR-003.
25​
26## Alternativas consideradas
271. Microservicios por dominio (pedidos, stock, crédito, notificaciones).
28   Rechazada: la garantía de CU-01 pasaría de una transacción local a una saga
29   con compensaciones, y sumaría contratos de red, autenticación entre servicios,
30   despliegues, tracing y fallos parciales. Ningún ASR exige escala independiente.
312. Monolito sin módulos (capas por tipo técnico, todo importa todo).
32   Rechazada: no protege los límites que hacen barata una futura separación y
33   vuelve riesgoso el cambio, también el que hace un agente de IA.
343. Funciones serverless por endpoint.
35   Rechazada para el primer release: transacciones largas con pool de
36   conexiones efímeras, mayor dificultad de tracing y cold starts sin beneficio
37   para una carga interna estable.
38​
39## Consecuencias
40Positivas
41- Una transacción local cubre pedido, líneas, reserva, crédito, idempotencia y outbox.
42- Menor costo operativo: un artefacto de aplicación, una base, un worker.
43- Trazabilidad simple: un request, un correlation id, un log.
44Negativas
45- Escala menos granular: si stock se carga mucho, se escala toda la aplicación.
46- Requiere disciplina para mantener los límites de módulos (por eso la regla de lint).
47- Despliegue acoplado: un defecto en un módulo puede afectar a todos y las
48  migraciones de base se coordinan en un solo lugar.
49​
50## Disparador de revisión
51Un módulo requiere escalado o aislamiento operativo materialmente distinto, o
52aparece un SLA incompatible con compartir proceso. Hasta que haya medición que
53lo muestre, esta decisión no se reabre por preferencia.
54​
55## Verificación
56- Regla de lint de dependencias entre módulos en CI.
57- Prueba de integración de CU-01 contra una sola base (T01, T09).

1# ADR-002 · PostgreSQL como fuente transaccional de stock y reserva
2​
3Estado: aceptada
4Decide: Responsable del Desarrollo. Revisa: Sergio (depósito), por impacto en la operación de stock.
5Relacionada: ADR-001 (monolito con worker), ADR-005 (idempotencia en la misma transacción).
6​
7## Contexto
8- RN-05: una reserva nunca puede dejar el disponible en negativo, por depósito y SKU.
9- Dos vendedores pueden pedir la última unidad de un SKU al mismo tiempo (EV-05, ASR-01).
10  Cada request, leído por separado, es correcto. El defecto está en el entrelazado.
11- Pedidos, líneas, reservas, idempotencia y auditoría ya viven en PostgreSQL (ADR-001).
12  La decisión de disponibilidad tiene que tomarse en la misma fuente que la actualiza.
13- Son dos depósitos (CBA y CEN) y decenas de usuarios internos. La contención esperable
14  sobre una fila de stock es baja.
15​
16## Decisión
17La disponibilidad se protege en PostgreSQL con una sentencia de actualización condicional
18dentro de la transacción de CU-01: `UPDATE stock_level SET reserved = reserved + $3 WHERE
19product_id = $1 AND warehouse_id = $2 AND on_hand - reserved >= $3`. Una restricción CHECK
20declara la misma invariante en la tabla. Las líneas de un pedido se reservan en orden
21determinista por SKU.
22​
23## Alternativas consideradas
241. `SELECT ... FOR UPDATE` seguido de `UPDATE`. Rechazada: llega al mismo resultado con dos
25   viajes a la base y la fila retenida entre ambos; es fácil de usar mal si alguien olvida el
26   `FOR UPDATE`.
272. Contador de reservas en Redis o cola de reservas. Rechazada: crea una segunda fuente de
28   verdad que hay que sincronizar con la base, su caída afecta el stock y ningún ASR lo pide.
293. Concurrencia optimista con columna `version`. Rechazada para la reserva: con contención alta
30   sobre la última unidad de un SKU popular produce tormentas de reintentos. Sirve en otras
31   operaciones.
324. Nivel SERIALIZABLE en toda la aplicación. Rechazada: obliga a manejar errores de
33   serialización en cada flujo para proteger una invariante de una sola fila.
34​
35## Consecuencias
36Positivas
37- La invariante vive donde están los datos y protege a cualquier escritor, incluido un script
38  de ajuste que no pase por la aplicación.
39- La prueba concurrente de T06 puede reproducir la carrera real con dos transacciones.
40- No se agrega ninguna pieza operativa nueva.
41​
42Negativas
43- El stock queda acoplado a la carga de la base principal.
44- Un pedido de varias líneas toma varios locks: sin orden determinista aparecen deadlocks.
45  La convención de orden por SKU es obligatoria y tiene que tener una prueba.
46- Un SKU caliente serializa sus reservas. A este volumen es aceptable, pero hay que medirlo.
47​
48## Disparador de revisión
49La medición de contención sobre `stock_level` empuja el p95 del registro de pedido por encima
50del presupuesto, o aparece un canal de escritura de stock que no puede usar la misma sentencia.
51​
52## Verificación
53- T06: dos transacciones concurrentes sobre una unidad; exactamente una reserva.
54- T09: falla inyectada antes del commit; la reserva desaparece junto con el pedido.
55- El CHECK rechaza un `UPDATE` manual que deje `reserved > on_hand`.

1# ADR-003 · Procesamiento asíncrono de efectos posteriores al commit en un worker
2​
3Estado: aceptada
4Decide: Responsable del Desarrollo.
5Relacionada: ADR-001 (estilo de despliegue, incluye el worker), ADR-004 (outbox).
6​
7## Contexto
8- Hay tres integraciones externas con latencia y disponibilidad distintas:
9  ERP legacy, sistema de preparación y proveedor fiscal.
10- El pedido ya confirmado no debe revertirse porque un tercero esté caído
11  (NFR-04, ASR-03).
12- Una llamada externa dentro del request retiene conexión y locks, y bloquea
13  al vendedor.
14​
15## Decisión
16Los efectos que ocurren después del commit (handoff a preparación, intención fiscal y,
17en la etapa 1, sincronizaciones con el ERP) no se ejecutan dentro del request. Un worker
18lee la tabla outbox (ADR-004), entrega a cada destino con clave idempotente y registra
19el resultado. Es un proceso aparte del web; su despliegue sigue lo que fija ADR-001. No
20expone HTTP de negocio (solo health) y puede reiniciarse o pausarse sin tocar la API.
21​
22## Alternativas consideradas
231. Ejecutar el trabajo asíncrono dentro del proceso web (timers en memoria).
24   Rechazada: un reinicio o deploy de la API interrumpe entregas, y el trabajo
25   compite por CPU y conexiones con los requests de los vendedores.
262. Cola o broker externo (RabbitMQ, SQS, Kafka).
27   Rechazada para el primer release: segunda fuente de verdad que hay que
28   mantener consistente con la base (vuelve el problema de doble escritura) y un
29   componente más para operar. No hay volumen que lo justifique.
303. Librería de jobs sobre PostgreSQL.
31   Viable. No se adopta ahora porque son pocos tipos de evento y el patrón de
32   reclamo con SKIP LOCKED cubre el caso con menos dependencias. Se revisa si
33   crece la variedad de trabajos.
34​
35## Consecuencias
36Positivas
37- Aísla fallos de terceros del camino crítico del vendedor.
38- Despliegue y reinicio independientes; el worker puede pausarse sin afectar ventas.
39Negativas
40- Un proceso más para desplegar, monitorear y alertar.
41- Entrega at-least-once: todo consumidor debe tolerar duplicados.
42- Latencia de entrega acotada por el intervalo de polling.
43​
44## Disparador de revisión
45Aparecen más tipos de trabajo, necesidad de programación diferida compleja, o el
46polling sobre la base se vuelve una carga medible. Entonces se reevalúa la
47alternativa 3 o un broker.

1Actuá como revisor de arquitectura. No propongas tecnología todavía.
2Contexto: asr-register.yaml (adjunto), RN-05, RN-06, NFR-04.
3Restricciones: equipo pequeño, unos 30 usuarios internos, ERP legacy como maestro.
4Tarea: para ASR-01 proponé tres mecanismos distintos. Para cada uno:
51) qué invariante protege y qué carrera NO cubre,
62) costo operativo (piezas nuevas, fallos nuevos),
73) qué evidencia haría que lo prefieras al más simple.
8Formato: una sección por mecanismo. Si algo depende de un dato que no tenés,
9escribilo como pregunta; no lo inventes.

7.10 Revisión de arquitectura: las preguntas antes de admirar el diagrama

Cuando termines de diseñar, recorré esta lista contra tu diagrama. Es la misma que se usa en el Sprint de Arquitectura:

• ¿Qué requisito o riesgo justifica cada componente que puede desplegarse o fallar de forma independiente?
• ¿Dónde vive la autoridad de cada dato crítico: precio, saldo, stock, estado, identidad?
• ¿Cuál es la unidad transaccional mínima y qué efectos quedan deliberadamente fuera?
• ¿Qué invariantes pueden romperse por concurrencia y qué mecanismo concreto las preserva?
• ¿Qué operación puede repetirse y cómo reconoce el sistema la misma intención?
• ¿Qué pasa después del commit si falla un proveedor externo?
• ¿Qué observación necesitarías para reconstruir un incidente sin entrar a producción a adivinar?
• ¿Qué parte de esta arquitectura podrías eliminar hoy sin dejar de cumplir un ASR? Si la respuesta es mucha, probablemente hay sobrearquitectura.

Vocabulario del módulo

Errores frecuentes

• Elegir la tecnología antes de escribir la invariante. Síntoma: el ADR dice "usamos Redis para concurrencia" y nadie puede decir qué propiedad protege. Causa: se partió del patrón, no del daño. Corrección: escribir primero la invariante y la carrera A/B; la tecnología entra recién como mecanismo.
• Transacción alrededor de todo el método. Síntoma: locks de stock_level retenidos 30 segundos y vendedores esperando. Causa: llamada HTTP al proveedor dentro de BEGIN ... COMMIT. Corrección: sacar el efecto externo a outbox y dejar en la transacción solo lo que hace verdadera la garantía mínima.
• Idempotencia que guarda la clave y nada más. Síntoma: un reintento con otras líneas devuelve el pedido anterior sin avisar. Causa: no se definió el caso de payload distinto. Corrección: huella del contenido y respuesta de conflicto, más reclamo atómico de la clave.
• Decidir fuera de la sentencia que escribe. Síntoma: el test pasa con requests secuenciales y falla en producción en horas pico. Causa: lectura, if y escritura separados. Corrección: condición dentro del UPDATE y test con dos transacciones concurrentes.
• ADR que vende la decisión. Síntoma: solo consecuencias positivas y ninguna alternativa seria. Causa: el ADR se escribió para convencer, no para recordar. Corrección: exigir al menos una consecuencia negativa real y un disparador de revisión.
• Autorización como bandera isAdmin. Síntoma: un vendedor carga pedidos para clientes de otra cartera. Causa: se modeló el rol, no el recurso ni el contexto. Corrección: política con actor, recurso y motivo de denegación, probada por separado.

Para llevarte

• Un ASR se reconoce por esta pregunta: si cambia, ¿hay que mover una frontera? Registralo con origen, escenario, decisión y prueba.
• La frontera transaccional sale de la garantía mínima del caso de uso: adentro lo que hace verdadera la garantía, afuera lo que depende de terceros.
• Primero la invariante en lenguaje verificable, después el mecanismo. Para Nexo: UPDATE ... WHERE on_hand - reserved >= qty más un CHECK, y una prueba que ejecute la carrera real.
• Idempotencia es clave más huella más reclamo atómico, con tres respuestas definidas: mismo resultado, conflicto, espera.
• Lo que ocurre después del commit se diseña con outbox y worker; el consumidor tolera duplicados porque la entrega es at-least-once.
• Un ADR sin alternativas, sin consecuencias negativas y sin disparador de revisión es publicidad, no memoria técnica.