245 lines
14 KiB
Markdown
245 lines
14 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.
|
||
|
||
## 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
|
||
|
||
```bash
|
||
# 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.
|