# 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//.`, overwrite ciblée V2 | | P2 | Extract générique | Faits universels + type suggéré, validés dans le review existant | 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_bytes`hors 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, `AppDatabase.kt`, `Migrations.kt`, `app/schemas/` exporté, tests `MigrationXToYTest`) - v19 : `resource_facts (id, resource_id FK CASCADE, fact_type, value_text, value_num, value_date, confidence, origin, updated_at)` + `resource_links (id, from_id, to_id, link_type, confidence, created_by)` + miroir `trashed_at` + `is_favorite` sur `files` (colonne, pas table — un flag suffit). DAO `FactsDao`, `LinksDao`. - v20 : 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é). - Écran review existant (`FilePendingReviewBadge` + flow « garder ») : ajouter section « Ce qu'on a compris » — chips `Émetteur: EDF • 84,20 € • Échéance: 12/04 (suggéré)` + correction en un tap → `enqueueCorrectFacts` dans la **même transaction** que `markProcessed` (le `create_resource` et la correction partent ensemble — pas d'état intermédiaire). - 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** (BE `000017/000018` + trash/restore/purge + cron purge 30j + mobile v19 partiel + `FileDeleter` → trash + garde walk `hasPendingTrash` + écran Corbeille) — done quand : supprimer → restaure depuis un 2e device, le walk ne ressuscite pas. 2. **S2 — Extract générique** (`extract/rules.go` + `service/extract.go` + `000019` + `UpsertAuto` + `GET /files/:id/facts`) — done quand : un scan EDF propose émetteur/montant/échéance. 3. **S3 — Review + correction** (mobile v19 facts + chips review + `correct_facts` + `PATCH /files/:id/facts` + B4 a11y du review) — done quand : corriger en un tap converge serveur ↔ 2e device. 4. **S4 — Recherche** (`000022` FTS + facettes serveur + Room FTS v20 + 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).