GET /v1/cafes?tueste=claro&tueste=medio   →   req.query.tueste === ['claro', 'medio']

app.use((req, res, next) => {
  console.log({
    method: req.method,
    originalUrl: req.originalUrl,
    path: req.path,
    params: req.params,
    query: req.query,
    contentType: req.get('Content-Type'),
    body: req.body,
  });
  next();
});

res.links({
  next: 'http://localhost:3000/v1/cafes?limite=20&desplazamiento=40',
  prev: 'http://localhost:3000/v1/cafes?limite=20&desplazamiento=0',
});

Link: <http://localhost:3000/v1/cafes?limite=20&desplazamiento=40>; rel="next", <http://localhost:3000/v1/cafes?limite=20&desplazamiento=0>; rel="prev"

// src/servicios/mapeadores.js

/** Convierte céntimos enteros a euros con dos decimales. 1450 → 14.5 */
export function centimosAEuros(centimos) {
  return Number((centimos / 100).toFixed(2));
}

/** Convierte euros a céntimos enteros. 14.5 → 1450 */
export function eurosACentimos(euros) {
  // Math.round evita que 14.5 * 100 dé 1449.9999999999998 por coma flotante.
  return Math.round(euros * 100);
}

/**
 * Modelo interno de café → representación pública.
 * Aquí se concentran las reglas de 02-05:
 *  - camelCase en todos los campos
 *  - euros por fuera, céntimos por dentro
 *  - campos siempre presentes, con null si no hay valor
 *  - arrays vacíos como [], nunca null
 *  - _links con self (los cafés no tienen enlaces de acción)
 */
export function cafeARepresentacion(cafe) {
  return {
    id: cafe.id,
    nombre: cafe.nombre,
    origen: cafe.origen,
    tueste: cafe.tueste,
    precioEuros: centimosAEuros(cafe.precioCentimos),
    stock: cafe.stock,
    notasCata: cafe.notasCata ?? [],
    descripcion: cafe.descripcion ?? null,
    fechaCreacion: cafe.fechaCreacion,
    _links: {
      self: { href: `/v1/cafes/${cafe.id}` },
      resenas: { href: `/v1/cafes/${cafe.id}/resenas` },
    },
  };
}

/**
 * Enlaces de acción de un pedido SEGÚN SU ESTADO (02-05, hipermedia
 * selectiva). Es la traducción literal de la tabla del contrato:
 *   pendiente_pago → self, cliente, pagar, anular
 *   pagado         → self, cliente, factura, envio, anular
 *   enviado        → self, cliente, factura, envio, devolver
 */
function enlacesDePedido(pedido) {
  const base = `/v1/pedidos/${pedido.id}`;
  const enlaces = {
    self: { href: base },
    cliente: { href: `/v1/clientes/${pedido.clienteId}` },
  };

  if (pedido.estado === 'pendiente_pago') {
    enlaces.pagar = { href: `${base}/pago`, method: 'POST' };
    enlaces.anular = { href: `${base}/anulacion`, method: 'POST' };
  }

  if (pedido.estado === 'pagado') {
    enlaces.factura = { href: `${base}/factura` };
    enlaces.envio = { href: `${base}/envio` };
    enlaces.anular = { href: `${base}/anulacion`, method: 'POST' };
  }

  if (pedido.estado === 'enviado') {
    enlaces.factura = { href: `${base}/factura` };
    enlaces.envio = { href: `${base}/envio` };
    enlaces.devolver = { href: `${base}/devolucion`, method: 'POST' };
  }

  return enlaces;
}

