Files
venture 4316da578f
Release / release-apk (push) Successful in 8m58s
Release / release-docker (push) Successful in 3m47s
CI / docker (push) Successful in 7s
CI / lint-backend (push) Successful in 1m44s
CI / lint-mobile (push) Failing after 18m59s
CI / test-backend (push) Successful in 2m12s
CI / test-mobile (push) Successful in 8m50s
CI / build-backend (push) Successful in 45s
V3 S7 : preview cloud + export chiffré + release 1.2.0
Backend : resource_previews (000024), GET /files/:id/preview (JPEG
512, images pur Go, PDF page 1 via pdftoppm + poppler au Dockerfile,
cache régénéré sur changement, 404 NO_PREVIEW sinon), POST /export
{password 8+} -> zip AES-256 streamé (fichiers vifs possédés +
manifest.json avec faits, metadata-only sans octets). Deps :
alexmullins/zip, x/image directs. Tests service + handlers + migrations.

Mobile : vignettes distantes (une requête/session puis cache WebP
versionné, garde tried, icône sinon), FileThumbnail cloud-only,
export (mot de passe jamais persisté, cache + partage FileProvider),
bouton Partager ACTION_SEND. Impression papier reportée V4. FR/EN.

Contrat docs/api-v1.md, V3.md (S7 livré, V3 close), AGENTS.md,
VERSION 1.2.0 + CHANGELOG.
2026-09-26 15:08:31 +02:00

21 KiB
Raw Permalink Blame History

Kazier V3 — « Le classeur qui comprend »

Statut : livrée en 1.2.0 (2026-09-26). 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 reste le contrat produit + plan d'exécution de la V3 (toutes slices S1–S7 livrées).

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_search_fts (livré S4) : colonne search_tsv TSVECTOR générée (name + ocr_text, french) + index GIN ; faits joints à la requête (rang, jamais d'exclusion).
  • 000021_links (S5, livré) : table resource_links (id 32-hex PK, from_id/to_id canoniques, link_type IN (same_scan, duplicate_of, same_issuer, same_reference) — pas de version_of, CHECK from != to, UNIQUE trio) + resources.scan_session_id (session opaque du create outbox). version_of non 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/password bump ; claim paseto tv, middleware RequireAuth rejette tv != 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/fonction user_used_bytes(user_id) (somme size_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 000020 en S4, décalant links→000021 et 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é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/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, 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).
  • v22 (S5, livré) : resource_links (miroir GET /relations, remplacement en bloc, verdicts REST directs) + LinksDao + collections (requêtes sauvegardées locales, jamais syncées) + CollectionDao. is_favorite reporté (non bloquant, S6+ si besoin).
  • 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 (livré : 000020 FTS + facettes serveur + Room FTS v21 + UI filtres + B4 a11y) — done quand : « facture edf mars » trouve scan_042.pdf offline ET online.
  5. S5 — Relations + B2 (livré : 000021 links + 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.
  6. S6 — Partage sobre + A1/A2/A4 + B1 (+B5 si temps) (livré : expiration liens 7j défaut + 000022 token_version + 000023 quota idempotente + 413 QUOTA_EXCEEDED + GET /devices + DELETE /devices/:id + EnforceDeviceExists prod + é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 ».
  7. S7 — Preview + export (livré : 000024 previews + GET /files/:id/preview JPEG 512 — images pur Go, PDF via pdftoppm + poppler, NO_PREVIEW sinon — + vignettes distantes mobile + POST /export zip AES + manifest + partage ACTION_SEND + release 1.2.0). Impression papier reportée V4 (pas de dep print).

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).