Files
Kazier/V3.md
T
venture ac8bd9acb4 V3 S3 : correction des faits (fiche document + correct_facts)
Backend : CorrectFacts (editor+, validation Go -> 400 jamais 500),
op outbox correct_facts (full-replace jeu user), PATCH
/files/:id/facts (renvoie jeu complet). Tests service + sync + handlers.

Mobile (Room v20) : table resource_facts + FactsDao, FactsRepository
(sync remplace-en-bloc, correction optimiste + outbox atomique),
fiche « Ce qu'on a compris » sur le viewer (chips, suggéré grisé,
édition par type, reset auto), bouton viewer si processed, FR/EN.

Contrat docs/api-v1.md, V3.md (S1-S3 livrés, FTS -> v21).
2026-09-26 10:28:33 +02:00

20 KiB
Raw Blame History

Kazier V3 — « Le classeur qui comprend »

Statut : vision validée (2026-09-25). V1 (1.0.0, socle local-first + partage) et V2 (1.1.0, multi-device : upload/download, placements, rétention, groupes) sont livrées. Ce document est le contrat produit + plan d'exécution de la V3.

1. Positionnement (acté)

  • Tout fichier est un document potentiel, y compris une photo. Une image (scan, photo de papier, photo tout court) suit le même pipeline : OCR quand il y a du texte, faits génériques, FTS, relations. En revanche aucune analyse biométrique ou sémantique d'image : pas de visages, pas de lieux, pas d'événements, pas de clustering de personnes. Si une photo contient du texte (affiche, facture photographiée), on l'exploite ; sinon elle reste un fichier comme un autre (nom, dossier, favori, partage).
  • Tous les documents comptent pareil. Pas de top-5 types prioritaires. Extraction générique d'abord (dates, montants, émetteurs, références), typage (facture, contrat…) en bonus humble : suggestion corrigeable, jamais gate, jamais pénalisant.
  • Humble par design. L'extraction se trompe (~20% au début). Donc : chaque fait porte une confidence, l'UI affiche le douteux en « suggéré », la recherche déclasse mais n'exclut jamais sur un fait douteux, et tout est corrigeable en un tap.
  • Échéance = facette, pas alerte. Trop bruitée pour notifier (faux « expiré » dangereux). Filtre + tri uniquement. Alertes = V4 éventuelle, sur preuve de fiabilité via feedback.
  • 100% self-hosté / local-first. Aucun appel IA externe. Règles FR + petits modèles CPU côté serveur, cache Room offline, workers async jamais bloquants (même pattern que Ocr.Run).
  • Pas de LLM génératif en V3. On extrait des faits vérifiables, on ne rédige rien. Moins d'hallucinations, moins de GPU, plus de confiance famille.

2. Les 5 piliers (cœur, scope 6–8 semaines)

# Pilier Promesse Réutilise
P1 Filet anti-perte Corbeille 30j + versions N=3 deleted_at soft-delete, UPLOAD_DIR/<user>/<resource>.<ext>, overwrite ciblée V2
P2 Extract générique Faits universels + type suggéré, corrigés depuis la fiche document Pipeline upload ciblé → Tesseract → resources.ocr_text → GET /files/:id/ocr, gate processed
P3 Recherche FTS nom+ocr+faits, facettes, offline FileDao.searchWithFilters (LIKE+accents), GET /files/search serveur
P4 Relations doc same_scan (sûr) + doublons/versions/même-émetteur (invalidables), collections virtuelles scan_sessions+scan_pages, content_hash (V2.md), versions P1
P5 Partage sobre Cercles (groupes V2-6), liens à expiration par défaut, révocation tokens, quota/3-2-1 visible Snapshot permissions + TTL 24h, share/create_link, PATCH /users/me/password

2bis. Plan A — cohérence obligatoire (inclus dans la V3, pas du scope en plus)

