P0 · Reconocimiento

Cubre: semanas 1 a 3 · Individual

Antes de rediseñar un sistema hay que saber qué hay. En esta entrega no llega ningún requisito nuevo y no se cambia el diseño de Tinkuy: se lee, se dibuja, se mide y se corrige una sola cosa. Lo que entreguen aquí es el punto de partida de todo el proyecto: los diagramas, los escenarios y las mediciones de P0 son el “antes” con el que van a comparar cada decisión de las entregas siguientes.

Su repositorio empieza como una copia de tinkuy/. Todo lo que sigue se hace ahí, dentro del contenedor del curso.

1. El requisito que llega

Ninguno todavía. En las entregas P1 a P5, esta sección trae un escenario de calidad que el sistema no cumple. Aquí los escenarios los escriben ustedes: tres, con sus seis partes y su medida, y los miden sobre el sistema tal como está. Lo esperable es que el Tinkuy inicial no cumpla algunos. Eso no es un problema de la entrega: es su resultado.

2. Lo que está fijo

  • La API no cambia. Las rutas, los cuerpos y los códigos de estado son los del README de Tinkuy.
  • El diseño no cambia, salvo lo mínimo para la parte 4 (una violación de dependencia). No agreguen un pool de conexiones, no arreglen consultas, no toquen la compra: si corrigen lo que miden, se quedan sin el “antes”.
  • make typecheck y make test siguen pasando.
  • make db, make start y las variables PORT, TINKUY_DB y GATEWAY_URL siguen funcionando como en el README: las pruebas públicas levantan su sistema con ellas.

3. Lo que se entrega

Parte 1: dos diagramas C4

docs/c4/context.md y docs/c4/containers.md, con el formato de la semana 1: dos tablas por diagrama, una de elementos y una de relaciones. Los archivos de partida están en code/week-01/lab/.

El diagrama de contenedores tiene que mostrar lo que de verdad corre, no lo que sugieren los nombres de las carpetas. Compruébenlo con el sistema arriba: qué procesos hay (ps aux), quién abre una conexión hacia quién, qué pasa si detienen cada cosa.

Parte 2: tres escenarios de calidad, medidos

docs/scenarios.md, con el template de la semana 2 y dos líneas más por escenario (el archivo de partida está en templates/scenarios.md):

## La lista de asientos cuando se abre una venta

- **Atributo de calidad:** rendimiento
- **Script de k6:** `load/seat-list.js`
- **Fuente del estímulo:** ...
  • Al menos tres escenarios medidos con k6, cada uno con su propio script en load/.
  • Entre los medidos, al menos dos atributos de calidad distintos. Con k6 se puede medir más que latencia: la fracción de pedidos que termina en error también es una medida.
  • El umbral del script es la medida del escenario: si el escenario dice “p95 menor que 300 ms”, el script tiene p(95)<300 en options.thresholds. Los scripts que trae Tinkuy (load/browse.js y load/sale.js) solo miden, no tienen umbrales: sirven de punto de partida, no de entrega.
  • Cada script lee la dirección del sistema de la variable BASE_URL, parte de los datos de make db y termina en 45 segundos o menos.
  • Pueden tener más escenarios sin script (uno de modificabilidad, por ejemplo). Llevan la línea del atributo de calidad y no la del script.

El número de cada medida se decide antes de medir, pensando en quien usa el sistema. Un umbral copiado del resultado no es un requisito.

Parte 3: las mediciones

docs/measurements/p0.md (archivo de partida: templates/measurements.md), con estas secciones:

Sección Contenido
## Máquina En qué computadora midieron, cuánta memoria y cuántos núcleos tiene Docker, y qué más estaba corriendo
## Resultados Por cada script (nombrado con su ruta, load/...), el resumen de k6 tal como salió, en un bloque de código, y una tabla con cada umbral, el valor medido y si se cumple
## Umbrales que no se cumplen Cuáles no se cumplen y por qué: qué hace el sistema que explica ese número. No los arreglen

