Flow Fix

flow-fix

Corrige un bug ou etend un flow d'automatisation existant.

Declenchement

/flow-fix {platform} {product} "{description}"

Exemples :

• /flow-fix alptis sante-select "Le dropdown ville ne se remplit plus"
• /flow-fix swisslifeone slsis "Ajouter support pour 3+ enfants"
• /flow-fix alptis sante-pro-plus "Erreur sur leads TNS"

Journal de bord

IMPORTANT : Tout au long du processus, maintenir un fichier journal qui documente chaque action.

Fichier journal

.claude/flow-logs/{platform}-{product}-fix-{slug}.md

Format du journal

# Journal de fix : {platform} {product}

**Probleme** : {description originale}
**Debut** : {date et heure}
**Branche** : fix/{platform}-{product}-{slug}
**Status** : EN COURS | TERMINE | BLOQUE

---

## Phase 1 : Diagnostic
**Debut** : {timestamp}

### Reproduction du probleme
- Test LEAD_INDEX=0 : PASS
- Test LEAD_INDEX=1 : FAIL
- Test LEAD_INDEX=2 : PASS

### Lead problematique identifie
- Lead #1 : Jean DUPONT
- Caracteristiques : TNS, profession "consultant senior"

### Analyse des logs

Error: Unable to find element matching selector "#profession-select" at Section2Fill.fillProfession (Section2Fill.ts:45)

### Cause identifiee
**Type** : Selector casse
**Fichier** : `selectors/section2.ts`
**Ligne** : 23
**Detail** : L'ID du dropdown profession a change de "#profession-select" vers "#categories-socio-professionnelles-adherent"

**Fin** : {timestamp}
**Duree** : 8 min

---

## Phase 2 : Correction
**Debut** : {timestamp}

### Fichiers modifies
1. `src/main/flows/platforms/{platform}/products/{product}/steps/form-fill/selectors/section2.ts`
   - Ligne 23 : Changement du selector profession
   - Ajout d'un selector alternatif

### Code modifie
```typescript
// AVANT
profession: {
  primary: '#profession-select',
  stability: 'UNSTABLE',
},

// APRES
profession: {
  primary: '#categories-socio-professionnelles-adherent',
  alternative: "select[name*='profession']",
  stability: 'STABLE',
},

Fin : {timestamp} Duree : 5 min Commit : fix(alptis/sante-select): update profession selector

Phase 3 : Validation

Debut : {timestamp}

Test cas specifique

• LEAD_INDEX=1 : PASS

Bulk validation

• Premier run : 22/22 PASS
• Non-regression : OK

Fin : {timestamp} Duree : 3 min Commit : test(alptis/sante-select): verify fix with bulk validation

Phase 4 : Finalisation

Debut : {timestamp}

Resume

• Probleme : Selector profession casse
• Cause : Changement d'ID sur le site Alptis
• Solution : Mise a jour du selector avec alternative
• Impact : Aucune regression

Tests finaux

• Lead specifique : PASS
• Bulk validation : 22/22 PASS
• Non-regression : PASS

Fin : {timestamp} Status : PRET POUR MERGE

Resume

• Temps total : 18 min
• Commits : 2
• Fichiers modifies : 1
• Tests : 22/22 PASS
• Status : TERMINE

### Regles du journal

1. **Creer le fichier au debut** de la Phase 1
2. **Mettre a jour en temps reel** a chaque action
3. **Documenter la cause** du probleme en detail
4. **Inclure le code modifie** (avant/apres)
5. **Noter tous les resultats de tests**
6. **Conserver le journal** meme apres merge (historique)

---

## Workflow

### Phase 1 : Diagnostic

1. **Creer la branche de fix**
   ```bash
   # Slug = 3-4 premiers mots de la description, kebab-case
   git checkout -b fix/{platform}-{product}-{slug}

Exemples :

• fix/alptis-sante-select-dropdown-ville
• fix/swisslifeone-slsis-support-3-enfants

