P1 · Módulos con límites

Cubre: semanas 3 a 5 · En equipo

Tinkuy tiene carpetas con nombres de módulos, pero no tiene sus límites: make deps todavía reporta violaciones, todas las tablas son de todos y el medio de pago se pregunta con un if en cuatro archivos. En esta entrega el equipo lo convierte en un modular monolith cuyos límites se comprueban en cada build, y agrega un medio de pago nuevo, Plin, de la forma en que desde ahora se va a agregar cualquier otro.

El punto de partida es su propio P0. Si el equipo tiene más de un P0, elijan uno y digan cuál en el primer ADR de esta entrega.

1. El requisito que llega

El área comercial quiere ofrecer Plin este mes, y ya avisó que después vienen más medios de pago. Hoy cada medio nuevo significa abrir el código de la compra.

Agregar un medio de pago

  • Atributo de calidad: modificabilidad
  • Fuente del estímulo: un desarrollador del equipo
  • Estímulo: hay que ofrecer un medio de pago nuevo que la pasarela ya acepta, con sus propios datos, su comisión y su forma de cobro
  • Artefacto: el código de Tinkuy (src/)
  • Entorno: en desarrollo, con make check pasando antes del cambio
  • Respuesta: el medio se agrega, se puede comprar con él y make check sigue pasando
  • Medida de la respuesta: 1 archivo nuevo, el del medio de pago, y a lo más 2 líneas agregadas en 1 archivo de registro; 0 líneas modificadas o borradas en el resto de src/

El segundo requisito no tiene un comprador detrás, pero es el que hace posible el primero y todos los que vienen: los límites entre módulos se comprueban solos. Un cambio en las tablas de un módulo no puede romper a otro sin que el build lo diga.

2. Lo que está fijo

Las reglas de dependencia

  • make deps pasa: cero violaciones.
  • Las tres reglas originales (no-circular, http-does-not-touch-db y modules-only-through-index) no se debilitan. Pueden agregar reglas a su .dependency-cruiser.cjs, y se espera que lo hagan; las pruebas públicas corren además las tres originales desde el archivo del curso, contra su src/.
  • make check incluye make deps.

Plin

POST /orders acepta un tercer medio de pago:

"payment": { "method": "plin", "phone": "987654321" }
  • phone es un celular de 9 dígitos que empieza con 9, como texto. Si falta o no cumple, la respuesta es 422 con INVALID_INPUT.
  • Plin no tiene comisión: feeCents es 0 y paymentMethod es "plin".
  • A la pasarela, el cobro le llega como { "amountCents": ..., "method": "plin", "reference": "...", "plin": { "phone": "987654321" } }. La pasarela de prueba ya lo acepta, y rechaza los celulares que terminan en 000: en ese caso Tinkuy responde 402 con PAYMENT_DECLINED, como con los otros medios.
  • El resto de la API no cambia.

Los datos

  • Cada tabla tiene un módulo que es su owner, y solo el código de ese módulo la nombra en su SQL. Los demás le piden los datos por su index.ts.
  • El mapa se declara en docs/data-ownership.md, en una tabla con las columnas Tabla y Módulo (archivo de partida: templates/data-ownership.md). Un módulo es una carpeta de src/. Están todas las tablas de la base de datos, también las que agreguen.
  • Las nueve tablas conservan su nombre, sus columnas actuales y el esquema public: las pruebas de esta entrega y de las siguientes leen el estado ahí. Pueden agregar tablas, columnas, índices y restricciones.

La convención para agregar un medio de pago

Para comprobar el escenario, las pruebas públicas agregan un medio de pago a una copia de su repositorio. Lo hacen de forma mecánica, así que la forma de agregar un medio tiene que seguir esta convención:

  • Cada medio de pago es un archivo en una carpeta de plug-ins que ustedes eligen. El de Plin se llama plin.ts.

  • Si su diseño tiene un registro (el lugar donde se listan los medios), es un archivo, y registrar un medio le agrega una o dos líneas que nombran al medio: su entrada en la lista y, si hace falta, su import. Cada entrada va en su propia línea.

  • docs/payment-methods.md (archivo de partida: templates/payment-methods.md) lo declara con dos líneas, y explica a una persona cómo se agrega un medio:

    - **Carpeta de plug-ins:** `src/.../`
    - **Archivo de registro:** `src/.../....ts`

    Si sus plug-ins se descubren solos y no hay registro, la segunda línea dice ninguno.

Con eso, la prueba crea el medio tunki así: copia plin.ts como tunki.ts cambiando plin por tunki (también Plin y PLIN), y en el archivo de registro repite, debajo de cada línea que nombra a Plin, la misma línea con el nombre cambiado. No toca nada más. La consecuencia para su diseño: fuera de esos dos archivos, nada en src/ puede necesitar saber que Plin existe.

