datakeen-session-react 1.1.140-dev.71 → 1.1.140-dev.72

package/CLAUDE.md

@@ -0,0 +1,227 @@
+# CLAUDE.md — Client Sessions React SDK
+
+## Vue d'ensemble
+
+Librairie React TypeScript servant d'orchestrateur côté client pour les parcours d'onboarding Datakeen (journeys). Publiée sur npm sous `datakeen-session-react`. Elle gère la navigation entre nœuds, la collecte de données (formulaires, documents, biométrique), le polling asynchrone des analyses et l'historique de navigation.
+
+**Stack :** React 18 (peer dep), TypeScript, Axios, i18next, Radix UI, TensorFlow (ML documents), Rollup (build ESM + CJS).
+
+**Tests :** Jest + React Testing Library.
+
+**Point d'entrée :** `src/components/DatakeenSession.tsx`
+
+---
+
+## Structure du projet
+
+```
+client-sessions-react-sdk/
+├── src/
+│   ├── components/
+│   │   ├── session/            # Orchestration session (SessionContent, UserInputForm)
+│   │   ├── template/           # Rendu nœuds (TemplateNodeRenderer, ConditionNodeHandler)
+│   │   ├── document-collection/
+│   │   ├── selfie/, id-check/, jdi/, signature-electronic/
+│   │   ├── start-flow/, end-flow/
+│   │   └── ui/                 # Composants réutilisables internes
+│   ├── hooks/
+│   │   ├── useStepNavigation.ts # Historique + navigation (CRITIQUE)
+│   │   ├── useSessionData.ts    # Chargement et synchro données
+│   │   ├── useTemplateLoader.ts # Résolution template
+│   │   └── useStepCSS.ts        # Styles dynamiques par nœud
+│   ├── services/
+│   │   ├── sessionService.ts    # API session + getOrderedJourneySteps
+│   │   ├── pollingService.ts    # Polling analyses documentaires
+│   │   ├── retryService.ts      # Gestion retryCounts
+│   │   └── ...
+│   ├── context/
+│   │   ├── SessionContext.tsx   # État session global
+│   │   ├── ConfigContext.tsx
+│   │   └── DocumentContext.tsx
+│   ├── types/
+│   │   ├── session.ts           # SessionTemplateNode, SessionTemplateEdge, CustomField
+│   │   └── ...
+│   ├── utils/
+│   │   ├── conditionEvaluator.ts # Évaluation conditions
+│   │   ├── cssLoader.ts          # Injection CSS dynamique
+│   │   └── documentLabels.ts
+│   └── i18n/
+│       ├── fr.json, en.json
+│       └── country/, documents/
+├── docs/                         # Documentation — LIRE EN PREMIER
+├── rollup.config.js              # Build production (ESM + CJS)
+└── dist/                         # Artefacts buildés (ne pas modifier)
+```
+
+---
+
+## Règles impératives
+
+### Avant de coder
+
+**Lire `docs/`** en premier :
+- `POLLING_SYSTEM.md` — spec complète polling v2.0.0
+- `navigation-history.md` — pièges navigation
+- `multi-runs.md` — convention `_list`
+- `JOURNEY_NODE_BUILDER.md` — checklist ajout nœud
+- `sdk_integration_guide.md` — intégration consommateur
+
+### Navigation entre nœuds
+
+Le fichier central est `src/hooks/useStepNavigation.ts`. Respecter strictement l'API :
+
+```typescript
+// ✅ Avancer vers le prochain nœud (résout via les edges du graphe)
+goToNextStep(nodeId, template, handle?)
+
+// ✅ Revenir en arrière (dépile l'historique)
+goBack()
+
+// ✅ Naviguer directement (cas spéciaux uniquement)
+setStep(n, skipHistory?)
+
+// ❌ Ne jamais faire ça
+setStep(step - 1) // arithmétique manuelle = bugs de navigation
+```
+
+**Index de navigation :**
+- `step=0` : écran de démarrage
+- `step=0.5` : QR code (si configuré)
+- `step≥1` : nœuds du template (1-indexed, triés par `order`)
+
+### Types de nœuds
+
+| Type | Description | Sorties |
+|------|-------------|---------|
+| `information-input` | Formulaires avec champs optionnellement verrouillés | 1 |
+| `document-selection` | Choix de document | 1 |
+| `document-collection` | Upload document + polling | 1 |
+| `controle-jdi` | Analyse JDI avec polling | 1 |
+| `selfie-capture` / `biometric-capture` | Biométrie | 1 |
+| `condition` | Branchement conditionnel (évalue `conditionTokens`) | 2 : `true` / `false` |
+| `end` | Fin de session | 0 |
+
+Le dispatcher est `src/components/template/TemplateNodeRenderer.tsx`.
+
+**Checklist ajout d'un nœud :**
+1. Ajouter le type dans `src/types/session.ts`
+2. Créer le composant dans `src/components/`
+3. Ajouter le case dans `TemplateNodeRenderer.tsx`
+4. Ajouter les traductions FR/EN dans `src/i18n/`
+5. Gérer `goToNextStep` à la complétion du nœud
+6. Gérer `goBack()` si le nœud a un bouton retour
+7. Tester avec les cas : nœud auto-exécutant → doit être sauté par `goBack()`
+
+### Système de polling
+
+Codes de résultat d'une analyse documentaire :
+
+| Code | Signification | Action |
+|------|---------------|--------|
+| `1.0` | Approuvé | `goToNextStep` |
+| `2.0` | Rejeté | Retry possible |
+| `3.0` | Erreur | Retry possible |
+| `4.0` | En vérification manuelle | Attendre |
+
+```typescript
+// Pattern polling
+pollingService.poll(analysisId, {
+  onProgress: (pct) => setProgress(pct), // 50% → analysisId absent, 100% → résultat
+  onComplete: (code, message) => handleResult(code),
+  interval: 2000,
+});
+```
+
+### Champs verrouillés (`lockedFromApi`)
+
+Définis dans `CustomField.lockedFromApi`. Le SDK **ne doit pas les afficher** à l'utilisateur :
+
+```typescript
+// Dans CustomFormFields.tsx — filtrer avant rendu
+const visibleFields = fields.filter(f => !f.lockedFromApi);
+```
+
+Le backend réinjecte la valeur originale via `stripLockedFields()` (protection côté serveur contre la manipulation). Ne jamais contourner ce mécanisme.
+
+### Multi-runs (convention `_list`)
+
+Cas : session avec plusieurs bénéficiaires passés à la création.
+
+```json
+{
+  "userInput": {
+    "_list": [
+      { "firstName": "Alice", "lastName": "Dupont" },
+      { "firstName": "Bob", "lastName": "Martin" }
+    ]
+  }
+}
+```
+
+- `session.retryCounts[nodeId]` = index du run courant (0-indexed)
+- Incrémenté automatiquement par `ConditionNodeHandler` en mode boucle
+- SDK sélectionne `_list[runIndex]` pour pré-remplir les formulaires
+- Si hors borne → formulaire vide (comportement attendu)
+
+### Historique de navigation (reconstruction)
+
+Au rechargement, l'historique est reconstruit depuis `initialStep` via `reconstructHistoryToStep()` dans `sessionService.ts`. La reconstruction suit la **première edge sortante** de chaque nœud — elle **ne reconnaît pas** les branches conditionnelles complexes. C'est une limitation connue et documentée.
+
+### Internationalisation
+
+- Toutes les chaînes visibles dans `src/i18n/fr.json` et `en.json`.
+- Ne jamais hardcoder de texte affiché à l'utilisateur.
+
+### Styles dynamiques
+
+- CSS chargé via `cssLoader.ts` selon `node.styles` (injection dynamique).
+- Fallback sur Tailwind pour les composants par défaut.
+- Ne pas utiliser de style inline.
+
+---
+
+## Build et publication
+
+```bash
+# Build de la librairie (ESM + CJS)
+npm run build   # ou pnpm build
+
+# Tests
+npm test
+
+# Développement avec watch
+npm run dev
+```
+
+Rollup génère deux artifacts dans `dist/` :
+- `dist/esm/index.js` — pour les bundlers modernes (import)
+- `dist/cjs/index.js` — pour CommonJS (require)
+- `dist/types/index.d.ts` — typages TypeScript
+
+**Ne jamais modifier `dist/` manuellement** — régénéré à chaque build.
+
+---
+
+## Fichiers critiques
+
+| Fichier | Rôle |
+|---------|------|
+| `src/components/DatakeenSession.tsx` | Point d'entrée public de la librairie |
+| `src/hooks/useStepNavigation.ts` | Navigation + historique (NE PAS casser l'API) |
+| `src/hooks/useSessionData.ts` | Chargement et synchro état session |
+| `src/components/template/TemplateNodeRenderer.tsx` | Dispatcher de rendu par type de nœud |
+| `src/services/sessionService.ts` | API session + `getOrderedJourneySteps` + `reconstructHistoryToStep` |
+| `src/services/pollingService.ts` | Polling analyses (voir `docs/POLLING_SYSTEM.md`) |
+| `src/utils/conditionEvaluator.ts` | Évaluation des conditions de branchement |
+| `src/types/session.ts` | Contrats de données principaux |
+
+---
+
+## À ne jamais faire
+
+- Utiliser `setStep(step - 1)` pour le retour — utiliser `goBack()`.
+- Appeler `setStep` directement pour avancer — utiliser `goToNextStep`.
+- Afficher un champ avec `lockedFromApi: true`.
+- Modifier les fichiers dans `dist/` — ils sont générés.
+- Introduire une dépendance directe vers le backend ou le frontend Datakeen — le SDK est agnostique.
+- Ajouter des dépendances `dependencies` qui devraient être en `peerDependencies` (React, Axios).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datakeen-session-react",
-  "version": "1.1.140-dev.71",
+  "version": "1.1.140-dev.72",
   "description": "React SDK component to manage and render Datakeen session experiences easily.",
   "publishConfig": {
     "access": "public",