/** Modelo interno de pedido → representación pública. */
export function pedidoARepresentacion(pedido) {
  return {
    id: pedido.id,
    clienteId: pedido.clienteId,
    estado: pedido.estado,
    // El precio de la línea va CONGELADO: es el que había el día de la
    // compra, no el actual del catálogo (02-05, sección de incrustación).
    lineas: pedido.lineas.map((linea) => ({
      cafeId: linea.cafeId,
      nombre: linea.nombre,
      cantidad: linea.cantidad,
      precioEuros: centimosAEuros(linea.precioCentimos),
    })),
    totalEuros: centimosAEuros(pedido.totalCentimos),
    fechaCreacion: pedido.fechaCreacion,
    fechaPago: pedido.fechaPago ?? null,
    fechaEnvio: pedido.fechaEnvio ?? null,
    _links: enlacesDePedido(pedido),
  };
}

/**
 * Versión reducida para las colecciones: en una lista, cada elemento solo
 * lleva 'self' (02-05: "los elementos dentro de una colección no llevan
 * _links completos, para no multiplicar el peso de la respuesta").
 */
export function aResumenDeColeccion(representacion) {
  return { ...representacion, _links: { self: representacion._links.self } };
}

// src/repositorios/cafes-memoria.js  (versión ampliada)

const cafes = [
  /* ... caf_001 y caf_002 como en 03-02 ... */
];

/** Contador para generar ids nuevos. En 03-05 lo hará la base de datos. */
let siguienteId = 3;

function generarId() {
  return `caf_${String(siguienteId++).padStart(3, '0')}`; // caf_003, caf_004...
}

export const repositorioCafes = {
  /**
   * Busca con filtros, ordenación y paginación.
   * @returns {{elementos: object[], total: number}}
   *   'total' es el número de coincidencias ANTES de paginar: el cliente
   *   necesita saber cuántas hay en total, no cuántas caben en la página.
   */
  buscar(criterios = {}) {
    const {
      origen,
      tueste,
      precioMinCentimos,
      precioMaxCentimos,
      disponible,
      q,
      ordenar = [{ campo: 'id', descendente: false }],
      limite = 20,
      desplazamiento = 0,
    } = criterios;

    let resultado = cafes.filter((cafe) => cafe.activo);

    // --- Filtros (Y lógico entre todos, como fijamos en 02-06) ---
    if (origen !== undefined) {
      resultado = resultado.filter((c) => c.origen.toLowerCase() === origen.toLowerCase());
    }
    if (tueste !== undefined) {
      resultado = resultado.filter((c) => c.tueste === tueste);
    }
    if (precioMinCentimos !== undefined) {
      resultado = resultado.filter((c) => c.precioCentimos >= precioMinCentimos);
    }
    if (precioMaxCentimos !== undefined) {
      resultado = resultado.filter((c) => c.precioCentimos <= precioMaxCentimos);
    }
    if (disponible !== undefined) {
      resultado = resultado.filter((c) => (disponible ? c.stock > 0 : c.stock === 0));
    }
    if (q !== undefined) {
      const termino = q.toLowerCase();
      resultado = resultado.filter(
        (c) =>
          c.nombre.toLowerCase().includes(termino) ||
          c.origen.toLowerCase().includes(termino) ||
          c.notasCata.some((nota) => nota.toLowerCase().includes(termino))
      );
    }

    const total = resultado.length; // ← antes de paginar

    // --- Ordenación multicampo ---
    resultado = [...resultado].sort((a, b) => {
      for (const { campo, descendente } of ordenar) {
        const va = a[campo];
        const vb = b[campo];
        if (va === vb) continue;
        const signo = va > vb ? 1 : -1;
        return descendente ? -signo : signo;
      }
      return 0;
    });

    // --- Paginación ---
    const elementos = resultado.slice(desplazamiento, desplazamiento + limite);

    return { elementos: elementos.map((c) => ({ ...c })), total };
  },

  buscarPorId(id) {
    const cafe = cafes.find((c) => c.id === id && c.activo);
    return cafe ? { ...cafe } : undefined;
  },

  crear(datos) {
    const cafe = {
      id: generarId(),
      ...datos,
      fechaCreacion: new Date().toISOString(),
      activo: true,
    };
    cafes.push(cafe);
    return { ...cafe };
  },

  /** Aplica cambios parciales sobre un café existente. */
  actualizar(id, cambios) {
    const indice = cafes.findIndex((c) => c.id === id && c.activo);
    if (indice === -1) return undefined;
    cafes[indice] = { ...cafes[indice], ...cambios };
    return { ...cafes[indice] };
  },

  /** Borrado LÓGICO (02-03): el registro se conserva, deja de estar activo. */
  borrar(id) {
    const cafe = cafes.find((c) => c.id === id && c.activo);
    if (!cafe) return false;
    cafe.activo = false;
    return true;
  },
};

