🔧 Référence Technique

Audit Stack

Règles architecturales absolues — custom-routes.ts — Dette technique — Workflows

📅 MàJ S64 — 1er avril 2026 📄 custom-routes.ts : 3 846 lignes 🔌 ~115 routes
📊 État custom-routes.ts (S63)
3 846
Lignes
48
instance.use() ✅
102
app.use() ⚠️ dette
117
getDb() utilisations
4
createConnection GED
10
Tools Eliot actifs
🚨 14 Règles techniques critiques
1

instance.use() uniquement — jamais app.use() MàJ S63

NestJS exige instance.use() pour les routes injectées. Les 102 app.use() restants sont de la dette technique en cours de migration progressive.

2

getDb() par connexion + db.end() dans finally

Toujours ouvrir une connexion par requête, toujours la fermer dans le bloc finally. Ne jamais réutiliser une connexion entre requêtes.

3

nginx strips /api/ — routes définies sans ce préfixe

Le proxy nginx supprime le préfixe /api/ avant de transmettre à l'API. Les routes dans custom-routes.ts ne commencent jamais par /api/.

4

PDF → Modal uniquement — jamais window.open()

Toute génération PDF doit s'ouvrir dans une modal <iframe> intégrée à la page. La navigation vers un nouvel onglet est interdite.

5

Portail Client → sessionStorage exclusivement

Le token de session du portail client est stocké uniquement en sessionStorage, jamais en localStorage.

6

BC = Bilan Comportemental — jamais EDC

La terminologie officielle est BC (Bilan Comportemental). Le terme EDC (Étude de Comportement) est proscrit dans tout le code, la documentation et l'interface.

7

Eliot → http.request (pas https) dans Docker MàJ S62

Les appels internes Eliot vers localhost:8080 dans le container Docker utilisent http.request, pas https. L'utilisation de https provoquerait des erreurs SSL.

8

instance.use() POST → _readBody() obligatoire NOUVEAU S63

NestJS ne parse pas automatiquement le body des requêtes passant par instance.use(). Toutes les routes POST doivent utiliser le helper _readBody() pour accéder aux données envoyées.

9

PowerShell → -LiteralPath pour chemins avec [id]

Les chemins contenant des crochets (ex: src/app/[id]/page.tsx) doivent utiliser le paramètre -LiteralPath en PowerShell pour éviter l'interprétation des wildcards.

10

Eliot est une Option commerciale — app fonctionnelle sans lui

Toutes les fonctionnalités de l'application doivent fonctionner indépendamment d'Eliot. L'agent IA est une couche optionnelle, jamais un prérequis fonctionnel.

11

COPIER_TOUTES_PAGES_v2.ps1 obligatoire avant tout build frontend

Le script de copie doit être exécuté avant chaque docker compose build frontend. L'erreur files.zip éventuellement affichée est inoffensive (verrou OneDrive).

12

API rebuild : build --no-cache → up -d → restart nginx

Ne jamais utiliser docker compose restart api seul — cela ne prend pas la nouvelle image. Toujours rebuilder puis redémarrer nginx.

13

Scripts Python → toujours dans $env:USERPROFILE\Downloads\

Jamais dans le répertoire OneDrive du projet. Les scripts Python de manipulation TypeScript évitent les problèmes d'encodage PowerShell avec les caractères français et les backticks.

14

git pull --rebase avant tout push sur petsuite-docs

Le repo docs peut recevoir des commits de plusieurs sessions. Toujours rebaser avant de pousser pour éviter les conflits de merge.

🐳 Commandes Docker essentielles
# Toujours depuis le dossier deploy ! cd "D:\...\micro_logiciel_frontend_nextjs\deploy" # Rebuild API (après modif custom-routes.ts) docker compose build api --no-cache docker compose up -d api docker compose restart nginx # Rebuild Frontend (après modif pages .tsx) cd .. .\COPIER_TOUTES_PAGES_v2.ps1 cd deploy docker compose build frontend docker compose up -d frontend docker compose restart nginx # Inspection / debug docker compose ps docker compose logs api --tail=30 docker builder prune --force # Si --no-cache ne suffit pas
# Python scripts — toujours dans Downloads C:\Python314\python.exe $env:USERPROFILE\Downloads\nom_script.py # Git push dev git add api/src/custom-routes.ts src/components/ClaudeWidget.tsx git commit -m "S6x - description" git push # Git push docs cd C:\AnimGest_Sav git pull --rebase git add . git commit -m "description" git push
⚠️ Dette technique — Catalogue S64
Dette Localisation Sévérité Plan d'action
102 app.use() → migrer vers instance.use() custom-routes.ts — liste via mon_script.py HAUTE Migration progressive par module (formules, devis, factures…)
4 createConnection sur BDD GED L2286, L2317, L2355, L2393 MOYENNE Créer helper getDbGed() + remplacer les 4 occurrences
3 tools Eliot en doublon dans la liste déclarée Bloc déclaration tools custom-routes.ts MOYENNE Supprimer les 3 doublons (implémentation déjà propre)
REG_STATUT résiduel dans un INSERT reglement ~L56376 custom-routes.ts HAUTE Localiser et supprimer (mon_script.py peut identifier la ligne)
PUT /devis/:id — lignes non supportées Route PUT devis HAUTE Ajouter logique DELETE/INSERT lignes + whitelist colonnes
🤖 Eliot — Règles métier immuables
✅ AUTORISÉ
  • ✓ Lecture (clients, animaux, devis, séances)
  • ✓ Création (devis, règlements, factures)
  • ✓ Modification statut devis
  • ✓ Envoi email avec PDF en PJ
  • ✓ Envoi lien portail client
❌ JAMAIS
  • ✗ Suppression de données
  • ✗ Modification de pages ou de code
  • ✗ Exécution SQL direct (passer par les routes API)
  • ✗ Création ou modification de tables BDD
  • ✗ Accès aux fichiers du serveur
🔧 Tools Eliot — État S63 (10 actifs)
search_client Recherche tiers + animal par nom ✅ S62
get_articles Liste des prestations avec prix ✅ S62
create_devis Crée devis + lignes via POST /devis ✅ S62
get_devis Lecture devis + lignes par ID ✅ S62
open_pdf_modal Signal UI → modal PDF dans le widget ✅ S62
send_email Envoi email devis/facture avec PDF (nodemailer réel) ✅ S63
get_seances Séances d'un client ✅ S62
update_statut_devis Transitions BROUILLON→ENVOYE→ACCEPTE→REFUSE→ANNULE ✅ S63
create_facture_depuis_devis Convertit devis ACCEPTE en facture ✅ S63
create_reglement INSERT reglement (REG_DATE, REG_MONTANT, REG_MODE, REG_REFERENCE) ✅ S63

⚠️ 3 doublons dans la liste déclarée (pas dans l'implémentation) — à corriger en S64

S64+ prévu : create_seance · get_planning · send_portail_link