GET /v1/cafes?torrefaccio=clar&torrefaccio=mitja   →   req.query.torrefaccio === ['clar', 'mitja']

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?limit=20&desplacament=40',
  prev: 'http://localhost:3000/v1/cafes?limit=20&desplacament=0',
});

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

// src/serveis/mapejadors.js

/** Converteix cèntims enters a euros amb dos decimals. 1450 → 14.5 */
export function centimsAEuros(centims) {
  return Number((centims / 100).toFixed(2));
}

/** Converteix euros a cèntims enters. 14.5 → 1450 */
export function eurosACentims(euros) {
  // Math.round evita que 14.5 * 100 doni 1449.9999999999998 per coma flotant.
  return Math.round(euros * 100);
}

/**
 * Model intern de cafè → representació pública.
 * Aquí es concentren les regles de 02-05:
 *  - camelCase a tots els camps
 *  - euros per fora, cèntims per dins
 *  - camps sempre presents, amb null si no hi ha valor
 *  - arrays buits com a [], mai null
 *  - _links amb self (els cafès no tenen enllaços d'acció)
 */
export function cafeARepresentacio(cafe) {
  return {
    id: cafe.id,
    nom: cafe.nom,
    origen: cafe.origen,
    torrefaccio: cafe.torrefaccio,
    preuEuros: centimsAEuros(cafe.preuCentims),
    estoc: cafe.estoc,
    notesTast: cafe.notesTast ?? [],
    descripcio: cafe.descripcio ?? null,
    dataCreacio: cafe.dataCreacio,
    _links: {
      self: { href: `/v1/cafes/${cafe.id}` },
      ressenyes: { href: `/v1/cafes/${cafe.id}/ressenyes` },
    },
  };
}

/**
 * Enllaços d'acció d'una comanda SEGONS EL SEU ESTAT (02-05, hipermèdia
 * selectiva). És la traducció literal de la taula del contracte:
 *   pendent_pagament → self, client, pagar, anullar
 *   pagat            → self, client, factura, enviament, anullar
 *   enviat           → self, client, factura, enviament, retornar
 */
function enllacosDeComanda(comanda) {
  const base = `/v1/comandes/${comanda.id}`;
  const enllacos = {
    self: { href: base },
    client: { href: `/v1/clients/${comanda.clientId}` },
  };

  if (comanda.estat === 'pendent_pagament') {
    enllacos.pagar = { href: `${base}/pagament`, method: 'POST' };
    enllacos.anullar = { href: `${base}/anullacio`, method: 'POST' };
  }

  if (comanda.estat === 'pagat') {
    enllacos.factura = { href: `${base}/factura` };
    enllacos.enviament = { href: `${base}/enviament` };
    enllacos.anullar = { href: `${base}/anullacio`, method: 'POST' };
  }

  if (comanda.estat === 'enviat') {
    enllacos.factura = { href: `${base}/factura` };
    enllacos.enviament = { href: `${base}/enviament` };
    enllacos.retornar = { href: `${base}/devolucio`, method: 'POST' };
  }

  return enllacos;
}

/** Model intern de comanda → representació pública. */
export function comandaARepresentacio(comanda) {
  return {
    id: comanda.id,
    clientId: comanda.clientId,
    estat: comanda.estat,
    // El preu de la línia va CONGELAT: és el que hi havia el dia de la
    // compra, no l'actual del catàleg (02-05, secció d'incrustació).
    linies: comanda.linies.map((linia) => ({
      cafeId: linia.cafeId,
      nom: linia.nom,
      quantitat: linia.quantitat,
      preuEuros: centimsAEuros(linia.preuCentims),
    })),
    totalEuros: centimsAEuros(comanda.totalCentims),
    dataCreacio: comanda.dataCreacio,
    dataPagament: comanda.dataPagament ?? null,
    dataEnviament: comanda.dataEnviament ?? null,
    _links: enllacosDeComanda(comanda),
  };
}

/**
 * Versió reduïda per a les col·leccions: en una llista, cada element només
 * porta 'self' (02-05: "els elements dins d'una col·lecció no porten
 * _links complets, per no multiplicar el pes de la resposta").
 */
