Aide-mémoire Node.js, npm et Express

applifrais-api/
├── package.json, package-lock.json, .env.example, .gitignore, Dockerfile, compose.yaml
├── docs/openapi.yaml
├── sql/schema.sql, sql/donnees.sql
├── src/
│   ├── server.js        démarrage, arrêt propre
│   ├── app.js           middlewares et routeurs, dans l'ordre
│   ├── config.js        variables d'environnement vérifiées
│   ├── db.js            pool mysql2
│   ├── logger.js        pino et pino-http
│   ├── erreurs.js       ErreurApi, route 404, gestionnaire d'erreurs
│   ├── middlewares/     authentifier, exigerRole, valider, televersement
│   ├── schemas/         schémas Zod
│   ├── routes/          un routeur par ressource
│   ├── controllers/     HTTP : lire req, choisir la réponse
│   ├── services/        règles de gestion
│   └── depots/          SQL
└── test/                tests node:test et Supertest

// src/app.js : l'ordre compte
app.use(journalRequetes);                         // 1. journal
app.use(helmet());                                // 2. en-têtes de sécurité
app.use(cors({ origin: config.origineFront }));   // 3. CORS
app.use(express.json({ limit: '100kb' }));        // 4. corps JSON
app.get('/sante', (req, res) => res.json({ statut: 'ok' }));
app.use('/v1/auth', routeurAuth);                 // 5. routes
app.use('/v1/fiches', routeurFiches);
app.use(routeInconnue);                           // 6. 404
app.use(gestionnaireErreurs);                     // 7. erreurs, quatre paramètres

import mysql from 'mysql2/promise';
export const pool = mysql.createPool({ ...config.db, connectionLimit: 10, decimalNumbers: true, dateStrings: true });

const [lignes] = await pool.execute('SELECT id, mois FROM fiche_frais WHERE id_visiteur = ?', [7]);
const [[{ total }]] = await pool.execute('SELECT COUNT(*) AS total FROM fiche_frais');
const [resultat] = await pool.execute('INSERT INTO … VALUES (?, ?)', [a, b]); // resultat.insertId
// UPDATE, DELETE : resultat.affectedRows
// LIMIT ? OFFSET ? : passer String(limite), String(decalage)

const connexion = await pool.getConnection();
try {
  await connexion.beginTransaction();
  // … connexion.execute(…) …
  await connexion.commit();
} catch (erreur) {
  await connexion.rollback();
  throw erreur;
} finally {
  connexion.release();
}

await prisma.ficheFrais.findMany({ where: { etat: 'CL' }, orderBy: { mois: 'desc' }, skip: 0, take: 20 });
await prisma.ficheFrais.findUnique({ where: { id: 12 }, include: { lignesForfait: true } });
await prisma.ficheFrais.create({ data: { visiteurId: 7, mois: '2026-11' } });
await prisma.ficheFrais.updateMany({ where: { id: 12, etat: 'CR' }, data: { etat: 'CL' } }); // { count }
await prisma.$transaction([requete1, requete2]);
await prisma.$queryRaw`SELECT … WHERE id = ${id}`; // paramétré ; jamais $queryRawUnsafe avec une saisie

z.config(z.locales.fr());
z.strictObject({ mois: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/) });  // corps : champs en trop refusés
z.object({ page: z.coerce.number().int().min(1).default(1) });          // chaîne de requête : conversion
z.iso.date(); z.email(); z.enum(['CR', 'CL']); z.number().positive().multipleOf(0.01);
z.stringbool();                                                           // booléen dans l'URL
const r = schema.safeParse(donnees);                                       // r.success, r.data, r.error.issues

const hachage = await argon2.hash(motDePasse);                 // stockage
await argon2.verify(hachage, motDePasse);                      // connexion
jwt.sign({ role }, secret, { subject: String(id), expiresIn: 900, algorithm: 'HS256' });
jwt.verify(jeton, secret, { algorithms: ['HS256'] });          // jamais jwt.decode pour authentifier