P2 · Diseño y primer sprint

Publicado: semana 5 · Entrega: semana 8 (demo del sprint 1) · En equipo · Tag: p2

Con el backlog de P1 aprobado, el equipo diseña el producto y lo empieza a construir. Esta entrega tiene dos mitades que se alimentan una a la otra: los documentos de diseño (design doc, ADRs y la especificación de la API) y un esqueleto que funciona de punta a punta (walking skeleton): una historia real del backlog que va desde la interfaz hasta la base de datos, con poco adorno pero con todas las capas conectadas. El sprint 1 termina con una demo al cliente.

Cubre las semanas 4 (especificaciones y design docs), 5 (complejidad, módulos profundos, acoplamiento y cohesión), 6 (APIs y OpenAPI) y 7 (arquitectura y ADRs). Los archivos de P1 se quedan y se mantienen al día: la revisión de P2 vuelve a correr la de P1.

1. El código

La aplicación es una aplicación web pequeña en TypeScript sobre Node.js 26, como en los laboratorios (ver la guía de estilo). La arquitectura la deciden ustedes en un ADR; para que la revisión automática pueda levantarla, la aplicación cumple este contrato:

• package.json con "type": "module" y los scripts start (levanta el servidor), test (corre las pruebas) y check (lo que el equipo exige antes de un merge: en P2 basta con npm test; en P3 se agregan tsc, ESLint y la cobertura).
• npm start levanta el servidor en el puerto de la variable PORT y guarda los datos en el archivo de la variable DB_PATH (la revisión le pasa un archivo temporal). Si la aplicación necesita otras variables (un token, una clave), van con valores de ejemplo en .env.example: la revisión las carga de ahí. Nunca suban .env con valores de verdad.
• GET / sirve la interfaz (HTML). Cada operación GET sin parámetros de ruta de la especificación responde algo que no es 404 ni 5xx (un 400 o un 401 están bien).
• Las pruebas son archivos *.test.ts que encuentra node --test desde la raíz del repositorio (por ejemplo en test/), con node:test y node:assert/strict. El código de la aplicación va en src/.
• Dependencias: lo del contenedor del curso (Node.js, node:sqlite, node:http y las herramientas de calidad). Una dependencia de npm más se justifica en un ADR (ver El cliente y las reglas).

2. Qué entregan

docs/diseno.md

Un design doc como los de la semana 4, con estas secciones ##:

• ## Contexto: el problema y los números que importan (cuántos usuarios, cuántos datos, en qué horario). Quien lea solo esta sección entiende para qué existe el sistema.
• ## Objetivos: lo que el diseño tiene que lograr, verificable.
• ## No objetivos: lo que a propósito no se va a hacer (y que alguien podría esperar).
• ## Diseño: la vista general (un diagrama de bloques o de contenedores), los módulos con su responsabilidad y lo que esconden, el modelo de datos y las decisiones de la API. Enlacen los ADRs.
• ## Alternativas consideradas: al menos dos diseños distintos que descartaron, y por qué.
• ## Riesgos: qué puede salir mal (técnico, de proceso, con el cliente), con qué probabilidad e impacto y qué hacen al respecto.

docs/adr/

Al menos 3 ADRs, uno por decisión, con el nombre NNNN-titulo.md (0001-node-http-y-sqlite.md). Cada uno con un título # ADR-NNNN: ... y estas secciones:

• ## Estado: Propuesta, Aceptada, Rechazada, Reemplazada (por cuál) u Obsoleta, con la fecha.
• ## Contexto: la situación y las fuerzas en juego.
• ## Decisión: lo que se decidió, en una o dos frases claras.
• ## Alternativas consideradas: las otras opciones, con lo bueno y lo malo de cada una.
• ## Consecuencias: lo que se gana, lo que se pierde y lo que ahora hay que hacer.

Decisiones típicas: la arquitectura y el stack, el modelo de datos o cómo se guardan los montos, cómo se autentica el personal, dónde se despliega (puede llegar en P4). Un ADR no se borra cuando cambia la decisión: se escribe uno nuevo que lo reemplaza.

docs/api/openapi.yaml