export function aResumDeColeccio(representacio) {
  return { ...representacio, _links: { self: representacio._links.self } };
}

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

const cafes = [
  /* ... caf_001 i caf_002 com a 03-02 ... */
];

/** Comptador per generar ids nous. A 03-05 ho farà la base de dades. */
let seguentId = 3;

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

export const repositoriCafes = {
  /**
   * Cerca amb filtres, ordenació i paginació.
   * @returns {{elements: object[], total: number}}
   *   'total' és el nombre de coincidències ABANS de paginar: el client
   *   necessita saber quantes n'hi ha en total, no quantes caben a la pàgina.
   */
  buscar(criteris = {}) {
    const {
      origen,
      torrefaccio,
      preuMinCentims,
      preuMaxCentims,
      disponible,
      q,
      ordenar = [{ camp: 'id', descendent: false }],
      limit = 20,
      desplacament = 0,
    } = criteris;

    let resultat = cafes.filter((cafe) => cafe.actiu);

    // --- Filtres (I lògic entre tots, com vam fixar a 02-06) ---
    if (origen !== undefined) {
      resultat = resultat.filter((c) => c.origen.toLowerCase() === origen.toLowerCase());
    }
    if (torrefaccio !== undefined) {
      resultat = resultat.filter((c) => c.torrefaccio === torrefaccio);
    }
    if (preuMinCentims !== undefined) {
      resultat = resultat.filter((c) => c.preuCentims >= preuMinCentims);
    }
    if (preuMaxCentims !== undefined) {
      resultat = resultat.filter((c) => c.preuCentims <= preuMaxCentims);
    }
    if (disponible !== undefined) {
      resultat = resultat.filter((c) => (disponible ? c.estoc > 0 : c.estoc === 0));
    }
    if (q !== undefined) {
      const terme = q.toLowerCase();
      resultat = resultat.filter(
        (c) =>
          c.nom.toLowerCase().includes(terme) ||
          c.origen.toLowerCase().includes(terme) ||
          c.notesTast.some((nota) => nota.toLowerCase().includes(terme))
      );
    }

    const total = resultat.length; // ← abans de paginar

    // --- Ordenació multicamp ---
    resultat = [...resultat].sort((a, b) => {
      for (const { camp, descendent } of ordenar) {
        const va = a[camp];
        const vb = b[camp];
        if (va === vb) continue;
        const signe = va > vb ? 1 : -1;
        return descendent ? -signe : signe;
      }
      return 0;
    });

    // --- Paginació ---
    const elements = resultat.slice(desplacament, desplacament + limit);

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

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

  crear(dades) {
    const cafe = {
      id: generarId(),
      ...dades,
      dataCreacio: new Date().toISOString(),
      actiu: true,
    };
    cafes.push(cafe);
    return { ...cafe };
  },

  /** Aplica canvis parcials sobre un cafè existent. */
  actualitzar(id, canvis) {
    const index = cafes.findIndex((c) => c.id === id && c.actiu);
    if (index === -1) return undefined;
    cafes[index] = { ...cafes[index], ...canvis };
    return { ...cafes[index] };
  },

  /** Esborrat LÒGIC (02-03): el registre es conserva, deixa d'estar actiu. */
  esborrar(id) {
    const cafe = cafes.find((c) => c.id === id && c.actiu);
    if (!cafe) return false;
    cafe.actiu = false;
    return true;
  },
};

// src/serveis/cafes.js
import { repositoriCafes } from '../repositoris/cafes-memoria.js';
import { eurosACentims } from './mapejadors.js';

export const serveiCafes = {
  /** Retorna una pàgina de cafès i el total de coincidències. */
  llistar(criteris) {
    return repositoriCafes.buscar(criteris);
  },

  /** Retorna un cafè o undefined si no existeix. */
  obtenir(id) {
    return repositoriCafes.buscarPerId(id);
  },

  /** Crea un cafè. Rep dades ja validades i en euros. */
  crear(dades) {
    return repositoriCafes.crear({
      nom: dades.nom.trim(),
      origen: dades.origen.trim(),
      torrefaccio: dades.torrefaccio,
      preuCentims: eurosACentims(dades.preuEuros),
      estoc: dades.estoc,
      notesTast: dades.notesTast ?? [],
      descripcio: dades.descripcio ?? null,
    });
  },

  /** Reemplaça completament un cafè (PUT). undefined si no existeix. */
  reemplacar(id, dades) {
    if (!repositoriCafes.buscarPerId(id)) return undefined;
    return repositoriCafes.actualitzar(id, {
      nom: dades.nom.trim(),
      origen: dades.origen.trim(),
      torrefaccio: dades.torrefaccio,
      preuCentims: eurosACentims(dades.preuEuros),
      estoc: dades.estoc,
      notesTast: dades.notesTast ?? [],
      descripcio: dades.descripcio ?? null,
    });
  },

  /** Modifica parcialment un cafè (PATCH). Només toca el que arriba. */
  modificar(id, canvis) {
    if (!repositoriCafes.buscarPerId(id)) return undefined;

    const parcials = {};
    if (canvis.nom !== undefined) parcials.nom = canvis.nom.trim();
    if (canvis.origen !== undefined) parcials.origen = canvis.origen.trim();
    if (canvis.torrefaccio !== undefined) parcials.torrefaccio = canvis.torrefaccio;
    if (canvis.preuEuros !== undefined) {
      parcials.preuCentims = eurosACentims(canvis.preuEuros);
    }
    if (canvis.estoc !== undefined) parcials.estoc = canvis.estoc;
    if (canvis.notesTast !== undefined) parcials.notesTast = canvis.notesTast;
    // A Merge Patch, null significa "esborra aquest camp" (02-03).
    if (canvis.descripcio !== undefined) parcials.descripcio = canvis.descripcio;

    return repositoriCafes.actualitzar(id, parcials);
  },

  /** Esborrat lògic. Retorna true si ha esborrat alguna cosa. */
  esborrar(id) {
    return repositoriCafes.esborrar(id);
  },
};

// src/controladors/cafes.js
import { serveiCafes } from '../serveis/cafes.js';
import { cafeARepresentacio, aResumDeColeccio, eurosACentims } from '../serveis/mapejadors.js';
import { construirCapcaleraLink } from './paginacio.js';

/** Camps pels quals es permet ordenar. Llista blanca: res més s'admet. */
const CAMPS_ORDENABLES = new Set(['nom', 'preuEuros', 'estoc', 'dataCreacio', 'id']);

/** Traducció de camp públic a camp intern per ordenar. */
const CAMP_INTERN = { preuEuros: 'preuCentims' };

/**
 * Interpreta el paràmetre 'ordenar' de 02-06:
 *   ?ordenar=-preuEuros,nom  →  preu descendent, després nom ascendent.
 * Sempre s'hi afegeix 'id' al final com a desempat, perquè la paginació
 * sigui estable: sense desempat, dos cafès al mateix preu poden canviar
 * d'ordre entre la pàgina 1 i la 2, i el client en veu un de repetit i un de perdut.
 */
function interpretarOrdenar(text) {
  if (!text) return [{ camp: 'id', descendent: false }];

  const criteris = [];
  for (const part of text.split(',')) {
    const descendent = part.startsWith('-');
    const campPublic = descendent ? part.slice(1) : part;

    if (!CAMPS_ORDENABLES.has(campPublic)) {
      return { error: `El camp d'ordenació '${campPublic}' no existeix.` };
    }
    criteris.push({ camp: CAMP_INTERN[campPublic] ?? campPublic, descendent });
  }

  criteris.push({ camp: 'id', descendent: false });
  return criteris;
}

/** Aplica ?camps=id,nom sobre una representació ja construïda. */
function projectar(representacio, camps) {
  if (!camps) return representacio;
  const demanats = new Set(camps.split(','));
  demanats.add('id'); // l'id es retorna sempre: sense ell la resposta és inútil
  return Object.fromEntries(
    Object.entries(representacio).filter(([clau]) => demanats.has(clau))
  );
}

export const controladorCafes = {
  /** GET /v1/cafes */
  llistar(req, res) {
    const { origen, torrefaccio, preuMin, preuMax, disponible, q, ordenar, camps } = req.query;

    // Paginació amb els seus valors per defecte i màxims (02-06).
    const limit = req.query.limit === undefined ? 20 : Number(req.query.limit);
    const desplacament =
      req.query.desplacament === undefined ? 0 : Number(req.query.desplacament);

    // Comprovacions mínimes: a 03-04 les farà el middleware de validació.
    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
      return res.status(400).json({
        error: {
          codi: 'parametre_invalid',
          missatge: "El paràmetre 'limit' ha de ser un enter entre 1 i 100.",
          detalls: [{ camp: 'limit', codi: 'fora_de_rang', missatge: 'Màxim 100.' }],
        },
      });
    }

    const criterisOrdre = interpretarOrdenar(ordenar);
    if (criterisOrdre.error) {
      return res.status(400).json({
        error: {
          codi: 'parametre_invalid',
          missatge: criterisOrdre.error,
          detalls: [{ camp: 'ordenar', codi: 'valor_desconegut', missatge: criterisOrdre.error }],
        },
      });
    }

    const { elements, total } = serveiCafes.llistar({
      origen,
      torrefaccio,
      // Els preus arriben en euros i el repositori parla en cèntims.
      preuMinCentims: preuMin === undefined ? undefined : eurosACentims(Number(preuMin)),
      preuMaxCentims: preuMax === undefined ? undefined : eurosACentims(Number(preuMax)),
      disponible: disponible === undefined ? undefined : disponible === 'true',
      q,
      ordenar: criterisOrdre,
      limit,
      desplacament,
    });

    const enllacos = construirCapcaleraLink({ req, limit, desplacament, total });
    if (Object.keys(enllacos).length > 0) res.links(enllacos);

    res.status(200).json({
      dades: elements
        .map(cafeARepresentacio)
        .map(aResumDeColeccio)
        .map((r) => projectar(r, camps)),
      total,
    });
  },

  /** GET /v1/cafes/:id */
  obtenir(req, res) {
    const cafe = serveiCafes.obtenir(req.params.id);
    if (!cafe) return noTrobat(res, req.params.id);
    res.status(200).json(projectar(cafeARepresentacio(cafe), req.query.camps));
  },
};

