// src/errors/error-api.js

/**
 * Error de domini de l'API.
 *
 * Porta la informació necessària per construir la resposta, però es llança
 * des dels serveis sense que aquests sàpiguen res d'Express: 'estat' és un
 * número, no una crida a res.status().
 */
export class ErrorApi extends Error {
  /**
   * @param {number} estat     Codi HTTP (404, 409, ...)
   * @param {string} codi      Codi del catàleg de 02-04 ('cafe_no_trobat')
   * @param {string} missatge  Missatge llegible per al consumidor
   * @param {object[]} detalls Llista de problemes concrets; SEMPRE present
   */
  constructor(estat, codi, missatge, detalls = []) {
    super(missatge);

    // Sense això, error.name seria 'Error' i els logs perdrien informació.
    this.name = 'ErrorApi';
    this.estat = estat;
    this.codi = codi;
    this.detalls = detalls;

    // Marca explícita: el middleware la fa servir per distingir un error
    // previst del catàleg d'una fallada inesperada del programa.
    this.esErrorApi = true;

    // Retalla la traça perquè comenci on es va llançar, no al constructor.
    Error.captureStackTrace?.(this, ErrorApi);
  }
}

// src/errors/error-api.js  (continuació)

export const errors = {
  // --- 400 ---
  dadesInvalides(detalls = []) {
    return new ErrorApi(
      400,
      'dades_invalides',
      'El cos de la petició conté errors de validació.',
      detalls
    );
  },

  parametreInvalid(detalls = []) {
    return new ErrorApi(
      400,
      'parametre_invalid',
      'Els paràmetres de la petició contenen errors.',
      detalls
    );
  },

  // --- 401 ---
  noAutenticat(missatge = "Aquesta operació requereix autenticació.") {
    return new ErrorApi(401, 'no_autenticat', missatge);
  },

  tokenCaducat() {
    return new ErrorApi(401, 'token_caducat', 'El token ha caducat. Torna a iniciar sessió.');
  },

  // --- 403 ---
  permisDenegat(rolsPermesos = []) {
    const detall =
      rolsPermesos.length > 0
        ? ` Es requereix un d'aquests rols: ${rolsPermesos.join(', ')}.`
        : '';
    return new ErrorApi(403, 'permisos_insuficients', `No tens permís.${detall}`);
  },

  // --- 404 ---
  noTrobat(tipus, id) {
    // Mapa entitat → codi del catàleg. Un tipus nou s'afegeix aquí.
    const codis = {
      cafe: 'cafe_no_trobat',
      client: 'client_no_trobat',
      comanda: 'comanda_no_trobada',
      ressenya: 'ressenya_no_trobada',
      cistella: 'cistella_no_trobada',
    };
    return new ErrorApi(
      404,
      codis[tipus] ?? 'ruta_no_trobada',
      `No existeix cap ${tipus} amb l'identificador '${id}'.`
    );
  },

  rutaNoTrobada(metode, url) {
    return new ErrorApi(404, 'ruta_no_trobada', `No existeix el recurs ${metode} ${url}.`);
  },

  // --- 405 / 409 / 413 / 415 ---
  metodeNoPermes(metode, ruta) {
    return new ErrorApi(405, 'metode_no_permes', `${metode} no està permès sobre ${ruta}.`);
  },

  conflicte(codi, missatge, detalls = []) {
    return new ErrorApi(409, codi, missatge, detalls);
  },

  cosMassaGran() {
    return new ErrorApi(413, 'cos_massa_gran', 'El cos supera la mida màxima (100 kB).');
  },

  formatNoSuportat(tipus) {
    return new ErrorApi(
      415,
      'format_no_suportat',
      `El tipus de contingut '${tipus}' no s'admet en aquesta operació.`
    );
  },

  // --- 500 ---
  errorIntern() {
    return new ErrorApi(500, 'error_intern', "S'ha produït un error inesperat.");
  },
};

// ABANS: convenis ad hoc que el controlador havia de conèixer
obtenir(id) {
  return repositoriCafes.buscarPerId(id);   // undefined si no existeix
},

// src/serveis/cafes.js  (modificat)
import { errors } from '../errors/error-api.js';

