# Journal d'incident - 2025-09-16

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