/** Resposta 404 del catàleg. Provisional: a 03-07 la centralitza ErrorApi. */
function noTrobat(res, id) {
  return res.status(404).json({
    error: {
      codi: 'cafe_no_trobat',
      missatge: `No existeix cap cafè amb l'identificador '${id}'.`,
      detalls: [],
    },
  });
}

// src/rutes/cafes.js
import { Router } from 'express';
import { controladorCafes } from '../controladors/cafes.js';

export const rutesCafes = Router();

rutesCafes.get('/', controladorCafes.llistar);
rutesCafes.post('/', controladorCafes.crear);
rutesCafes.get('/:id', controladorCafes.obtenir);
rutesCafes.put('/:id', controladorCafes.reemplacar);
rutesCafes.patch('/:id', controladorCafes.modificar);
rutesCafes.delete('/:id', controladorCafes.esborrar);

// Així quedarà al final del mòdul (avançament):
rutesCafes.post('/', autenticar, exigirRol('empleat'), validar(esquemaCrearCafe), controladorCafes.crear);

# Filtre simple
curl -s "http://localhost:3000/v1/cafes?origen=Colòmbia" | jq '.total'

1

# Filtres combinats (I lògic) i rang de preu
curl -s "http://localhost:3000/v1/cafes?torrefaccio=clar&preuMax=15" | jq '.dades[].nom'