export const serveiCafes = {
  /** Retorna un cafè. Llança si no existeix. */
  obtenir(id) {
    const cafe = repositoriCafes.buscarPerId(id);
    if (!cafe) throw errors.noTrobat('cafe', id);
    return cafe;
  },

  reemplacar(id, dades) {
    this.obtenir(id);   // llança 404 si no existeix: sense duplicar el missatge
    return repositoriCafes.actualitzar(id, { /* ...camps... */ });
  },

  esborrar(id) {
    if (!repositoriCafes.esborrar(id)) throw errors.noTrobat('cafe', id);
  },
};

// src/serveis/comandes.js  (modificat)
import { errors } from '../errors/error-api.js';
import { crearComandaAtomica } from '../repositoris/comandes-sqlite.js';

export const serveiComandes = {
  obtenirPer(id, usuari) {
    const comanda = repositoriComandes.buscarPerId(id);
    const esPersonal = ['empleat', 'administrador'].includes(usuari.rol);

    // Comanda inexistent i comanda aliena donen EXACTAMENT el mateix error,
    // per no filtrar-ne l'existència (03-06, secció 14).
    if (!comanda || (comanda.clientId !== usuari.id && !esPersonal)) {
      throw errors.noTrobat('comanda', id);
    }
    return comanda;
  },

  crear({ clientId, linies }) {
    try {
      const id = crearComandaAtomica({ clientId, linies });
      return repositoriComandes.buscarPerId(id);
    } catch (error) {
      // El repositori llança errors amb 'codiDomini' (03-05); aquí es
      // converteixen en ErrorApi. La traducció viu al servei perquè
      // és ell qui decideix que un estoc insuficient és un 409.
      if (error.codiDomini === 'estoc_insuficient') {
        throw errors.conflicte('estoc_insuficient', error.message);
      }
      if (error.codiDomini === 'cafe_no_trobat') {
        throw errors.noTrobat('cafe', "d'alguna línia de la comanda");
      }
      throw error;   // no és nostre: que el middleware el tracti com un 500
    }
  },

  pagar(id, usuari) {
    const comanda = this.obtenirPer(id, usuari);
    if (comanda.estat === 'pagat') {
      throw errors.conflicte('comanda_ja_pagada', `La comanda '${id}' ja està pagada.`);
    }
    // ...marcar com a pagada...
  },
};

// src/controladors/cafes.js  (modificat)
obtenir(req, res) {
  const cafe = serveiCafes.obtenir(req.params.id);   // si falla, llança
  res.status(200).json(projectar(cafeARepresentacio(cafe), req.query.camps));
},

// src/middleware/asincron.js

/**
 * Embolcalla un gestor perquè qualsevol rebuig de promesa acabi a
 * next(error) i, per tant, al middleware d'errors.
 *
 * Promise.resolve() funciona igual si fn és síncrona (retorna una promesa
 * ja resolta) o asíncrona, així que es pot embolcallar TOT sense pensar-hi.
 */
export function asincron(fn) {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
}

// src/rutes/cafes.js  (modificat)
import { asincron } from '../middleware/asincron.js';

rutesCafes.get('/', validar(esquemaConsultaCafes, 'query'), asincron(controladorCafes.llistar));
rutesCafes.get('/:id', validar(esquemaIdCafe, 'params'), asincron(controladorCafes.obtenir));
rutesCafes.post(
  '/',
  autenticar,
  exigirRol('empleat', 'administrador'),
  validar(esquemaCrearCafe),
  asincron(controladorCafes.crear)
);
// ...i així a totes

// src/middleware/errors.js
import { ZodError } from 'zod';
import { ErrorApi, errors } from '../errors/error-api.js';
import { entorn } from '../config/entorn.js';

/**
 * Middleware d'errors.
 *
 * LA SIGNATURA DE QUATRE ARGUMENTS ÉS OBLIGATÒRIA. Express distingeix un
 * middleware d'errors d'un de normal comptant els paràmetres de la
 * funció: amb tres és normal, amb quatre és d'errors. Per això 'next'
 * s'ha de declarar encara que no es faci servir, i per això ESLint
 * necessitava la regla argsIgnorePattern: '^_' que vam configurar a 03-01.
 */
