mkdir servicio-catalogo && cd servicio-catalogo
echo "20" > .nvmrc && nvm use
npm init -y
npm install express mongodb pino pino-http zod @techcorp/comun-http
npm install --save-dev nodemon dotenv

{
  "name": "@techcorp/servicio-catalogo",
  "version": "0.1.0",
  "private": true,
  "engines": { "node": ">=20" },
  "scripts": {
    "start": "node src/servidor.js",
    "dev": "nodemon -r dotenv/config src/servidor.js",
    "test": "jest",
    "semilla": "node -r dotenv/config scripts/semilla.js"
  }
}

servicio-catalogo/
├── src/
│   ├── servidor.js                  # arranque: config, conexiones, listen, SIGTERM
│   ├── app.js                       # compone Express: middlewares, rutas, errores (SIN listen)
│   ├── config.js                    # variables de entorno validadas (versión mínima; se amplía en 04-03)
│   ├── salud.js                     # comprobaciones para crearRutasSalud (cuando hay varias dependencias)
│   ├── rutas/productos.js           # HTTP ⇄ servicio (parsear, validar, responder)
│   ├── servicios/productosServicio.js        # casos de uso: lote por ids, detalle, listado paginado
│   ├── repositorios/productosRepositorio.js  # acceso a MongoDB
│   └── infra/mongo.js               # conexión, ping, cierre
├── scripts/semilla.js               # datos de ejemplo (p-501, p-777)
├── contratos/openapi.yaml           # el contrato de 03-01/03-06 (design-first)
├── .env.ejemplo
└── package.json

// src/infra/mongo.js
const { MongoClient } = require('mongodb');

// Una conexión (en realidad un pool gestionado por el driver) para todo el proceso.
async function conectarMongo({ url, nombreBd, logger }) {
  const cliente = new MongoClient(url, {
    serverSelectionTimeoutMS: 5000,   // si Mongo no aparece en 5 s al arrancar, fallamos rápido
    maxPoolSize: 20                   // conexiones simultáneas máximas de esta réplica
  });
  await cliente.connect();
  logger.info({ nombreBd }, 'conectado a MongoDB');
  const bd = cliente.db(nombreBd);
  return {
    bd,
    ping: () => bd.command({ ping: 1 }),   // comprobación barata para /health/ready
    cerrar: () => cliente.close()          // cierre ordenado: espera a las operaciones en curso
  };
}

module.exports = { conectarMongo };

// src/repositorios/productosRepositorio.js
function crearProductosRepositorio(bd) {
  const coleccion = bd.collection('productos');
  // Proyección: solo los campos que la API pública expone (03-01). El resto no sale de aquí.
  const PROYECCION = { _id: 1, nombre: 1, precio: 1, publicado: 1, categoria: 1 };

  return {
    // Lote por ids: una sola consulta con $in (máx. 100, lo limita la ruta)
    async buscarPorIds(ids) {
      return coleccion.find({ _id: { $in: ids } }, { projection: PROYECCION }).toArray();
    },
    async obtenerPorId(id) {
      return coleccion.findOne({ _id: id }, { projection: PROYECCION });
    },
    // Paginación por cursor: "los `limite` siguientes a `despuesDeId` dentro de `categoria`".
    // Ordenamos por _id (único y estable): el cursor es simplemente el último _id devuelto.
    async listar({ categoria, despuesDeId, limite }) {
      const filtro = {};
      if (categoria) filtro.categoria = categoria;
      if (despuesDeId) filtro._id = { $gt: despuesDeId };
      // limite + 1 para saber si hay página siguiente sin una segunda consulta
      return coleccion.find(filtro, { projection: PROYECCION }).sort({ _id: 1 }).limit(limite + 1).toArray();
    },
    // Índices que este servicio necesita; createIndex es idempotente
    async asegurarIndices() {
      await coleccion.createIndex({ categoria: 1, _id: 1 });
    }
  };
}

module.exports = { crearProductosRepositorio };

// src/servicios/productosServicio.js
const { ErrorNegocio } = require('@techcorp/comun-http');

// Documento de Mongo → representación pública del contrato de 03-01
function aDto(doc) {
  return { id: doc._id, nombre: doc.nombre, precio: doc.precio, moneda: 'EUR', disponible: doc.publicado === true };
}

// Cursor opaco: base64url de un JSON con el último id. Opaco para el cliente, legible para nosotros.
const codificarCursor = (id) => Buffer.from(JSON.stringify({ id })).toString('base64url');
function decodificarCursor(cursor) {
  try { return JSON.parse(Buffer.from(cursor, 'base64url').toString()).id; }
  catch { throw new ErrorNegocio('DATOS_NO_VALIDOS', 'cursor no válido', 422); }
}

