# 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.