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 checkpasando antes del cambio - Respuesta: el medio se agrega, se puede comprar con él y
make checksigue 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 depspasa: cero violaciones.- Las tres reglas originales (
no-circular,http-does-not-touch-dbymodules-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 susrc/. make checkincluyemake deps.
Plin
POST /orders acepta un tercer medio de pago:
"payment": { "method": "plin", "phone": "987654321" }
phonees un celular de 9 dígitos que empieza con 9, como texto. Si falta o no cumple, la respuesta es 422 conINVALID_INPUT.- Plin no tiene comisión:
feeCentses 0 ypaymentMethodes"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 en000: en ese caso Tinkuy responde 402 conPAYMENT_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 columnasTablayMódulo(archivo de partida:templates/data-ownership.md). Un módulo es una carpeta desrc/. 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:
- 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.
- 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
docs/c4/context.md,docs/c4/containers.mdydocs/c4/components.mdpasan juntos el revisor de la semana 1, y el tercero es de nivelcomponentes(con su líneaContenedor:).docs/scenarios.mdpasa el revisor de la semana 2 y tiene un escenario conAtributo de calidad: modificabilidad.docs/adr/tiene al menos tres ADR en total, todos con sus cinco secciones y al menos dos alternativas.docs/measurements/p1.mdtiene las seccionesAntesyDespuésy al menos un bloque de código.docs/data-ownership.mdtiene la tabla| Tabla | Módulo |.docs/payment-methods.mdtiene las dos líneas de la convención, la carpeta existe y contieneplin.ts.
Límites
- Las tres reglas del curso reportan 0 violaciones en su
src/. make depstermina con código 0.make -n checkmuestra una llamada adepcruise.
Sistema
- Las diez pruebas de la API de P0.
- Una compra con Plin responde 201 con
feeCents0 ypaymentMethod"plin", y la pasarela recibe exactamente un cobro, conmethod: "plin",plin: { phone }y el total de la orden. - Plin con un celular que termina en
000responde 402 y deja el asiento libre. - Plin sin
phone, con"12345"o con un número en vez de texto responde 422. - Todas las tablas de la base de datos (esquema
public) están en el mapa, con un módulo que es una carpeta desrc/. Y en ningún archivo.tsdesrc/aparece, después deFROM,JOIN,INTO,UPDATEoTABLE, 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)
- El archivo de registro nombra a Plin en una o dos líneas.
make typecheckymake depspasan en la copia.- Una compra con
{ "method": "tunki", "phone": "987654321" }responde 201 confeeCents0 ypaymentMethod"tunki", y la pasarela recibetunki: { phone }. tunkicon un celular que termina en000responde 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
JOINque 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 eseif) 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
tunkino va a pasarmake 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 --staty bórrenla. Ese conteo es su secciónDespués. - Una regla no está terminada hasta que la vieron fallar. Para cada regla
que agreguen, escriban el
importprohibido, 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.