// eslint-disable-next-line no-unused-vars
export function gestorErrors(err, req, res, next) {
  const errorApi = traduir(err);

  // --- Registre per a l'equip ---
  if (errorApi.estat >= 500) {
    // Els 5xx són fallades NOSTRES: es registren senceres, amb traça.
    console.error(
      JSON.stringify({
        nivell: 'error',
        tracaId: req.tracaId,
        metode: req.method,
        ruta: req.originalUrl,
        usuari: req.usuari?.id ?? null,
        missatge: err.message,
        pila: err.stack,
      })
    );
  } else {
    // Els 4xx són fallades del client: n'hi ha prou amb una línia informativa.
    console.warn(
      JSON.stringify({
        nivell: 'avis',
        tracaId: req.tracaId,
        metode: req.method,
        ruta: req.originalUrl,
        codi: errorApi.codi,
      })
    );
  }

  // --- Capçaleres que exigeix el contracte segons el cas ---
  if (errorApi.estat === 401) {
    res.set('WWW-Authenticate', 'Bearer realm="api.botigaaroma.example"');
  }
  if (errorApi.estat === 405 && err.metodesPermesos) {
    res.set('Allow', err.metodesPermesos.join(', '));
  }
  if (errorApi.codi === 'format_no_suportat' && req.method === 'PATCH') {
    res.set('Accept-Patch', 'application/merge-patch+json');
  }

  // --- Cos del contracte (02-04) ---
  const cos = {
    error: {
      codi: errorApi.codi,
      missatge: errorApi.missatge ?? errorApi.message,
      detalls: errorApi.detalls ?? [],
    },
  };

  // tracaId NOMÉS als 5xx, com vam decidir a 02-04.
  if (errorApi.estat >= 500) {
    cos.error.tracaId = req.tracaId;

    // En desenvolupament ajuda veure la causa; en producció, MAI.
    if (entorn.nodeEnv !== 'produccio') {
      cos.error.depuracio = err.message;
    }
  }

  res.status(errorApi.estat).json(cos);
}

// src/middleware/errors.js  (continuació)

/** Converteix qualsevol excepció en un ErrorApi del catàleg. */
function traduir(err) {
  // 1. Ja és nostre: es fa servir tal qual.
  if (err?.esErrorApi) return err;

  // 2. Validació de Zod que s'ha escapat del middleware de validació.
  if (err instanceof ZodError) {
    return errors.dadesInvalides(
      err.issues.map((i) => ({
        camp: i.path.join('.') || '(cos)',
        codi: 'valor_invalid',
        missatge: i.message,
      }))
    );
  }

  // 3. JSON mal format, detectat per express.json().
  if (err instanceof SyntaxError && 'body' in err) {
    return new ErrorApi(400, 'dades_invalides', 'El cos no és JSON vàlid.', [
      { camp: '(cos)', codi: 'json_mal_format', missatge: err.message },
    ]);
  }

  // 4. Cos massa gran (limit d'express.json).
  if (err?.type === 'entity.too.large') return errors.cosMassaGran();

  // 5. Errors de SQLite.
  const deSqlite = traduirSqlite(err);
  if (deSqlite) return deSqlite;

  // 6. Qualsevol altra cosa és un bug nostre: 500 sense filtrar res.
  return errors.errorIntern();
}

{
  "error": {
    "codi": "error_intern",
    "missatge": "S'ha produït un error inesperat.",
    "detalls": [],
    "tracaId": "trz_8f4a1c92"
  }
}

// src/middleware/traca.js
import { randomBytes } from 'node:crypto';

/**
 * Assigna un identificador únic a cada petició.
 * Si ve d'un proxy o d'una passarel·la que ja el va generar, es respecta:
 * així la traça és contínua al llarg de tot el sistema (04-07).
 */
export function assignarTracaId(req, res, next) {
  const heretat = req.get('Aroma-Traca-Id');
  req.tracaId = heretat ?? `trz_${randomBytes(4).toString('hex')}`;

  // Es retorna sempre, no només als errors: permet al client
  // referenciar qualsevol petició en obrir una incidència.
  res.set('Aroma-Traca-Id', req.tracaId);
  next();
}

// src/middleware/validacio.js  (modificat)
import { errors } from '../errors/error-api.js';

