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