"Etiòpia Yirgacheffe"

# Cerca de text: mira nom, origen i notes de tast
curl -s "http://localhost:3000/v1/cafes?q=xocolata" | jq '.dades[].nom'

"Colòmbia Huila"

curl -s "http://localhost:3000/v1/cafes?ordenar=-preuEuros" | jq '.dades[] | {nom, preuEuros}'

{ "nom": "Etiòpia Yirgacheffe", "preuEuros": 14.5 }
{ "nom": "Colòmbia Huila", "preuEuros": 12.9 }

# Camp inexistent → 400 del catàleg, no s'ignora en silenci
curl -s "http://localhost:3000/v1/cafes?ordenar=color" | jq .error

{
  "codi": "parametre_invalid",
  "missatge": "El camp d'ordenació 'color' no existeix.",
  "detalls": [
    { "camp": "ordenar", "codi": "valor_desconegut", "missatge": "El camp d'ordenació 'color' no existeix." }
  ]
}

// src/controladors/paginacio.js

/**
 * Construeix les relacions de la capçalera Link (RFC 8288) per a una
 * col·lecció paginada per desplaçament, CONSERVANT tots els filtres de la
 * petició original: sense això, el client que segueix 'next' perd el
 * filtre i rep resultats que no havia demanat.
 */
