webmanager-mvp/project_docs/BATCH_DIRECTORY_MOVE_V1_DESIGN.md

# Batch Directory Move v1

## 1. Scope

Doel van batch directory move v1 is het gecontroleerd ondersteunen van verplaatsingen voor meerdere geselecteerde items via de bestaande move/task-flow, zonder de huidige file-flow te destabiliseren.

Aanbevolen v1-scope:
- alleen same-root batch move
- meerdere directories ondersteunen
- gemengde selectie van files + directories ondersteunen, maar alleen binnen dezelfde root
- geen cross-root batch directory move
- geen rollback
- geen recursive copy-delete move voor directories
- geen partial rename-semantiek in batchmodus

Niet in scope:
- cross-root batch directory move
- batch move met meerdere roots tegelijk
- batch move met conflictoplossing UI
- cancel/retry
- rollback bij gedeeltelijk succes
- hernoemen per item binnen batch-popup

## 2. Selectiesituaties

### Meerdere directories
- Toegestaan in v1, mits alle geselecteerde directories binnen dezelfde root vallen.
- Bestemming is de current path van het inactieve paneel.
- Elk item krijgt als doelpad: `destination_base + / + item.name`.

### Meerdere files + directories gemengd
- Toegestaan in v1, mits alle geselecteerde items binnen dezelfde root vallen.
- Files en directories worden in dezelfde batch verwerkt.
- Elk item gebruikt dezelfde destination-map semantiek.

### 1 directory + meerdere files
- Valt onder gemengde selectie en is dus toegestaan onder dezelfde same-root-regels.

### Niet toegestaan in v1
- selectie die items uit verschillende roots combineert
- selectie waarbij voor een directory het doelpad in de eigen subtree valt
- selectie met symlink-source-items
- selectie waarbij een doelpad al bestaat

## 3. Same-root versus cross-root

Aanbevolen v1-keuze:
- batch directory move blijft beperkt tot same-root
- cross-root batch directory move wordt expliciet geblokkeerd

Motivatie:
- same-root kan native rename/move gebruiken en sluit aan op de huidige directory move v1
- cross-root voor directories vereist recursieve copy + delete en introduceert veel meer partial-failure-risico
- gemengde batch over roots maakt progress, foutafhandeling en rollback aanzienlijk complexer

Geblokkeerde melding in v1:
- `Cross-root batch directory move is not supported in v1`

## 4. Taskmodel

Aanbevolen richting:
- één task voor de hele batch

Motivatie:
- sluit beter aan op de gebruikersactie: één batch-confirmatie, één batchresultaat
- voorkomt een explosie van losse tasks bij grote selecties
- maakt batchprogress en foutsamenvatting eenvoudiger zichtbaar

Progress:
- `done_items` / `total_items` zijn leidend
- `total_items` = aantal geselecteerde top-level items in de batch
- `done_items` telt per succesvol verplaatst top-level item op
- `done_bytes` / `total_bytes` blijven `null` in v1 voor batch directory move
  - ook bij gemengde selectie is het verstandig in v1 item-gebaseerde progress leidend te houden

Failure-semantiek:
- fail-fast binnen de batchtask
- bij eerste runtime-fout stopt verdere verwerking
- task eindigt als `failed`
- reeds verplaatste items blijven verplaatst
- geen rollback in v1

Partial completion model:
- partial completion wordt impliciet zichtbaar via `done_items < total_items`
- `failed_item` bevat het item waarop de batch stopte
- geen aparte `partial_completed` status in v1

## 5. Backend-impact

Hergebruik:
- bestaande move-validatie voor individuele file/directory move
- bestaande task persistence en read-endpoints
- bestaande same-root native move in filesystem adapter
- bestaande path_guard containment en symlink-afwijzing

Waarschijnlijke wijzigingen:
- move service: batchvalidatie en task-creatie voor meerdere items
- task runner: batch move worker
- filesystem adapter: hergebruik van bestaande file move en directory move primitives
- task repository: waarschijnlijk geen schemawijziging nodig als `done_items`, `total_items`, `current_item`, `failed_item` al volstaan

Belangrijk semantisch behoud:
- rename voor exact 1 item blijft apart via bestaande rename-flow/F6-popupbeslislogica
- batchmodus is altijd move, nooit rename

## 6. UI-impact

Gedrag voor Move-knop en F6:
- bij meerdere geselecteerde items mag de bestaande batch move-confirmatie worden hergebruikt
- die confirmatie moet duidelijk tonen:
  - aantal geselecteerde items
  - destination-map
  - dat batch same-root vereist voor directories
- voor gemengde selectie moet dezelfde batch-confirmatie bruikbaar blijven

Benodigde meldingen:
- `Cross-root batch directory move is not supported in v1`
- `Batch move requires all selected items to be in the same root`
- `Destination already exists for one or more items`
- `Destination cannot be inside source`
- `Source must not be a symlink`

Aanbeveling:
- hergebruik bestaande batch confirm-popup
- geen extra popup-type toevoegen in v1
- alleen de validatietekst en submit-logica uitbreiden

## 7. Security en validatie

Per item moeten minimaal deze checks gelden:
- source ligt binnen whitelist
- destination-parent ligt binnen whitelist
- source is geen symlink
- destination bestaat nog niet
- directory destination ligt niet in subtree van source
- same-root verplicht voor directories in batch v1

Gemengde foutgevallen:
- als selectie meerdere roots bevat: directe validatiefout vóór task-creatie
- als één item ongeldig is: hele batchcreatie afwijzen vóór task-creatie
- geen "best effort" pre-validatie waarbij geldige items toch alvast starten

Containment:
- path_guard blijft leidend voor alle bron- en doelpaden
- geen vrije pathconstructie buiten bestaande root mapping

## 8. Teststrategie

Golden tests:
- batch same-root directories success
- batch same-root mixed files + directories success
- batch cross-root directories blocked
- batch mixed-root selection blocked
- batch destination exists blocked
- batch destination inside source blocked
- batch symlink source blocked
- batch task failed shape bij runtime io_error

Regressietests:
- exacte 1 file move-flow blijft ongewijzigd
- exacte 1 directory same-root move blijft werken
- batch file-only move blijft werken
- F6 rename/move voor exact 1 item blijft semantisch gelijk

Securitytests:
- traversal in één van de source paths
- traversal in destination base
- symlink directory source
- symlink file source binnen gemengde selectie

Runtime edge cases:
- eerste item succeeds, tweede faalt -> task failed met `done_items == 1`
- destination conflict ontdekt vóór task-creatie
- empty selection blijft no-op in UI, geen backend-aanroep

## 9. Aanbeveling

Aanbevolen v1-richting met laag regressierisico:
- ondersteun alleen same-root batch move
- ondersteun gemengde selectie van files + directories alleen als alle items in dezelfde root zitten
- gebruik één task per batch
- gebruik item-based progress (`done_items` / `total_items`)
- fail-fast zonder rollback
- hergebruik bestaande batch move-confirmatie in de UI

Waarom deze richting:
- bouwt rechtstreeks voort op de huidige same-root directory move v1 en batch file move
- beperkt backendcomplexiteit tot validatie + batchrunner, zonder cross-root recursieve directorylogica
- houdt de UI voorspelbaar: één batchactie, één task, één resultaat
- minimaliseert regressierisico voor de bestaande single-item file-flow en F6-semantiek