aad52027c1
- Alignement backend: seules 4 entités retournées (persons, companies, addresses, contractual) - Version API mise à jour à 1.0.1 dans /api/health - Interface onglets d entités: Personnes, Adresses, Entreprises, Contractuel - Correction erreurs TypeScript pour build stricte - Tests et documentation mis à jour - CHANGELOG.md mis à jour avec version 1.1.1
169 lines
10 KiB
Markdown
169 lines
10 KiB
Markdown
# 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.
|