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.

Mise à jour – 2025-09-19

État du dépôt et de la build

• Build Vite/TypeScript: OK (production) — artefacts générés dans dist/.
• Lint JS/TS: 134 erreurs, 9 avertissements (principalement no-explicit-any, deps de hooks, no-empty).
• Lint Markdown: nombreuses erreurs dans docs/ et dans des dépendances tierces sous backend/node_modules/.

Détails des constats

• Router: découpage de code via React.lazy et Suspense dans src/router/index.tsx.
• État: centralisé via Redux Toolkit, persistance localStorage (src/store/index.ts).
• Services: séparation claire (src/services/api.ts, backendApi.ts, folderApi.ts, openai.ts).
• Vues: UploadView, ExtractionView, AnalyseView, ContexteView, ConseilView.

Résultats outillés

# Lint JS/TS
npm run lint

# Lint Markdown
npm run mdlint

# Build prod
npm run build

# Tests unitaires
npm run test

Observations clés:

• npm run build: succès, aucun blocage de typage.
• npm run lint: erreurs récurrentes @typescript-eslint/no-explicit-any dans:
  • src/services/backendApi.ts, src/services/fileExtract.ts, src/views/*, src/store/*.
  • Règles hooks: react-hooks/exhaustive-deps (App.tsx, Layout.tsx, UploadView.tsx).
• npm run mdlint: le linter inspecte des fichiers tiers dans backend/node_modules/. À ignorer côté script.

Tests (Vitest)

• Suites en échec: tests/ocr.test.js, tests/collectors.test.js, tests/ExtractionView.tabs.test.tsx.
• Erreurs d’import pour supertest dans tests/api.test.js et tests/e2e.test.js.
• Problèmes identifiés:
  • ExtractionView.tabs.test.tsx: useNavigate hors Router → utiliser MemoryRouter.
  • api.test.js / e2e.test.js: dépendance manquante supertest.
  • ocr.test.js: fichiers images manquants (Sharp) → fournir fixtures ou mocker I/O.
  • collectors.test.js: timeouts et attentes non alignées → mock fetch et ajuster assertions.
  • Port 3001 occupé pendant les tests (EADDRINUSE) → ne pas démarrer de serveur réel, utiliser des doubles/ports éphémères.

Recommandations immédiates (ordre conseillé)

1. Qualité TypeScript
   • Remplacer any par des types précis (ou unknown avec affinage) dans backendApi.ts, fileExtract.ts, views/*, store/*.
   • Corriger les dépendances de hooks (react-hooks/exhaustive-deps).
2. Tests
   • Ajouter devDependency supertest ou conditionner les tests d’API.
   • Enrober les rendus dépendants du router par MemoryRouter.
   • Mocker les appels réseaux (collectors) et I/O (OCR/Sharp).
   • Éviter l’écoute du port 3001 pendant les tests.
3. Markdownlint
   • Mettre à jour le script mdlint pour ignorer backend/node_modules et autres dossiers de dépendances (appr. requise).
4. Documentation
   • Poursuivre l’alignement sur ExtractionResult et documenter les champs backend réels dans docs/API_BACKEND.md.

Demandes d’approbation

• Puis-je modifier package.json (script mdlint) pour ajouter --ignore backend/node_modules ?
• Souhaitez-vous ajouter supertest en devDependency afin de rétablir tests/api.test.js et tests/e2e.test.js ?

Prochaines actions proposées

• Corriger une première tranche d’erreurs any dans src/services/backendApi.ts et src/store/index.ts.
• Mettre à jour tests/ExtractionView.tabs.test.tsx pour utiliser MemoryRouter.
• Ajouter des mocks pour fetch dans tests/collectors.test.js et des fixtures/mocks OCR.