// src/servicios/cafes.js
import { repositorioCafes } from '../repositorios/cafes-memoria.js';
import { eurosACentimos } from './mapeadores.js';

export const servicioCafes = {
  /** Devuelve una página de cafés y el total de coincidencias. */
  listar(criterios) {
    return repositorioCafes.buscar(criterios);
  },

  /** Devuelve un café o undefined si no existe. */
  obtener(id) {
    return repositorioCafes.buscarPorId(id);
  },

  /** Crea un café. Recibe datos ya validados y en euros. */
  crear(datos) {
    return repositorioCafes.crear({
      nombre: datos.nombre.trim(),
      origen: datos.origen.trim(),
      tueste: datos.tueste,
      precioCentimos: eurosACentimos(datos.precioEuros),
      stock: datos.stock,
      notasCata: datos.notasCata ?? [],
      descripcion: datos.descripcion ?? null,
    });
  },

  /** Reemplaza por completo un café (PUT). undefined si no existe. */
  reemplazar(id, datos) {
    if (!repositorioCafes.buscarPorId(id)) return undefined;
    return repositorioCafes.actualizar(id, {
      nombre: datos.nombre.trim(),
      origen: datos.origen.trim(),
      tueste: datos.tueste,
      precioCentimos: eurosACentimos(datos.precioEuros),
      stock: datos.stock,
      notasCata: datos.notasCata ?? [],
      descripcion: datos.descripcion ?? null,
    });
  },

  /** Modifica parcialmente un café (PATCH). Solo toca lo que llega. */
  modificar(id, cambios) {
    if (!repositorioCafes.buscarPorId(id)) return undefined;

    const parciales = {};
    if (cambios.nombre !== undefined) parciales.nombre = cambios.nombre.trim();
    if (cambios.origen !== undefined) parciales.origen = cambios.origen.trim();
    if (cambios.tueste !== undefined) parciales.tueste = cambios.tueste;
    if (cambios.precioEuros !== undefined) {
      parciales.precioCentimos = eurosACentimos(cambios.precioEuros);
    }
    if (cambios.stock !== undefined) parciales.stock = cambios.stock;
    if (cambios.notasCata !== undefined) parciales.notasCata = cambios.notasCata;
    // En Merge Patch, null significa "borra este campo" (02-03).
    if (cambios.descripcion !== undefined) parciales.descripcion = cambios.descripcion;

    return repositorioCafes.actualizar(id, parciales);
  },

  /** Borrado lógico. Devuelve true si borró algo. */
  borrar(id) {
    return repositorioCafes.borrar(id);
  },
};

// src/controladores/cafes.js
import { servicioCafes } from '../servicios/cafes.js';
import { cafeARepresentacion, aResumenDeColeccion, eurosACentimos } from '../servicios/mapeadores.js';
import { construirCabeceraLink } from './paginacion.js';

/** Campos por los que se permite ordenar. Lista blanca: nada más se admite. */
const CAMPOS_ORDENABLES = new Set(['nombre', 'precioEuros', 'stock', 'fechaCreacion', 'id']);

/** Traducción de campo público a campo interno para ordenar. */
const CAMPO_INTERNO = { precioEuros: 'precioCentimos' };

/**
 * Interpreta el parámetro 'ordenar' de 02-06:
 *   ?ordenar=-precioEuros,nombre  →  precio descendente, luego nombre asc.
 * Siempre se añade 'id' al final como desempate, para que la paginación
 * sea estable: sin desempate, dos cafés al mismo precio pueden cambiar de
 * orden entre la página 1 y la 2, y el cliente ve uno repetido y otro perdido.
 */
