Files
Kazier/AGENTS.md
T
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

16 KiB

Kazier

Project Status

backend/ (Go) et mobile-kotlin/ (Kotlin/Android) ont du scaffolding en place. Le client mobile est local-first : il reflète le SAF dans une base Room (v22, migrations, DAO) et pousse les métadonnées de ses mutations locales via un outbox transactionnel (pending_operations + worker WorkManager → POST /sync/ops). Upload physique ciblée (pipeline OCR : POST /files/upload + resourceId), streaming lecture des fichiers distants (GET /files/:id/content, jamais persisté + vignettes GET /files/:id/preview en cache), OCR serveur consommé côté client, recherche locale via Room FTS (+ facettes, + recherche serveur exposée), export chiffré (POST /export).

Architecture

  • Backend: Go, Gin HTTP framework, PostgreSQL, Tesseract OCR (system call)
  • Frontend: Kotlin/Android — Jetpack Compose, Room (SQLite), Hilt (DI), Retrofit + Moshi + OkHttp, SAF (DocumentsContract)

Key Commands

# Backend
mise up_backend                    # docker compose up postgres + go run cmd/server/main.go
cd backend && go run cmd/server/main.go

# Backend tests (tests repo/handlers via dbtest)
cd backend && go test ./...

# Frontend (build + install app Android debug)
mise up_mobile [device|emulator]  # défaut: emulator
cd mobile-kotlin && ./gradlew :app:assembleDebug

# Frontend tests (JVM, Robolectric + Room in-memory)
cd mobile-kotlin && ./gradlew :app:testDebugUnitTest

# PostgreSQL (via docker-compose)
docker compose up postgres -d

Tests mobiles : JVM unit tests dans app/src/test (JUnit + Robolectric + Room in-memory), lancés via :app:testDebugUnitTest. Pas de tests instrumentés (androidTest).