export function construirCapcaleraLink({ req, limit, desplacament, total }) {
  // Reconstruïm la URL absoluta de la petició actual.
  const url = new URL(req.originalUrl, `${req.protocol}://${req.get('host')}`);

  /** Retorna la URL actual amb un altre desplaçament. */
  const ambDesplacament = (valor) => {
    const copia = new URL(url);
    copia.searchParams.set('limit', String(limit));
    copia.searchParams.set('desplacament', String(valor));
    return copia.toString();
  };

  const enllacos = {};
  const ultimDesplacament = Math.max(0, Math.floor((total - 1) / limit) * limit);

  if (desplacament + limit < total) {
    enllacos.next = ambDesplacament(desplacament + limit);
  }
  if (desplacament > 0) {
    enllacos.prev = ambDesplacament(Math.max(0, desplacament - limit));
  }
  if (total > limit) {
    enllacos.first = ambDesplacament(0);
    enllacos.last = ambDesplacament(ultimDesplacament);
  }

  return enllacos;
}

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

Link: <http://localhost:3000/v1/cafes?limit=1&ordenar=nom&desplacament=1>; rel="next", <http://localhost:3000/v1/cafes?limit=1&ordenar=nom&desplacament=0>; rel="first", <http://localhost:3000/v1/cafes?limit=1&ordenar=nom&desplacament=1>; rel="last"

curl -s "http://localhost:3000/v1/cafes?camps=nom,preuEuros" | jq '.dades[0]'

{ "id": "caf_001", "nom": "Etiòpia Yirgacheffe", "preuEuros": 14.5 }

// src/controladors/cafes.js  (afegir a l'objecte controladorCafes)

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

  // Comprovació provisional. A 03-04 la substitueix validar(esquemaCrearCafe).
  const obligatoris = ['nom', 'origen', 'torrefaccio', 'preuEuros', 'estoc'];
  const mancants = obligatoris.filter((camp) => dades?.[camp] === undefined);
  if (mancants.length > 0) {
    return res.status(400).json({
      error: {
        codi: 'dades_invalides',
        missatge: 'Falten camps obligatoris.',
        detalls: mancants.map((camp) => ({
          camp,
          codi: 'requerit',
          missatge: `El camp '${camp}' és obligatori.`,
        })),
      },
    });
  }

  const cafe = serveiCafes.crear(dades);
  const representacio = cafeARepresentacio(cafe);

  // La capçalera Location és OBLIGATÒRIA en tota creació (02-04).
  res.set('Location', `/v1/cafes/${cafe.id}`);
  res.status(201).json(representacio);
},

curl -i -s -X POST http://localhost:3000/v1/cafes \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Kenya Nyeri",
    "origen": "Kenya",
    "torrefaccio": "mitja",
    "preuEuros": 16.75,
    "estoc": 40,
    "notesTast": ["grosella", "tomàquet", "cítric"]
  }'

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

{"id":"caf_003","nom":"Kenya Nyeri","origen":"Kenya","torrefaccio":"mitja","preuEuros":16.75,"estoc":40,"notesTast":["grosella","tomàquet","cítric"],"descripcio":null,"dataCreacio":"2026-03-14T10:41:22.113Z","_links":{"self":{"href":"/v1/cafes/caf_003"},"ressenyes":{"href":"/v1/cafes/caf_003/ressenyes"}}}

// src/controladors/cafes.js  (continuació)

