📚 Unidad ISS-00 · Requisitos previos — capa 🧠 APRENDER

🛠 Construir este bloque → · ✅ Condiciones de cierre (GATE) · 📝 Evaluación

Capa Página Para qué

🧠 Aprender esta página comprender, explicar y relacionar

🛠 Construir Requisitos previos ejecutar, programar y verificar

✅ GATE Cierre de la unidad condición para pasar al bloque siguiente

Mapa de correspondencias. Cada fila enlaza el mismo tema en las dos capas de la unidad; los enlaces apuntan a secciones reales del material (anclas de MkDocs, sin acentos).

Tema	🧠 Aprender (esta página)	🛠 Construir (ISS técnico)
Ruta y ficha de la unidad	Ruta de aprendizaje · Ficha del ISS	Contenido de la unidad
Mapas y estructura	Mapa mental · Mapa del backend · Árbol de archivos	Contenido de la unidad
Recorrido y comandos	Comandos explicados · Recorrido paso a paso	Contenido de la unidad
Diagnóstico	Diagnóstico	Criterios de aceptación
Evaluación y cierre	Criterios · Evaluación · GATE	Condiciones de cierre · Cierre

ISS-00 — Cuaderno de aprendizaje visual

Tema

Requisitos previos: dejar el entorno listo (Node, npm y un motor de base de datos accesible) antes de escribir una sola línea de backend.

Fuente técnica autoritativa


Archivo fuente	`../manual/01-ISS-00-requisitos.md`
Estado	Solo lectura — este cuaderno no modifica el ISS
Alcance	45 líneas, 2 bloques de código, 1 checklist de aceptación

Este cuaderno es una capa pedagógica sobre ese archivo: todo su contenido técnico (comandos, versiones, criterios) aparece aquí íntegro y verbatim. El ISS manda; el cuaderno explica.

Pregunta que responde: ¿qué necesito tener instalado antes de empezar el laboratorio?

Regla del ISS

Objetivo: entorno listo para el laboratorio. Bloqueado por: ninguno.

La condición que el propio ISS exige es minimalista y estricta a la vez: no hay criterio de "código que funciona", porque todavía no hay código. Lo único que debe cumplirse es que las tres herramientas respondan y que el motor de base de datos sea accesible. Nada más. Este ISS no crea archivos.

Cómo leer este cuaderno

Cada concepto se presenta tres veces, desde tres ángulos distintos:

                 CONCEPTO
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
   EXPLICACIÓN    CÓDIGO      VISUAL
        │           │           │
    ¿qué es?    ¿dónde está?  ¿cómo lo
    ¿por qué?   ¿qué hace?     visualizo?
    ¿para qué?  ¿cómo opera?  ¿con qué
                               se relaciona?

Pregunta que responde: ¿cómo está organizado este cuaderno y qué espero encontrar en cada parte?

El recorrido de lectura es:

EXPLICACIÓN
    ↓
CÓDIGO
    ↓
VISUAL

Y cada cuaderno contiene los mismos seis componentes:

Componente	Dónde vive	Para qué sirve
Texto	todas las secciones	entender el por qué
Código	`Recorrido del ISS`	ver el qué exacto
Diagramas	`Mapa mental`, `Mapa del backend`, `Flujos`	ver el cómo se conecta
Preguntas	`Evaluación`	comprobar que entendiste
Evaluación	`Evaluación`	practicar y autoevaluarte
GATE	`GATE`	saber si puedes pasar al siguiente ISS

Ruta de aprendizaje

Esta ruta es específica de este ISS: solo hay que comprobar el entorno, no hay nada que construir.

Comprobar Node
    ↓
Comprobar npm
    ↓
Comprobar motor de BD
    ↓
Verificar (GATE)

Fíjate en lo que no aparece: no hay «inicializar proyecto», ni «estructurar carpetas», ni «configurar TypeScript». Todo eso es ISS-01. Aquí solo se comprueba que el terreno está preparado.

Ficha del ISS

Campo	Valor
ISS	ISS-00
Título	Requisitos previos
Objetivo	Entorno listo para el laboratorio
Fase	Fase 0 — Preparación (previa a Fase I: Business)
Tecnología principal	Node.js, npm y motor de base de datos
Depende de	Nada — es el primer ISS
Habilita	ISS-01 — Esqueleto del proyecto
Archivos creados	Ninguno
Archivos parcheados	Ninguno
Componentes incorporados	Ninguno (solo verificación de herramientas)
Verificación principal	`node -v && npm -v` responde sin error
Resultado esperado	Node v20+ (laboratorio: v24.x), npm operativo, motor de BD accesible
GATE	Los tres criterios de aceptación en verde