La especificación de la API en OpenAPI 3 (3.0 o 3.1), con al menos 3 operaciones, como en la semana 6. Tiene que pasar redocly lint sin errores con el conjunto de reglas recommended (la revisión usa su propia configuración: un redocly.yaml del equipo no cambia el resultado). Los avisos no hacen fallar la revisión, pero léanlos. Las tres reglas de recommended que más fallan en un primer borrador:

• no-empty-servers: declaren servers (por ejemplo - url: http://localhost:3000).
• operation-summary: cada operación lleva summary.
• security-defined: cada operación dice su seguridad. Las públicas, con security: []; las protegidas, con el esquema que definan en components.securitySchemes.

La especificación describe lo que la aplicación hace de verdad: la revisión llama a las operaciones GET sin parámetros de ruta y falla si la aplicación responde 404.

README.md

• ## Instalación: cómo clonar, configurar (las variables de .env.example) y correr la aplicación y las pruebas, en el contenedor del curso. Quien no conoce el proyecto la tiene que poder levantar siguiendo solo esta sección.
• ## Convenciones: nombres de ramas, mensajes de commit, cómo se abre, se revisa y se integra un pull request, y quién revisa qué.

En P4 y P5 el README crece (despliegue, arquitectura, cómo contribuir).

.github/pull_request_template.md

Qué cambia, por qué, qué historia (HU-NN), cómo se probó y si se usó una herramienta de IA. GitHub la usa para todo pull request nuevo. CODEOWNERS es opcional.

docs/sprints/sprint-1.md

• ## Planificación: el objetivo del sprint en una frase, las historias comprometidas (por id, HU-01), quién toma cada una y la capacidad estimada.
• ## Revisión: la demo con el cliente (fecha, quién estuvo, qué se mostró, qué dijo, qué cambió en el backlog) y qué historias quedaron terminadas.
• ## Retrospectiva: qué funcionó, qué no, y dos o tres acciones concretas, con responsable, para el sprint 2.

3. Git y pull requests

• Todo entra a main por un pull request revisado por otra persona. La revisión de P2 pide al menos un pull request integrado en la historia principal de main; desde P3, todos los cambios después del primer pull request.
• En GitHub, integren con Create a merge commit o con Squash and merge. No usen Rebase and merge: deja los commits en main sin rastro del pull request, y la revisión los cuenta como commits directos.
• La historia de Git es parte de lo que se revisa: commits pequeños, con mensajes que explican el porqué, y trabajo repartido.

4. Revisión automática

Dentro del contenedor del curso, desde la carpeta del repositorio del equipo, clonado dentro de la carpeta del curso (P1, sección 1):

cd /work/equipo-nombre
make -f /work/projects/p2-diseno/Makefile check

Corre las reglas de P1 y estas:

La revisión no puede ver la demo ni juzgar el diseño: eso lo hacen el docente y el cliente.

5. Cómo entregar

Igual que P1, con el tag p2 sobre el commit de main que se entrega, antes del plazo. La demo del sprint 1 con el cliente es en la semana 8, en el laboratorio o en el lugar del cliente; si fue con el cliente, en el laboratorio muestran la grabación o la repiten con el docente.

6. Consejos y errores comunes

• Diseñar todo antes de construir algo. El esqueleto existe para descubrir temprano lo que el design doc no previó (el despliegue, las fechas, la base de datos). Constrúyanlo en la primera semana del sprint y ajusten los documentos.
• Un esqueleto que no es de punta a punta. Una página que muestra datos inventados, o una API que nadie llama, no cuenta. Una historia, completa, aunque sea fea.
• Módulos superficiales. Un archivo por tabla con funciones que solo pasan datos de un lado a otro no esconde nada. Las reglas del negocio del cliente (horarios, precios, cupos) merecen un módulo propio, sin HTTP ni SQL, que se pueda probar solo (semana 5).
• ADRs escritos al final para cumplir. Un ADR sin alternativas reales o con consecuencias solo buenas no documenta una decisión. Escríbanlos cuando deciden, aunque luego cambien de estado.
• La especificación y el código divergen. Si cambian una ruta, cambien openapi.yaml en el mismo pull request. La revisión llama a la API con la especificación en la mano.
• Con IA. Un agente puede escribir el esqueleto en minutos; pidan la especificación primero (el design doc, la OpenAPI) y revisen que el código la cumpla. Lo que no entiendan, no lo integren: en la defensa oral se pregunta por cualquier parte. Registren el uso en docs/registro-ia.md.