4NK_IA_front/docs/ANALYSE_REPO.md

Journal d'incident - 2025-09-16

Mise à jour – 2025-09-18

État d’avancement

• Backend: support explicite des .txt, upgrade multer@^2, sécurisation de tous les accès .length (OCR/NER), traitement asynchrone robuste (flags .pending, nettoyage garanti).
• Cache unifié: usage de cache/ à la racine; backup puis purge de backend/cache/ (doublon) pour éviter les incohérences.
• Outils: scripts/precache.cjs pour préremplir le cache à partir d’uploads/ (détection root/backend automatique).
• Documentation: ajout docs/CACHE_ET_TRAITEMENT_ASYNC.md et enrichissement de l’analyse.
• Frontend: code splitting confirmé (React.lazy/Suspense), React Router v7, MUI v7, Redux Toolkit. Nouvelles commandes de tests: test:collectors, test:ocr, test:api, test:e2e, test:all.

Conformité aux bonnes pratiques

• Qualité: ESLint 9, Prettier, markdownlint; Vitest + Testing Library; tsconfig strict; Docker multi-stage avec Nginx pour SPA.
• Architecture: couche services HTTP (Axios) isolée, état centralisé (Redux Toolkit), routing moderne, mécanismes de cache et asynchronisme documentés.

Risques et points de vigilance

• Dépendance suspecte router-dom (doublon de react-router-dom) dans package.json racine: à supprimer si non utilisée.
• Alignement de types: vérifier la stricte conformité entre ExtractionResult (front) et la réponse normalisée backend (ex. champs additionnels comme timestamp).
• Rigueur markdownlint: s’assurer des lignes vides autour des titres/blocs et de longueurs de ligne raisonnables dans les nouveaux docs.
• CI/Tagging: respecter le préfixe de commit ci: docker_tag=dev-test et les conventions internes.

Actions prioritaires

1. Mettre à jour CHANGELOG.md (support .txt, durcissement .length, cache unifié, script precache, doc async/cache).
2. Lancer npm run lint, npm run mdlint, npm run test:all, npm run build et corriger les erreurs TS/ESLint éventuelles (types d’entités, variables inutilisées, deps de hooks).
3. Retirer router-dom si non utilisée.
4. Committer et pousser sur dev avec message CI conforme; proposer un tag.

Résumé

Le frontend affichait des erreurs 502 Bad Gateway via Nginx pour les endpoints /api/health et /api/folders/{hash}/results.

Constat

• curl https://ia.4nkweb.com/api/health retournait 502.
• Aucun service n'écoutait en local sur le port 3001.
• backend.log montrait des tentatives de traitement sur un fichier .txt avec erreurs Sharp (format non supporté), indiquant un arrêt préalable du service.

Actions de rétablissement

1. Installation de Node via nvm (Node 22.x) pour satisfaire engines.
2. Installation des dépendances (npm ci) côté backend et racine.
3. Démarrage du backend Express sur 3001 en arrière‑plan avec logs et PID.
4. Vérifications:
   • curl http://127.0.0.1:3001/api/health → 200 OK
   • curl https://ia.4nkweb.com/api/health → 200 OK
   • curl https://ia.4nkweb.com/api/folders/7d99a85daf66a0081a0e881630e6b39b/results → 200 OK

Causes probables

• Processus backend arrêté (pas de listener sur 3001).
• Gestion incomplète des fichiers .txt côté backend (détection MIME), pouvant entraîner des erreurs avec Sharp.

Recommandations de suivi

• Ajouter le mapping .txt → text/plain dans la détection MIME backend.
• Dans /api/extract, gérer explicitement les .txt (lecture directe) comme dans processDocument.
• Mettre à jour Multer vers 2.x (1.x est vulnérable et déprécié).
• Surveiller backend.log et ajouter une supervision (systemd/service manager).

---

Audit détaillé du dépôt 4NK_IA_front

Portée

• Code analysé: frontend React/TypeScript sous Vite, répertoire /home/debian/4NK_IA_front.
• Commandes exécutées: npm ci, npm run lint, npm run mdlint, npm run test, npm run build.

Architecture et pile technique

• Framework: React 19 + TypeScript, Vite 7 (vite.config.ts).
• UI: MUI v7.
• État: Redux Toolkit + react-redux (src/store/index.ts, src/store/documentSlice.ts).
• Routing: React Router v7 avec code-splitting via React.lazy/Suspense (src/router/index.tsx).
• Services: couche d’abstraction HTTP via Axios (src/services/api.ts), backend direct (src/services/backendApi.ts), OpenAI (src/services/openai.ts), fichiers/ dossiers (src/services/folderApi.ts).
• Build/Runtime: Docker multi‑stage Node→Nginx, config SPA (Dockerfile, nginx.conf).
• Qualité: ESLint + Prettier + markdownlint, Vitest + Testing Library.

Points forts

• Code splitting déjà en place au niveau du routeur.
• Centralisation d’état propre (slices, middlewares, persistance localStorage).
• Abstraction des services HTTP claire (Axios + backends alternatifs).
• Docker production prêt (Nginx + healthcheck) et CI potentielle via docker-compose.registry.yml.

Problèmes détectés

Lint TypeScript/JS