export function validar(esquema, origen = 'body') {
  return (req, res, next) => {
    const resultat = esquema.safeParse(req[origen]);

    if (!resultat.success) {
      const detalls = aDetalls(resultat.error);
      // El middleware d'errors s'encarrega del format i del registre.
      return next(
        origen === 'body' ? errors.dadesInvalides(detalls) : errors.parametreInvalid(detalls)
      );
    }

    req[origen] = resultat.data;
    next();
  };
}

// src/middleware/errors.js  (continuació)

/** Errors de SQLite → errors del catàleg. Retorna null si no ho és. */
function traduirSqlite(err) {
  const codi = err?.code;
  if (typeof codi !== 'string' || !codi.startsWith('SQLITE_')) return null;

  switch (codi) {
    case 'SQLITE_CONSTRAINT_UNIQUE':
    case 'SQLITE_CONSTRAINT_PRIMARYKEY':
      // Algú ha intentat duplicar un valor únic (un email, per exemple).
      return new ErrorApi(409, 'recurs_duplicat', 'Ja existeix un recurs amb aquell valor únic.');

    case 'SQLITE_CONSTRAINT_FOREIGNKEY':
      // Es referencia alguna cosa que no existeix: una comanda d'un client inexistent.
      return new ErrorApi(
        409,
        'referencia_invalida',
        "L'operació referencia un recurs que no existeix."
      );

    case 'SQLITE_CONSTRAINT_CHECK':
      // Un CHECK de l'esquema (torrefacció invàlida, estoc negatiu). Si arriba
      // aquí és que la validació de 03-04 té un forat: es registra
      // com a 5xx perquè l'equip ho vegi, encara que la culpa sembli del client.
      return new ErrorApi(400, 'dades_invalides', 'Les dades no compleixen una restricció del model.');

    case 'SQLITE_BUSY':
      return new ErrorApi(503, 'servei_no_disponible', 'La base de dades està ocupada. Reintenta-ho.');

    default:
      return null;   // desconegut: que sigui un 500 amb el seu log complet
  }
}

# JSON mal format: falta una cometa
curl -s -X POST http://localhost:3000/v1/cafes \
  -H "Content-Type: application/json" \
  -d '{"nom": "Kenya, "origen": "Kenya"}' | jq

{
  "error": {
    "codi": "dades_invalides",
    "missatge": "El cos no és JSON vàlid.",
    "detalls": [
      {
        "camp": "(cos)",
        "codi": "json_mal_format",
        "missatge": "Unexpected token o in JSON at position 20"
      }
    ]
  }
}

# Cos de 2 MB contra un límit de 100 kB
curl -s -X POST http://localhost:3000/v1/cafes \
  -H "Content-Type: application/json" \
  --data-binary @gegant.json | jq .error.codi

"cos_massa_gran"

// src/middleware/no-trobat.js
import { errors } from '../errors/error-api.js';

/** Cap ruta no ha coincidit: 404 ruta_no_trobada. */
export function gestorNoTrobat(req, res, next) {
  next(errors.rutaNoTrobada(req.method, req.originalUrl));
}

// src/middleware/no-trobat.js  (continuació)
import { ErrorApi } from '../errors/error-api.js';

/**
 * Retorna un gestor que respon 405 amb Allow.
 * Es registra amb router.all() al final de cada grup de rutes, així que
 * només s'assoleix si la URI ha coincidit però cap mètode no ho ha fet.
 */
export function metodeNoPermes(...metodesPermesos) {
  return (req, res, next) => {
    const error = new ErrorApi(
      405,
      'metode_no_permes',
      `${req.method} no està permès sobre ${req.baseUrl}${req.path}.`
    );
    // El middleware d'errors llegirà aquesta propietat per posar Allow.
    error.metodesPermesos = [...metodesPermesos, 'OPTIONS'];
    next(error);
  };
}

// src/rutes/cafes.js  (al final del fitxer, després de totes les rutes)
import { metodeNoPermes } from '../middleware/no-trobat.js';

rutesCafes.all('/', metodeNoPermes('GET', 'POST'));
rutesCafes.all('/:id', metodeNoPermes('GET', 'PUT', 'PATCH', 'DELETE'));