function interpretarOrdenar(texto) {
  if (!texto) return [{ campo: 'id', descendente: false }];

  const criterios = [];
  for (const parte of texto.split(',')) {
    const descendente = parte.startsWith('-');
    const campoPublico = descendente ? parte.slice(1) : parte;

    if (!CAMPOS_ORDENABLES.has(campoPublico)) {
      return { error: `El campo de ordenación '${campoPublico}' no existe.` };
    }
    criterios.push({ campo: CAMPO_INTERNO[campoPublico] ?? campoPublico, descendente });
  }

  criterios.push({ campo: 'id', descendente: false });
  return criterios;
}

/** Aplica ?campos=id,nombre sobre una representación ya construida. */
function proyectar(representacion, campos) {
  if (!campos) return representacion;
  const solicitados = new Set(campos.split(','));
  solicitados.add('id'); // el id se devuelve siempre: sin él la respuesta es inútil
  return Object.fromEntries(
    Object.entries(representacion).filter(([clave]) => solicitados.has(clave))
  );
}

export const controladorCafes = {
  /** GET /v1/cafes */
  listar(req, res) {
    const { origen, tueste, precioMin, precioMax, disponible, q, ordenar, campos } = req.query;

    // Paginación con sus valores por defecto y máximos (02-06).
    const limite = req.query.limite === undefined ? 20 : Number(req.query.limite);
    const desplazamiento =
      req.query.desplazamiento === undefined ? 0 : Number(req.query.desplazamiento);

    // Comprobaciones mínimas: en 03-04 las hará el middleware de validación.
    if (!Number.isInteger(limite) || limite < 1 || limite > 100) {
      return res.status(400).json({
        error: {
          codigo: 'parametro_invalido',
          mensaje: "El parámetro 'limite' debe ser un entero entre 1 y 100.",
          detalles: [{ campo: 'limite', codigo: 'fuera_de_rango', mensaje: 'Máximo 100.' }],
        },
      });
    }

    const criteriosOrden = interpretarOrdenar(ordenar);
    if (criteriosOrden.error) {
      return res.status(400).json({
        error: {
          codigo: 'parametro_invalido',
          mensaje: criteriosOrden.error,
          detalles: [{ campo: 'ordenar', codigo: 'valor_desconocido', mensaje: criteriosOrden.error }],
        },
      });
    }

    const { elementos, total } = servicioCafes.listar({
      origen,
      tueste,
      // Los precios llegan en euros y el repositorio habla en céntimos.
      precioMinCentimos: precioMin === undefined ? undefined : eurosACentimos(Number(precioMin)),
      precioMaxCentimos: precioMax === undefined ? undefined : eurosACentimos(Number(precioMax)),
      disponible: disponible === undefined ? undefined : disponible === 'true',
      q,
      ordenar: criteriosOrden,
      limite,
      desplazamiento,
    });

    const enlaces = construirCabeceraLink({ req, limite, desplazamiento, total });
    if (Object.keys(enlaces).length > 0) res.links(enlaces);

    res.status(200).json({
      datos: elementos
        .map(cafeARepresentacion)
        .map(aResumenDeColeccion)
        .map((r) => proyectar(r, campos)),
      total,
    });
  },

  /** GET /v1/cafes/:id */
  obtener(req, res) {
    const cafe = servicioCafes.obtener(req.params.id);
    if (!cafe) return noEncontrado(res, req.params.id);
    res.status(200).json(proyectar(cafeARepresentacion(cafe), req.query.campos));
  },
};

/** Respuesta 404 del catálogo. Provisional: en 03-07 la centraliza ErrorApi. */
function noEncontrado(res, id) {
  return res.status(404).json({
    error: {
      codigo: 'cafe_no_encontrado',
      mensaje: `No existe ningún café con el identificador '${id}'.`,
      detalles: [],
    },
  });
}