function crearProductosServicio({ repositorio }) {
  return {
    // GET /v1/productos?ids=  → { datos, noEncontrados }
    async obtenerLote(ids) {
      const docs = await repositorio.buscarPorIds(ids);
      const encontrados = new Set(docs.map((d) => d._id));
      return { datos: docs.map(aDto), noEncontrados: ids.filter((id) => !encontrados.has(id)) };
    },
    // GET /v1/productos/{id} → dto o PRODUCTO_NO_EXISTE (404)
    async obtener(id) {
      const doc = await repositorio.obtenerPorId(id);
      if (!doc) throw new ErrorNegocio('PRODUCTO_NO_EXISTE', `No existe el producto ${id}`, 404);
      return aDto(doc);
    },
    // GET /v1/productos?categoria=&cursor=&limite= → { datos, paginacion }
    async listar({ categoria, cursor, limite }) {
      const despuesDeId = cursor ? decodificarCursor(cursor) : undefined;
      const docs = await repositorio.listar({ categoria, despuesDeId, limite });
      const haySiguiente = docs.length > limite;
      const pagina = haySiguiente ? docs.slice(0, limite) : docs;
      return {
        datos: pagina.map(aDto),
        paginacion: { limite, haySiguiente, siguienteCursor: haySiguiente ? codificarCursor(pagina.at(-1)._id) : null }
      };
    }
  };
}

module.exports = { crearProductosServicio };

// src/rutas/productos.js
const express = require('express');
const { z } = require('zod');

// Esquemas de entrada (zod). Se validan ANTES de tocar el servicio.
const esquemaLote = z.object({
  ids: z.string().min(1)
        .transform((s) => [...new Set(s.split(',').map((x) => x.trim()).filter(Boolean))])   // "p-501, p-777" → ['p-501','p-777'] sin duplicados
        .refine((arr) => arr.length <= 100, { message: 'máximo 100 ids por petición' })
});
const esquemaListado = z.object({
  categoria: z.string().min(1).max(50).optional(),
  cursor: z.string().max(200).optional(),
  limite: z.coerce.number().int().min(1).max(100).default(20)     // coerce: "20" (texto de la query) → 20
});
const esquemaId = z.object({ id: z.string().regex(/^p-\d+$/, 'id de producto con formato p-<n>') });

function crearRutasProductos({ productosServicio }) {
  const enrutador = express.Router();

  enrutador.get('/v1/productos', async (req, res, next) => {
    try {
      if (req.query.ids !== undefined) {
        // ---- Forma 1: lote por ids (03-01 §5.3) ----
        const { ids } = esquemaLote.parse(req.query);      // lanza ZodError → 400 en el middleware de errores
        const resultado = await productosServicio.obtenerLote(ids);
        return res.set('Cache-Control', 'public, max-age=30').json(resultado);
      }
      // ---- Forma 2: listado paginado por cursor ----
      const filtros = esquemaListado.parse(req.query);
      const resultado = await productosServicio.listar(filtros);
      const enlaces = { self: { href: req.originalUrl } };
      if (resultado.paginacion.haySiguiente) {   // HATEOAS mínimo (03-01): el enlace a la página siguiente ya construido
        enlaces.siguiente = { href: `/v1/productos?${new URLSearchParams({ ...req.query, limite: String(filtros.limite), cursor: resultado.paginacion.siguienteCursor })}` };
      }
      res.set('Cache-Control', 'public, max-age=30').json({ ...resultado, _links: enlaces });
    } catch (err) { next(err); }
  });

  enrutador.get('/v1/productos/:id', async (req, res, next) => {
    try {
      // ---- Forma 3: detalle ----
      const { id } = esquemaId.parse(req.params);
      const producto = await productosServicio.obtener(id);   // lanza PRODUCTO_NO_EXISTE → 404
      res.set('Cache-Control', 'public, max-age=30').json({ ...producto, _links: { self: { href: `/v1/productos/${id}` } } });
    } catch (err) { next(err); }
  });

  return enrutador;
}

module.exports = { crearRutasProductos };

// @techcorp/comun-http — middlewareErrores.js
const { responderProblema } = require('./responderProblema');   // el helper de 03-01

function middlewareErrores({ logger }) {
  return (err, req, res, _next) => {                             // 4 parámetros: así reconoce Express un middleware de error
    if (err.name === 'ZodError') {
      const errores = err.issues.map((i) => ({ campo: i.path.join('.') || '(query)', mensaje: i.message }));
      return responderProblema(res, req, { status: 400, codigo: 'PETICION_INVALIDA', detail: `${errores.length} campo(s) no válido(s)`, errores });
    }
    if (err.codigo && err.status) return responderProblema(res, req, { status: err.status, codigo: err.codigo, detail: err.message }); // ErrorNegocio
    if (err.type === 'entity.parse.failed') return responderProblema(res, req, { status: 400, codigo: 'PETICION_INVALIDA', detail: 'JSON mal formado' });
    (req.log ?? logger).error({ err, requestId: req.id }, 'error no controlado');   // log completo; al cliente, nada interno
    responderProblema(res, req, { status: 500, codigo: 'ERROR_INTERNO', detail: `Error interno. Referencia: ${req.id}` });
  };
}
module.exports = { middlewareErrores };

