webmanager-mvp/project_docs/BACKEND_V1_CONSOLIDATION.md

BACKEND_V1_CONSOLIDATION.md

Doel

Consolidatie van de huidige backend v1 contracten en beperkingen.

Huidige endpoints

Directe endpoints (geen task-creatie):

• GET /api/browse
• POST /api/files/mkdir
• POST /api/files/rename
• POST /api/files/delete
• GET /api/tasks
• GET /api/tasks/{task_id}

Task-based create endpoints:

• POST /api/files/copy
• POST /api/files/move

Semantiek per endpoint

GET /api/browse

• Browse van een directory binnen whitelist roots.
• Hidden files standaard verborgen, optioneel via show_hidden=true.

POST /api/files/mkdir

• Maakt directory op exact parent_path + name.
• Geen impliciete pad-normalisatie buiten path_guard validatie.

POST /api/files/rename

• Hernoemt binnen dezelfde parent directory.
• Geen verborgen move naar andere map.

POST /api/files/delete

• Verwijdert file direct.
• Verwijdert alleen lege directory.
• Non-empty directory => conflict.

POST /api/files/copy

• File-only copy.
• destination is volledig doelpad (geen "copy into directory").
• Task wordt aangemaakt (202, task_id, queued) en daarna uitgevoerd.

POST /api/files/move

• File-only move.
• destination is volledig doelpad.
• Task wordt aangemaakt (202, task_id, queued) en daarna uitgevoerd.
• Same-root: native move.
• Cross-root: copy + delete binnen dezelfde task.

GET /api/tasks

• Lijst van tasks, gesorteerd op created_at DESC.
• Item bevat minimaal: id, operation, status, source, destination, created_at, finished_at.

GET /api/tasks/{task_id}

• Detailstatus inclusief progress/foutvelden.
• Statusset: queued, running, completed, failed.

Foutmodel per endpointgroep

Browse/file-validatie

• invalid_request
• path_traversal_detected
• path_outside_whitelist
• invalid_root_alias
• path_not_found
• type_conflict
• already_exists
• directory_not_empty (delete)

Task create runtime

• validatiefouten vóór task-creatie: directe API-fout, geen task
• runtime-fouten tijdens task-uitvoering: task naar failed met io_error

Tasks read

• task_not_found bij onbekend task id

Expliciete v1-beperkingen

• copy: file-only
• move: file-only
• delete: alleen file + lege directory
• geen recursive delete
• geen directory copy/move
• geen rollback
• geen cancel/retry
• geen batch-operaties