From 6dd5faf65d1c9f090e13ea43ac3149b1b6b89a38 Mon Sep 17 00:00:00 2001 From: Dev Date: Fri, 3 Apr 2026 09:07:34 +0200 Subject: [PATCH] docs(04): capture phase context for Bulk Operations and Provisioning Co-Authored-By: Claude Opus 4.6 (1M context) --- .../04-CONTEXT.md | 114 ++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 .planning/phases/04-bulk-operations-and-provisioning/04-CONTEXT.md diff --git a/.planning/phases/04-bulk-operations-and-provisioning/04-CONTEXT.md b/.planning/phases/04-bulk-operations-and-provisioning/04-CONTEXT.md new file mode 100644 index 0000000..7c6160c --- /dev/null +++ b/.planning/phases/04-bulk-operations-and-provisioning/04-CONTEXT.md @@ -0,0 +1,114 @@ +# Phase 4: Bulk Operations and Provisioning - Context + +**Gathered:** 2026-04-02 +**Status:** Ready for planning + + +## Phase Boundary + +Users can execute bulk write operations (member additions, site creation, file transfer) with per-item error reporting and cancellation, capture site structures as reusable templates, apply templates to create new sites, and provision folder structures from CSV — all without silent partial failures. + +Requirements: BULK-01, BULK-02, BULK-03, BULK-04, BULK-05, TMPL-01, TMPL-02, TMPL-03, TMPL-04, FOLD-01, FOLD-02 + + + + +## Implementation Decisions + +### Bulk operation failure behavior +- Continue all items on error, report summary at end — never stop on first failure +- Errors are logged live in the log panel (red) AND user can export a CSV of failed items after completion +- Failed-items CSV includes: original row data, error message, timestamp — user can fix and re-import +- "Retry Failed" button appears after completion with partial failures, re-runs only failed items +- User can also manually re-import the corrected failed-items CSV +- Always show a confirmation summary dialog before any bulk write operation starts (e.g., "12 members will be added to 3 groups — Proceed?") + +### File transfer semantics +- User chooses Copy or Move (radio button or dropdown) — both options always visible +- Move deletes source files only after successful transfer to destination +- Conflict policy is user-selectable per operation: Skip / Overwrite / Rename (append suffix) +- One conflict policy applies to all files in the batch +- Source and destination selection: site picker + library/folder tree browser on both sides (reuse SitePickerDialog pattern from Phase 2) +- Metadata preservation: best effort — try to set original author and dates via CSOM; if SharePoint rejects (common cross-tenant), log a warning and continue + +### Template capture scope +- User selects what to capture via checkboxes (not a fixed capture) +- Available capture options (core set): Libraries, Folders, Permission groups, Site logo, Site settings (title, description, regional settings) +- No custom columns, content types, or navigation links in v1 — keep templates lightweight +- Template remembers source site type (Communication or Teams) and creates the same type on apply — no user choice of target type +- Templates persisted as JSON locally (TMPL-03) +- Dedicated Templates tab in the main UI — templates are a first-class feature area with: list of saved templates, capture button, apply button, rename/delete + +### CSV format and pre-flight validation +- Bundled example CSV templates shipped with the app for each bulk operation (member addition, site creation, folder structure) — pre-filled with sample data as reference +- After CSV import: full validation pass + DataGrid preview showing all rows with valid/invalid indicators +- User reviews the preview grid, then clicks "Execute" to proceed +- Invalid rows highlighted — user can fix and re-import before executing +- CSV encoding: UTF-8 with BOM detection (accept with or without BOM, matches Excel output and app's own CSV exports) + +### Tab organization +- Each operation gets its own top-level tab: Transfer, Bulk Members, Bulk Sites, Folder Structure, Templates +- Matches the existing PowerShell tool's tab structure +- Each tab follows FeatureViewModelBase pattern (AsyncRelayCommand + IProgress + CancellationToken) + +### Claude's Discretion +- Exact CSV column names and schemas for each bulk operation type +- Tree browser component implementation details for file transfer source/destination +- Template JSON schema structure +- PnP Provisioning Engine usage details for template apply +- Confirmation dialog layout and wording +- DataGrid preview grid column configuration +- Retry mechanism implementation details + + + + +## Existing Code Insights + +### Reusable Assets +- `FeatureViewModelBase`: Base for all feature ViewModels — AsyncRelayCommand, IProgress, CancellationToken, TenantSwitchedMessage handling +- `SitePickerDialog`: Site selection dialog from Phase 2 — reuse for source/destination pickers in file transfer +- `OperationProgress(int Current, int Total, string Message)`: Shared progress model used by all services +- `ExecuteQueryRetryHelper`: Auto-retry on 429/503 with exponential backoff — all CSOM calls use this +- `SharePointPaginationHelper`: Async enumerable for paginated list queries +- `SessionManager`: Singleton holding all ClientContext instances — GetOrCreateContextAsync(TenantProfile, CancellationToken) +- `CsvExportService` pattern: UTF-8 BOM, RFC 4180 quoting — follow for bulk operation error report exports + +### Established Patterns +- Service interfaces registered as transient in DI (App.xaml.cs) +- ViewModels use `[ObservableProperty]` attributes + `ObservableCollection` for results +- Export commands use SaveFileDialog wired via Func<> factory from View code-behind +- Per-tab progress bar + cancel button (Visibility bound to IsRunning) +- Results accumulated in List on background thread, assigned as new ObservableCollection on UI thread + +### Integration Points +- `App.xaml.cs RegisterServices()`: Add new services, ViewModels, Views +- `MainWindow.xaml`: Add new TabItems for Transfer, Bulk Members, Bulk Sites, Folder Structure, Templates +- `MainWindow.xaml.cs`: Wire View content from DI at runtime (same pattern as Permissions, Storage, Search tabs) +- `Core/Models/`: New models for bulk operation items, template schema, CSV row types +- `Services/`: New service interfaces and implementations for each bulk operation +- `Strings.resx` / `Strings.fr.resx`: Localization keys for all Phase 4 UI strings + + + + +## Specific Ideas + +- Tab structure should match the existing PowerShell tool (9 tabs: Perms, Storage, Templates, Search, Dupes, Transfer, Bulk, Struct, Versions) +- Bundled CSV examples should have realistic sample data (not just headers) so MSP admins can understand the format immediately +- Confirmation dialog before writes is non-negotiable — these are destructive operations on client tenants +- Failed-items CSV should be directly re-importable without editing (same format as input CSV, with an extra error column appended) + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 04-bulk-operations-and-provisioning* +*Context gathered: 2026-04-02*