curl -i -s -X DELETE http://localhost:3000/v1/cafes | head -5

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST, OPTIONS
Content-Type: application/json; charset=utf-8

{"error":{"codi":"metode_no_permes","missatge":"DELETE no està permès sobre /v1/cafes.","detalls":[]}}

// src/app.js  (versió final del mòdul)
import express from 'express';
import { rutesV1 } from './rutes/index.js';
import { assignarTracaId } from './middleware/traca.js';
import { gestorNoTrobat } from './middleware/no-trobat.js';
import { gestorErrors } from './middleware/errors.js';

export const app = express();

app.disable('x-powered-by');

// --- 1. Identitat de la petició: el PRIMER, perquè tot la pugui fer servir ---
app.use(assignarTracaId);

// --- 2. Registre de peticions (04-07 el substituirà per logs estructurats) ---
app.use((req, res, next) => {
  const inici = Date.now();
  res.on('finish', () => {
    console.log(`${req.method} ${req.originalUrl} → ${res.statusCode} (${Date.now() - inici} ms)`);
  });
  next();
});

// --- 3. Analitzadors del cos ---
app.use(
  express.json({
    limit: '100kb',
    type: ['application/json', 'application/merge-patch+json'],
  })
);
app.use(express.urlencoded({ extended: false, limit: '10kb' }));

// --- 4. Salut (fora de /v1: no forma part del contracte) ---
app.get('/salut', (req, res) => {
  res.status(200).json({ estat: 'ok', versio: '1.0.0', moment: new Date().toISOString() });
});

// --- 5. API versionada ---
app.use('/v1', rutesV1);

// --- 6. Cap ruta no ha coincidit ---
app.use(gestorNoTrobat);

// --- 7. Middleware d'errors: SEMPRE L'ÚLTIM ---
app.use(gestorErrors);

// src/servidor.js  (versió final del mòdul)
import { app } from './app.js';
import { entorn } from './config/entorn.js';
import { tancarBaseDades } from './config/base-dades.js';

const servidor = app.listen(entorn.port, () => {
  console.log(`API de la Botiga Aroma escoltant a ${entorn.baseUrl}/v1`);
});

let tancant = false;

function tancarOrdenadament(motiu, codiSortida = 0) {
  if (tancant) return;   // dos senyals seguits no han de duplicar el tancament
  tancant = true;

  console.log(`Tancant per: ${motiu}`);

  servidor.close(() => {
    tancarBaseDades();
    console.log('Servidor i base de dades tancats.');
    process.exit(codiSortida);
  });

  // Xarxa de seguretat: si en 10 s no ha acabat, es força la sortida.
  // Sense això, una connexió oberta pot impedir l'apagada per sempre.
  setTimeout(() => {
    console.error("Tancament forçat després del temps d'espera.");
    process.exit(1);
  }, 10000).unref();
}

process.on('SIGINT', () => tancarOrdenadament('SIGINT'));
process.on('SIGTERM', () => tancarOrdenadament('SIGTERM'));

/**
 * Excepció no capturada: el procés està en un estat DESCONEGUT.
 * Es registra i se surt. Intentar continuar és pitjor: pot haver-hi
 * transaccions a mitges, fitxers oberts i estat corrupte.
 */
process.on('uncaughtException', (error) => {
  console.error(
    JSON.stringify({ nivell: 'fatal', tipus: 'uncaughtException', missatge: error.message, pila: error.stack })
  );
  tancarOrdenadament('uncaughtException', 1);
});

/** Promesa rebutjada sense catch. Des de Node 15, també acaba el procés. */
process.on('unhandledRejection', (rao) => {
  console.error(
    JSON.stringify({ nivell: 'fatal', tipus: 'unhandledRejection', missatge: String(rao) })
  );
  tancarOrdenadament('unhandledRejection', 1);
});

{
  "type": "https://api.botigaaroma.example/errors/estoc-insuficient",
  "title": "Estoc insuficient",
  "status": 409,
  "detail": "Només queden 3 unitats d'‘Etiòpia Yirgacheffe’ i se'n demanen 5.",
  "instance": "/v1/comandes"
}