/** PUT /v1/cafes/:id — reemplaçament complet */
reemplacar(req, res) {
  const cafe = serveiCafes.reemplacar(req.params.id, req.body);
  if (!cafe) return noTrobat(res, req.params.id);
  res.status(200).json(cafeARepresentacio(cafe));
},

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

  // El contracte de 02-03 admet NOMÉS merge-patch (i application/json per
  // comoditat). JSON Patch (application/json-patch+json) es rebutja amb
  // 415 i la capçalera Accept-Patch que diu què SÍ que s'admet.
  const admesos = ['application/merge-patch+json', 'application/json'];
  const esAdmes = admesos.some((t) => tipus.startsWith(t));

  if (!esAdmes) {
    res.set('Accept-Patch', 'application/merge-patch+json');
    return res.status(415).json({
      error: {
        codi: 'format_no_suportat',
        missatge: `El tipus '${tipus}' no s'admet a PATCH. Fes servir application/merge-patch+json.`,
        detalls: [],
      },
    });
  }

  const cafe = serveiCafes.modificar(req.params.id, req.body);
  if (!cafe) return noTrobat(res, req.params.id);
  res.status(200).json(cafeARepresentacio(cafe));
},

# PATCH correcte: només es toca l'estoc
curl -s -X PATCH http://localhost:3000/v1/cafes/caf_001 \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"estoc": 95}' | jq '{nom, estoc, preuEuros}'

{ "nom": "Etiòpia Yirgacheffe", "estoc": 95, "preuEuros": 14.5 }

# PATCH amb 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":"/estoc","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/controladors/cafes.js  (continuació)

