feat: logging toegevoegd

project_docs/HISTORY_V1_DESIGN.md

@@ -0,0 +1,207 @@
+# History v1 Design
+
+## 1. Doel
+History is nuttig om recente bestandsacties snel terug te kunnen zien zonder in logs of taskdetails te hoeven zoeken. In de huidige app is dat vooral relevant omdat er nu zowel directe acties bestaan als task-based acties.
+
+Praktisch nut in v1:
+
+- snel zien wat net is aangemaakt, hernoemd, verwijderd, gekopieerd of verplaatst
+- foutgevallen terugvinden zonder afhankelijk te zijn van vluchtige statusmeldingen in de UI
+- task-based acties en directe acties in één compact overzicht samenbrengen
+
+Relatie tot het taskmodel:
+
+- tasks beschrijven vooral uitvoering en progress van asynchrone operaties
+- history beschrijft afgeronde of mislukte gebruikersacties in een uniform audit-achtig overzicht
+- history is dus geen vervanging van tasks, maar een compacte gebruikslaag erboven
+
+## 2. Scope
+Acties die in v1 in history komen:
+
+- `mkdir`
+- `rename`
+- `delete`
+- `copy`
+- `move`
+
+Voorstel voor opnamegedrag:
+
+- zowel success als failure opnemen
+- validatiefouten vóór task-creatie ook opnemen, zodat mislukte gebruikersacties zichtbaar blijven
+- task-based runtime failures ook opnemen
+
+Niet in scope in v1:
+
+- browse-navigatie
+- bookmark-acties
+- view/edit openen
+- theme- of UI-acties
+
+## 3. Relatie Tasks Versus History
+Aanbevolen richting: history als aparte tabel/model.
+
+Waarom niet alleen afleiden uit tasks:
+
+- `mkdir`, `rename` en `delete` zijn directe acties en hebben nu geen task-record
+- een uniforme history uit alleen tasks zou dus onvolledig zijn
+- directe acties kunstmatig als tasks modelleren zou scope verbreden en regressierisico verhogen
+
+Aanbevolen model:
+
+- `tasks` blijft bestaan voor asynchrone uitvoering en polling
+- `history` wordt een aparte persistente tabel
+- directe acties schrijven direct naar `history`
+- task-based acties schrijven naar `history`:
+  - bij task-creatie: history-item aanmaken met `status = queued` of `running` is mogelijk, maar niet nodig voor compacte v1
+  - aanbevolen eenvoudiger v1: history-item pas definitief vullen bij task completion/failure
+
+Pragmatische v1-keuze:
+
+- bij create van copy/move-task meteen een history-record aanmaken met initiële status `queued`
+- task-runner werkt dat record daarna bij naar `completed` of `failed`
+- directe acties schrijven direct één afgerond history-record
+
+Dit geeft één consistent overzicht zonder complexe reconstructie.
+
+## 4. Minimale Data Per History-Item
+Minimaal benodigde velden:
+
+- `id`
+- `operation`
+- `status`
+- `source`
+- `destination`
+- `path`
+- `error_code`
+- `error_message`
+- `created_at`
+- `finished_at`
+
+Aanbevolen semantiek per veld:
+
+- `id`: intern history-id
+- `operation`: `mkdir | rename | delete | copy | move`
+- `status`: `completed | failed | queued | running`
+- `source`: bronpad voor `copy`, `move`, eventueel `rename`
+- `destination`: doelpad voor `copy`, `move`, eventueel impliciet nieuw pad bij `rename`
+- `path`: enkelvoudig actiedoel voor directe acties zoals `mkdir` en `delete`
+- `error_code`: gestandaardiseerde foutcode indien mislukt
+- `error_message`: compacte user-facing fouttekst
+- `created_at`: moment waarop actie of task gestart is
+- `finished_at`: moment waarop actie of task eindigde
+
+Opmerking:
+
+- niet elk veld is voor elke operatie gevuld
+- `path` is vooral nuttig voor enkelvoudige directe acties
+- `source` en `destination` zijn vooral nuttig voor `copy/move/rename`
+
+## 5. UI-richting
+De dual-pane workspace moet leidend blijven. History moet dus niet als permanent groot paneel in het hoofdscherm verschijnen.
+
+Aanbevolen UI-richting voor v1:
+
+- compacte aparte modal of slide-over vanuit de topbar of functiebalk
+- toont een eenvoudige lijst van recente acties
+- recentste items bovenaan
+- per regel compact:
+  - operation
+  - status
+  - kernpad of source -> destination
+  - tijdstip
+
+Waarom geen vast zijpaneel:
+
+- dat zou de dual-pane workspace verstoren
+- history is ondersteunend, niet primair
+
+Aanbevolen v1-keuze:
+
+- aparte `History` modal met compacte lijstweergave
+- optioneel later uitbreidbaar met detailweergave
+
+## 6. Scopebeperking
+Niet in scope in v1:
+
+- undo
+- retry
+- export
+- uitgebreide filtering
+- full-text search
+- pagination, tenzij de lijst onverwacht groot wordt
+
+Aanbevolen eenvoud:
+
+- beperk API en UI in v1 tot recente items, bijvoorbeeld de laatste 100 of 200 records
+- sortering: `created_at DESC`
+
+## 7. Backend-impact
+Waarschijnlijk geraakte componenten:
+
+- SQLite schema/migratie
+- repository-laag voor `history`
+- services voor directe acties:
+  - `mkdir`
+  - `rename`
+  - `delete`
+- task create-services:
+  - `copy`
+  - `move`
+- task runner voor statusupdate van task-based history-items
+- nieuwe read-endpoint(s) voor history
+
+SQLite-uitbreiding:
+
+- ja, een aparte `history` tabel is nodig
+
+Aanbevolen v1-vulling:
+
+- directe acties:
+  - service maakt history-record direct bij succes/failure
+- task-acties:
+  - bij task-creatie history-record met `queued`
+  - task-runner update naar `running`, `completed` of `failed`
+
+Voordeel:
+
+- history wordt niet afgeleid uit meerdere bronnen bij read-time
+- minder complexe querylogica
+- lagere kans op inconsistent UI-gedrag
+
+## 8. Teststrategie
+Golden tests:
+
+- `GET /api/history` lege lijst
+- lijstshape voor gemengde directe en task-based entries
+- directe success-entry voor `mkdir`
+- directe failure-entry voor `rename` of `delete`
+- task-based completed-entry voor `copy` of `move`
+- task-based failed-entry voor `copy` of `move`
+- sortering `created_at DESC`
+
+Regressietests:
+
+- bestaande endpoints behouden hun contract
+- toevoegen van history mag directe actie- of taskflows niet veranderen
+- taskstatus en historystatus moeten consistent blijven
+
+Handmatige validatie:
+
+- na `mkdir/rename/delete` verschijnt history-item correct
+- na `copy/move` verschijnt history-item met juiste status na afloop
+- foutmeldingen in history zijn begrijpelijk en compact
+
+## 9. Aanbeveling
+Aanbevolen v1-richting met laag regressierisico:
+
+- voeg een aparte `history` tabel toe in SQLite
+- vul history expliciet vanuit services en task-runner
+- expose één eenvoudige read-API voor recente history-items
+- toon history in een compacte aparte modal, niet in het hoofdscherm
+
+Waarom dit de veiligste richting is:
+
+- geen herontwerp van bestaand taskmodel nodig
+- directe acties en task-based acties komen uniform samen
+- UI blijft compact en de dual-pane workflow blijft centraal
+- implementatie is incrementeel en goed testbaar