Backend Structure

  • Entry point: backend/cmd/server/main.go (wiring gin + config + routes)
  • config/ — env (godotenv, optionnel) + defaults: PORT, DATABASE_URL, UPLOAD_DIR, MAX_FILE_SIZE_MB, OCR_LANG, AUTH_SECRET (secret des tokens paseto), ADMIN_USERNAME/ADMIN_PASSWORD (bootstrap du premier admin)
  • models/ — domain entities (users, devices, documents/resources, clients)
  • service/ — business logic (permissions, upload, create folder, move, sync outbox + snapshot, bootstrap admin)
  • handlers/ — HTTP handlers (health, devices register/list/revoke, auth/login, users resolve + change password (révoque les tokens) + usage, files CRUD/upload/search (+facettes) , folders, sync/ops + sync/permissions, ocr/jobs, files/:id/content, files/:id/preview, files/:id/shares, files/:id/links, files/:id/placements, files/:id/versions, files/:id/facts, files/:id/relations, trash, duplicates, export, groups CRUD + membres — réels) ; middleware RequireAuth (+ révocation tv, devices si EnforceDeviceExists)
  • repository/ — Postgres persistence (repository.Resources : insert/list/get/soft-delete scoping owner_id, search, move, rename, root-name unique index, ListOwned pour le snapshot, OpenContent (bytes streaming + lazy healing has_content), ListShares/ListLinks (owner-only), SetHasContent ; repository.Devices : Upsert, Exists, MarkUser ; repository.Operations : trace outbox idempotente (device_id, operation_id) ; repository.OcrJobs : jobs queued→processing→done/failed ; repository.Users : GetByUsernameNormalized, ResolveExact, UpdatePassword ; repository.Shares : Upsert/UpsertGroup/Revoke, CreateLink/RevokeLink, ListActiveForResource, ListActiveLinksForResource, snapshot ListEffectivePermissions (grants user + groupe) ; repository.Groups : Create/ListForUser/AddMember/RemoveMember/Delete (V2-6, un niveau, sans imbrication) ; repository.Placements : EnsureLocation/Report/ListForResource (V2 multi-device) ; IDs sont TEXT 32-hex, NewID() = crypto/rand 16 octets hex (jamais UUID conversion, cf. docs/api-v1.md)
  • db/ — package migrations (golang-migrate/v4, embarquées via embed dans db/migrations/*.sql, 000001→000016) : db.MigrateDatabase(url) au boot du serveur ; test harness db/migrations_test.go (up → assertions schéma → down, TEST_DATABASE_URL, skip si PG indisponible) ; dbtest/ — helper cross-package pour les tests repo/handlers (crée la DB test si absente, reset schema, migrate ; skip si PG down)
  • ocr/ — OCR engine behind an interface (Tesseract system call, OCR_LANG défaut fra+eng)
  • pkg/api/ — response helpers (response.go) ; pkg/auth/ — tokens paseto v4-local (subject = user_id, claim = device_id, TTL 7j, voir docs/api-v1.md) ; pkg/passwd/ — hashing/vérification argon2id (comparaison subtle, délai égalisé)
  • File uploads stored in backend/uploads/
  • Standard JSON response envelope: { "data": ..., "meta": { "page": ..., "total": ... } }
  • Error format: { "error": { "code": "...", "message": "..." } }
  • Route list is a tracked contract (cmd/server/router_test.go mirrors the mobile client)

Frontend Structure (mobile-kotlin)

  • Entry point: app/src/main/java/com/kazier/mobile/KazierApplication.kt (Hilt + HiltWorkerFactory) + MainActivity.kt (Hilt) ; navigation Compose dans ui/navigation/ (NavGraph.kt, KazierApp.kt)
  • Data layer — data/:
    • data/local/ — Room SQLite (DB dot.db, version 22, Migrations.kt : tables folders, files (+ category, processed, content, ocr_text, ocr_attempts, ocr_queued_at, bytes_uploaded, bytes_upload_attempts, has_content_server, wanted_offline, trashed_at), user_preferences, pending_operations (+ device_id, parent_resource_id), scan_sessions, scan_pages, resource_permissions, resource_facts, files_fts (FTS4 + triggers FtsTriggers), resource_links, collections) : entités + DAO, tri (FileOrdering), schéma exporté (app/schemas/, m22) ; flag processed sur files (mode review « traiter », local au device, gate de sync : un fichier pas encore traité n'est jamais poussé) ; outbox transactionnel pending_operations
    • data/remote/ — Retrofit/Moshi : ApiService.kt + dto/Dtos.kt = contrat HTTP ({ data, meta }, erreurs { error: { code, message } }) ; ApiClient.kt normalise les réponses ; interceptors OkHttp (AuthInterceptor, ServerUrlInterceptor) ; SafMultipart.kt (multipart SAF paresseux partagé upload OCR + V2)
    • data/repository/ — FolderRepository, FileRepository, AuthRepository, OutboxRepository (enqueue create_resource (+scanSessionId S5)/move_resource/update_metadata (+baseUpdatedAt S6)/trash_resource/restore_resource/purge_resource (V3, delete_resource legacy mappé serveur) + ops partage share/update_share/revoke_share/create_link (expiration 7j défaut)/revoke_link + report_bytes V2 ({ hasBytes }, nouvel operation_id par état) + correct_facts S3 (full-replace jeu user), écrivains dans la même transaction Room que la mutation parente ; pour un fichier SAF, la mutation parente du create_resource est le garder de la review (markProcessed), et hasCreateOperation en garde l'unicité), ShareRepository (hydratation + delta + canAccess depuis GET /sync/permissions), OcrRepository (upload ciblé + jobs + syncFromServer), FactsRepository (sync remplace-en-bloc + corrections optimistes), LinksRepository (graphe + verdicts REST), TrashRepository (restore/purge/convergence), CollectionsRepository (local), DevicesRepository (appareils + usage), RemoteContentRepository (streaming GET /files/:id/content, jamais persisté ; upload V2 des octets après metadata synced, bytes_uploaded ; download V2 vers SAF + rattachement, wanted_offline)
  • features/ — logique descendue côté client :
    • sync/DeviceSync.kt + SafScanner.kt — sync device↔SAF : two-pass walk (listing hors transaction puis upserts Room dans une seule transaction), réconciliation exists = 0 (jamais de suppression), single-flight via Mutex ; les nouveaux dossiers sont journalisés dans l'outbox à la découverte, les fichiers uniquement au « garder » de la review (gate processed)
    • saf/ — SafUris, SafFolderCreator, FileMover (relocalisation SAF DocumentsContract.moveDocument, repli métadonnée seule ; le déplacement est poussé en move_resource), SafFileDeleter (suppression SAF + delete_resource atomique), FileDeleter.releaseLocalCopies (purge sûre V2-3 : gate isReleasable, détachement cloud-only, zéro outbox)
    • sync/OutboxSyncWorker.kt — worker WorkManager (enqueueUniqueWork KEEP, single-flight, NetworkType.CONNECTED, backoff 30s) qui draine pending_operations vers POST /sync/ops (batch 20, dead-letter immédiat failed sur erreur 4xx non-idempotente — attempts diagnostic, purge synced > 7 jours, sauf report_bytes : dead-letter + suite du batch, jamais bloquant) ; schedulé au login/restauration de session (AuthViewModel) et après chaque syncAll() (SyncViewModel) ; enchaîne OcrAutoWorker + BytesUploadWorker quand un fichier est promu (DownloadWorker sur demande hors-ligne) ; RetentionWorker (passe quotidienne, purge sûre des copies anciennes selon RetentionStore, sans réseau)
    • sync/SyncViewModel.kt — état du sync exposé à l'UI (SyncStatus : marche en cours, ops en attente, dernières opérations) via le badge header ui/components/SyncStatusBadge.kt + SyncOperationsDialog.kt (« liste des sync »)
  • auth/ — session (login user + token paseto + re-login silencieux sur 401 via identifiants chiffrés persistés, single-flight, événements Reauthenticated/SessionExpired) : SessionManager, SecureTokenStore, TokenProvider, TokenStore (+ Credentials)
  • ui/ — écrans Compose : folderlist, folderdetail, document (contenu PDF/image/texte local + streaming distant image/texte/PDF multi-pages via RemoteDocumentViewer, autres types non supportés en streaming + fiche faits/liens + partage ACTION_SEND), search (recherche locale via Room FTS + facettes + collections locales), settings (URL serveur + thème + stockage/retention + export chiffré + appareils + corbeille + doublons), trash, duplicates, devices, facts (bottom-sheet), pdfbuilder (multi-select → génération PDF), auth (login, mode local, avis d'expiration), share (ShareBottomSheet : grants + liens + ouverture de lien + copies V2 + groupes V2-6 ; OpenLinkScreen + deep-link kazier://share/<token>), components, theme
  • domain/ — stores de préférences: DeviceIdentity, ActiveUserStore, LocalModeStore, ServerConfigStore, ThemePreferenceStore, RetentionStore (all | last_months:N), GenerateId (identifiants 32-hex)
  • di/ — modules Hilt (AppModule, DatabaseModule, NetworkModule)
  • Base URL serveur configurée à l'exécution dans les Réglages (ServerConfigStore, persistée en user_preferences), défaut http://10.0.2.2:8080/api/v1 (pas de variable d'env)
  • Client local-first : lecture via GET /files/folders, GET /files (+ streaming distant GET /files/:id/content pour les fichiers cloud-only, jamais persisté) ; mutations locales poussées via l'outbox POST /sync/ops (create_resource/move_resource/delete_resource + ops partage) ; POST /devices, POST /auth/login ; upload physique limité au pipeline OCR (POST /files/upload + resourceId ciblé)

Data Conventions

  • Canonical identity for folders/files is resource_id: opaque 32-hex, generated locally (GenerateId), never reused. The physical uri (SAF) is nullable (NULL = cloud-only) and is the reconciliation key for the SAF walk (unique index, NULLs distincts).
  • pending_operations.operation_id est un TEXT 32-hex généré par le client (^[0-9a-f]{32}$, CHECK-enforced côté serveur depuis la migration 000008), distinct de resource_id. L'idempotence outbox reste par device : UNIQUE(device_id, operation_id) (colonne device_id côté mobile depuis Room v12).
  • owner_id is nullable in the Room schema; it is set at runtime from DeviceIdentity.getOrCreate() during the SAF walk.
  • Folder/file sync_status is a placement state: local | cloud | local-cloud. It is not a push progress marker.
  • Client storage: user_preferences (clé/valeur) pour l'identité device, le compte actif, l'URL serveur, le thème, le mode local.
  • Outbox atomique : create_resource/move_resource/delete_resource sont écrits dans la même transaction Room que la mutation parente ; l'écrivain (repository) et le worker partagent ce contrat. En mode local (pas de token), le worker est no-op. Gate processed : un fichier SAF nouvellement découvert est importé localement mais poussé seulement au « garder » (markProcessed, qui enqueue le create_resource dans la même transaction, une seule fois via hasCreateOperation) — d'où le filtrage des documents par l'utilisateur avant toute synchro. Un delete_resource n'est journalisé que si un create_resource a existé (jamais pour un fichier non poussé).
  • Cache de permissions côté client : ShareRepository hydrate resource_permissions depuis GET /sync/permissions (delta + pull complet, TTL 24h → downgrade lecture seule) et expose canAccess ; le serveur reste la source de vérité.

API Contract (V1)

  • Le client mobile est le contrat: les formes d'endpoints dans mobile-kotlin/.../data/remote/ApiService.kt + dto/Dtos.kt sont autoritatives et doivent matcher exactement ; le serveur ne renégocie pas. Spec consolidée: docs/api-v1.md.

  • Identity (user-first, V1 finale): le device s'enregistre (POST /devices, { "deviceId" } seul, sans token), puis POST /auth/login (username + password + device_id) émet le seul token paseto v4-local — subject = user_id (autorise, scoping de toutes les ressources), claim device_id (porté, non autorisant seul), TTL 7j sans refresh. À expiration, le client re-logine silencieusement via les identifiants chiffrés persistés (SecureTokenStore, single-flight, événements Reauthenticated/SessionExpired), sans rejouer la requête en vol.

  • Bootstrap: au premier démarrage, si users est vide, ADMIN_USERNAME/ADMIN_PASSWORD (env) créent le premier admin ; absents → le serveur refuse de démarrer. L'env n'écrase jamais un compte existant. Usernames résolus sur username_normalized (lowercase + trim), GET /users/resolve exact uniquement (pas d'énumération).

  • Identifiers: resource_id / device_user_id / user_id / share-link token / operation_id sont des lowercase 32-hex TEXT (^[0-9a-f]{32}$, CHECK-enforced), stockés tels quels côté serveur (pas de conversion UUID). Le mobile génère toujours 32-hex.

  • Outbox idempotence + ordering: le serveur applique les batchs de pending_operations séquentiellement, s'arrête à la première erreur non-idempotente et retourne l'index atteint. Consommé par le client Kotlin (OutboxSyncWorker → POST /sync/ops, batch 20, dead-letter immédiat sur 4xx non-idempotente, purge > 7 jours). create_resource porte le parentResourceId optionnel (racine si absent) ; report_bytes ({ hasBytes }, V2 placements, nouvel operation_id par état) ; share/update_share acceptent granteeUserId XOR granteeGroupId (V2-6) — le walk SAF garantit parent avant enfant dans l'ordre d'id.

  • Permissions snapshot: le serveur pousse des snapshots resource_permissions (effective_access ranking viewer < commenter < editor < owner, inherit, expires_at, TTL 24h → read-only downgrade). Consommé par le client Kotlin (ShareRepository : hydratation + delta + canAccess).

  • Lecture partagée : GET /files/:id/shares + GET /files/:id/links (owner uniquement, 404 sinon) exposent grants et liens au propriétaire ; GET /files/:id/content streame les octets (viewer+, Range supporté).

Non-Goals (V1)

  • Plugin system
  • On-device OCR
  • Full multi-tenant federation / public discovery
  • Multi-writer sync conflicts (single-owner device identity)
  • Upload physique généralisé client→cloud et download persistant (seuls l'upload ciblé OCR et le streaming lecture existent, cf. docs/api-v1.md)

References

  • docs/api-v1.md — contrat API V1 (autoritatif, consolidé depuis le client data/remote/)
  • V2.md — modèle cible Postgres/ReBAC (identifiants en TEXT 32-hex, cf. docs/api-v1.md)