// src/rutas/cafes.js
import { Router } from 'express';
import { controladorCafes } from '../controladores/cafes.js';

export const rutasCafes = Router();

rutasCafes.get('/', controladorCafes.listar);
rutasCafes.post('/', controladorCafes.crear);
rutasCafes.get('/:id', controladorCafes.obtener);
rutasCafes.put('/:id', controladorCafes.reemplazar);
rutasCafes.patch('/:id', controladorCafes.modificar);
rutasCafes.delete('/:id', controladorCafes.borrar);

// Así quedará al final del módulo (adelanto):
rutasCafes.post('/', autenticar, exigirRol('empleado'), validar(esquemaCrearCafe), controladorCafes.crear);

# Filtro simple
curl -s "http://localhost:3000/v1/cafes?origen=Colombia" | jq '.total'

1

# Filtros combinados (Y lógico) y rango de precio
curl -s "http://localhost:3000/v1/cafes?tueste=claro&precioMax=15" | jq '.datos[].nombre'

"Etiopía Yirgacheffe"

# Búsqueda de texto: mira nombre, origen y notas de cata
curl -s "http://localhost:3000/v1/cafes?q=chocolate" | jq '.datos[].nombre'

"Colombia Huila"

curl -s "http://localhost:3000/v1/cafes?ordenar=-precioEuros" | jq '.datos[] | {nombre, precioEuros}'

{ "nombre": "Etiopía Yirgacheffe", "precioEuros": 14.5 }
{ "nombre": "Colombia Huila", "precioEuros": 12.9 }

# Campo inexistente → 400 del catálogo, no se ignora en silencio
curl -s "http://localhost:3000/v1/cafes?ordenar=color" | jq .error

{
  "codigo": "parametro_invalido",
  "mensaje": "El campo de ordenación 'color' no existe.",
  "detalles": [
    { "campo": "ordenar", "codigo": "valor_desconocido", "mensaje": "El campo de ordenación 'color' no existe." }
  ]
}

// src/controladores/paginacion.js

/**
 * Construye las relaciones de la cabecera Link (RFC 8288) para una
 * colección paginada por offset, CONSERVANDO todos los filtros de la
 * petición original: sin eso, el cliente que sigue 'next' pierde el
 * filtro y recibe resultados que no había pedido.
 */
export function construirCabeceraLink({ req, limite, desplazamiento, total }) {
  // Reconstruimos la URL absoluta de la petición actual.
  const url = new URL(req.originalUrl, `${req.protocol}://${req.get('host')}`);

  /** Devuelve la URL actual con otro desplazamiento. */
  const conDesplazamiento = (valor) => {
    const copia = new URL(url);
    copia.searchParams.set('limite', String(limite));
    copia.searchParams.set('desplazamiento', String(valor));
    return copia.toString();
  };

  const enlaces = {};
  const ultimoDesplazamiento = Math.max(0, Math.floor((total - 1) / limite) * limite);

  if (desplazamiento + limite < total) {
    enlaces.next = conDesplazamiento(desplazamiento + limite);
  }
  if (desplazamiento > 0) {
    enlaces.prev = conDesplazamiento(Math.max(0, desplazamiento - limite));
  }
  if (total > limite) {
    enlaces.first = conDesplazamiento(0);
    enlaces.last = conDesplazamiento(ultimoDesplazamiento);
  }

  return enlaces;
}

curl -i -s "http://localhost:3000/v1/cafes?limite=1&ordenar=nombre" | grep -i "^link"

Link: <http://localhost:3000/v1/cafes?limite=1&ordenar=nombre&desplazamiento=1>; rel="next", <http://localhost:3000/v1/cafes?limite=1&ordenar=nombre&desplazamiento=0>; rel="first", <http://localhost:3000/v1/cafes?limite=1&ordenar=nombre&desplazamiento=1>; rel="last"

curl -s "http://localhost:3000/v1/cafes?campos=nombre,precioEuros" | jq '.datos[0]'

