docs(phase-14): plan selective analysis and byte cache

2026-06-23 14:24:43 +02:00
parent 3514fdcf3a
commit b528b51881
13 changed files with 1117 additions and 16 deletions
@@ -0,0 +1,93 @@
+# Phase 14 Patterns
+
+## Shared Boundaries
+
+- `StorageBrowser.vue` remains the only file browser. Analysis actions, aggregate progress, and expandable queue UI belong there.
+- `CloudFolderView.vue` remains a thin data provider. It calls the store/API helpers and refreshes browse state; it does not own browser layout or queue rendering.
+- Backend routers translate typed request/response schemas and HTTP status codes only. Service modules own analysis, cache, quota, and idempotency behavior and must not raise `HTTPException`.
+- Cloud provider credentials are decrypted only inside route/task provider boundaries. Celery payloads contain IDs and control flags only.
+
+## Status Vocabulary
+
+Durable internal item statuses:
+
+- `queued`
+- `downloading`
+- `extracting`
+- `classifying`
+- `indexed`
+- `already_current`
+- `cancelled`
+- `failed`
+- `unsupported`
+- `stale`
+
+UI label mapping:
+
+- simple default: waiting, working, done, skipped, failed
+- detailed setting: queued, downloading, extracting, classifying, indexed, cancelled, failed
+
+Do not let frontend components invent a second status translation. Put API-to-UI translation in the Pinia store or a shared formatter/helper.
+
+## Version Keys
+
+Create one shared helper for cloud analysis version keys. All estimate, enqueue, duplicate-check, cache lookup, and worker paths must call it.
+
+Precedence:
+
+1. `version`
+2. `etag`
+3. metadata fingerprint from provider item id, size, modified time, content type
+4. content hash as an additional post-hydration fact, never as a pre-download requirement
+
+## Cache Lifecycle
+
+1. Resolve owner and item.
+2. Compute version key.
+3. Reuse non-evicted matching cache entry if present.
+4. Otherwise hydrate provider bytes through the mutable/content adapter boundary.
+5. Store bytes under a UUID/private MinIO key.
+6. Atomically increment user quota by retained size.
+7. Pin for active job or preview.
+8. Release pin when finished.
+9. Evict inactive LRU entries when the user's configured limit or quota pressure requires it.
+
+Eviction failure must not hide successful analysis. It should surface controlled warning state and leave quota/cache metadata consistent.
+
+## Estimate Semantics
+
+Small file jobs may start directly. Folder and connection jobs estimate first when thresholds are crossed, and whole-connection analysis always estimates unless trivially small.
+
+Estimate responses include:
+
+- supported file count
+- provider-reported byte total
+- unsupported/skipped item count
+- whether recursion applies
+- whether the estimate is complete or partial
+
+The estimate endpoint must never download bytes.
+
+## Error and Control Semantics
+
+- Batch failure behavior defaults to `pause_batch`.
+- `continue_item` pauses only the failed item and keeps later queued items running.
+- Per-item retry restarts the full item.
+- Per-item skip/cancel affects that item only.
+- Batch cancel cancels queued items and requests cooperative cancellation for running work.
+- Typed error bodies use controlled `kind` and `reason` fields, matching the Phase 13 mutation response style.
+
+## Test Pattern
+
+Each implementation plan starts with focused red tests for its slice, then implementation, then targeted verification.
+
+Required negative coverage by the end of the phase:
+
+- foreign user cannot estimate, enqueue, read status, cancel, retry, or read cache metadata
+- admin cannot access cloud analysis/cache routes
+- cache object keys and credentials never appear in responses or audit logs
+- unchanged etag/version skips duplicate analysis without byte download
+- cached bytes count against quota while retained and decrement after eviction
+- active jobs/previews are not evicted
+- folder/connection analysis does not mutate provider files
+