Tres horas. Media hora para saber qué se evalúa y qué cambia al publicar, y dos horas y media cerrando el proyecto, desplegándolo, auditándolo y defendiéndolo.
Hoy · Hoja de ruta
- 1. Aprende: Qué comprueba quien recibe un proyecto, qué documentación necesita un servicio y qué deja de funcionar igual cuando deja tu máquina.
- 2. Haz: Cierra la aplicación, publícala, audítala, revisa la de un compañero y defiende la tuya.
- 3. Comprueba: Funciona de punta a punta desde una instalación limpia, tiene una URL pública y puedes explicar cualquier decisión que contenga.
Antes de empezar · 5 minutos, sin apuntes
- Si clonas tu proyecto en una carpeta nueva, ¿arranca?
- ¿Qué queda a medias, con un comentario que dice «arreglar esto»?
- ¿Qué pasará con tu fichero de datos cuando el servicio se reinicie en un servidor ajeno?
Se explica
25 minutos · criterios y preparación
Hoy no hay concepto nuevo. Lo que hay es el cambio de punto de vista que cierra el módulo: el proyecto deja de mirarse desde dentro, por quien lo escribió, y pasa a mirarse desde fuera, por quien lo recibe sin poder preguntar nada.
La prueba de la instalación limpia
- Clonar en una carpeta vacía
- Copiar el ejemplo de entorno y rellenarlo
- Instalar dependencias
- Sembrar los datos
- Arrancar
- Abrir el navegador y usarlo
Cada tropiezo en ese recorrido es un fallo que tu corrector encontrará también. La única forma de saberlo es recorrerlo de verdad, en otra carpeta y sin arreglar nada por el camino con lo que ya tienes instalado.
El README que sirve
Lo que no puede faltar
- Qué es esto y qué problema resuelve, en tres líneas.
- Cómo instalarlo y arrancarlo, con las órdenes exactas.
- Las variables de entorno, con su significado y si son obligatorias.
- La tabla de rutas: método, ruta, qué hace y qué devuelve.
- El formato de error y sus códigos.
- Cómo ejecutar las pruebas.
- Qué decisiones tomaste y qué dejaste fuera a propósito.
Ese último punto distingue el README de un proyecto de clase del de uno profesional: decir qué no hace y por qué evita que quien lo lea lo tome por un fallo.
Publicar
{
"scripts": { "start": "node src/servidor.js" },
"engines": { "node": ">=22" }
}Casi todas las plataformas gratuitas hacen lo mismo: clonan tu repositorio, ejecutan la instalación y arrancan con npm start. Lo que hay que preparar es esto:
| Detalle | Qué hay que hacer |
|---|---|
| El puerto | Tomarlo de la variable de entorno que dé la plataforma |
| Las variables | Configurarlas en su panel, no en el repositorio |
| El entorno | Poner NODE_ENV en producción |
| Los datos | Saber que el disco puede borrarse en cada despliegue |
| El registro | Escribir a la salida estándar, que es lo que la plataforma recoge |
Un fichero en el disco de un servicio desplegado no es permanente
Muchas plataformas reconstruyen el contenedor en cada despliegue, y algunas también al reiniciar por inactividad. Tus productos creados desaparecen, sin que haya ningún fallo en tu código.
Ese es el motivo por el que existen las bases de datos gestionadas, y el problema con el que empieza el módulo de servidor. De momento, sepas explicarlo y siembra los datos al arrancar.
Qué se evalúa
| Criterio | Puntos |
|---|---|
| Diseño por recursos y contrato sostenido en toda la API | 1,5 |
| CRUD completo con los códigos de estado del contrato | 1,5 |
| Validación en el servidor, con lista blanca de campos | 1,5 |
| Separación real en rutas, servicio y repositorio | 1,5 |
| Contrato de errores único, usado de punta a punta | 1 |
| Cliente conectado y formularios de extremo a extremo | 1 |
| Configuración por entorno, seguridad mínima y escapado | 1 |
| Pruebas automáticas en verde y aplicación desplegada | 1 |
No puntúa el tamaño del proyecto. Puntúa que el contrato se sostenga: que cada ruta responda lo que promete, que ninguna entrada se acepte sin validar y que puedas defender por qué está hecho así.
Las preguntas de la defensa final
- Enséñame el recorrido de una petición desde que alguien pulsa un botón hasta que el dato se guarda.
- ¿Por qué esta ruta y no otra? ¿Por qué este código de estado?
- ¿Dónde validas y por qué no basta con hacerlo en el cliente?
- Enséñame una decisión de accesibilidad y explícame a quién ayuda.
- ¿Qué pasa si tu API recibe un campo que no esperabas?
- Si mañana hubiera que cambiar el fichero por una base de datos, ¿qué tocarías?
- Enséñame el fallo que más te costó encontrar y cuéntame cómo lo encontraste.
- ¿Qué harías distinto si empezaras hoy el proyecto?
Salen cuatro de esa lista, elegidas al azar, y cubren el módulo entero y no solo esta unidad. Las dos últimas valen tanto como las demás: saber qué te costó y qué harías distinto demuestra que has entendido lo que hiciste.
Se trabaja
150 minutos · cerrar, publicar y defender
El README se trae escrito de casa: el tiempo de clase es para desplegar, auditar y defender, que es donde aparecen los problemas que no se pueden prever.
Paso 1 · Cerrar el proyecto · 40 min
- Clona tu repositorio en una carpeta vacía y recorre la instalación limpia entera, anotando cada tropiezo sin arreglarlo sobre la marcha.
- Corrige después todos los tropiezos anotados, empezando por los que impiden arrancar.
- Recorre la aplicación de punta a punta y marca la lista siguiente.
Lo que tiene que funcionar seguido
- La página inicial llega generada por el servidor.
- El catálogo se filtra, se busca y se ordena.
- El alta crea un producto que persiste tras reiniciar.
- Un dato inválido se rechaza y el error aparece en su campo.
- Un borrado desaparece de la lista y del fichero.
- Sin servidor, el cliente muestra su estado de error.
- Todo se puede hacer con el teclado.
npm testestá en verde.
- Cierra lo que siempre queda: rutas del contrato sin implementar, códigos de estado que no coinciden con lo documentado, mensajes de depuración olvidados, el README desactualizado y el
.env.examplesin las variables nuevas. - Comprueba que el repositorio no contiene secretos ni dependencias instaladas.
Paso 2 · Publicar · 35 min
- Prepara el proyecto: puerto tomado del entorno, script
startyengines. - Despliega en una plataforma gratuita.
- Configura las variables en su panel, incluida la clave de API.
- Comprueba la aplicación desde otro dispositivo, con otra red si puedes.
- Añade una ruta de estado que informe de si el servicio responde, y consúltala desde fuera.
- Anota qué se comporta distinto respecto a tu máquina. Habrá al menos tres diferencias, y una de ellas tendrá que ver con los datos.
Antes de continuar: crea un producto en el despliegue, fuerza un reinicio y comprueba si sigue ahí. Sepas explicar el resultado, sea cual sea.
Paso 3 · La auditoría · 30 min
Marca las tres listas sobre tu proyecto ya desplegado, no sobre el de tu máquina. Cada punto sin marcar se apunta con lo que falta para marcarlo.
Auditoría · la API
- Las rutas se organizan por recursos y son predecibles.
- Cada operación devuelve el código del contrato, también en los errores.
- Todos los errores tienen la misma forma.
- Toda entrada se valida con lista blanca en el servidor.
- Las respuestas no exponen campos internos.
Auditoría · la arquitectura
- Ruta, servicio y repositorio están separados de verdad.
- La aplicación se crea sin arrancarse.
- Cambiar el almacén no toca rutas ni servicio.
- La configuración vive fuera del código y se comprueba al arrancar.
- Los errores se traducen a HTTP en un único sitio.
Auditoría · el conjunto del módulo
- El HTML es semántico y válido, también el generado en el servidor.
- El diseño se adapta y respeta las preferencias del usuario.
- Todo se maneja con teclado y los cambios se anuncian.
- Todo dato ajeno se escapa antes de entrar en la página.
- Las pruebas pasan y detectan las roturas.
- El repositorio no contiene secretos ni dependencias instaladas.
Paso 4 · Revisión por pares · 25 min
Intercambia proyectos y trabaja sobre el ajeno sin preguntar nada a quien lo escribió. Todo lo que necesites debe estar en su README.
- Clona, configura, siembra y arranca. Anota cada tropiezo con su hora.
- Usa la aplicación entera solo con el teclado.
- Ataca la API: datos inválidos, campos de más, rutas fuera de lo público, escritura sin clave.
- Ejecuta sus pruebas, rompe algo a propósito y comprueba si lo detectan.
- Encuentra dónde vive una regla de negocio y explícala en voz alta.
- Devuelve por escrito tres cosas que funcionan bien, tres que fallan y una pregunta que el README no responde.
Paso 5 · La defensa y la entrega · 20 min
- Prepara tres minutos: el recorrido de una petición, una decisión que defiendas y una que cambiarías.
- Responde las cuatro preguntas que salgan de la lista, con el código delante.
- Incorpora al proyecto lo que haya salido de la revisión del compañero y quepa en el tiempo.
- Escribe el documento de una página con las tres decisiones técnicas de las que estés más satisfecho y las tres que cambiarías.
- Comprueba la entrega completa contra la lista del cierre y envíala.
Ampliación si has completado el trabajo
Primero termina y comprueba los cinco pasos. Los dos retos son las dos continuaciones naturales del proyecto: crecer en recursos y resolver el problema de los datos que desaparecen.
Reto 1 · El segundo recurso, de contrato a pruebas
Una API con un solo recurso esconde casi todas las decisiones difíciles. Añade el segundo, relacionado con el primero: categorías, pedidos o valoraciones.
- Escribe su contrato antes de escribir una línea: rutas, cuerpos, códigos y errores.
- Decide cómo se expresa la relación en las rutas, y qué ocurre al pedir un recurso a través del otro.
- Impleméntalo con sus tres capas, reutilizando el manejador de errores y la validación.
- Decide qué pasa al borrar algo de lo que dependen otros elementos. Hay al menos tres políticas posibles: impedirlo, borrar en cascada o dejar la referencia huérfana. Elige, justifica y escríbelo en el contrato.
- Provoca la situación del apartado anterior y comprueba que tu decisión se cumple.
- Añade sus pruebas, incluida una de la relación.
- Anota cuánto código nuevo has escrito y cuánto has reutilizado. Esa proporción mide lo que valían las decisiones de las sesiones 1 y 3.
Reto 2 · Datos que sobreviven al despliegue
Tu fichero desaparece en cada reconstrucción del servicio. Resuélvelo sin romper la frontera del repositorio.
- Busca qué ofrece tu plataforma: disco persistente, base de datos gestionada o almacenamiento externo. Anota el coste y el límite de cada opción en su capa gratuita.
- Elige una y escribe un repositorio nuevo contra ella, con la misma lista de funciones. Ninguna ruta ni ningún servicio debe cambiar.
- Adapta el script de siembra para que funcione también contra el almacén nuevo.
- Despliega y comprueba que un producto creado sobrevive a un reinicio y a un despliegue.
- Decide cómo eliges el repositorio en cada entorno: memoria en las pruebas, fichero en tu máquina, el nuevo en producción. Un solo punto de decisión.
- Ejecuta la batería de pruebas contra el almacén de producción en un entorno aparte, y anota qué pruebas dejan de valer cuando los datos no se reinician entre ejecuciones.
- Escribe en tres líneas qué problema nuevo has adquirido. Un almacén externo puede tardar, puede caer y puede quedarse a medias, y esos tres casos ahora son tuyos.
Cierre
5 minutos · entrega y recuerdo
Lista de verificación de la sesión
- El proyecto arranca desde una instalación limpia sin ayuda.
- Tiene una URL pública y las variables viven en la plataforma.
- El README basta para instalarlo y usar la API.
- Las tres listas de auditoría están marcadas.
- Has revisado un proyecto ajeno y recibido la revisión del tuyo.
- Puedes explicar cualquier decisión del proyecto con el código delante.
Antes de cerrar · 3 minutos, sin mirar
- ¿Qué hace quien recibe tu proyecto, paso a paso, antes de verlo funcionar?
- ¿Qué apartados no pueden faltar en un README?
- ¿Qué pasa con un fichero de datos en un servicio desplegado, y por qué?
- ¿De dónde salen las variables de entorno en producción?
- Si hubiera que cambiar el almacén, ¿qué ficheros tocarías?
- ¿Qué se puntúa en este proyecto, si no es su tamaño?
Ver respuestas
1 · Clonar, configurar el entorno, instalar, sembrar, arrancar y usarlo en el navegador.
2 · Qué es, cómo se instala, las variables, la tabla de rutas, el formato de error, cómo probar y qué decisiones se tomaron.
3 · Que puede desaparecer en cada despliegue o reinicio, porque el contenedor se reconstruye.
4 · Del panel de la plataforma, nunca del repositorio.
5 · Solo el repositorio y el punto donde se elige cuál se usa.
6 · Que el contrato se sostenga de punta a punta y que puedas defender cada decisión.
El repositorio con la aplicación completa: cliente y API servidos juntos, capas separadas, contrato documentado, configuración por entorno, seguridad mínima y pruebas en verde. La URL del despliegue. El README con sus siete apartados. Las tres listas de auditoría marcadas. La revisión del compañero por escrito. Finalmente, un documento de una página con las tres decisiones técnicas de las que estés más satisfecho y las tres que cambiarías.
Microprueba semanal 6 · 10 minutos
Individual, sin IA y sin apuntes.
- Enumera los cinco puntos que revisarías en una API antes de darla por terminada.
- Explica una decisión de diseño de tu API y una alternativa que descartaste.
- Si mañana el fichero JSON fuera una base de datos, ¿qué tocarías y qué no?