{ "id": "caf_001", "nombre": "Etiopía Yirgacheffe", "precioEuros": 14.5 }

// src/controladores/cafes.js  (añadir al objeto controladorCafes)

/** POST /v1/cafes */
crear(req, res) {
  const datos = req.body;

  // Comprobación provisional. En 03-04 la sustituye validar(esquemaCrearCafe).
  const obligatorios = ['nombre', 'origen', 'tueste', 'precioEuros', 'stock'];
  const faltantes = obligatorios.filter((campo) => datos?.[campo] === undefined);
  if (faltantes.length > 0) {
    return res.status(400).json({
      error: {
        codigo: 'datos_invalidos',
        mensaje: 'Faltan campos obligatorios.',
        detalles: faltantes.map((campo) => ({
          campo,
          codigo: 'requerido',
          mensaje: `El campo '${campo}' es obligatorio.`,
        })),
      },
    });
  }

  const cafe = servicioCafes.crear(datos);
  const representacion = cafeARepresentacion(cafe);

  // La cabecera Location es OBLIGATORIA en toda creación (02-04).
  res.set('Location', `/v1/cafes/${cafe.id}`);
  res.status(201).json(representacion);
},

curl -i -s -X POST http://localhost:3000/v1/cafes \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Kenia Nyeri",
    "origen": "Kenia",
    "tueste": "medio",
    "precioEuros": 16.75,
    "stock": 40,
    "notasCata": ["grosella", "tomate", "cítrico"]
  }'

HTTP/1.1 201 Created
Location: /v1/cafes/caf_003
Content-Type: application/json; charset=utf-8

{"id":"caf_003","nombre":"Kenia Nyeri","origen":"Kenia","tueste":"medio","precioEuros":16.75,"stock":40,"notasCata":["grosella","tomate","cítrico"],"descripcion":null,"fechaCreacion":"2026-03-14T10:41:22.113Z","_links":{"self":{"href":"/v1/cafes/caf_003"},"resenas":{"href":"/v1/cafes/caf_003/resenas"}}}

// src/controladores/cafes.js  (continuación)

/** PUT /v1/cafes/:id — reemplazo completo */
reemplazar(req, res) {
  const cafe = servicioCafes.reemplazar(req.params.id, req.body);
  if (!cafe) return noEncontrado(res, req.params.id);
  res.status(200).json(cafeARepresentacion(cafe));
},

/** PATCH /v1/cafes/:id — modificación parcial con Merge Patch */
modificar(req, res) {
  const tipo = req.get('Content-Type') ?? '';

  // El contrato de 02-03 admite SOLO merge-patch (y application/json por
  // comodidad). JSON Patch (application/json-patch+json) se rechaza con
  // 415 y la cabecera Accept-Patch que dice qué SÍ se admite.
  const admitidos = ['application/merge-patch+json', 'application/json'];
  const esAdmitido = admitidos.some((t) => tipo.startsWith(t));

  if (!esAdmitido) {
    res.set('Accept-Patch', 'application/merge-patch+json');
    return res.status(415).json({
      error: {
        codigo: 'formato_no_soportado',
        mensaje: `El tipo '${tipo}' no se admite en PATCH. Usa application/merge-patch+json.`,
        detalles: [],
      },
    });
  }

  const cafe = servicioCafes.modificar(req.params.id, req.body);
  if (!cafe) return noEncontrado(res, req.params.id);
  res.status(200).json(cafeARepresentacion(cafe));
},

# PATCH correcto: solo se toca el stock
curl -s -X PATCH http://localhost:3000/v1/cafes/caf_001 \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"stock": 95}' | jq '{nombre, stock, precioEuros}'

{ "nombre": "Etiopía Yirgacheffe", "stock": 95, "precioEuros": 14.5 }

# PATCH con JSON Patch: 415 + Accept-Patch
curl -i -s -X PATCH http://localhost:3000/v1/cafes/caf_001 \
  -H "Content-Type: application/json-patch+json" \
  -d '[{"op":"replace","path":"/stock","value":95}]' | head -5