Sans ces 4 items, les piliers grincent. Ils sont petits et intégrés aux slices S1–S6 :

  • A1 Appareils connectés : exposer storage_locations (existe depuis V2, migration 000015) en lecture GET /devices + DELETE /devices/:id (révocation = bump token_version ciblé ou suppression ligne ; le device révoqué retombe en 401 → re-login refusé INVALID_DEVICE_ID). Écran Réglages « Appareils » : voir / révoquer un téléphone perdu. Grosse valeur famille, ~1 endpoint + 1 écran.
  • A2 Quota enforcement : /usage (P5) n'est que de l'affichage. Ajouter users.storage_quota_bytes (défaut 10 Go, cf. V2.md §3.1) + garde-fou à l'upload (413 QUOTA_EXCEEDED) + à l'overwrite versionnée. Migration 000023_quota. Sans ça, un foyer remplit le disque.
  • A3 Corbeille cohérente des deux côtés : règle purge serveur (cron au boot + passe quotidienne : trashed_at < NOW()-30j → purge dure) + miroir mobile (trashed_at Room, filtre global exists=1 AND trashed_at IS NULL, écran Corbeille). Le walk SAF doit ignorer les trashés (garde hasPendingTrash, même pattern que FEEDBACK M5) sinon ils ressuscitent. Fait partie de S1, pas une option.
  • A4 Conflits rename transparents : update_metadata concurrent (2 devices renomment) = last-writer-wins silencieux aujourd'hui. Minimum V3 : comparer updated_at (perdant = op arrivée sur updated_at plus récent que son base_updated_at → appliquée quand même mais flag conflict remonté dans la réponse POST /sync/ops + badge UI « renommé ailleurs » via snapshot). Pas de CRDT, juste de la transparence. Payload update_metadata étendu : { name?, baseUpdatedAt? }.

