feat: logging toegevoegd
This commit is contained in:
kodi
@@ -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
|
||||
@@ -0,0 +1,89 @@
|
||||
# UI Directory Selection Parity v1
|
||||
|
||||
## 1. Haalbaarheid
|
||||
De huidige advanced selection logica is grotendeels generiek genoeg om ook directories te dragen.
|
||||
|
||||
Wat al generiek werkt:
|
||||
|
||||
- `selectedItems` bevat zowel files als directories
|
||||
- `currentRowIndex` is niet typegebonden
|
||||
- `selectionAnchorIndex` is niet typegebonden
|
||||
- `Shift + ArrowUp/ArrowDown` werkt op `visibleItems` en kan daardoor in principe zowel files als directories meenemen
|
||||
- checkbox-toggle gebruikt al `{ path, name, kind }` en werkt daarmee voor beide itemtypes
|
||||
- `Cmd/Ctrl + klik` toggle-logica is ook type-onafhankelijk opgezet
|
||||
|
||||
Wat expliciet aandacht vraagt:
|
||||
|
||||
- directorynaam heeft een aparte open-semantiek en moet dus buiten selectieclicks blijven vallen
|
||||
- rij-click en naam-click moeten scherp gescheiden blijven, anders ontstaat onbedoelde navigatie of onbedoelde selectie
|
||||
- parent-entry `..` mag niet in gewone selectie terechtkomen
|
||||
|
||||
Conclusie: directory selection parity is technisch goed haalbaar binnen het huidige model. Er is geen nieuw state-model nodig.
|
||||
|
||||
## 2. Gewenst Gedrag Voor Directories
|
||||
Voor directories moet exact dit gelden:
|
||||
|
||||
- gewone rij-click op een directory, buiten de naam:
|
||||
- single-select van die directory
|
||||
- checkbox-click op een directory:
|
||||
- toggle selectie van die directory
|
||||
- `Cmd + klik` op Mac / `Ctrl + klik` op niet-Mac op een directoryrij, buiten de naam:
|
||||
- toggle die directory zonder andere selectie te wissen
|
||||
- `Shift + ArrowUp/ArrowDown`:
|
||||
- directories mogen normaal onderdeel zijn van een range
|
||||
- klik op directorynaam:
|
||||
- opent de directory
|
||||
- selecteert niet
|
||||
|
||||
Dit sluit aan op het bestaande uitgangspunt dat de directorynaam een navigatie-affordance is en de rest van de rij een selectie-affordance.
|
||||
|
||||
## 3. Gemengde Selectie
|
||||
Gemengde selectie van files en directories in dezelfde selectie of range is logisch en veilig binnen de huidige UI, mits dezelfde regels blijven gelden:
|
||||
|
||||
- range-selectie volgt de zichtbare volgorde in de lijst, ongeacht itemtype
|
||||
- `selectedItems` mag dus een mix bevatten van files en directories
|
||||
- vervolgacties bepalen daarna zelf of de selectie geldig is voor die actie
|
||||
|
||||
Dat past al bij de huidige UI:
|
||||
|
||||
- delete accepteert gemengde selectie al functioneel volgens backendmogelijkheden
|
||||
- move/copy tonen of blokkeren al op basis van inhoud en scope
|
||||
- rename/view/edit blijven enkel- of typegebonden
|
||||
|
||||
Conclusie: gemengde selectie is in de huidige UI logisch en hoeft niet apart verboden te worden.
|
||||
|
||||
## 4. Regressierisico
|
||||
Belangrijkste risico's:
|
||||
|
||||
- botsing tussen directorynaam = openen en rij-click = selecteren
|
||||
- modifier-click op of rond de directorynaam die per ongeluk navigeert in plaats van togglet
|
||||
- inconsistentie waarbij file-naam single-select doet, maar directorynaam opent
|
||||
|
||||
Dit risico is beheersbaar zolang de scheiding expliciet blijft:
|
||||
|
||||
- directorynaam is alleen navigatie
|
||||
- checkbox is alleen toggle
|
||||
- rij buiten de naam is selectie
|
||||
|
||||
Het grootste praktische regressierisico zit niet in range-selectie, maar in click-targets binnen de directoryrij. Als event bubbling of target-selectie daar niet scherp genoeg is, voelt directory-selectie inconsistent.
|
||||
|
||||
## 5. Aanbeveling
|
||||
Aanbevolen conclusie voor v1:
|
||||
|
||||
- directory selection parity vraagt waarschijnlijk geen herontwerp
|
||||
- er is waarschijnlijk hooguit een kleine frontend-correctiestap nodig als bij handmatige verificatie blijkt dat modifier-click of row-click rond directorynamen nog niet overal exact hetzelfde aanvoelt als bij files
|
||||
|
||||
Concreet advies:
|
||||
|
||||
- eerst handmatig valideren of directoryrijen zich nu al correct gedragen voor:
|
||||
- gewone rij-click
|
||||
- checkbox-toggle
|
||||
- `Cmd/Ctrl + klik`
|
||||
- `Shift + Arrow` range
|
||||
- alleen als daar inconsistentie blijkt, een kleine gerichte frontend-fix doen in `app.js`
|
||||
|
||||
Kort oordeel:
|
||||
|
||||
- het huidige model is sterk genoeg voor directory parity
|
||||
- waarschijnlijk is geen grote codewijziging nodig
|
||||
- mogelijk is alleen een kleine frontend-correctiestap nodig rond click-target gedrag
|
||||
Reference in New Issue
Block a user