Al terminar esta lección
- Escribir tres invariantes concurrentes de Nexo y armar el entrelazado A/B que podría romper una de ellas.
- Definir la frontera transaccional de CU-01 y justificar, con la garantía mínima, qué efectos quedan después del commit.
- Especificar timeout, reintento, idempotencia, degradación y señal observable para dos integraciones.
- Redactar un ADR de una decisión no obvia, con su comparación contra los ASR, sus riesgos y su criterio de revisión.
- Revisar el gate contra evidencia y dejar visibles los criterios que todavía no podés demostrar.
Práctica E07 · Defender una arquitectura mínima
Situación. Otro desarrollador propone microservicios para catálogo, pedidos, crédito y stock porque "va a escalar mejor".
Entregá. comparación contra ASR; ADR de decisión; riesgos del monolito y de microservicios; criterio de revisión futura.
Está listo cuando. la decisión no depende de gusto; se reconoce costo operativo; concurrencia/transacción están tratadas; se explican condiciones que harían cambiar la elección.
Solución comentada: Solución comentada E07. Comparala después de producir tu entrega.
Defendé una arquitectura mínima para Nexo partiendo de cinco ASR. No menciones tecnología hasta haber escrito el riesgo que cada decisión debe reducir.
Este taller tiene seis pasos. Cada uno pide un artefacto, tiene un ejemplo parcial trabajado y una solución parcial que podés revelar después de intentarlo. Escribí tu respuesta antes de abrir la solución: el ejercicio no pide que tu texto coincida con el de ejemplo, pide que cada afirmación tenga motivo. El tiempo sugerido suma unos 110 minutos. Si te quedás sin tiempo, priorizá los pasos 1, 2 y 5: son los que el gate revisa primero.
Paso 1 · Invariantes concurrentes
Objetivo: escribir tres invariantes de Nexo, en una oración cada una, que se puedan verificar leyendo la base sin mirar el código. Tiempo sugerido: 15 minutos.
Ejemplo parcial. Estas son tres invariantes de referencia, con la regla de origen:
- Stock (RN-05): para cada depósito y SKU, la cantidad reservada nunca supera el stock físico registrado.
- Crédito (RN-01): para un cliente estándar, el saldo deudor más los pedidos confirmados nunca supera el límite de crédito.
- Estado (ASR-05 y la máquina de 7.1): un pedido cancelado no conserva reservas activas, y un pedido confirmado tiene todas sus reservas firmes.
La carrera de la tercera muestra por qué las invariantes de estado importan tanto como las de stock. Un vendedor confirma mientras Marta cancela el mismo pedido desde otra pantalla:
A (confirmar) lee el pedido: estado RESERVADO
B (cancelar) cambia el pedido a CANCELADO y libera las reservas
A (confirmar) escribe CONFIRMADO sobre las reservas ya liberadas
resultado: pedido confirmado sin stock
La defensa es la misma idea de 7.1 aplicada al estado: el cambio se escribe con UPDATE orders SET status = 'CONFIRMADO' WHERE id = $1 AND status = 'RESERVADO', y si cero filas cambian, el caso de uso informa el conflicto en lugar de pisar el cambio de Marta.
Escribí tres invariantes de Nexo
Escribí una invariante de stock, una de crédito y una de estado, distintas de las tres del ejemplo. Cada una en una oración sin nombrar tecnología. Para una de ellas, armá el entrelazado A/B que la rompe, paso a paso.
Paso 2 · Frontera transaccional de CU-01
Objetivo: separar, para CU-01, qué mutaciones van dentro de la transacción local y cuáles quedan afuera, y justificar cada decisión con la garantía mínima del caso de uso. Tiempo sugerido: 15 minutos.
Ejemplo parcial. La garantía mínima dice que ante cualquier fallo antes del commit no queda pedido parcial, débito ficticio ni reserva huérfana. Desde esa frase sale la lista:
- Dentro: reclamo del
requestId, precio resuelto en el servidor, decisión de crédito con su auditoría si hay excepción, reservas por SKU con la sentencia condicional, pedido y líneas con snapshot de precio, y las filas del outbox. - Fuera: la llamada al proveedor fiscal, el envío a preparación, el aviso al vendedor y la actualización de métricas.
Para cada elemento de la lista de afuera hay una pregunta de verificación: si esto falla, ¿la garantía mínima deja de ser cierta? Si la respuesta es no, va afuera. Para el aviso al vendedor la respuesta es no, porque la pantalla ya muestra el estado del pedido. Para la intención fiscal la respuesta también es no, porque el pedido es válido aunque el proveedor esté caído, pero sí necesita durabilidad, así que va al outbox y no a una llamada directa.
Armá la frontera de CU-01
Hacé una tabla con dos columnas, dentro y fuera de la transacción. En cada elemento, escribí la garantía que lo justifica. Incluí al menos un efecto que tu primer intento había puesto dentro y que sacaste, y explicá por qué.
Paso 3 · Idempotencia en sus cuatro casos
Objetivo: definir la respuesta exacta del sistema para cuatro situaciones con el mismo requestId, incluida la que nadie suele pensar. Tiempo sugerido: 10 minutos.
Ejemplo parcial. Los cuatro casos que el ADR-005 necesita cubrir son:
requestIdnuevo: se procesa, se reclama la clave, se confirma el pedido. Respuesta con número de pedido yreplayed: false.- Mismo
requestId, misma huella, pedido ya confirmado: respuesta con el mismo número yreplayed: true, sin efectos nuevos. - Mismo
requestId, huella distinta: conflicto con el motivorequest_id_reused, sin efectos nuevos. - Mismo
requestIdmientras el primer request todavía está en curso: el segundo espera a que la transacción termine y responde según el resultado.
El caso que nadie piensa es el rechazo por stock insuficiente. Si el primer intento se rechaza, la transacción se revierte completa, incluida la clave. Un reintento se vuelve a evaluar con el stock actual. Eso es una decisión, y tiene que estar en el ADR porque el vendedor puede esperar lo contrario.
Definí las cuatro respuestas
Para los cuatro casos del ejemplo y para el rechazo por stock insuficiente, escribí la respuesta del sistema (tipo de resultado, efectos nuevos) y la razón. Después decidí, con una frase, si el rechazo debe congelar la clave o no, y qué le pasaría al vendedor en cada caso.
Paso 4 · Dos integraciones con su contrato
Objetivo: especificar, para dos integraciones, timeout, reintento, idempotencia, degradación y señal observable. Tiempo sugerido: 20 minutos.
Ejemplo parcial. La integración fiscal queda así:
- Timeout: un valor propuesto de 5 segundos, que el contrato del proveedor debe confirmar o cambiar. No se pone un número sin contrato.
- Reintento: backoff exponencial con tope de una hora y un máximo de intentos. El máximo es propuesta: lo define Operaciones con datos de la primera semana.
- Idempotencia:
Idempotency-Keyigual aliddel evento del outbox, con el proveedor deduplicando. - Degradación: el pedido queda confirmado con
billing_status = PENDIENTE_FACTURACION. Ningún vendedor queda bloqueado. - Señal observable: antigüedad del evento
PENDIENTEmás viejo y cantidad deFALLIDO, en el panel de operaciones.
El diagrama de despliegue muestra dónde viaja cada una de estas llamadas. Lo que importa no son las cajas, sino las flechas: cuál de ellas puede bloquear al vendedor y cuál no.
Leé el diagrama con esta pregunta: ¿qué flecha puede tirar al vendedor abajo? Solo la del ERP, porque sin precio no hay pedido. Las otras dos son asíncronas y su falla se ve como estado.
Especificá una integración de Nexo
Elegí el sistema de preparación o el ERP maestro y completá las cinco columnas: timeout, reintento, idempotencia, degradación y señal observable. Si un valor no tiene dato que lo respalde, escribilo como pregunta para el dueño del dato, no como un número.
Paso 5 · El ADR de la decisión E07
Objetivo: escribir un ADR que defienda la arquitectura frente al argumento "va a escalar mejor", con comparación contra los ASR, riesgos de cada opción y un criterio de revisión. Tiempo sugerido: 25 minutos.
Ejemplo parcial. La propuesta de microservicios para catálogo, pedidos, crédito y stock tiene un costo que no aparece en el diagrama:
- CU-01 deja de ser una transacción local. Pedido, reserva y crédito pasarían a una saga con compensaciones, y una reserva compensada es más difícil de explicar que un rollback.
- Aparecen contratos de red entre servicios, autenticación entre ellos, tracing y despliegues independientes. Para un equipo pequeño (RES-01), cada despliegue es un costo de operación.
- Ningún ASR pide escala independiente por componente. El volumen es de decenas de usuarios internos (NFR-01, 30 concurrentes), no de millones.
Los riesgos del monolito modular también existen: escala menos granular, disciplina para mantener los límites y deploy acoplado. El ADR los escribe, porque sin consecuencias negativas el ADR vende la decisión en lugar de registrarla. El disparador de revisión es concreto: un módulo con necesidad de escala o aislamiento operativo medido, o un SLA que no se puede cumplir compartiendo proceso.
Escribí el ADR de E07
Escribí un ADR completo para la decisión de la práctica E07: contexto con los ASR, decisión, alternativas consideradas (incluida la propuesta de microservicios), consecuencias positivas y negativas, y disparador de revisión. Usá el formato de ADR-001 de 7.1 como referencia, con tus propias pruebas.
Paso 6 · Cuaderno de campo: cinco fallos narrados
Objetivo: narrar cinco fallos paso a paso, clasificar sus efectos y decir qué garantía sobrevive. Tiempo sugerido: 25 minutos.
Los cinco fallos del expediente 07 son: dos vendedores compiten por la última unidad, el servicio de crédito no responde, el sistema de preparación está caído, el cliente reintenta tras un corte y el operador no tiene permiso para la acción que intenta. Para cada uno, escribí qué ya ocurrió antes del error, qué no debe ocurrir, qué puede reintentarse y quién observa el estado.
El clasificador siguiente toma los fallos más típicos y pide la garantía que aplica a cada uno. La pregunta no es si el fallo es grave, sino si el pedido queda válido, rechazado o con un efecto pendiente.
¿Qué garantía sobrevive a cada fallo?
Clasificá cada situación según el resultado para el pedido y para el negocio. Pensá si el fallo ocurre antes o después del commit.
Dos vendedores confirman por la última unidad de COR-118 al mismo tiempo, y uno pierde la carrera.
El servicio de crédito no responde mientras se evalúa un pedido, antes del commit.
El sistema de preparación no responde después de que el pedido se confirmó.
El proveedor fiscal no responde a una intención de facturar, horas después del commit.
El tablero de volumen de pedidos no se actualiza durante una hora.
Este clasificador tiene una trampa que el taller quiere mostrar. Los casos 3 y 4 parecen parecidos, pero el 4 es más peligroso si lo tratás como best-effort. Una intención fiscal perdida es un comprobante que nunca se emite, así que su durabilidad es igual de importante que la de la reserva.
Presentación a Marta sin nombres de tecnología
Marta (dueña) escucha la propuesta de arquitectura en una reunión de cuarenta minutos. Vos tenés que explicar riesgos y fronteras. Marta no es técnica y tampoco quiere una clase.
Marta (dueña)
Me dijeron que se va a escalar mejor si lo separamos en servicios. ¿Por qué no lo hacemos así desde el principio?
¿Qué respondés?
Criterio de revisión. La arquitectura está lista cuando podés quitar un componente y explicar qué requisito o riesgo deja de estar cubierto, y cuando podés mantener un componente explicando qué costo introduce.
Hoja de entrega 7 · completá antes de pasar el gate
Este bloque no se completa "de memoria". Volvé a tus artefactos, evidencia y resultados. El objetivo es obligarte a hacer explícito qué vas a defender frente a un mentor o cliente.
- Artefacto que entrego y versión:
- Tres evidencias que sostienen mis decisiones:
- Decisiones que tomé yo y que un agente no podía tomar:
- Desconocidos o riesgos que siguen abiertos:
- Feedback o propuesta de IA que rechacé, y por qué:
- Qué tendría que ocurrir para que yo mismo cambie esta conclusión:
- Revisión de calidad: qué corregí antes de enviar o presentar:
- Firma del mentor/reviewer o referencia del feedback:
Qué puede hacer el agente: proponer tres arquitecturas alternativas, enumerar riesgos de cada una, revisar tus invariantes buscando ambigüedad y redactar un borrador de ADR a partir de tus notas.
Qué no debe decidir: qué arquitectura elegís, qué consecuencia negativa aceptás, si una integración puede bloquear al vendedor, ni qué valor de timeout o de reintento se usa sin contrato. Esas decisiones son tuyas y tienen que quedar en la Hoja de entrega.
Contexto mínimo útil: los ASR y RES de tu registro, RN-01 a RN-07 con su estado, CU-01 con su garantía mínima, la lista de integraciones con sus contratos y el ADR que estés revisando.
Cómo verificar: cada componente de la propuesta del agente tiene que apuntar a un ASR o a una restricción. Lo que no apunta a nada es un componente de "best practice", y lo rechazás.
Prompt de trabajo:
Actuá como revisor de arquitectura. No propongas tecnología todavía.
Contexto: asr-register.yaml, RN-05, RN-07 (BLOCKED), NFR-04, CU-01 con su garantía mínima.
Restricciones: equipo pequeño, decenas de usuarios internos, ERP legacy como maestro de precios.
Tarea: para el caso de la última unidad y el fallo del proveedor fiscal, proponé tres arquitecturas distintas.
Para cada una: 1) qué ASR cubre y cuál deja sin cubrir, 2) componentes nuevos y su costo operativo,
3) un fallo que introduce y no existía antes, 4) qué evidencia la haría preferible a la más simple.
Si algo depende de un dato que no tenés, escribilo como pregunta y no lo inventes.
Cómo revisar la salida: tachá toda propuesta sin eslabón ASR, riesgo y prueba. Buscá cifras que no están en el contexto: un volumen o un plazo que aparece de la nada es un dato inventado. Pedile que marque qué parte es hecho del caso y qué parte es suposición.
Gate 7 · la arquitectura tiene razón de existir
Un gate no es una formalidad. Si una condición crítica no se cumple, el trabajo correcto es hacer visible la incertidumbre y volver a buscar evidencia.
Criterios de revisión
Revisá tus artefactos antes de marcar cada criterio. El checklist registra tu autoevaluación; la aprobación requiere revisar la evidencia.
Guardá tu entrega
Completá la entrega 07, adjuntá evidencia y registrá los criterios del gate que todavía no podés demostrar.
Cuando termines tu entrega, compará tu razonamiento con la solución comentada E07. No hay una única respuesta correcta: la comparación busca fuentes, decisiones y evidencia.
Errores frecuentes
- Entregar un ADR sin consecuencias negativas. Síntoma: el mentor pregunta qué cuesta la decisión y el ADR no responde. Causa: se escribió para convencer, no para registrar. Corrección: agregar al menos una consecuencia negativa real y un disparador observable.
- Armar el paso 2 sin la garantía mínima. Síntoma: la lista de "dentro" incluye todo el método y nadie puede decir qué pasa si falla una línea. Causa: se derivó la transacción del código y no de la garantía. Corrección: cada elemento de la columna "dentro" debe tener una garantía que se rompería sin él.
- Timeouts y reintentos sin contrato. Síntoma: "5 segundos, reintento tres veces" aparece en la entrega sin fuente. Causa: el valor se copió de un ejemplo. Corrección: marcarlo como propuesta y registrar la pregunta para el dueño del sistema externo.
- Presentar la arquitectura con nombres de tecnologías. Síntoma: Marta pregunta por el riesgo y la respuesta habla de contenedores. Causa: no se separó el riesgo del mecanismo. Corrección: describir primero el daño en lenguaje del negocio y después nombrar el mecanismo.
Para llevarte
- Cada invariante se escribe sin tecnología, se verifica leyendo datos y tiene un entrelazado que la rompe.
- La frontera transaccional de CU-01 sale de la garantía mínima: adentro lo que la hace verdadera, afuera lo que depende de un tercero y se encola.
- Las cuatro respuestas de idempotencia (nuevo, mismo contenido, conflicto y espera) son parte del contrato, y el rechazo por stock es una decisión explícita.
- Para cada integración, timeout, reintento, degradación y señal observable son parte del contrato. Los valores sin fuente son preguntas.
- Un ADR de decisión tiene alternativas con costo real, consecuencias negativas y un disparador que se puede medir.
- Un gate no se aprueba por inercia: los criterios que no podés demostrar quedan visibles en la hoja de entrega.
¿Cómo valoras el contenido técnico de esta lección?
Tu feedback nos ayuda a mejorar los laboratorios prácticos de Eje Z.