# 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