/** DELETE /v1/cafes/:id — esborrat lògic */
esborrar(req, res) {
  const esborrat = serveiCafes.esborrar(req.params.id);
  if (!esborrat) return noTrobat(res, req.params.id);

  // 204 No Content: sense cos. Ni {} ni null: RES.
  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.codi

HTTP/1.1 204 No Content

"cafe_no_trobat"

// src/repositoris/comandes-memoria.js

const comandes = [
  {
    id: 'com_5001',
    clientId: 'cli_842',
    estat: 'pendent_pagament',
    linies: [
      { cafeId: 'caf_001', nom: 'Etiòpia Yirgacheffe', quantitat: 2, preuCentims: 1450 },
    ],
    totalCentims: 2900, // 29,00 € — la suma de les línies, en cèntims
    dataCreacio: '2026-03-14T10:30:00Z',
    dataPagament: null,
    dataEnviament: null,
  },
];

export const repositoriComandes = {
  buscar({ clientId, estat, limit = 20, desplacament = 0 } = {}) {
    let resultat = [...comandes];
    if (clientId !== undefined) resultat = resultat.filter((c) => c.clientId === clientId);
    if (estat !== undefined) resultat = resultat.filter((c) => c.estat === estat);

    const total = resultat.length;
    // Ordre per defecte de 02-06: les més recents primer.
    resultat.sort((a, b) => b.dataCreacio.localeCompare(a.dataCreacio) || a.id.localeCompare(b.id));

    return {
      elements: resultat.slice(desplacament, desplacament + limit).map((c) => ({ ...c })),
      total,
    };
  },

  buscarPerId(id) {
    const comanda = comandes.find((c) => c.id === id);
    return comanda ? { ...comanda } : undefined;
  },
};

// src/serveis/comandes.js
import { repositoriComandes } from '../repositoris/comandes-memoria.js';

export const serveiComandes = {
  llistar(criteris) {
    return repositoriComandes.buscar(criteris);
  },
  obtenir(id) {
    return repositoriComandes.buscarPerId(id);
  },
};

// src/controladors/comandes.js
import { serveiComandes } from '../serveis/comandes.js';
import { comandaARepresentacio, aResumDeColeccio } from '../serveis/mapejadors.js';
import { construirCapcaleraLink } from './paginacio.js';

export const controladorComandes = {
  /** GET /v1/comandes */
  llistar(req, res) {
    const limit = req.query.limit === undefined ? 20 : Number(req.query.limit);
    const desplacament =
      req.query.desplacament === undefined ? 0 : Number(req.query.desplacament);

    const { elements, total } = serveiComandes.llistar({
      clientId: req.query.clientId,
      estat: req.query.estat,
      limit,
      desplacament,
    });

    const enllacos = construirCapcaleraLink({ req, limit, desplacament, total });
    if (Object.keys(enllacos).length > 0) res.links(enllacos);

    res.status(200).json({
      dades: elements.map(comandaARepresentacio).map(aResumDeColeccio),
      total,
    });
  },

  /** GET /v1/comandes/:id */
  obtenir(req, res) {
    const comanda = serveiComandes.obtenir(req.params.id);
    if (!comanda) {
      return res.status(404).json({
        error: {
          codi: 'comanda_no_trobada',
          missatge: `No existeix cap comanda amb l'identificador '${req.params.id}'.`,
          detalls: [],
        },
      });
    }
    res.status(200).json(comandaARepresentacio(comanda));
  },
};

// src/rutes/comandes.js
import { Router } from 'express';
import { controladorComandes } from '../controladors/comandes.js';

export const rutesComandes = Router();

rutesComandes.get('/', controladorComandes.llistar);
rutesComandes.get('/:id', controladorComandes.obtenir);
// POST /v1/comandes arriba a 03-04 (validació) i 03-05 (transacció amb estoc).

import { rutesComandes } from './comandes.js';
rutesV1.use('/comandes', rutesComandes);

curl -s http://localhost:3000/v1/comandes/com_5001 | jq '{estat, totalEuros, _links}'

{
  "estat": "pendent_pagament",
  "totalEuros": 29,
  "_links": {
    "self": { "href": "/v1/comandes/com_5001" },
    "client": { "href": "/v1/clients/cli_842" },
    "pagar": { "href": "/v1/comandes/com_5001/pagament", "method": "POST" },
    "anullar": { "href": "/v1/comandes/com_5001/anullacio", "method": "POST" }
  }
}

// Gestor asíncron que falla. Express 4 NO captura aquest error.
rutesCafes.get('/:id', async (req, res) => {
  const cafe = await serveiCafes.obtenir(req.params.id);
  if (!cafe) throw new Error('no trobat'); // ← es perd
  res.json(cafeARepresentacio(cafe));
});

rutesCafes.get('/:id', (req, res) => {
  throw new Error('això sí que ho captura Express'); // → 500 amb la pàgina HTML per defecte
});

/** Embolcalla un gestor async i encamina qualsevol rebuig cap a next(). */
export function asincron(fn) {
  return (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
}

// Ús:
rutesCafes.get('/:id', asincron(controladorCafes.obtenir));

let disponible;
if (req.query.disponible !== undefined) {
  if (req.query.disponible !== 'true' && req.query.disponible !== 'false') {
    return res.status(400).json({
      error: {
        codi: 'parametre_invalid',
        missatge: "El paràmetre 'disponible' només admet 'true' o 'false'.",
        detalls: [
          {
            camp: 'disponible',
            codi: 'valor_invalid',
            missatge: `S'ha rebut '${req.query.disponible}'.`,
          },
        ],
      },
    });
  }
  disponible = req.query.disponible === 'true';
}

criteris.push({ camp: 'id', descendent: false });

// src/controladors/clients.js
import { serveiClients } from '../serveis/clients.js';
import { serveiComandes } from '../serveis/comandes.js';
import { comandaARepresentacio, aResumDeColeccio } from '../serveis/mapejadors.js';
import { construirCapcaleraLink } from './paginacio.js';

export const controladorClients = {
  /** GET /v1/clients/:id/comandes */
  llistarComandes(req, res) {
    // Primer, que el client existeixi: si no, 404 del client, no llista buida.
    if (!serveiClients.obtenir(req.params.id)) {
      return res.status(404).json({
        error: {
          codi: 'client_no_trobat',
          missatge: `No existeix cap client amb l'identificador '${req.params.id}'.`,
          detalls: [],
        },
      });
    }

    const limit = req.query.limit === undefined ? 20 : Number(req.query.limit);
    const desplacament =
      req.query.desplacament === undefined ? 0 : Number(req.query.desplacament);

    const { elements, total } = serveiComandes.llistar({
      clientId: req.params.id, // ← l'id ve de la RUTA, no de la query
      estat: req.query.estat,
      limit,
      desplacament,
    });

    const enllacos = construirCapcaleraLink({ req, limit, desplacament, total });
    if (Object.keys(enllacos).length > 0) res.links(enllacos);

    res.status(200).json({
      dades: elements.map(comandaARepresentacio).map(aResumDeColeccio),
      total,
    });
  },
};