La explicación es la parte que más pesa. “El p95 salió alto porque el endpoint es lento” no explica nada. Una explicación nombra qué hace el sistema en ese pedido (qué consultas, cuántas, qué espera y de quién) y trae una evidencia que otra persona puede repetir.

Parte 4: una regla de dependencia que deja de violarse

make deps reporta hoy cuatro violaciones de las reglas de .dependency-cruiser.cjs. Corrijan una, la que ustedes elijan, de modo que make deps reporte a lo más tres, sin cambiar las reglas y con make test todavía pasando sin modificar ninguna prueba.

Hay más de una forma de hacer que una violación deje de reportarse, y no todas arreglan algo. Expliquen su elección en un ADR: docs/adr/0001-<titulo-en-kebab-case>.md (archivo de partida: templates/adr.md), con las secciones Contexto, Alternativas consideradas, Decisión, Estado y Consecuencias. El ADR dice cuál de las cuatro corrigieron, por qué esa y no otra, y qué queda pendiente.

4. Lo que deciden

  • Qué escenarios escribir, de qué atributos y con qué medida.
  • Cuál de las cuatro violaciones corregir y cómo (un ADR, con al menos dos alternativas comparadas).

5. Lo que comprueban las pruebas públicas

p0.public.test.ts tiene tres grupos.

Documentos

  1. docs/c4/context.md y docs/c4/containers.md pasan el revisor de la semana 1 (check-c4.ts), juntos: también la regla de coherencia entre los dos.
  2. En el diagrama de contenedores hay un contenedor cuya tecnología nombra Node.js, un almacén de datos cuya tecnología nombra PostgreSQL y un sistema externo que es la pasarela de pagos.
  3. docs/scenarios.md pasa el revisor de la semana 2 (scenario-check.ts): seis partes en cada escenario y un número en la medida.
  4. Todos los escenarios tienen la línea Atributo de calidad. Al menos tres tienen la línea Script de k6, con tres scripts distintos, y entre ellos hay al menos dos atributos distintos.
  5. Cada script está en load/, termina en .js y define options.thresholds.
  6. docs/measurements/p0.md tiene las tres secciones, al menos un bloque de código y nombra cada script por su ruta.
  7. docs/adr/0001-*.md existe, tiene las cinco secciones con contenido y compara al menos dos alternativas (una por ítem de lista o por subtítulo).

Dependencias

  1. Las reglas del curso (el .dependency-cruiser.cjs de tinkuy/, no el de su repositorio) reportan a lo más 3 violaciones en su src/.

Sistema

  1. La API responde lo que dice el README de Tinkuy: catálogo, compra con tarjeta y con Yape, pago rechazado (402), asiento vendido (409), datos inválidos (422) y reporte de ventas. Son diez pruebas que entran por HTTP y comparan con la base de datos.
  2. Cada script de escenario corre con k6 contra su sistema, desde datos recién cargados, y reporta sus umbrales. k6 debe terminar con código 0 (umbrales cumplidos) o 99 (alguno sin cumplir): que un umbral no se cumpla no hace fallar la prueba. Falla si el script no corre, no hace ningún pedido a BASE_URL, no reporta umbrales o pasa de 75 segundos.

Las pruebas no saben si sus diagramas son ciertos, si sus umbrales tienen sentido ni si su explicación es correcta. Eso lo lee el docente.

Las pruebas se repiten en la revisión con otra semilla (SEED). Si un script compra asientos, que los pida al sistema (GET /events, GET /events/:id/seats) en vez de traer ids escritos.

6. Cómo se comprueba

Dentro del contenedor, desde su repositorio:

make -f /work/projects/p0-reconocimiento/Makefile check

