webmanager-mvp/project_docs/HISTORY_V1_DESIGN.md

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