2. Reproduire le probleme (headless)

   LEAD_INDEX=0 npx playwright test e2e/{platform}/{product}/single-lead-journey.spec.ts
   

   Si le test passe, essayer avec d'autres leads :

   LEAD_INDEX=1 npx playwright test e2e/{platform}/{product}/single-lead-journey.spec.ts
   LEAD_INDEX=2 npx playwright test e2e/{platform}/{product}/single-lead-journey.spec.ts
   

3. Identifier la cause

   Symptome	Cause probable	Fichiers a verifier
   Element not found	Selector casse	platforms/{platform}/products/{product}/steps/form-fill/selectors/*.ts
   Wrong value selected	Mapper incorrect	platforms/{platform}/products/{product}/transformers/mappers/*.ts
   Validation error	Transformer ou validator	transformers/LeadTransformer.ts, validators/*.ts
   Timeout	Timing issue	steps/form-fill/operations/*.ts, config timeouts
   Champ manquant	Nouveau champ sur le formulaire	Cartographie + selectors
   Test passe mais mauvaise valeur	Verifier le mapping	mappers/*.ts, LeadTransformer.ts

4. Analyser les logs

   # Les screenshots sont captures en cas d'erreur
   ls -la test-results/
   ls -la artifacts/
   

5. Inspecter le formulaire si necessaire (headless)

   npx playwright test e2e/{platform}/{product}/.detailed/explore-selectors.spec.ts
   

Phase 2 : Correction

Appliquer le fix minimal selon le cas identifie :

Cas 1 : Selector casse

Le site a change et l'ID ou la classe n'existe plus.

// selectors/section2.ts

// AVANT (UUID qui a change)
nom: {
  primary: '#f2d8ce6f-b18a-4f27-900d-1c10eb9bf440',
  stability: 'UNSTABLE',
},

// APRES (selector plus stable)
nom: {
  primary: "input[class*='totem-input__input'][placeholder*='nom']",
  alternative: "label:has-text('Nom') + input",
  fallback: "#nom",
  stability: 'MODERATE',
},

Fichiers a modifier :

• src/main/flows/platforms/{platform}/products/{product}/steps/form-fill/selectors/*.ts

Cas 2 : Mapper incorrect

Une valeur du lead n'est pas correctement mappee.

// mappers/profession-mapper.ts

const PROFESSION_MAPPING: Record<string, string> = {
  // ...existing mappings

  // AJOUTER le nouveau cas
  'consultant independant': 'PROFESSIONS_LIBERALES',
  'auto-entrepreneur': 'ARTISANS_COMMERCANTS',
};

Fichiers a modifier :

• src/main/flows/platforms/{platform}/products/{product}/transformers/mappers/*.ts

Cas 3 : Timing issue

Le formulaire a besoin de plus de temps pour charger.

// operations/DropdownOperations.ts

// AVANT
await page.click(selector);
await page.waitForTimeout(300);

// APRES (attente explicite)
await page.click(selector);
await page.waitForSelector('.dropdown-options', { state: 'visible', timeout: 5000 });
await page.waitForTimeout(500); // Animation

Fichiers a modifier :

• src/main/flows/platforms/{platform}/products/{product}/steps/form-fill/operations/*.ts
• src/main/flows/config/{platform}.config.ts (pour les timeouts globaux)

Cas 4 : Nouveau champ sur le formulaire

Le site a ajoute un nouveau champ obligatoire.

1. Mettre a jour la cartographie :

   // cartography/{platform}/{platform}-{product}-exhaustive-mapping.json
   {
     "fields": [
       // ... existing
       {
         "field_id": "nouveau_champ",
         "section": "Section X",
         "type": "text",
         "selector": {
           "primary": "#nouveau-champ",
           "stability": "STABLE"
         },
         "validation": { "required": true }
       }
     ]
   }
   

2. Ajouter le selector :

   // selectors/sectionX.ts
   export const SECTION_X_SELECTORS = {
     // ... existing
     nouveau_champ: {
       primary: '#nouveau-champ',
       stability: 'STABLE',
     },
   };
   

3. Etendre les types :

   // transformers/types.ts
   export type FormData = {
     // ... existing
     nouveau_champ?: string;
   };
   

4. Mettre a jour le transformer :

   // transformers/LeadTransformer.ts
   return {
     // ... existing
     nouveau_champ: lead.subscriber.nouveau_champ ?? 'valeur_defaut',
   };
   

5. Mettre a jour le SectionFill :

   // sections/SectionXFill.ts
   if (data.nouveau_champ) {
     await page.locator(SELECTORS.nouveau_champ.primary).fill(data.nouveau_champ);
   }
   

Fichiers a modifier :

• src/main/flows/cartography/{platform}/*.json
• src/main/flows/platforms/{platform}/products/{product}/steps/form-fill/selectors/*.ts
• src/main/flows/platforms/{platform}/products/{product}/transformers/types.ts
• src/main/flows/platforms/{platform}/products/{product}/transformers/LeadTransformer.ts
• src/main/flows/platforms/{platform}/products/{product}/steps/form-fill/sections/*.ts

Cas 5 : Extension (nouveau cas d'usage)

Exemple : supporter 3+ enfants au lieu de 2.

1. Identifier les limites actuelles
2. Modifier la logique dans FormFillOrchestrator
3. Ajouter des tests pour le nouveau cas
4. Generer des leads de test si necessaire

COMMIT : fix({platform}/{product}): {description courte}

Phase 3 : Validation

1. Tester le cas specifique (headless)

   LEAD_INDEX={index_du_lead_problematique} npx playwright test e2e/{platform}/{product}/single-lead-journey.spec.ts
   

2. Non-regression : bulk test (headless)

   npx playwright test e2e/{platform}/{product}/bulk-validation.spec.ts
   

3. Si modification dans du code partage (engine, config commune) :

   # Tester TOUS les flows affectes
   npx playwright test e2e/alptis/sante-select/bulk-validation.spec.ts
   npx playwright test e2e/alptis/sante-pro-plus/bulk-validation.spec.ts
   npx playwright test e2e/swisslifeone/slsis/bulk-validation.spec.ts
   

COMMIT : test({platform}/{product}): verify fix with bulk validation

Phase 4 : Finalisation

Quand tous les tests passent :

Fix applique pour {platform}_{product}.

Probleme: {description originale}
Cause: {cause identifiee}
Solution: {description de la solution}

Tests:
- Lead specifique: PASS
- Bulk validation: {n}/{n} PASS
- Non-regression: PASS

Prochaine etape: merge de la branche

Demander a l'utilisateur s'il veut :

1. Merger la branche
2. Voir les details du fix
3. Faire des ajustements supplementaires

Patterns de debug courants

Ajouter des logs

logger?.debug('Filling field', { selector, value, fieldIndex });
logger?.info('Section completed', { sectionName, duration });

Prendre un screenshot pour debug

await page.screenshot({ path: `debug-${stepId}-${Date.now()}.png` });

Afficher l'etat du DOM

const html = await page.locator(selector).innerHTML();
console.log('DOM state:', html);

Verifier existence et visibilite

const count = await page.locator(selector).count();
const isVisible = await page.locator(selector).isVisible();
console.log({ selector, count, isVisible });

Inspecter tous les elements similaires

const inputs = await page.locator('input').all();
for (const [i, input] of inputs.entries()) {
  const id = await input.getAttribute('id');
  const name = await input.getAttribute('name');
  const visible = await input.isVisible();
  console.log(`Input ${i}: id=${id}, name=${name}, visible=${visible}`);
}

Fichiers de reference

Conventions

Format branche

fix/{platform}-{product}-{slug}

Le slug = 3-4 premiers mots de la description, en kebab-case.

Format commits

fix({platform}/{product}): {description courte}

- Detail du probleme
- Solution appliquee

Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Checklist

• Branche fix/{platform}-{product}-{slug} creee
• Probleme reproduit
• Cause racine identifiee
• Fix minimal applique
• Test du cas specifique: PASS (headless)
• Bulk validation: 100% PASS (headless)
• Non-regression verifiee (si code partage)
• Commits descriptifs
• Cartographie mise a jour (si nouveau champ)