• Commande: npm run lint.
• Résultat: 57 problèmes trouvés (49 erreurs, 8 avertissements).
• Catégories principales:
  • Types interdits any dans plusieurs services, ex. src/services/backendApi.ts (lignes 23–36, 90, 97, 107) et src/services/fileExtract.ts (lignes 2, 5, 55, 63, 110).
  • Variables non utilisées, ex. src/App.tsx ligne 8 (setCurrentFolderHash), src/store/documentSlice.ts lignes 7, 56, 420, 428, src/services/openai.ts variables _file, _address, etc.
  • Règles react-hooks/exhaustive-deps dans src/App.tsx (ligne 65) et src/components/Layout.tsx (ligne 84).
  • Regex avec échappements inutiles dans src/services/ruleNer.ts (lignes 33–34, 84, 119).
  • Typage middleware Redux avec any dans src/store/index.ts ligne 8.

Lint Markdown

• Commande: npm run mdlint.
• Problèmes récurrents:
  • Manque de lignes vides autour des titres et listes: CHANGELOG.md, docs/API_BACKEND.md, docs/architecture-backend.md, docs/changelog-pending.md, docs/HASH_SYSTEM.md.
  • Longueur de ligne > 120 caractères: docs/API_BACKEND.md, docs/architecture-backend.md, docs/HASH_SYSTEM.md, docs/systeme-pending.md.
  • Blocs de code sans langage ou sans lignes vides autour.
  • Titres en emphase non conformes (MD036) dans certains documents.

Tests

• Commande: npm run test.
• Résultat: 1 suite OK, 1 suite en échec.
  • Échec: tests/testFilesApi.test.ts — import introuvable ../src/services/testFilesApi (le fichier n’existe pas). Il faut soit créer src/services/testFilesApi.ts, soit adapter le test pour la source disponible.

Build de production

• Commande: npm run build.
• Résultat: erreurs TypeScript empêchant la compilation.
  • Incohérences de types côté ExtractionResult consommé vs structures produites dans src/services/api.ts (propriété timestamp non prévue dans ExtractionResult).
  • Types d’entités utilisés en views/ExtractionView.tsx traités comme string au lieu d’objets typés (Identity, Address). Ex: accès à firstName, lastName, street, city, postalCode, confidence sur des string.
  • Variables non utilisées dans plusieurs fichiers (cf. lint ci‑dessus).

Causes probables et pistes de résolution

• Modèle de données: divergence entre la structure standardisée ExtractionResult (src/types/index.ts) et le mapping réalisé dans src/services/api.ts/backendApi.ts. Il faut:
  • Aligner les champs (ex. déplacer timestamp vers status.timestamp ou vers des métadonnées conformes).
  • Harmoniser la forme des entités retournées (personnes/adresses) pour correspondre strictement à Identity[] et Address[].
• Composants de vues: ExtractionView.tsx suppose des entités objets alors que les données mappées peuvent contenir des chaînes. Il faut normaliser en amont (mapping service) et/ou renforcer les garde‑fous de rendu.
• Tests: ajouter src/services/testFilesApi.ts (ou ajuster l’import) pour couvrir l’API de fichiers de test référencée par tests/testFilesApi.test.ts.
• Qualité:
  • Remplacer les any par des types précis (ou unknown + raffinements), surtout dans backendApi.ts, fileExtract.ts, openai.ts.
  • Corriger les dépendances de hooks React.
  • Nettoyer les variables non utilisées et directives eslint-disable superflues.
  • Corriger les regex avec échappements inutiles dans ruleNer.ts.
  • Corriger les erreurs markdown (MD013, MD022, MD031, MD032, MD036, MD040, MD047) en ajoutant lignes vides et langages de blocs.

Sécurité et configuration

• Variables d’environnement: VITE_API_URL, VITE_USE_OPENAI, clés OpenAI masquées en dev (src/services/api.ts). OK.
• Nginx: SPA et healthcheck définis (nginx.conf). OK pour production statique.
• Docker: image multi‑stage; healthcheck HTTP. Tagging via scripts et docker-compose.registry.yml (variable TAG). À aligner avec conventions internes du registre.

Recommandations prioritaires (ordre d’exécution)

1. Corriger les erreurs TypeScript bloquantes du build:
   • Aligner ExtractionResult consommé/produit (services + vues). Supprimer/relocaliser timestamp au bon endroit.
   • Normaliser identities/addresses en objets typés dans le mapping service.
   • Corriger ExtractionView.tsx pour refléter les types réels.
2. Supprimer variables non utilisées et corriger any majeurs dans services critiques (backendApi.ts, fileExtract.ts).
3. Ajouter/implémenter src/services/testFilesApi.ts ou corriger l’import de test.
4. Corriger les règles react-hooks/exhaustive-deps.
5. Corriger markdownlint dans CHANGELOG.md et docs/*.md (lignes vides, langages de blocs, longueurs de ligne raisonnables).
6. Relancer lint, tests et build pour valider.

Notes de compatibilité

• Node: engines >=20.19 <23. Testé avec Node 22.12.0 (OK) conformément au README.
• ESLint: config moderne (eslint@9, typescript-eslint@8) — stricte sur any et hooks React.

Annexes (références de fichiers)

• src/types/index.ts — définitions ExtractionResult, Identity, Address.
• src/services/api.ts — mapping de la réponse backend; contient la propriété non typée timestamp sur ExtractionResult (à déplacer).
• src/views/ExtractionView.tsx — accès de propriétés d’objets sur des string (à corriger après normalisation du mapping).
• tests/testFilesApi.test.ts — dépend de src/services/testFilesApi.ts non présent.