HTTP/1.1 415 Unsupported Media Type
Accept-Patch: application/merge-patch+json
Content-Type: application/json; charset=utf-8

// src/controladores/cafes.js  (continuación)

/** DELETE /v1/cafes/:id — borrado lógico */
borrar(req, res) {
  const borrado = servicioCafes.borrar(req.params.id);
  if (!borrado) return noEncontrado(res, req.params.id);

  // 204 No Content: sin cuerpo. Ni {} ni null: NADA.
  res.status(204).end();
},

curl -i -s -X DELETE http://localhost:3000/v1/cafes/caf_003 | head -2
curl -s http://localhost:3000/v1/cafes/caf_003 | jq .error.codigo

HTTP/1.1 204 No Content

"cafe_no_encontrado"

// src/repositorios/pedidos-memoria.js

const pedidos = [
  {
    id: 'ped_5001',
    clienteId: 'cli_842',
    estado: 'pendiente_pago',
    lineas: [
      { cafeId: 'caf_001', nombre: 'Etiopía Yirgacheffe', cantidad: 2, precioCentimos: 1450 },
    ],
    totalCentimos: 2900, // 29,00 € — la suma de las líneas, en céntimos
    fechaCreacion: '2026-03-14T10:30:00Z',
    fechaPago: null,
    fechaEnvio: null,
  },
];

export const repositorioPedidos = {
  buscar({ clienteId, estado, limite = 20, desplazamiento = 0 } = {}) {
    let resultado = [...pedidos];
    if (clienteId !== undefined) resultado = resultado.filter((p) => p.clienteId === clienteId);
    if (estado !== undefined) resultado = resultado.filter((p) => p.estado === estado);

    const total = resultado.length;
    // Orden por defecto de 02-06: los más recientes primero.
    resultado.sort((a, b) => b.fechaCreacion.localeCompare(a.fechaCreacion) || a.id.localeCompare(b.id));

    return {
      elementos: resultado.slice(desplazamiento, desplazamiento + limite).map((p) => ({ ...p })),
      total,
    };
  },

  buscarPorId(id) {
    const pedido = pedidos.find((p) => p.id === id);
    return pedido ? { ...pedido } : undefined;
  },
};

// src/servicios/pedidos.js
import { repositorioPedidos } from '../repositorios/pedidos-memoria.js';

export const servicioPedidos = {
  listar(criterios) {
    return repositorioPedidos.buscar(criterios);
  },
  obtener(id) {
    return repositorioPedidos.buscarPorId(id);
  },
};

// src/controladores/pedidos.js
import { servicioPedidos } from '../servicios/pedidos.js';
import { pedidoARepresentacion, aResumenDeColeccion } from '../servicios/mapeadores.js';
import { construirCabeceraLink } from './paginacion.js';

export const controladorPedidos = {
  /** GET /v1/pedidos */
  listar(req, res) {
    const limite = req.query.limite === undefined ? 20 : Number(req.query.limite);
    const desplazamiento =
      req.query.desplazamiento === undefined ? 0 : Number(req.query.desplazamiento);

    const { elementos, total } = servicioPedidos.listar({
      clienteId: req.query.clienteId,
      estado: req.query.estado,
      limite,
      desplazamiento,
    });

    const enlaces = construirCabeceraLink({ req, limite, desplazamiento, total });
    if (Object.keys(enlaces).length > 0) res.links(enlaces);

    res.status(200).json({
      datos: elementos.map(pedidoARepresentacion).map(aResumenDeColeccion),
      total,
    });
  },

  /** GET /v1/pedidos/:id */
  obtener(req, res) {
    const pedido = servicioPedidos.obtener(req.params.id);
    if (!pedido) {
      return res.status(404).json({
        error: {
          codigo: 'pedido_no_encontrado',
          mensaje: `No existe ningún pedido con el identificador '${req.params.id}'.`,
          detalles: [],
        },
      });
    }
    res.status(200).json(pedidoARepresentacion(pedido));
  },
};