2ter. Plan B — quick wins produit (inclus : B1, B2, B4 ; B3/B5 en stretch)

  • B1 Import « classeur » unifié : un seul point d'entrée « Ajouter un papier » (scan / photo / PDF / fichier) + file d'attente d'import visible (compteur unprocessed, déjà en Room). Aujourd'hui scan + upload + PDF builder sont 3 chemins séparés — les unifier en UX, zéro backend nouveau. Inclus (S6).
  • B2 Doublons visibles + action : duplicate_of (P4, hash) exposé en écran « Doublons (240 Mo récupérables) » + action « garder un seul » (= trash les autres, même op trash_resource). Les familles adorent. Inclus (S5).
  • B3 Impression / export PDF : ouvrir le PDF builder existant aux docs déjà stockés (pas qu'au multi-select) + ACTION_SEND / impression système. Stretch S7 (pur mobile, pas de backend).
  • B4 Accessibilité + i18n : labels TalkBack sur review/chips/facettes, contrastes, chaînes FR/EN des nouveaux écrans dès la slice (pas de rattrapage). Inclus, transverse à chaque slice.
  • B5 Onboarding foyer : écran « Crée ton cercle Famille » au premier login + import guidé des 3 premiers papiers (deep-link vers B1 + création groupe V2-6 pré-rempli). Sans ça, les cercles P5 restent vides. Stretch S6 si le temps manque (1 écran + 1 CTA, pas de backend).

2quater. Plan C — dette V2.md : solder ou enterrer (décisions actées)

  • C1 retention_policies serveur (V2.md §3.6) : ENTERRÉ. La rétention V2 mobile (RetentionStore + RetentionWorker) fait le job ; une politique serveur ajouterait un 2e cerveau en conflit avec le walk local-first. Documenter dans docs/api-v1.md : « la rétention est une affaire locale ».
  • C2 sync_queue serveur (V2.md §3.7) : ENTERRÉ. L'outbox client (pending_operations + batch 20 + dead-letter) + workers WM couvrent le besoin. Ne pas rouvrir.
  • C3 Backup 3-2-1 réel : EXPORT, pas second serveur. role='backup' reste un modèle, pas une infra. Minimum V3 : bouton « Exporter tout » (zip + manifest resource_id, name, hash, facts) depuis Réglages/Stockage — testé, restaurable, chiffré par le mot de passe (zip AES). Stretch S7, à arbitrer contre les embeddings : l'export gagne (vrai 3-2-1 perçu, zéro GPU).

3. Backend — plan fichier par fichier

3.1 Migrations (backend/db/migrations/, une par palier, up+down + migrations_test.go)

  • 000017_trash : rien à créer — ajouter index partiel idx_resources_deleted_at ON resources(deleted_at) WHERE deleted_at IS NOT NULL + colonne trashed_at TIMESTAMPTZ (NULL = vivant ; purge = trashed_at < NOW()-30j). Le DELETE actuel devient trash (soft), pas de breaking change API.
  • 000018_versions : table resource_versions (id 32-hex PK, resource_id FK CASCADE, version_no INT, size_bytes BIGINT, content_hash TEXT, stored_path TEXT, created_at) + UNIQUE(resource_id, version_no). À chaque overwrite d'octets (upload ciblé), la copie précédente est poussée en version (garder N=3, purger la plus vieille).
  • 000019_facts : table resource_facts (id 32-hex PK, resource_id FK CASCADE, fact_type TEXT CHECK IN ('date','due_date','period','amount','issuer','reference','doc_type'), value_text TEXT, value_num NUMERIC NULL, value_date DATE NULL, confidence REAL CHECK 0..1, origin TEXT CHECK IN ('auto','user'), created_at, updated_at) + index (resource_id), (fact_type, value_text). doc_type n'est qu'un fait comme un autre (suggestion, pas statut).
  • 000020_links : table resource_links (id 32-hex PK, from_id FK CASCADE, to_id FK CASCADE, link_type TEXT CHECK IN ('same_scan','duplicate_of','version_of','same_issuer','same_reference'), confidence REAL, created_by TEXT CHECK IN ('auto','user'), CHECK(from_id != to_id), UNIQUE(from_id,to_id,link_type)).
  • 000021_token_version : ALTER TABLE users ADD COLUMN token_version INT NOT NULL DEFAULT 0 — PATCH /users/me/password bump ; claim paseto tv, middleware RequireAuth rejette tv != users.token_version (lève la limite V1 « tokens non révoqués »).
  • 000022_search_fts : colonne search_tsv TSVECTOR sur resources (générée : name + ocr_text ; les facts sont joints à la requête, pas dupliqués) + index GIN + trigger UPDATE sur name/ocr_text. Fait après P2 pour ne pas indexer du vide.
  • 000023_quota (A2) : ALTER TABLE users ADD COLUMN storage_quota_bytes BIGINT NOT NULL DEFAULT 10737418240 (10 Go, V2.md §3.1) + vue/fonction user_used_bytes(user_id) (somme size_byteshors trash). Check à l'upload et à l'overwrite versionnée → 413 QUOTA_EXCEEDED (nouveau code §7).

3.2 Extract — nouveau worker (miroir service/ocr.go, cmd/server/main.go)

  • Nouveau backend/extract/rules.go : pur package, testable sans PG — entrée text string, sortie []Fact{Type, ValueText/Num/Date, Confidence}. Règles FR : dates (12/03/2026, mars 2026, échéance ..), montants (1 234,56 €, EUR), raisons sociales (ligne en capitales + SIRET/SIREN voisin), références (n°, facture n°, contrat, IBAN masqué → on ne stocke que les 4 derniers chiffres).
  • Nouveau backend/service/extract.go : struct Extract{Repository} + Run(ctx) — même squelette que Ocr.Run (poll file, FOR UPDATE SKIP LOCKED, QueuePollInterval, ResetStale au boot). Déclencheur : après chaque OCR done avec texte non vide (appel direct Extract.Enqueue/Process depuis Ocr.process, pas de nouvelle file PG — une colonne extract_status sur ocr_jobs ou simple appel synchrone borné suffit en V3).
  • backend/repository/facts.go : UpsertAuto(resourceID, facts) (remplace les origin='auto', ne touche jamais aux origin='user'), Correct(resourceID, facts) (écrit origin='user', confidence 1.0), ListForResource, SearchFacets(...).
  • backend/repository/links.go : EnsureAuto (idempotent, upsert par (from,to,type)), SetUserVerdict (confirme/invalide → created_by='user', confidence 0/1), ListForResource. Règles auto V3 : same_scan (déterministe depuis scan_sessions — en fait côté mobile, voir §4, serveur : duplicate_of via content_hash égal, version_of via resource_versions, same_issuer via facts issuer normalisé identique + confidence = min des deux facts).
  • backend/service/resources.go : trash/restore/purge (Trash = set trashed_at, Restore = NULL, Purge = hard delete + versions + faits + liens + fichier physique) ; overwrite d'octets → pousser l'ancienne copie en resource_versions avant écriture.
  • backend/service/sync.go : nouvelles ops outbox trash_resource / restore_resource / purge_resource / correct_facts (même enveloppe §6.1, operation_id 32-hex, idempotence (device_id, operation_id), arrêt au premier échec non-idempotent). delete_resource legacy → mappé vers trash_resource (pas de break client existant). correct_facts porte [{fact_type, value, confidence}], applique Correct (writer = user, écrase l'auto).
  • backend/handlers/ : GET /trash (liste trashed, paginé, même enveloppe {data,meta}), POST /files/:id/restore, DELETE /files/:id?mode=purge (défaut trash ; purge = définitif), GET /files/:id/versions + POST /files/:id/versions/:n/restore, GET /files/:id/facts + PATCH /files/:id/facts (correction directe, même sémantique que correct_facts), GET /files/:id/links, GET /users/me/usage (quota + copies 3-2-1 : used_bytes, quota_bytes, copies, offsite_ok), GET /devices + DELETE /devices/:id (A1, lecture storage_locations + révocation), GET /export (C3, zip + manifest, streamé). Tous scopés viewer+ lecture / owner mutation sauf correct_facts (editor+, comme update_metadata).
  • backend/handlers/router.go + cmd/server/router_test.go : enregistrer les routes (le test de contrat miroir du client doit rester vert).
  • docs/api-v1.md §6.1/§7 : documenter les 4 ops + codes (TRASHED vs NOT_FOUND — une ressource trashée reste NOT_FOUND en lecture normale, visible seulement via /trash).

3.3 Recherche serveur

  • repository/resources.go SearchFilesVisible : brancher search_tsv @@ plainto_tsquery('french', q) en OR avec le LIKE existant (compat), rank ts_rank + bonus si match facts (issuer, reference). Jamais d'exclusion sur fait basse-confiance : confidence < 0.5 → pondération /2, pas filtre.
  • Facettes : GET /files/search?q=&issuer=&from=&to=&min_amount=&max_amount=&doc_type= — filtres SQL sur resource_facts (jointure, origin indifférent, doc_type = suggestion acceptée comme filtre mais affichée « suggéré » si origin='auto').

4. Mobile — plan fichier par fichier

4.1 Room (v19 → v20 faits, v21 FTS — voir S3/S4, app/schemas/ exporté, tests MigrationXToYTest)

  • v19 (S1, livré) : trashed_at sur files + folders.
  • v20 (S3, livré) : resource_facts (id, resource_id, fact_type, value_text, value_num, value_date, confidence, origin, updated_at) + FactsDao (remplacement en bloc au sync, corrections user poussées en outbox). resource_links, is_favorite et collections → S5.
  • v21 (S4) : FTS4 files_fts (name, ocr_text, facts_text) + triggers sync + requête searchDocuments(query, facets) remplaçant searchWithFilters pour les docs (garder l'ancien pour dossiers). facts_text = concat des value_text — reconstruit à chaque sync facts.
  • OutboxRepository.kt : enqueueTrash/restore/purge, enqueueCorrectFacts (payload [{fact_type, value}], GenerateId 32-hex, même transaction Room que la mutation parente — contrat outbox atomique inchangé). delete_resource existant → renommé en trash côté appelants (FileDeleter, FolderDeleter).

4.2 Review = moment de vérité (zéro écran en plus)

  • OcrRepository.syncFromServer : après ocr_text, rapatrier GET /files/:id/facts → Room (même pattern syncFromServer, poll existant réutilisé).
  • Fiche document (livré S3 — pas le review : le deck ne contient que des fichiers jamais OCR-és, sans faits) : fiche « Ce qu'on a compris » (FactsBottomSheet, bouton viewer si processed) — chips Émetteur: EDF • 84,20 € • Échéance: 12/04 (suggéré), confiance < 0.5 grisée, user gagne par type à l'affichage, édition par type (texte/nombre/date ISO) → enqueueCorrectFacts dans la même transaction que l'écriture Room optimiste, reset « rétablir auto » (jeu vide poussé).
  • Fiche document : section « Voir aussi » (LinksDao → same_scan d'abord avec badge « sûr », puis autres avec bouton invalider) + section « Faits » (grisé si confidence < 0.5).

4.3 Relations same_scan (déterministe, local)

  • ScanExport.kt : à l'export multi-pages, écrire les liens same_scan entre les resource_id de la session (même transaction que les create_resource). Confiance 1.0, created_by='user' (acte volontaire). Poussés via correct_facts-like ? Non — nouvelle op link_pages ou piggyback sur create_resource payload (préféré : champ scanSessionId dans le payload create_resource, le serveur en déduit same_scan — zéro nouvelle op).
  • Collections virtuelles : table locale collections + collection_members (requêtes sauvées sur facts, ex. « Impôts 2026 » = doc_type suggéré:impôt + period:2026) — pur local en V3, pas de sync (un device, pas de conflit). Sync serveur = V4.

4.4 Recherche + facettes UI

  • Barre unique : texte + chips facettes (émetteur, période, montant, type suggéré). Requête Room FTS offline ; si réseau, GET /files/search enrichit (même ranking affiché, source badgée « serveur »).
  • OutboxSyncWorker : après drain, enchaîner FactsSync (comme OcrAutoWorker aujourd'hui) — pas de nouveau worker WM, simple étape dans le worker existant.

4.5 Partage sobre + confiance

  • Sheet existant : expiration lien 7j par défaut (aujourd'hui null), badge « suggéré » sur doc_type, section copies déjà là (placements V2) + ligne quota/3-2-1 (GET /users/me/usage → Réglages/Stockage existant).
  • SessionManager : tv claim (voir §3.1 token_version) — changement de password → autres devices 401 → re-login silencieux existant (aucun code nouveau, juste le claim).

5. Ordre d'exécution (7–9 semaines, chaque ligne = shippable)

  1. S1 — Filet + A3 (livré : BE 000017/000018 + trash/restore/purge + cron purge 30j + mobile v19 + FileDeleter → trash + gardes walk + écran Corbeille) — done quand : supprimer → restaure depuis un 2e device, le walk ne ressuscite pas.
  2. S2 — Extract générique (livré : extract/rules.go + service/extract.go + 000019 + UpsertAuto + GET /files/:id/facts) — done quand : un scan EDF propose émetteur/montant/échéance.
  3. S3 — Fiche + correction (livré : PATCH /files/:id/facts + op correct_facts editor+ + Room v20 facts + fiche viewer + FactsRepository + B4 a11y fiche) — done quand : corriger en un tap converge serveur ↔ 2e device.
  4. S4 — Recherche (000022 FTS + facettes serveur + Room FTS v21 + barre à chips + B4 a11y facettes) — done quand : « facture edf mars » trouve scan_042.pdf offline ET online.
  5. S5 — Relations + B2 (000020 + duplicate/same_issuer auto + same_scan via scanSessionId + fiche « Voir aussi » + collections locales + écran Doublons « garder un seul ») — done quand : fiche CNI → verso + doublon listés, invalidables ; doublons chiffrés en Mo récupérables.
  6. S6 — Partage sobre + A1/A2/A4 + B1 (+B5 si temps) (expiration défaut 7j + 000021 token_version + 000023 quota + 413 QUOTA_EXCEEDED + GET /devices + écran Appareils + update_metadata{baseUpdatedAt} + flag conflict + import « classeur » unifié B1 + onboarding cercle B5) — done quand : lien RIB expiré → NOT_FOUND, password changé → autres devices re-logués, device perdu révoqué, quota plein → 413 propre, rename concurrent → badge « renommé ailleurs ».
  7. S7 — Preview 1ère page (pdf_preview V2.md §3.3, une seule taille) + C3 export chiffré (GET /export zip + manifest) + B3 impression si temps + polish + release 1.2.0. Arbitrage stretch : export > embeddings (vrai 3-2-1 perçu, zéro GPU).

6. Tests (mêmes harnais, pas de nouveau framework)

  • BE : dbtest + go test ./... — extract/rules_test.go (corpus FR : factures, bulletins, courriers, cas limites montants/dates), tests repo facts/links (upsert auto n'écrase pas user, recherche ne filtre pas sur low-confidence), tests handlers (trash/restore/purge, versions, facts, links, usage, devices, export, quota 413, conflit rename), router_test.go vert.
  • Mobile : :app:testDebugUnitTest (Robolectric + Room in-memory) — Migration18To19/19To20Test, FactsSyncTest (round-trip correct_facts), SearchFtsTest (accents, %/_ échappés, facettes), SameScanTest (export multi-pages → liens), TrashWalkTest (walk n ressuscite pas les trashés, miroir FEEDBACK M5), DuplicatesTest, QuotaBadgeTest.

7. Non-goals V3 (actés, basculables V4)

Alertes d'échéance, résumés/chat LLM, embeddings sémantiques (déscopés au profit de C3 export — tables facts/links déjà prêtes à les accueillir en V4), analyse d'image biométrique/sémantique (visages, lieux, événements, clustering personnes — hors vision par principe, les photos restent des documents image), OCR on-device, transcodage vidéo, E2EE dédiée (les facts/liens héritent des perms viewer+ comme ocr_text — pas de nouveau modèle de droits), sync des collections, client desktop/web, fédération, retention_policies serveur (C1 enterré : rétention = affaire locale), sync_queue serveur (C2 enterré : l'outbox client fait le job).