Qué implementamos AHORA

Únicamente verificamos el entorno. En términos de código: nada. Este es un ISS de reconocimiento: sirve para detectar problemas de instalación antes de que se mezclen con problemas de programación, que es mucho peor diagnosticar.

Qué todavía NO implementamos

Casi todo el curso. En concreto, y para que no haya confusión:

No se implementa aquí	Llega en
`package.json`, scripts `build`/`dev`	ISS-01
Estructura `src/` por features	ISS-01
`tsconfig.json`, TypeScript	ISS-01
Servidor Express (`src/server.ts`, `src/config/index.ts`)	ISS-01
Conexión a la BD desde el código (`sequelize`, `testConnection`)	ISS-02
Cualquier modelo, controller, service o repositorio	ISS-03

Ojo con la trampa habitual: tener MySQL instalado no es lo mismo que tener la conexión configurada en el proyecto. La configuración llega en ISS-02; aquí solo se comprueba que el motor existe y responde.

Mapa mental del ISS

mindmap
  root((ISS-00<br/>Requisitos))
    Objetivo
      Entorno listo
      Detectar fallos de instalación
    Comandos
      node -v
      npm -v
    Conceptos
      Versión mínima
      Motor de BD accesible
    Archivos
      Ninguno
    Verificación
      node -v and npm -v
    GATE
      Checklist en verde

Pregunta que responde: ¿de qué trata este ISS y qué piezas lo componen?

Mapa del backend

Esta representación responde siempre a la misma pregunta: ¿en qué parte del backend estamos?

IMPLEMENTADO HASTA ESTE ISS
───────────────────────────

   (nada todavía)

   🖥️  Entorno local
       ├── Node.js  v20+   ✅
       ├── npm             ✅
       └── Motor de BD     ✅ (instalado y accesible)


OBJETIVO DE ARQUITECTURA
────────────────────────

   HTTP
    ↓
   Routes
    ↓
   Controller
    ↓
   Service
    ↓
   Repository
    ↓
   Model
    ↓
   Sequelize
    ↓
   Base de datos

   ⬜  Todas las capas, sin empezar

Pregunta que responde: ¿qué capas del backend existen ya y cuáles son todavía objetivo?

En este punto el proyecto está antes de la primera línea. La arquitectura de arriba es la meta del curso completo, no una descripción del estado actual.

Árbol de archivos

Estructura antes

(directorio vacío: 
 todavía no existe el proyecto)

Archivos creados / modificados en este ISS

(niguno)

Estructura después

(directorio vacío: 
 todavía no existe el proyecto)

Como ves, el árbol no cambia. Este ISS no toca el sistema de archivos: su único efecto es que tú sabes si tu máquina puede ejecutar lo que viene.

Pregunta que responde: ¿el ISS modifica la estructura del proyecto? — No.

Comandos explicados

El ISS define exactamente dos comandos y una verificación. Los tres son de diagnóstico.

`node -v`

COMANDO
   ↓
node -v
   ↓
QUÉ HACE
   Imprime la versión del intérprete de Node.js instalado.
   ↓
POR QUÉ SE NECESITA
   Express 5, TypeScript 5.9 y ts-node exigen un Node moderno. Con una
   versión antigua el fallo aparecería más tarde, camuflado como un error
   de TypeScript, y sería mucho más difícil de diagnosticar.
   ↓
QUÉ CREA O MODIFICA
   Nada. Es una consulta de solo lectura.
   ↓
RESULTADO ESPERADO
   Un número de versión v20 o superior. En este laboratorio: v24.x
   ↓
CÓMO VERIFICARLO
   El propio comando es la verificación: si imprime v20+, el criterio pasa.

`npm -v`

COMANDO
   ↓
npm -v
   ↓
QUÉ HACE
   Imprime la versión del gestor de paquetes npm.
   ↓
POR QUÉ SE NECESITA
   Todos los ISS instalan dependencias con `npm install`. Si npm no está
   (o está corrupto), el ISS-01 fallará en su primer paso.
   ↓
