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 typecheckymake testsiguen pasando.make db,make starty las variablesPORT,TINKUY_DByGATEWAY_URLsiguen 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)<300enoptions.thresholds. Los scripts que trae Tinkuy (load/browse.jsyload/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 demake dby 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
docs/c4/context.mdydocs/c4/containers.mdpasan el revisor de la semana 1 (check-c4.ts), juntos: también la regla de coherencia entre los dos.- En el diagrama de contenedores hay un
contenedorcuya tecnología nombra Node.js, unalmacén de datoscuya tecnología nombra PostgreSQL y unsistema externoque es la pasarela de pagos. docs/scenarios.mdpasa el revisor de la semana 2 (scenario-check.ts): seis partes en cada escenario y un número en la medida.- Todos los escenarios tienen la línea
Atributo de calidad. Al menos tres tienen la líneaScript de k6, con tres scripts distintos, y entre ellos hay al menos dos atributos distintos. - Cada script está en
load/, termina en.jsy defineoptions.thresholds. docs/measurements/p0.mdtiene las tres secciones, al menos un bloque de código y nombra cada script por su ruta.docs/adr/0001-*.mdexiste, tiene las cinco secciones con contenido y compara al menos dos alternativas (una por ítem de lista o por subtítulo).
Dependencias
- Las reglas del curso (el
.dependency-cruiser.cjsdetinkuy/, no el de su repositorio) reportan a lo más 3 violaciones en susrc/.
Sistema
- 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.
- 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-saleymake overselly 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.