// src/app.js
const express = require('express');
const pinoHttp = require('pino-http');
const { middlewareRequestId, middlewareErrores, crearRutasSalud, responderProblema } = require('@techcorp/comun-http');
const { crearRutasProductos } = require('./rutas/productos');
const { crearProductosServicio } = require('./servicios/productosServicio');

// Recibe las dependencias ya construidas: así las pruebas pueden pasar un repositorio en memoria
function crearApp({ repositorio, logger, comprobacionesSalud = {} }) {
  const app = express();
  app.disable('x-powered-by');                                   // no anunciamos la tecnología
  app.use(middlewareRequestId());                                // 1. X-Request-Id en req.id y en la respuesta
  app.use(pinoHttp({ logger, genReqId: (req) => req.id }));      // 2. una línea de log por petición, con el mismo id
  app.use(express.json({ limit: '100kb' }));                     // 3. cuerpo JSON (Catálogo aún no lo usa; la plantilla lo trae)
  app.use(crearRutasSalud({ comprobaciones: comprobacionesSalud }));   // 4. /health/live y /health/ready (03-05)

  const productosServicio = crearProductosServicio({ repositorio });
  app.use(crearRutasProductos({ productosServicio }));           // 5. la API

  app.use((req, res) => responderProblema(res, req, { status: 404, codigo: 'RUTA_NO_EXISTE', detail: `No existe ${req.method} ${req.originalUrl}` }));
  app.use(middlewareErrores({ logger }));                        // 6. SIEMPRE el último
  return app;
}

module.exports = { crearApp };

// src/servidor.js
const { crearLogger } = require('@techcorp/comun-http');
const { config } = require('./config');                 // { PUERTO, MONGO_URL, MONGO_BD, LOG_NIVEL } validados; 04-03 lo amplía
const { conectarMongo } = require('./infra/mongo');
const { crearProductosRepositorio } = require('./repositorios/productosRepositorio');
const { crearApp } = require('./app');

async function arrancar() {
  const logger = crearLogger({ servicio: 'servicio-catalogo', nivel: config.LOG_NIVEL });

  // 1. Dependencias externas primero: si Mongo no está, el proceso muere y Kubernetes lo reintentará
  const mongo = await conectarMongo({ url: config.MONGO_URL, nombreBd: config.MONGO_BD, logger });
  const repositorio = crearProductosRepositorio(mongo.bd);
  await repositorio.asegurarIndices();

  // 2. Componer la app con sus dependencias reales
  const app = crearApp({ repositorio, logger, comprobacionesSalud: { mongodb: mongo.ping } });

  // 3. Escuchar
  const servidor = app.listen(config.PUERTO, () => logger.info({ puerto: config.PUERTO }, 'servicio-catalogo escuchando'));
  servidor.keepAliveTimeout = 65000;                    // > timeout del balanceador (60 s típico): evita cortes en keep-alive

  // 4. Apagado ordenado. Kubernetes envía SIGTERM y espera (30 s por defecto) antes de SIGKILL.
  //    crearRutasSalud ya ha puesto /health/ready en 503 al recibir SIGTERM (03-05): dejan de llegar peticiones nuevas.
  const apagar = (senal) => {
    logger.info({ senal }, 'apagado iniciado');
    servidor.close(async () => {                        // deja de aceptar conexiones; espera a las peticiones en curso
      await mongo.cerrar();
      logger.info('apagado completado');
      process.exit(0);
    });
    setTimeout(() => { logger.error('apagado forzado por timeout'); process.exit(1); }, 10000).unref();
  };
  process.on('SIGTERM', () => apagar('SIGTERM'));
  process.on('SIGINT', () => apagar('SIGINT'));         // Ctrl+C en local
}

arrancar().catch((err) => { console.error('no se pudo arrancar', err); process.exit(1); });

docker run -d --name mongo-catalogo -p 27017:27017 mongo:7
cp .env.ejemplo .env     # PUERTO=3001  MONGO_URL=mongodb://localhost:27017  MONGO_BD=catalogo  LOG_NIVEL=debug

// scripts/semilla.js
const { MongoClient } = require('mongodb');