// src/rutas/pedidos.js
import { Router } from 'express';
import { controladorPedidos } from '../controladores/pedidos.js';

export const rutasPedidos = Router();

rutasPedidos.get('/', controladorPedidos.listar);
rutasPedidos.get('/:id', controladorPedidos.obtener);
// POST /v1/pedidos llega en 03-04 (validación) y 03-05 (transacción con stock).

import { rutasPedidos } from './pedidos.js';
rutasV1.use('/pedidos', rutasPedidos);

curl -s http://localhost:3000/v1/pedidos/ped_5001 | jq '{estado, totalEuros, _links}'

{
  "estado": "pendiente_pago",
  "totalEuros": 29,
  "_links": {
    "self": { "href": "/v1/pedidos/ped_5001" },
    "cliente": { "href": "/v1/clientes/cli_842" },
    "pagar": { "href": "/v1/pedidos/ped_5001/pago", "method": "POST" },
    "anular": { "href": "/v1/pedidos/ped_5001/anulacion", "method": "POST" }
  }
}

// Manejador asíncrono que falla. Express 4 NO captura este error.
rutasCafes.get('/:id', async (req, res) => {
  const cafe = await servicioCafes.obtener(req.params.id);
  if (!cafe) throw new Error('no encontrado'); // ← se pierde
  res.json(cafeARepresentacion(cafe));
});

rutasCafes.get('/:id', (req, res) => {
  throw new Error('esto sí lo captura Express'); // → 500 con la página HTML por defecto
});

/** Envuelve un manejador async y encamina cualquier rechazo hacia next(). */
export function asincrono(fn) {
  return (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
}

// Uso:
rutasCafes.get('/:id', asincrono(controladorCafes.obtener));

let disponible;
if (req.query.disponible !== undefined) {
  if (req.query.disponible !== 'true' && req.query.disponible !== 'false') {
    return res.status(400).json({
      error: {
        codigo: 'parametro_invalido',
        mensaje: "El parámetro 'disponible' solo admite 'true' o 'false'.",
        detalles: [
          {
            campo: 'disponible',
            codigo: 'valor_invalido',
            mensaje: `Se recibió '${req.query.disponible}'.`,
          },
        ],
      },
    });
  }
  disponible = req.query.disponible === 'true';
}

criterios.push({ campo: 'id', descendente: false });

// src/controladores/clientes.js
import { servicioClientes } from '../servicios/clientes.js';
import { servicioPedidos } from '../servicios/pedidos.js';
import { pedidoARepresentacion, aResumenDeColeccion } from '../servicios/mapeadores.js';
import { construirCabeceraLink } from './paginacion.js';

export const controladorClientes = {
  /** GET /v1/clientes/:id/pedidos */
  listarPedidos(req, res) {
    // Primero, que el cliente exista: si no, 404 del cliente, no lista vacía.
    if (!servicioClientes.obtener(req.params.id)) {
      return res.status(404).json({
        error: {
          codigo: 'cliente_no_encontrado',
          mensaje: `No existe ningún cliente con el identificador '${req.params.id}'.`,
          detalles: [],
        },
      });
    }

    const limite = req.query.limite === undefined ? 20 : Number(req.query.limite);
    const desplazamiento =
      req.query.desplazamiento === undefined ? 0 : Number(req.query.desplazamiento);

    const { elementos, total } = servicioPedidos.listar({
      clienteId: req.params.id, // ← el id viene de la RUTA, no de la query
      estado: req.query.estado,
      limite,
      desplazamiento,
    });

    const enlaces = construirCabeceraLink({ req, limite, desplazamiento, total });
    if (Object.keys(enlaces).length > 0) res.links(enlaces);

    res.status(200).json({
      datos: elementos.map(pedidoARepresentacion).map(aResumenDeColeccion),
      total,
    });
  },
};