check corre primero make typecheck y make test de su repositorio, y después las pruebas públicas con los documentos. Las pruebas públicas borran y vuelven a crear la base de datos tinkuy (con make db) y levantan su servidor en el puerto 3100 y una pasarela de prueba en el 4100, así que no chocan con lo que tengan corriendo en el 3000 y el 4000. Tarda entre uno y dos minutos, casi todo en los scripts de k6.

make -f … public corre solo las pruebas públicas, y SEED=11 al final del comando las corre con otros datos de ejemplo.

Sobre el Tinkuy inicial, sin nada hecho, el segundo paso termina así:

== 2 de 2 · Pruebas públicas y documentos (semilla 7)

P0 · documentos
  ✖ los diagramas de contexto y de contenedores pasan el revisor de la semana 1
      docs/c4/context.md: no existe
      docs/c4/containers.md: no existe
  ✖ el diagrama de contenedores nombra lo que de verdad corre
      docs/c4/containers.md: no existe
  ✖ docs/scenarios.md pasa el revisor de la semana 2
      docs/scenarios.md: no existe
  ✖ hay al menos tres escenarios medidos con k6, de al menos dos atributos de calidad
      0 escenario(s) tienen la línea "- **Script de k6:** load/<archivo>.js" y se piden al menos 3
  ✔ cada script de k6 está en load/ y define umbrales
  ✖ docs/measurements/p0.md tiene sus secciones y nombra cada script
      docs/measurements/p0.md: no existe
  ✖ el ADR 0001 existe y tiene las secciones de un ADR
      falta docs/adr/0001-<titulo-en-kebab-case>.md

P0 · dependencias
  ✖ las reglas de dependencia del curso reportan a lo más 3 violaciones
      quedan 4 violaciones y se piden a lo más 3:
        http-does-not-touch-db: src/http/order-handlers.ts → src/db.ts
        modules-only-through-index: src/reports/sales-report.ts → src/catalog/events.ts
        modules-only-through-index: src/reports/sales-report.ts → src/orders/order-repository.ts
        no-circular: src/catalog/events.ts → src/orders/index.ts

P0 · sistema
  ✔ API: GET /health responde ok
  ✔ API: GET /events lista todos los eventos, por fecha, con los asientos que les quedan
  ...
  ✔ API: el reporte de ventas coincide con las órdenes pagadas del evento

18 pruebas: 11 pasan, 7 fallan

Las pruebas de la API ya pasan: el sistema funciona. Lo que falta es todo lo demás.

7. Pistas

  • Diagramas. El laboratorio de la semana 1 recorre Tinkuy con esta pregunta. Si dudan de si algo es un contenedor, usen la definición del formato: algo que tiene que estar corriendo para que el sistema funcione. Fíjense en cómo se “envía” el correo de confirmación antes de dibujar un servidor de correo.
  • Escenarios. El apunte de la semana 2 tiene las secciones Cómo se escribe: el template y el revisor y la de umbrales. code/week-02/load/ tiene un script que separa las métricas por endpoint, que es lo que necesitan para poner un umbral sobre un endpoint y no sobre todos juntos.
  • Qué medir. Corran make load-browse, make load-sale y make oversell y miren los resúmenes completos antes de escribir nada. Un buen escenario suele salir de un número que les llamó la atención.
  • Mediciones. Las tres reglas están en el laboratorio del entorno: percentiles, la misma máquina y más de una corrida. Partan siempre de make db.
  • La violación. El apunte de la semana 3 explica las cuatro en Las cuatro violaciones de Tinkuy. Para cada candidata pregúntense qué cambio futuro se vuelve más barato al corregirla, y si su corrección quita el acoplamiento o solo lo deja de reportar.

8. Fuera de alcance

  • Cumplir los umbrales. Se cumplen (o no) con el sistema como está.
  • Corregir las otras tres violaciones: eso es P1.
  • Evitar que un asiento se venda dos veces. Si lo ven al medir, anótenlo: es P2.
  • Diagrama de componentes: llega en P1.