Backend : token_version (000022, claim tv, 401 si révoqué, bump au password — fin limite V1), quota (000023 idempotente, colonne héritée de 000001, 413 QUOTA_EXCEEDED, GET /users/me/usage), devices (GET + DELETE révocation, EnforceDeviceExists en prod), renames concurrents transparents (baseUpdatedAt + conflicts[] non-fataux, tolérance 2 s). Tests service + handlers + migrations + auth. Mobile : pipeline conflits (DTO + SyncConflictStore + worker + dialogue), baseUpdatedAt prêt, liens 7j par défaut, écran Appareils (+ quota), import classeur unifié (scan/note/dossier), onboarding cercle Famille. Contrat docs/api-v1.md, V3.md (S6 livré).
21 KiB
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, migration000015) en lectureGET /devices+DELETE /devices/:id(révocation = bumptoken_versionciblé 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. Ajouterusers.storage_quota_bytes(défaut 10 Go, cf. V2.md §3.1) + garde-fou à l'upload (413 QUOTA_EXCEEDED) + à l'overwrite versionnée. Migration000023_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_atRoom, filtre globalexists=1 AND trashed_at IS NULL, écran Corbeille). Le walk SAF doit ignorer les trashés (gardehasPendingTrash, même pattern que FEEDBACK M5) sinon ils ressuscitent. Fait partie de S1, pas une option. - A4 Conflits rename transparents :
update_metadataconcurrent (2 devices renomment) = last-writer-wins silencieux aujourd'hui. Minimum V3 : comparerupdated_at(perdant = op arrivée surupdated_atplus récent que sonbase_updated_at→ appliquée quand même mais flagconflictremonté dans la réponsePOST /sync/ops+ badge UI « renommé ailleurs » via snapshot). Pas de CRDT, juste de la transparence. Payloadupdate_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 optrash_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_policiesserveur (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 dansdocs/api-v1.md: « la rétention est une affaire locale ». - C2
sync_queueserveur (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 + manifestresource_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 partielidx_resources_deleted_at ON resources(deleted_at) WHERE deleted_at IS NOT NULL+ colonnetrashed_at TIMESTAMPTZ(NULL = vivant ; purge =trashed_at < NOW()-30j). LeDELETEactuel devient trash (soft), pas de breaking change API.000018_versions: tableresource_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: tableresource_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_typen'est qu'un fait comme un autre (suggestion, pas statut).000020_search_fts(livré S4) : colonnesearch_tsv TSVECTORgénérée (name + ocr_text,french) + index GIN ; faits joints à la requête (rang, jamais d'exclusion).000021_links(S5, livré) : tableresource_links (id 32-hex PK, from_id/to_id canoniques, link_type IN (same_scan, duplicate_of, same_issuer, same_reference) — pas deversion_of, CHECK from != to, UNIQUE trio)+resources.scan_session_id(session opaque du create outbox).version_ofnon matérialisé (versions DANS la ressource).000022_token_version(S6) :ALTER TABLE users ADD COLUMN token_version INT NOT NULL DEFAULT 0—PATCH /users/me/passwordbump ; claim pasetotv, middlewareRequireAuthrejettetv != users.token_version(lève la limite V1 « tokens non révoqués »).000023_quota(A2, S6) :ALTER TABLE users ADD COLUMN storage_quota_bytes BIGINT NOT NULL DEFAULT 10737418240(10 Go, V2.md §3.1) + vue/fonctionuser_used_bytes(user_id)(sommesize_byteshors trash). Check à l'upload et à l'overwrite versionnée →413 QUOTA_EXCEEDED(nouveau code §7).
Ordre imposé par golang-migrate (montée stricte, pas de trous) : FTS a pris
000020en S4, décalant links→000021et token→000022.
3.2 Extract — nouveau worker (miroir service/ocr.go, cmd/server/main.go)
- Nouveau
backend/extract/rules.go: pur package, testable sans PG — entréetext 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: structExtract{Repository}+Run(ctx)— même squelette queOcr.Run(poll file,FOR UPDATE SKIP LOCKED,QueuePollInterval,ResetStaleau boot). Déclencheur : après chaque OCRdoneavec texte non vide (appel directExtract.Enqueue/ProcessdepuisOcr.process, pas de nouvelle file PG — une colonneextract_statussurocr_jobsou simple appel synchrone borné suffit en V3). backend/repository/facts.go:UpsertAuto(resourceID, facts)(remplace lesorigin='auto', ne touche jamais auxorigin='user'),Correct(resourceID, facts)(écritorigin='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 depuisscan_sessions— en fait côté mobile, voir §4, serveur :duplicate_ofviacontent_hashégal,version_ofviaresource_versions,same_issuervia factsissuernormalisé identique + confidence = min des deux facts).backend/service/resources.go: trash/restore/purge (Trash= settrashed_at,Restore= NULL,Purge= hard delete + versions + faits + liens + fichier physique) ; overwrite d'octets → pousser l'ancienne copie enresource_versionsavant écriture.backend/service/sync.go: nouvelles ops outboxtrash_resource/restore_resource/purge_resource/correct_facts(même enveloppe §6.1,operation_id32-hex, idempotence(device_id, operation_id), arrêt au premier échec non-idempotent).delete_resourcelegacy → mappé verstrash_resource(pas de break client existant).correct_factsporte[{fact_type, value, confidence}], appliqueCorrect(writer = user, écrase l'auto).backend/handlers/:GET /trash(listetrashed, 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 quecorrect_facts),GET /files/:id/relations+POST /files/:id/relations/verdict(livrés S5 —/linksétant pris par les liens de partage),GET /duplicates(livré S5 B2),GET /users/me/usage(quota + copies 3-2-1 :used_bytes,quota_bytes,copies,offsite_ok),GET /devices+DELETE /devices/:id(A1, lecturestorage_locations+ révocation),GET /export(C3, zip + manifest, streamé). Tous scopésviewer+lecture /ownermutation saufcorrect_facts(editor+, commeupdate_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 (TRASHEDvsNOT_FOUND— une ressource trashée resteNOT_FOUNDen lecture normale, visible seulement via/trash).
3.3 Recherche serveur
repository/resources.goSearchFilesVisible: branchersearch_tsv @@ plainto_tsquery('french', q)en OR avec leLIKEexistant (compat), rankts_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 surresource_facts(jointure,originindifférent,doc_type= suggestion acceptée comme filtre mais affichée « suggéré » siorigin='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_atsur 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, correctionsuserpoussées en outbox). - v22 (S5, livré) :
resource_links(miroirGET /relations, remplacement en bloc, verdicts REST directs) +LinksDao+collections(requêtes sauvegardées locales, jamais syncées) +CollectionDao.is_favoritereporté (non bloquant, S6+ si besoin). - v21 (S4) : FTS4
files_fts (name, ocr_text, facts_text)+ triggers sync + requêtesearchDocuments(query, facets)remplaçantsearchWithFilterspour les docs (garder l'ancien pour dossiers).facts_text= concat desvalue_text— reconstruit à chaque sync facts. OutboxRepository.kt:enqueueTrash/restore/purge,enqueueCorrectFacts(payload[{fact_type, value}],GenerateId32-hex, même transaction Room que la mutation parente — contrat outbox atomique inchangé).delete_resourceexistant → renommé en trash côté appelants (FileDeleter,FolderDeleter).
4.2 Review = moment de vérité (zéro écran en plus)
OcrRepository.syncFromServer: aprèsocr_text, rapatrierGET /files/:id/facts→ Room (même patternsyncFromServer, 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 siprocessed) — 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) →enqueueCorrectFactsdans la même transaction que l'écriture Room optimiste, reset « rétablir auto » (jeu vide poussé). - Fiche document : section « Voir aussi » (
LinksDao→same_scand'abord avec badge « sûr », puis autres avec bouton invalider) + section « Faits » (grisé siconfidence < 0.5).
4.3 Relations same_scan (déterministe, local)
ScanExport.kt: à l'export multi-pages, écrire les lienssame_scanentre lesresource_idde la session (même transaction que lescreate_resource). Confiance 1.0,created_by='user'(acte volontaire). Poussés viacorrect_facts-like ? Non — nouvelle oplink_pagesou piggyback surcreate_resourcepayload (préféré : champscanSessionIddans le payloadcreate_resource, le serveur en déduitsame_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/searchenrichit (même ranking affiché, source badgée « serveur »). - OutboxSyncWorker : après drain, enchaîner
FactsSync(commeOcrAutoWorkeraujourd'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é » surdoc_type, section copies déjà là (placements V2) + ligne quota/3-2-1 (GET /users/me/usage→ Réglages/Stockage existant). SessionManager:tvclaim (voir §3.1token_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)
- 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. - 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. - S3 — Fiche + correction (livré :
PATCH /files/:id/facts+ opcorrect_factseditor+ + Room v20 facts + fiche viewer +FactsRepository+ B4 a11y fiche) — done quand : corriger en un tap converge serveur ↔ 2e device. - S4 — Recherche (livré :
000020FTS + facettes serveur + Room FTS v21 + UI filtres + B4 a11y) — done quand : « facture edf mars » trouvescan_042.pdfoffline ET online. - S5 — Relations + B2 (livré :
000021links + doublons SHA-256 + same_scan outbox +GET /relations+ verdict +GET /duplicates+ Room v22 + « Voir aussi » + Doublons + collections locales) — done quand : fiche CNI → verso + doublon listés, invalidables ; doublons chiffrés en Mo récupérables. - S6 — Partage sobre + A1/A2/A4 + B1 (+B5 si temps) (livré : expiration liens 7j défaut +
000022token_version +000023quota idempotente +413 QUOTA_EXCEEDED+GET /devices+DELETE /devices/:id+EnforceDeviceExistsprod + écran Appareils + quota/usage +update_metadata{baseUpdatedAt}+conflicts[]+ pipeline mobile + import « classeur » unifié + onboarding cercle Famille) — 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 ». - S7 — Preview 1ère page (
pdf_previewV2.md §3.3, une seule taille) + C3 export chiffré (GET /exportzip + 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 repofacts/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.govert. - Mobile :
:app:testDebugUnitTest(Robolectric + Room in-memory) —Migration18To19/19To20Test,FactsSyncTest(round-tripcorrect_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).