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.
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) ; middlewareRequireAuth(+ révocationtv, devices siEnforceDeviceExists)repository/— Postgres persistence (repository.Resources: insert/list/get/soft-delete scopingowner_id, search, move, rename, root-name unique index,ListOwnedpour le snapshot,OpenContent(bytes streaming + lazy healinghas_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, snapshotListEffectivePermissions(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/rand16 octets hex (jamais UUID conversion, cf.docs/api-v1.md)db/— package migrations (golang-migrate/v4, embarquées viaembeddansdb/migrations/*.sql, 000001→000016) :db.MigrateDatabase(url)au boot du serveur ; test harnessdb/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_LANGdéfautfra+eng)pkg/api/— response helpers (response.go) ;pkg/auth/— tokens paseto v4-local (subject =user_id, claim =device_id, TTL 7j, voirdocs/api-v1.md) ;pkg/passwd/— hashing/vérification argon2id (comparaisonsubtle, 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.gomirrors 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 dansui/navigation/(NavGraph.kt,KazierApp.kt) - Data layer —
data/:data/local/— Room SQLite (DBdot.db, version 22,Migrations.kt: tablesfolders,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 + triggersFtsTriggers),resource_links,collections) : entités + DAO, tri (FileOrdering), schéma exporté (app/schemas/, m22) ; flagprocessedsurfiles(mode review « traiter », local au device, gate de sync : un fichier pas encore traité n'est jamais poussé) ; outbox transactionnelpending_operationsdata/remote/— Retrofit/Moshi :ApiService.kt+dto/Dtos.kt= contrat HTTP ({ data, meta }, erreurs{ error: { code, message } }) ;ApiClient.ktnormalise les réponses ; interceptors OkHttp (AuthInterceptor,ServerUrlInterceptor) ;SafMultipart.kt(multipart SAF paresseux partagé upload OCR + V2)data/repository/—FolderRepository,FileRepository,AuthRepository,OutboxRepository(enqueuecreate_resource(+scanSessionIdS5)/move_resource/update_metadata(+baseUpdatedAtS6)/trash_resource/restore_resource/purge_resource(V3,delete_resourcelegacy mappé serveur) + ops partageshare/update_share/revoke_share/create_link(expiration 7j défaut)/revoke_link+report_bytesV2 ({ hasBytes }, nouveloperation_idpar état) +correct_factsS3 (full-replace jeuuser), écrivains dans la même transaction Room que la mutation parente ; pour un fichier SAF, la mutation parente ducreate_resourceest le garder de la review (markProcessed), ethasCreateOperationen garde l'unicité),ShareRepository(hydratation + delta +canAccessdepuisGET /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(streamingGET /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éconciliationexists = 0(jamais de suppression), single-flight viaMutex; les nouveaux dossiers sont journalisés dans l'outbox à la découverte, les fichiers uniquement au « garder » de la review (gateprocessed)saf/—SafUris,SafFolderCreator,FileMover(relocalisation SAFDocumentsContract.moveDocument, repli métadonnée seule ; le déplacement est poussé enmove_resource),SafFileDeleter(suppression SAF +delete_resourceatomique),FileDeleter.releaseLocalCopies(purge sûre V2-3 : gateisReleasable, détachement cloud-only, zéro outbox)sync/OutboxSyncWorker.kt— worker WorkManager (enqueueUniqueWorkKEEP, single-flight,NetworkType.CONNECTED, backoff 30s) qui drainepending_operationsversPOST /sync/ops(batch 20, dead-letter immédiatfailedsur erreur 4xx non-idempotente —attemptsdiagnostic, purge synced > 7 jours, saufreport_bytes: dead-letter + suite du batch, jamais bloquant) ; schedulé au login/restauration de session (AuthViewModel) et après chaquesyncAll()(SyncViewModel) ; enchaîneOcrAutoWorker+BytesUploadWorkerquand un fichier est promu (DownloadWorkersur demande hors-ligne) ;RetentionWorker(passe quotidienne, purge sûre des copies anciennes selonRetentionStore, 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 headerui/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énementsReauthenticated/SessionExpired) :SessionManager,SecureTokenStore,TokenProvider,TokenStore(+Credentials)ui/— écrans Compose :folderlist,folderdetail,document(contenu PDF/image/texte local + streaming distant image/texte/PDF multi-pages viaRemoteDocumentViewer, 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-linkkazier://share/<token>),components,themedomain/— 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 enuser_preferences), défauthttp://10.0.2.2:8080/api/v1(pas de variable d'env) - Client local-first : lecture via
GET /files/folders,GET /files(+ streaming distantGET /files/:id/contentpour les fichiers cloud-only, jamais persisté) ; mutations locales poussées via l'outboxPOST /sync/ops(create_resource/move_resource/delete_resource+ ops partage) ;POST /devices,POST /auth/login; upload physique limité au pipeline OCR (POST /files/upload+resourceIdciblé)
Data Conventions
- Canonical identity for folders/files is
resource_id: opaque 32-hex, generated locally (GenerateId), never reused. The physicaluri(SAF) is nullable (NULL = cloud-only) and is the reconciliation key for the SAF walk (unique index, NULLs distincts). pending_operations.operation_idest un TEXT 32-hex généré par le client (^[0-9a-f]{32}$, CHECK-enforced côté serveur depuis la migration000008), distinct deresource_id. L'idempotence outbox reste par device :UNIQUE(device_id, operation_id)(colonnedevice_idcôté mobile depuis Room v12).owner_idis nullable in the Room schema; it is set at runtime fromDeviceIdentity.getOrCreate()during the SAF walk.- Folder/file
sync_statusis 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_resourcesont é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. Gateprocessed: un fichier SAF nouvellement découvert est importé localement mais poussé seulement au « garder » (markProcessed, qui enqueue lecreate_resourcedans la même transaction, une seule fois viahasCreateOperation) — d'où le filtrage des documents par l'utilisateur avant toute synchro. Undelete_resourcen'est journalisé que si uncreate_resourcea existé (jamais pour un fichier non poussé). - Cache de permissions côté client :
ShareRepositoryhydrateresource_permissionsdepuisGET /sync/permissions(delta + pull complet, TTL 24h → downgrade lecture seule) et exposecanAccess; 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.ktsont 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), puisPOST /auth/login(username+password+device_id) émet le seul token paseto v4-local — subject =user_id(autorise, scoping de toutes les ressources), claimdevice_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énementsReauthenticated/SessionExpired), sans rejouer la requête en vol. -
Bootstrap: au premier démarrage, si
usersest 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 surusername_normalized(lowercase + trim),GET /users/resolveexact uniquement (pas d'énumération). -
Identifiers:
resource_id/device_user_id/user_id/ share-linktoken/operation_idsont 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_operationssé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_resourceporte leparentResourceIdoptionnel (racine si absent) ;report_bytes({ hasBytes }, V2 placements, nouveloperation_idpar état) ;share/update_shareacceptentgranteeUserIdXORgranteeGroupId(V2-6) — le walk SAF garantit parent avant enfant dans l'ordre d'id. -
Permissions snapshot: le serveur pousse des snapshots
resource_permissions(effective_accessranking 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/contentstreame les octets (viewer+,Rangesupporté).
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 clientdata/remote/)V2.md— modèle cible Postgres/ReBAC (identifiants en TEXT 32-hex, cf.docs/api-v1.md)