V3 S1-S2 : corbeille + versions + extract générique

S1 filet (backend + mobile) : corbeille 30j (deleted_at réutilisé,
trash/restore récursifs, purge auto serveur), versions N=3 à chaque
overwrite, ops outbox trash/restore/purge (delete legacy mappé), Room
v19 (trashed_at), Deleters -> trash, écran Corbeille, walk guards.

S2 extract (backend) : package extract (règles FR stdlib, corpus
testé), resource_facts 000019 (origin auto/user), hook worker OCR +
backfill boot, GET /files/:id/facts (viewer+).

Contrat docs/api-v1.md étendu, V3.md (vision + plan).
This commit is contained in:
venture
2026-09-26 10:14:07 +02:00
parent a34220bf2d
commit 95b4cf79cf
75 changed files with 5220 additions and 119 deletions
+11 -3
View File
@@ -38,13 +38,18 @@ Références : `V2.md` (modèle cible), `mobile/services/db/` (conventions sync)
| GET | `/files` | query `folderId?`, `page?`, `pageSize?`, `sort?` | `FileDto[]` (+ `meta`) | — |
| GET | `/files/:id` | — | `FileDto` | `NOT_FOUND` |
| GET | `/files/:id/content` | — (binaire brut, hors enveloppe `{data}` ; `Range` supporté) | octets physiques (`Content-Type` du fichier, `Content-Disposition: inline`) — streaming lecture seule, jamais persisté côté client | `NOT_FOUND` (invisible OU metadata-only jamais uploadé — indistinguables) |
| DELETE | `/files/:id` | — | `{ "id": "…" }` | `NOT_FOUND` |
| DELETE | `/files/:id` | query `mode?` (`trash` défaut, `purge` = définitif) | `{ "id": "…" }` | `NOT_FOUND` |
| POST | `/files/:id/restore` | — | `{ "id": "…" }` | `NOT_FOUND` (absente/étrangère/purgée ; vivante = succès idempotent) |
| GET | `/trash` | query `page?`, `pageSize?` | `TrashDto[]` (`{ id, type, name, size, trashedAt, updatedAt }` + `meta`) | — |
| GET | `/files/:id/versions` | — (parent live uniquement) | `VersionDto[]` (`{ versionNo, size, mimeType, createdAt }`, plus récent d'abord) | `NOT_FOUND` |
| POST | `/files/:id/versions/:n/restore` | — (l'actuel est à son tour versionné) | `FileDto` | `NOT_FOUND` |
| GET | `/files/search` | query `q` (obligatoire), `page?`, `pageSize?` | `FileDto[]` (+ `meta`) | — |
| GET | `/files/folders` | — | `FolderDto[]` (racines) | — |
| POST | `/files/upload` | multipart : `file` (uri/name/type), `folderId?` | `FileDto` | `FILE_TOO_LARGE` |
| POST | `/ocr/jobs` | `{ "fileId": "…" }` | `OcrJob` | — |
| GET | `/ocr/jobs/:id` | — | `OcrJob` | `NOT_FOUND` |
| GET | `/files/:id/ocr` | — | `FileOcr` (`{ text, updatedAt }`) | `NOT_FOUND` |
| GET | `/files/:id/facts` | — (viewer+, même portée que l'OCR) | `Fact[]` (`{ factType: date|due_date|period|amount|issuer|reference|doc_type, valueText?, valueNum?, valueDate? (ISO), confidence (0..1), origin: auto|user }`, `[]` si rien d'extractible) | `NOT_FOUND` (trashé/absent/étranger) |
| GET | `/files/:id/shares` | — (owner uniquement) | `ShareGrant[]` (`{ granteeUserId, granteeKind: "user"|"group", username, access, inherit, expiresAt (ms|null), updatedAt (ms) }`) | `NOT_FOUND` (non-owner ou inconnue — pas d'énumération) |
| GET | `/files/:id/links` | — (owner uniquement) | `ShareLink[]` (même forme que `GET /shares/links/:token`) | `NOT_FOUND` (non-owner ou inconnue) |
| GET | `/files/:id/placements` | — (owner uniquement) | `Placement[]` (`{ locationType: "server"|"mobile", deviceId?, hasBytes, updatedAt }`, entrée serveur en premier) | `NOT_FOUND` (non-owner ou inconnue) |
@@ -94,6 +99,7 @@ type FileOcr = { text: string; updatedAt?: string | null };
- `fileId` inconnu/pas du user → `NOT_FOUND`. Fichier physique introuvable (ex. suppression manuelle sous `UPLOAD_DIR`) → job `failed` `"file not readable"`. Le job est créé par le device courant (`ocr_jobs.device_id`) mais la validation de la ressource est scopée par le **user**.
- **Le texte atterrit sur la ressource** : à la complétion (`done` avec texte non vide), le worker écrit l'extrait trimé dans `resources.ocr_text` (et **bump `updated_at`**, d'où une injection dans le delta outbox/snapshot). `ocr_jobs.text` reste l'historique du job.
- **`GET /files/:id/ocr`** → `FileOcr { text, updatedAt }` : l'extrait server-side du fichier, lisible par le **possédant ET les grantees** (`viewer+`, même portée que `GET /files/:id` ; `text` `""` si pas encore extrait). Un **second device** rapatrie ainsi le texte d'un OCR fait par un autre device (ou par la ressource partagée) **sans re-téléverser les octets ni re-soumettre de job** — le client Kotlin le fait en tête de `OcrRepository.syncFromServer`/`processAuto` et du viewer (`OcrViewModel`).
- **Faits génériques V3 (`GET /files/:id/facts`)** : après chaque OCR `done`, le worker en dérive des faits vérifiables (règles FR, sans ML : dates ISO, échéances (`due_date` si mot-clé `échéance|à payer avant|date limite`), périodes (`2026-03`), montants € (confiance 0.9 si mot-clé `total|montant|à payer`), émetteurs (lignes capitales), références (`facture:FA-…`, `siret:…`, IBAN masqué `rib:••••1234`), `doc_type` suggéré (seuil de score, jamais gate). Chaque fait porte `confidence` (0..1) et `origin` (`auto` remplacé à chaque passe, `user` intouchable — corrections S3). Même portée que l'OCR (`viewer+`) ; `[]` si rien d'extractible. Backfill borné au boot (OCR d'avant la V3).
## 6. Contrat de sync (outbox + snapshot)
@@ -115,7 +121,7 @@ type FileOcr = { text: string; updatedAt?: string | null };
}
```
- `operation` ∈ `create_resource | update_metadata | delete_resource | move_resource | share | revoke_share | update_share | create_link | revoke_link | report_bytes` (cf. `PendingOperationType` mobile).
- `operation` ∈ `create_resource | update_metadata | delete_resource | move_resource | share | revoke_share | update_share | create_link | revoke_link | report_bytes | trash_resource | restore_resource | purge_resource` (cf. `PendingOperationType` mobile).
- **Identifiants** : `operation_id` est un **TEXT 32-hex** généré par le client (`^[0-9a-f]{32}$`, CHECK-enforced depuis la migration `000008`), distinct de `resource_id`. L'idempotence outbox reste **par device** : `UNIQUE(device_id, operation_id)` (la réinscription d'un device avec un login différent ne réutilise pas l'historique outbox d'un autre compte). Pour chaque op : si déjà traitée → **no-op** (comptée comme appliquée, les doublons arrivent à cause du backoff/retry). Sinon appliquée si valide.
- **Ordre** : les opérations sont appliquées **séquentiellement**, dans l'ordre du batch. Le serveur **s'arrête à la première erreur non-idempotente** et renvoie l'index atteint — le client reprend à cet index.
- Réponse : `2xx` avec `{ "applied": int, "failed": { "operation_id": "…32-hex", "code": string, "message": string } | null }` (`applied` = index de la prochaine op à envoyer).
@@ -123,7 +129,9 @@ type FileOcr = { text: string; updatedAt?: string | null };
- Sémantique d'application (côté serveur) :
- `create_resource` : crée la ressource ; **déjà présente → no-op** (rejeu idempotent). `payload.name` obligatoire ; `payload.parentResourceId` (32-hex, optionnel) = dossier parent — absent → racine. **Parent inexistant → `NOT_FOUND`** (cohérent avec `move_resource`). Ordre garanti par construction client : le walk SAF émet les `create` des dossiers (ordre préfixe) avant ceux des fichiers, dans la même transaction Room → `id ASC` = parent avant enfant.
- `update_metadata` : ressource absente → **no-op** (état terminal atteint) ; **ressource partagée : nécessite `editor+`** (§6.2) — sinon `NOT_FOUND` (une ressource visible mais sans droit de mutation n'est pas renommée) ; une ressource sans relation applicable (ni owner, ni grant) reste un no-op (pas d'énumération). `move_resource` / `delete_resource` restent **owner-only** (scoping par `user_id`, les ops d'un non-owner sont des no-op).
- `delete_resource` : **idempotent** — suppression d'une ressource absente = succès.
- `delete_resource` : **legacy → mappé vers `trash_resource`** (corbeille, restaurable, même idempotence : absent/déjà trashé = succès, vivant d'autrui = `NOT_FOUND` halt).
- **Corbeille V3** (`trash_resource` / `restore_resource` / `purge_resource`, owner-only) : `trash` pose `deleted_at` sur la ressource **et son subtree** (dossier → contenu) ; `restore` lève le flag sur la ressource, son subtree **et sa chaîne d'ancêtres** (un fichier restauré dont le dossier est encore trashé resterait injoignable) ; `purge` détruit lignes + versions + octets. Sémantique : absent → no-op (`trash`/`restore`/`purge`), vivant d'autrui → `NOT_FOUND` halt, `restore` d'un live → no-op succès. Une ressource trashée reste `NOT_FOUND` en lecture normale, visible seulement via `GET /trash`. Passe serveur : destruction définitive après 30j (`TrashRetention`).
- **Versions V3** : chaque overwrite d'octets (upload ciblé) fige l'ancienne génération (`resource_versions`, N=3, élagage auto) ; `POST /files/:id/versions/:n/restore` recopie vers le live (l'actuel est à son tour versionné). Upload ciblé vers une ressource trashée → `NOT_FOUND` (jamais de résurrection d'octets).
- **Partage** (`share` / `update_share`, même sémantique d'upsert) : `payload = { "granteeUserId"?: "…32-hex", "granteeGroupId"?: "…32-hex", "access": "viewer"|"commenter"|"editor", "inherit"?: bool, "expiresAt"?: ms }` — **exactement un** principal (user XOR groupe, V2-6). La ressource doit **appartenir** au user appelant (sinon `NOT_FOUND`) ; le grantee user doit exister (sinon `GRANTEE_NOT_FOUND`), le groupe doit exister (sinon `GROUP_NOT_FOUND`) ; accès déjà partagé → mis à jour (idempotent). Privilégier `viewer` < `commenter` < `editor` (< `owner` réservé à l'ownership, non partageable → `INVALID_REQUEST`). Les membres d'un groupe partagé héritent du grant (un niveau, sans imbrication) dans le snapshot comme dans l'enforcement.
- `revoke_share` : `payload = { "granteeUserId": "…32-hex" }`. **Idempotent** (déjà révoqué/absent → no-op).
- `create_link` : `payload = { "token": "…32-hex", "access": "viewer"|"commenter"|"editor", "expiresAt"?: ms }`. Le token est **généré côté client** (`GenerateId`), c'est l'identifiant du lien (colonne `id` de `share_links`).