PD-103 — Agent Developer — Module capture-ocr (M3)¶

1. Identite¶

2. Fichiers produits¶

3. Invariants couverts¶

4. Criteres d'acceptation couverts¶

5. Matrice de couverture tests contractuels¶

6. Tests additionnels (non contractuels)¶

7. Couverture¶

8. Architecture¶

8.1 Interface abstraite OcrEngine¶

interface OcrEngine {
  recognizeText(imageBytes: Uint8Array): Promise<RawOcrResult>;
}

Pattern identique a KekProvider (M2) : interface abstraite permettant : - MockOcrEngine pour les tests (resultat deterministe configurable) - NoOpOcrEngine pour les environnements sans Vision natif (Expo Go, simulateur) - Implementation native Apple Vision a venir (native module React Native)

8.2 OcrService¶

Service principal consomme par l'orchestrateur (M6) :

OcrService.extract(imageBytes, enabled)
  |
  +-- enabled=false → null (CA-103-05)
  +-- imageBytes vide → null
  +-- try {
  |     engine.recognizeText(imageBytes) → RawOcrResult
  |     sanitizeOcrText(raw.text) → NFC + strip C0/C1
  |     clampOcrConfidence(raw.confidence) → [0.0, 1.0]
  |     validateOcrLanguage(raw.language) → BCP-47 ou fallback
  |     → OcrResult { ocrText, ocrConfidence, ocrLanguage }
  |   }
  +-- catch → null (INV-103-04, INV-103-05)

8.3 Sanitisation contractuelle (§5.1)¶

• NFC : String.prototype.normalize("NFC") — normalisation Unicode
• C0 strip : [\x00-\x08\x0B\x0C\x0E-\x1F] supprime (conserve TAB \x09, LF \x0A, CR \x0D)
• C1 strip : [\x7F-\x9F] supprime
• Longueur max : 20000 chars post-sanitisation, rejet si depasse (pas de troncature — §5.1)

9. Decisions architecturales¶

Decision 1 : Interface abstraite OcrEngine¶

• Decision : Abstraire le moteur OCR derriere une interface OcrEngine
• Rationale : Apple Vision n'est disponible qu'en environnement natif iOS ; les tests unitaires tournent en Jest/jsdom sans acces au framework natif
• Alternatives considerees : (1) Mock inline du module natif dans jest.config.js, (2) Conditionnel Platform.OS dans le service
• Trade-offs : Indirection supplementaire vs testabilite complete + swap facile de l'implementation native

Decision 2 : Absorption des erreurs dans le service (pas dans l'orchestrateur)¶

• Decision : Le try/catch absorbant est dans OcrService.extract(), pas dans l'orchestrateur M6
• Rationale : INV-103-04 et INV-103-05 sont des invariants du module OCR ; la responsabilite de non-blocage appartient au service OCR, pas a l'appelant
• Alternatives considerees : (1) Laisser l'orchestrateur catch, (2) Pattern Result
• Trade-offs : L'orchestrateur ne voit jamais d'erreur OCR, simplifie M6 ; perte de visibilite erreur (acceptable car OCR est optionnel)

10. Hypotheses¶

11. Dependances¶

Consomme par ce module¶

Consomme ce module¶

12. Verification qualite¶