QUÉ CREA O MODIFICA
   Nada.
   ↓
RESULTADO ESPERADO
   Un número de versión. Cualquier versión que acompañe a Node 20+ sirve.
   ↓
CÓMO VERIFICARLO
   Que el comando responda con un número, no con «command not found».

Verificación conjunta

COMANDO
   ↓
node -v && npm -v
   ↓
QUÉ HACE
   Encadena los dos comandos: `&&` ejecuta el segundo solo si el primero
   tuvo éxito.
   ↓
POR QUÉ SE NECESITA
   Es el criterio de cierre del ISS condensado en una línea: comprueba
   Node y npm de una sola vez y falla en cascada si Node no existe.
   ↓
QUÉ CREA O MODIFICA
   Nada.
   ↓
RESULTADO ESPERADO
   Dos líneas: la versión de Node y la de npm.
   ↓
CÓMO VERIFICARLO
   Salida sin errores y sin «command not found».

El tercer criterio: el motor de base de datos

El ISS lo pide como criterio de aceptación («Motor de BD accesible (MySQL recomendado para el primer sync)») pero no da un comando, porque depende de tu instalación. Lo que debes garantizar es que el motor esté instalado y responda antes de llegar a ISS-02, donde sequelize.sync() intentará conectarse por primera vez.

Pregunta que responde: ¿por qué no hay un comando único para verificar la base de datos?

Recorrido del ISS, paso a paso

A partir de aquí viene el contenido técnico completo del ISS, verbatim: su objetivo, sus criterios de aceptación y sus comandos. Se reproduce sin resumir y sin reformatear; solo se han degradado los encabezados un nivel para que aniden bajo esta sección, y se han ajustado los enlaces relativos para que abran bien desde docs/aprendizaje/.

Fase I: Business — ISS-00 — Requisitos previos

Contexto mínimo (autosuficiente). Si abres este archivo aislado —o lo llevas a otra IA—, esto es lo que hay que saber antes de ejecutarlo. - Proyecto: app-storelab-express-ii — Express 5 + TypeScript + Sequelize, arquitectura por features, Fase I solo Business (sin auth ni roles). - Recorrido obligatorio de una petición: HTTP → Controller → Service → Repository → Model → Sequelize → BD. Ninguna capa se salta a la siguiente. - Diseño de datos (columnas, tipos, FK RESTRICT, índices, transacciones): ../bd-storelab.md, Fase I — Business. - Capas, convenciones y reglas transversales: 00-contexto.md.

Este ISS

Título Requisitos previos

Feature / tabla —

API —

Depende de ninguno (es el primero)

Habilita ISS-01 — Esqueleto del proyecto

Contenido de este ISS

Criterios de aceptación (ISS-00)
Pasos
Verificación del ISS

Objetivo: entorno listo para el laboratorio.
Bloqueado por: ninguno.

Criterios de aceptación (ISS-00)

[ ] node -v muestra v20+ (lab: v24.x)
[ ] npm -v responde
[ ] Motor de BD accesible (MySQL recomendado para el primer sync)

Pasos

node -v
npm -v

Verificación del ISS

node -v && npm -v

Diagnóstico

Síntoma	Causa probable	Solución
`node: command not found`	Node no está instalado o no está en el `PATH`	Instalar Node 20+ (nvm, instalador oficial o el gestor de tu SO); reabrir la terminal
Node responde pero con `v16` o menos	Versión antigua	Cambiar de versión con `nvm install 24 && nvm use 24`
`npm: command not found` con Node instalado	Instalación incompleta de npm (poco habitual)	Reinstalar Node, que incluye npm
El motor de BD no responde	Servicio detenido, puerto ocupado o credenciales	Arrancar el servicio (`systemctl start mysql`, XAMPP, Docker…) y verificar que acepta conexiones
El comando responde bien en una terminal y mal en otra	Distinta configuración de `PATH` entre terminales	Usar la misma terminal (o el mismo perfil de shell) para todo el curso

Pregunta que responde: si algo falla aquí, ¿por dónde empiezo a mirar?

Criterios de aceptación

Los del ISS, textuales:

[ ] node -v muestra v20+ (lab: v24.x)
[ ] npm -v responde
[ ] Motor de BD accesible (MySQL recomendado para el primer sync)

Evaluación

Preguntas de comprensión