const PRODUCTOS = [
  { _id: 'p-501', productoId: 'p-501', nombre: 'Auriculares BT X200', categoria: 'audio', precio: 59.90, publicado: true,
    descripcion: 'Auriculares inalámbricos con cancelación de ruido', atributos: { color: 'negro', autonomiaHoras: 30, bluetooth: '5.3' } },
  { _id: 'p-777', productoId: 'p-777', nombre: 'Cable USB-C 2 m', categoria: 'accesorios', precio: 9.90, publicado: true,
    descripcion: 'Cable USB-C a USB-C, 100 W', atributos: { longitudMetros: 2, potenciaW: 100 } },
  { _id: 'p-802', productoId: 'p-802', nombre: 'Altavoz portátil S10', categoria: 'audio', precio: 34.50, publicado: false, atributos: { color: 'azul' } }
];

async function main() {
  const cliente = new MongoClient(process.env.MONGO_URL ?? 'mongodb://localhost:27017');
  await cliente.connect();
  const coleccion = cliente.db(process.env.MONGO_BD ?? 'catalogo').collection('productos');
  for (const p of PRODUCTOS) {
    await coleccion.updateOne({ _id: p._id }, { $set: { ...p, actualizadoEn: new Date().toISOString() } }, { upsert: true });
  }
  console.log(`semilla aplicada: ${PRODUCTOS.length} productos`);
  await cliente.close();
}
main().catch((e) => { console.error(e); process.exit(1); });

npm run semilla     # semilla aplicada: 3 productos
npm run dev         # {"level":30,"servicio":"servicio-catalogo","puerto":3001,"msg":"servicio-catalogo escuchando"}

# 1. Lote (el contrato que consumirá Pedidos en 04-04). p-999 no existe → va a noEncontrados, no es 404
curl -s -i "http://localhost:3001/v1/productos?ids=p-501,p-777,p-999"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=30
X-Request-Id: req-01J5A2X7Q0K3

{"datos":[{"id":"p-501","nombre":"Auriculares BT X200","precio":59.9,"moneda":"EUR","disponible":true},
          {"id":"p-777","nombre":"Cable USB-C 2 m","precio":9.9,"moneda":"EUR","disponible":true}],
 "noEncontrados":["p-999"]}

# 2. Detalle inexistente → 404 application/problem+json, codigo PRODUCTO_NO_EXISTE (el JSON del apartado 6)
curl -s -i http://localhost:3001/v1/productos/p-999 | head -2
# 3. Listado paginado: 1 por página, categoría audio (p-501 y p-802; p-802 sale con disponible=false)
curl -s "http://localhost:3001/v1/productos?categoria=audio&limite=1"
# {"datos":[{"id":"p-501",...}],"paginacion":{"limite":1,"haySiguiente":true,"siguienteCursor":"eyJpZCI6InAtNTAxIn0"},"_links":{...,"siguiente":{"href":"/v1/productos?categoria=audio&limite=1&cursor=eyJpZCI6InAtNTAxIn0"}}}
# 4. Validación: limite=500 (o 101 ids) → 400 PETICION_INVALIDA
curl -s "http://localhost:3001/v1/productos?limite=500" | jq .codigo     # "PETICION_INVALIDA"
# 5. Salud: listo con Mongo; 503 sin Mongo
curl -s http://localhost:3001/health/ready      # {"estado":"listo","dependencias":{"mongodb":"ok"}}
docker stop mongo-catalogo && curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3001/health/ready   # 503
docker start mongo-catalogo
# 6. Apagado ordenado: Ctrl+C en la terminal de npm run dev → "apagado iniciado" ... "apagado completado"

async obtenerLote(ids) {
  const docs = await repositorio.buscarPorIds(ids);
  const vendibles = docs.filter((d) => d.publicado === true);
  const encontrados = new Set(vendibles.map((d) => d._id));
  return { datos: vendibles.map(aDto), noEncontrados: ids.filter((id) => !encontrados.has(id)) };
}

// pruebas/dobles/productosRepositorioEnMemoria.js
function crearProductosRepositorioEnMemoria(productos = []) {
  const datos = [...productos];
  return {
    async buscarPorIds(ids) { return datos.filter((p) => ids.includes(p._id)); },
    async obtenerPorId(id) { return datos.find((p) => p._id === id) ?? null; },
    async listar({ categoria, despuesDeId, limite }) {
      return datos.filter((p) => !categoria || p.categoria === categoria).filter((p) => !despuesDeId || p._id > despuesDeId)
                  .sort((a, b) => a._id.localeCompare(b._id)).slice(0, limite + 1);
    },
    async asegurarIndices() {}
  };
}
// uso: ningún cambio en app.js, rutas ni servicio; esa es la recompensa de la inyección de dependencias
const app = crearApp({ repositorio: crearProductosRepositorioEnMemoria([{ _id: 'p-501', nombre: 'Auriculares BT X200', precio: 59.90, publicado: true, categoria: 'audio' }]),
                       logger: require('pino')({ level: 'silent' }) });