rutesComandes.post('/', autenticar, async (req, res) => {
  try {
    const comanda = await serveiComandes.crear(req.body);
    res.status(201).json(comandaARepresentacio(comanda));
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// src/middleware/idempotencia.js
import { createHash } from 'node:crypto';
import { ErrorApi, errors } from '../errors/error-api.js';
import { baseDades } from '../config/base-dades.js';

// Taula necessària (migració 003):
//   CREATE TABLE claus_idempotencia (
//     clau TEXT PRIMARY KEY, empremta TEXT NOT NULL,
//     resposta TEXT, data TEXT NOT NULL
//   );

const buscarClau = baseDades.prepare('SELECT * FROM claus_idempotencia WHERE clau = ?');
const desarClau = baseDades.prepare(
  'INSERT INTO claus_idempotencia (clau, empremta, data) VALUES (?, ?, ?)'
);

export function exigirClauIdempotencia(req, res, next) {
  const clau = req.get('Idempotency-Key');

  if (!clau) {
    return next(
      new ErrorApi(
        400,
        'clau_idempotencia_requerida',
        'Aquesta operació requereix la capçalera Idempotency-Key.'
      )
    );
  }

  // Empremta del cos: identifica "la mateixa petició".
  const empremta = createHash('sha256').update(JSON.stringify(req.body ?? {})).digest('hex');
  const registre = buscarClau.get(clau);

  if (registre) {
    if (registre.empremta !== empremta) {
      // Mateixa clau, cos diferent: contradicció del client.
      return next(
        new ErrorApi(
          422,
          'clau_idempotencia_reutilitzada',
          "Aquesta Idempotency-Key ja es va fer servir amb un cos diferent."
        )
      );
    }
    if (registre.resposta) {
      // Reintent legítim: es retorna la resposta original.
      return res.status(200).json(JSON.parse(registre.resposta));
    }
    return next(
      new ErrorApi(409, 'operacio_en_curs', "Una petició idèntica s'està processant.")
    );
  }

  desarClau.run(clau, empremta, new Date().toISOString());
  req.clauIdempotencia = clau;
  next();
}

rutesComandes.post(
  '/',
  autenticar,
  exigirRol('client', 'empleat', 'administrador'),
  exigirClauIdempotencia,
  validar(esquemaCrearComanda),
  asincron(controladorComandes.crear)
);

// src/controladors/comandes.js
crear: async (req, res) => {
  const comanda = await serveiComandes.crear({
    clientId: req.usuari.id,        // del token, MAI del cos (03-06)
    linies: req.body.linies,
  });
  res.set('Location', `/v1/comandes/${comanda.id}`);
  res.status(201).json(comandaARepresentacio(comanda));
},

// src/rutes/comandes.js
rutesComandes.post(
  '/',
  autenticar,
  exigirClauIdempotencia,
  validar(esquemaCrearComanda),
  asincron(controladorComandes.crear)
);

HTTP/1.1 415 Unsupported Media Type
Accept-Patch: application/merge-patch+json
Aroma-Traca-Id: trz_1a2b3c4d

{"error":{"codi":"format_no_suportat","missatge":"El tipus de contingut 'application/json-patch+json' no s'admet en aquesta operació.","detalls":[]}}

HTTP/1.1 404 Not Found
Aroma-Traca-Id: trz_5e6f7a8b

{"error":{"codi":"comanda_no_trobada","missatge":"No existeix cap comanda amb l'identificador 'com_5001'.","detalls":[]}}

HTTP/1.1 403 Forbidden
Aroma-Traca-Id: trz_9c0d1e2f

{"error":{"codi":"permisos_insuficients","missatge":"No tens permís. Es requereix un d'aquests rols: empleat, administrador.","detalls":[]}}

HTTP/1.1 500 Internal Server Error
Aroma-Traca-Id: trz_3a4b5c6d

{"error":{"codi":"error_intern","missatge":"S'ha produït un error inesperat.","detalls":[],"tracaId":"trz_3a4b5c6d"}}

{"nivell":"error","tracaId":"trz_3a4b5c6d","metode":"GET","ruta":"/v1/cafes/caf_007","usuari":null,
 "missatge":"Cannot read properties of null (reading 'map')",
 "pila":"TypeError: ... at cafeARepresentacio (/app/src/serveis/mapejadors.js:31:29) ..."}