3. Lo que deciden

Al menos dos ADR nuevos (docs/adr/0002-… en adelante), cada uno con al menos dos alternativas comparadas:

  1. Los límites entre módulos. Qué exporta cada módulo, cómo se rompe el ciclo y qué pasa con las consultas que hoy cruzan tablas de dos módulos.
  2. El contrato de los plug-ins. Qué operaciones tiene un medio de pago, qué le está permitido y qué no, y cómo se registra.

Otras decisiones que van a tener que tomar, y que pueden ir en esos ADR o en otros: qué hacen con las llaves foráneas entre tablas de módulos distintos, y cómo participan varios módulos en la transacción de la compra.

4. Lo que comprueban las pruebas públicas

check corre las pruebas de P0 y después p1.public.test.ts, que tiene cuatro grupos.

Documentos

  1. docs/c4/context.md, docs/c4/containers.md y docs/c4/components.md pasan juntos el revisor de la semana 1, y el tercero es de nivel componentes (con su línea Contenedor:).
  2. docs/scenarios.md pasa el revisor de la semana 2 y tiene un escenario con Atributo de calidad: modificabilidad.
  3. docs/adr/ tiene al menos tres ADR en total, todos con sus cinco secciones y al menos dos alternativas.
  4. docs/measurements/p1.md tiene las secciones Antes y Después y al menos un bloque de código.
  5. docs/data-ownership.md tiene la tabla | Tabla | Módulo |.
  6. docs/payment-methods.md tiene las dos líneas de la convención, la carpeta existe y contiene plin.ts.

Límites

  1. Las tres reglas del curso reportan 0 violaciones en su src/.
  2. make deps termina con código 0.
  3. make -n check muestra una llamada a depcruise.

Sistema

  1. Las diez pruebas de la API de P0.
  2. Una compra con Plin responde 201 con feeCents 0 y paymentMethod "plin", y la pasarela recibe exactamente un cobro, con method: "plin", plin: { phone } y el total de la orden.
  3. Plin con un celular que termina en 000 responde 402 y deja el asiento libre.
  4. Plin sin phone, con "12345" o con un número en vez de texto responde 422.
  5. Todas las tablas de la base de datos (esquema public) están en el mapa, con un módulo que es una carpeta de src/. Y en ningún archivo .ts de src/ aparece, después de FROM, JOIN, INTO, UPDATE o TABLE, el nombre de una tabla que el mapa le da a otro módulo. Un archivo que no está dentro de un módulo (src/db.ts, por ejemplo) no puede nombrar ninguna.

Modificabilidad (sobre la copia con tunki agregado)

  1. El archivo de registro nombra a Plin en una o dos líneas.
  2. make typecheck y make deps pasan en la copia.
  3. Una compra con { "method": "tunki", "phone": "987654321" } responde 201 con feeCents 0 y paymentMethod "tunki", y la pasarela recibe tunki: { phone }.
  4. tunki con un celular que termina en 000 responde 402, y las compras con tarjeta y con Plin siguen respondiendo 201.

La comprobación 14 es una expresión regular sobre el texto: no entiende SQL armado por partes ni tablas separadas por comas en un FROM. Que su SQL la pase por escribirlo raro no es cumplir el requisito, y se ve al leer el código.

5. Documentos

Archivo Contenido
docs/adr/0002-…, 0003-… Las decisiones de la sección 3
docs/c4/components.md El servidor por dentro: un componente por módulo (y los que hagan falta para los plug-ins), con las flechas que make deps permite. Los otros dos diagramas, al día
docs/scenarios.md Los de P0 más el de modificabilidad, con la medida que el equipo se compromete a cumplir (puede ser más estricta que la del enunciado)
docs/data-ownership.md El mapa de tablas y módulos
docs/payment-methods.md La convención y los pasos para agregar un medio
docs/measurements/p1.md ## Antes: cuántos archivos existentes había que modificar para agregar un medio, con el comando que lo muestra y su salida. ## Después: lo mismo con el diseño nuevo. Y si el rediseño volvió más lento algo que se pueda medir, el número (archivo de partida: templates/measurements.md)

6. Cómo se comprueba

make -f /work/projects/p1-modulos/Makefile check

Corre make typecheck, make deps y make test de su repositorio, y después las pruebas públicas de P0 y de P1. Como en P0, las pruebas borran y vuelven a crear la base de datos tinkuy y usan los puertos 3100 y 4100; la copia con tunki se hace en /tmp/tinkuy-check/p1-copia y se borra al terminar. Tarda cerca de dos minutos.

Sobre un P0 terminado y nada más, las pruebas de P0 pasan y las de P1 terminan así:

P1 · documentos
  ✖ los tres diagramas C4 pasan el revisor, y hay uno de componentes
      docs/c4/components.md: no existe
  ✖ docs/scenarios.md pasa el revisor y tiene un escenario de modificabilidad
      ningún escenario tiene la línea "- **Atributo de calidad:** modificabilidad"
  ✖ hay al menos tres ADR (el de P0 y dos de esta entrega), con sus secciones
      docs/adr/ tiene 1 ADR con nombre NNNN-titulo.md y esta entrega pide al menos 3 en total
  ✖ docs/measurements/p1.md compara el antes y el después
      docs/measurements/p1.md: no existe
  ✖ docs/data-ownership.md tiene la tabla | Tabla | Módulo |
      docs/data-ownership.md: no existe
  ✖ docs/payment-methods.md dice dónde van los plug-ins y cuál es el registro
      docs/payment-methods.md: no existe

P1 · límites
  ✖ las tres reglas de dependencia del curso no reportan ninguna violación
      quedan 3 violaciones:
      ...
  ✖ make deps pasa con las reglas del repositorio
      make deps terminó con código 2:
      depcruise src --config .dependency-cruiser.cjs
      ...
      x 3 dependency violations (3 errors, 0 warnings). 36 modules, 89 dependencies cruised.
  ✖ make check incluye las reglas de dependencia
      make -n check no muestra ninguna llamada a depcruise

P1 · sistema
  ✔ API: GET /health responde ok
  ...
  ✔ API: el reporte de ventas coincide con las órdenes pagadas del evento
  ✖ Plin: 201 sin comisión, y a la pasarela le llega plin: { phone }
      {"error":{"code":"INVALID_INPUT","message":"payment.method debe ser card o yape"}}

      422 !== 201

  ✖ Plin: la pasarela rechaza el celular que termina en 000 y Tinkuy responde 402
      {"error":{"code":"INVALID_INPUT","message":"payment.method debe ser card o yape"}}

      422 !== 402

  ✔ Plin: sin celular, o con uno que no tiene 9 dígitos, da 422
  ✖ cada tabla tiene un módulo que es su owner, y ningún módulo nombra en su SQL una tabla ajena
      docs/data-ownership.md: no existe

P1 · modificabilidad: un medio de pago nuevo sin tocar el núcleo
  ✖ con el medio nuevo agregado, make typecheck y make deps siguen pasando
      no se pudo agregar el medio de pago a la copia: docs/payment-methods.md: no existe
  ...

26 pruebas: 11 pasan, 15 fallan

La prueba de Plin sin celular ya pasa, por la razón equivocada: hoy todo pago con Plin es un 422.

7. Pistas

  • Por dónde empezar. Primero los límites, después el plug-in. Con el ciclo roto y las tablas repartidas, mover los medios de pago es un cambio dentro de un módulo. Al revés, van a mover los mismos archivos dos veces.
  • El ciclo. El apunte de la semana 3 tiene Cuatro maneras de romper el ciclo. No todas valen lo mismo para un solo dato; el ADR compara al menos dos.
  • Los datos. El apunte de la semana 4, en Los datos como límite y El JOIN que cruza dos módulos, muestra tres salidas para una consulta que cruza módulos, con lo que cuesta cada una. code/week-04/shop/ tiene el mismo problema resuelto en otro dominio y con otra convención (un esquema de PostgreSQL por módulo, que aquí no pueden usar).
  • La transacción de la compra. Que cada módulo sea owner de sus tablas no obliga a partir la transacción: piensen qué tiene que recibir una función de un módulo para escribir en sus tablas dentro de la transacción de otro.
  • El plug-in. El laboratorio de la semana 4 hace los pasos 1 a 6 sobre su propio Tinkuy; code/week-04/microkernel/ es la técnica completa en chico. La tabla del paso 1 (archivo, función, qué decide ese if) es la mitad del ADR del contrato.
  • Los tipos. Si el tipo de los datos de pago es una unión cerrada con un caso por medio, la copia con tunki no va a pasar make typecheck. Decidan qué sabe el núcleo de los datos de un medio.
  • Antes de entregar. Hagan ustedes lo que hace la prueba: agreguen un medio inventado en una rama, cuenten los archivos con git diff --stat y bórrenla. Ese conteo es su sección Después.
  • Una regla no está terminada hasta que la vieron fallar. Para cada regla que agreguen, escriban el import prohibido, vean el error y quítenlo.

8. Fuera de alcance

  • Rendimiento. Si el rediseño vuelve más lento un endpoint, se mide y se anota; no se optimiza aquí.
  • Que un asiento no se venda dos veces: P2.
  • Sacar un módulo a otro proceso. Los límites de esta entrega son dentro de un solo proceso y una sola base de datos; P4 saca los pagos.
  • Devoluciones, cuotas y medios de pago que no responden en el momento. Vale discutir en el ADR si su contrato los soportaría; no hay que implementarlos.