¿Por qué el ISS-00 no crea ningún archivo? Porque su función es de reconocimiento: verificar que las herramientas existen y responden. Crear archivos es responsabilidad de ISS-01 (esqueleto del proyecto). Separar «comprobar el entorno» de «construir» hace que un fallo de instalación no se confunda con un fallo de código.
¿Por qué se exige Node v20 o superior y no simplemente «Node instalado»? Porque el stack del curso (Express 5, TypeScript 5.9, ts-node 10.9) usa características que no existen en versiones antiguas. Si la versión fuera baja, los errores aparecerían más adelante y disfrazados de errores de compilación.
Tener MySQL corriendo, ¿basta para dar el ISS-00 por bueno? Sí para el criterio del ISS («motor de BD accesible»), pero conviene no confundirlo: la conexión configurada en el proyecto (variables de entorno, sequelize, sync) es ISS-02. Aquí solo se comprueba que el motor está disponible.
¿Qué significa exactamente && en node -v && npm -v? Es un operador lógico de shell: ejecuta el comando de la derecha solo si el de la izquierda terminó con código de salida 0. Así, si Node no existe, npm ni se intenta, y el error apunta directamente al problema real.
¿Por qué hay un criterio de base de datos si todavía no hay código que se conecte? Porque el primer sync ocurre en ISS-02. Detectar ahora que el motor no responde evita tener que distinguir, más tarde y con código de por medio, si el fallo es de red, de credenciales o del modelo de datos.

Ejercicios

Ejercicio 1 — Auditoría del entorno. Ejecuta los comandos del ISS y anota las tres versiones (Node, npm y motor de BD). Explica, en dos líneas, si tu entorno cumpliría el GATE.

Respuesta razonada

node -v && npm -v

Salida esperada: algo como `v24.20.0` y `11.x.x`. El GATE se cumple si la versión de Node es `v20` o superior y npm responde. Para el motor, lo relevante no es la versión sino que **acepte conexiones**. Un resultado inesperado típico es tener Node 18 o 16 (de una instalación previa del sistema) mientras crees usar la versión de nvm: eso indica que el `PATH` de tu shell no está tomando la versión de nvm.

Ejercicio 2 — Simular un fallo. Abre una terminal con el PATH vacío (env -i bash) y ejecuta node -v. Explica por qué falla y qué lección de diagnóstico deja.

Respuesta razonada

Falla con `command not found` porque `PATH` vacío significa que el shell no sabe en qué directorios buscar ejecutables. La lección: la mayoría de los «no funciona» de un entorno recién montado no son fallos de instalación sino de **configuración del entorno** (`PATH`, servicio detenido, puerto ocupado). Saber distinguirlos ahorra horas.

Ejercicio 3 — Justificar el orden. Explica por qué el curso empieza comprobando el entorno en lugar de escribir directamente npm init -y.

Respuesta razonada

Porque `npm init -y` requiere que npm funcione. Si el entorno está roto, ese comando falla y el error que ves habla de npm, no de la causa real. Comprobar primero aísla la variable: cuando llegues a ISS-01 sabes que el entorno no es el problema, así que cualquier fallo posterior es de código o configuración del proyecto.

GATE

Para cerrar el ISS-00, ejecuta:

node -v && npm -v

Resultado esperado: dos líneas, la versión de Node (v20+, en el laboratorio v24.x) y la de npm, sin ningún error.

Y confirma el tercer criterio por tu cuenta: que el motor de base de datos esté instalado y acepte conexiones.

Checklist de cierre:

[ ] node -v → v20 o superior
[ ] npm -v → responde con un número de versión
[ ] Motor de base de datos instalado y accesible

Con los tres en verde, el ISS-00 está cumplido y puedes pasar al ISS-01 — Esqueleto del proyecto, donde nace el proyecto npm, la estructura por features, TypeScript y el primer servidor Express.

Navegación de la ruta: ↑ Ruta Express · → ISS-00 · 🛠 Construir

Capa	Página	Para qué
🧠 Aprender	esta página	comprender, explicar y relacionar
🛠 Construir	Requisitos previos	ejecutar, programar y verificar
✅ GATE	Cierre de la unidad	condición para pasar al bloque siguiente

Este ISS
Título	Requisitos previos
Feature / tabla	—
API	—
Depende de	ninguno (es el primero)
Habilita	ISS-01 — Esqueleto del proyecto