207 lines
11 KiB
Markdown
207 lines
11 KiB
Markdown
# Feature Specification: Policy Explorer V2
|
|
|
|
**Feature Branch**: `004-policy-explorer-v2`
|
|
**Created**: 2025-12-08
|
|
**Status**: Draft
|
|
**Input**: "Policy Explorer V2 - Advanced data table with pagination, sorting, filtering, column management, bulk export, and enhanced detail view for Intune policy settings analysis"
|
|
|
|
## Overview
|
|
|
|
Erweiterung des bestehenden Policy Explorers (`/search`) von einer einfachen Such-/Tabellenansicht zu einem vollwertigen Admin-Interface für die Analyse großer Policy-Datasets mit erweiterten Funktionen für Navigation, Filterung, Sortierung und Export.
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### User Story 1 - Advanced Data Table Navigation (Priority: P1)
|
|
|
|
Als Intune-Admin möchte ich durch große Policy-Datasets navigieren können mit Pagination, Sortierung und anpassbaren Spalten, um schnell relevante Settings zu finden.
|
|
|
|
**Why this priority**: Grundlegende Tabellenfunktionalität ist essentiell für die Arbeit mit >100 Settings. Ohne Pagination und Sortierung wird die Tabelle unbrauchbar.
|
|
|
|
**Independent Test**: Dataset mit 500+ Settings laden, Pagination durchklicken, nach verschiedenen Spalten sortieren, Spalten ein-/ausblenden.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** der Admin hat 200+ Policy Settings im System, **When** er den Policy Explorer öffnet, **Then** sieht er maximal 50 Settings pro Seite mit Pagination Controls (Previous, Next, Page Numbers).
|
|
2. **Given** der Admin sieht die Tabelle, **When** er auf einen Spalten-Header klickt, **Then** wird die Tabelle nach dieser Spalte sortiert (Toggle: ASC/DESC).
|
|
3. **Given** der Admin sieht die Tabelle, **When** er das Column Visibility Menu öffnet und Spalten deselektiert, **Then** werden diese Spalten ausgeblendet und die Einstellung bleibt beim Reload erhalten (localStorage).
|
|
4. **Given** der Admin sieht die Tabelle, **When** er eine Spaltenbreite mit der Maus anpasst, **Then** wird die neue Breite gespeichert (localStorage).
|
|
5. **Given** der Admin scrollt nach unten, **When** er weiter scrollt, **Then** bleibt der Table Header sichtbar (sticky).
|
|
|
|
---
|
|
|
|
### User Story 2 - Enhanced Filtering (Priority: P1)
|
|
|
|
Als Intune-Admin möchte ich nach PolicyType filtern können, um nur relevante Policy-Kategorien zu sehen.
|
|
|
|
**Why this priority**: Filter sind essentiell für die Arbeit mit verschiedenen Policy-Typen (Compliance, Security, Configuration).
|
|
|
|
**Independent Test**: PolicyType Filter auswählen, Ergebnisse validieren, Filter kombinieren mit Suche.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** der Admin öffnet den Policy Explorer, **When** er den PolicyType Filter öffnet, **Then** sieht er alle verfügbaren Policy Types als Checkboxen (deviceConfiguration, compliancePolicy, etc.).
|
|
2. **Given** der Admin hat einen PolicyType ausgewählt, **When** die Tabelle lädt, **Then** werden nur Settings dieses Typs angezeigt.
|
|
3. **Given** der Admin hat Filter + Suche kombiniert, **When** er die Seite neu lädt, **Then** bleiben Filter und Suche aktiv (URL state).
|
|
|
|
---
|
|
|
|
### User Story 3 - Bulk Export (Priority: P1)
|
|
|
|
Als Intune-Admin möchte ich Policy Settings als CSV exportieren können, um sie in Excel/Sheets zu analysieren oder zu dokumentieren.
|
|
|
|
**Why this priority**: Export ist ein häufig gefordertes Feature für Compliance-Reports und Dokumentation.
|
|
|
|
**Independent Test**: Rows selektieren, CSV Export triggern, Datei öffnen und Inhalt validieren.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** der Admin hat Rows in der Tabelle selektiert, **When** er "Export Selected" klickt, **Then** wird ein CSV mit den selektierten Rows heruntergeladen.
|
|
2. **Given** der Admin hat Filter angewendet, **When** er "Export All Filtered" klickt, **Then** wird ein CSV mit allen gefilterten Results heruntergeladen (serverseitig generiert).
|
|
3. **Given** das CSV wurde generiert, **When** der Admin die Datei öffnet, **Then** enthält sie alle relevanten Spalten (Policy Name, Type, Setting Name, Value, Last Synced) mit korrektem CSV-Escaping.
|
|
|
|
---
|
|
|
|
### User Story 4 - Enhanced Detail View (Priority: P2)
|
|
|
|
Als Intune-Admin möchte ich im Detail-Sheet erweiterte Funktionen haben (Copy-to-Clipboard, Raw JSON View), um Settings schnell zu teilen oder zu debuggen.
|
|
|
|
**Why this priority**: Quality-of-Life Verbesserung für Power-User. Nicht MVP-blocking aber sehr nützlich.
|
|
|
|
**Independent Test**: Detail-Sheet öffnen, Copy-Buttons testen, Raw JSON Tab öffnen.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** der Admin öffnet das Detail-Sheet für ein Setting, **When** er auf "Copy Policy ID" klickt, **Then** wird die graphPolicyId in die Zwischenablage kopiert.
|
|
2. **Given** der Admin sieht das Detail-Sheet, **When** er auf "Raw JSON" Tab klickt, **Then** sieht er die kompletten Rohdaten formatiert als JSON.
|
|
3. **Given** das Setting hat eine graphPolicyId, **When** der Admin "Open in Intune" klickt, **Then** öffnet sich ein neues Tab mit dem Intune Portal Link (oder wird Policy ID kopiert als Fallback).
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- Was passiert bei sehr breiten Tabellen (viele Spalten)? → Horizontales Scrolling + Sticky erste Spalte.
|
|
- Wie verhält sich Export bei >10.000 Rows? → Server-seitige Limitierung auf max 5000 Rows pro Export mit Warning.
|
|
- Was passiert wenn keine Rows selektiert sind beim Export? → Button disabled mit Tooltip "Select rows first".
|
|
- Wie wird Sorting mit Pagination kombiniert? → Server-seitig: Sort state wird an API übergeben.
|
|
- Was passiert bei Column Resize auf mobilen Geräten? → Touch-optimierte Resize Handles oder Feature deaktiviert auf <768px.
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: System MUSS serverseitige Pagination mit konfigurierbarer Page Size (10/25/50/100) unterstützen.
|
|
- **FR-002**: System MUSS Sortierung nach allen Spalten unterstützen (ASC/DESC Toggle).
|
|
- **FR-003**: System MUSS Column Visibility Management bereitstellen (Spalten ein-/ausblenden via Dropdown).
|
|
- **FR-004**: System MUSS Column Resizing unterstützen (Drag & Drop an Spaltenrändern).
|
|
- **FR-005**: System MUSS Sticky Table Header implementieren (bleibt beim Scrollen sichtbar).
|
|
- **FR-006**: System MUSS PolicyType Filter als Multi-Select Checkbox implementieren.
|
|
- **FR-007**: System MUSS Filter + Suche kombinierbar machen (beide aktiv gleichzeitig).
|
|
- **FR-008**: System MUSS URL State für Filter/Sort/Search speichern (shareable links).
|
|
- **FR-009**: System MUSS localStorage für Column Settings verwenden (Breite, Visibility, Reihenfolge).
|
|
- **FR-010**: System MUSS Row Selection mit Checkboxes implementieren (einzeln + Select All).
|
|
- **FR-011**: System MUSS CSV Export für Selected Rows bereitstellen (client-seitig generiert).
|
|
- **FR-012**: System MUSS CSV Export für All Filtered Results bereitstellen (server-seitig, max 5000 Rows).
|
|
- **FR-013**: System MUSS Copy-to-Clipboard Buttons für Policy ID, Setting Name, Setting Value implementieren.
|
|
- **FR-014**: System MUSS Raw JSON View im Detail-Sheet anzeigen.
|
|
- **FR-015**: System MUSS "Open in Intune" Button implementieren (wenn graphPolicyId vorhanden).
|
|
- **FR-016**: System MUSS Truncation + Tooltip für lange Werte/IDs implementieren.
|
|
- **FR-017**: System MUSS Compact/Comfortable Density Mode Toggle bereitstellen.
|
|
- **FR-018**: System MUSS Meta-Info Zeile über Tabelle anzeigen (X settings · Y policies · Last sync).
|
|
|
|
### Key Entities
|
|
|
|
Erweitert `PolicySetting` Datenmodell (keine Schema-Änderungen nötig):
|
|
|
|
- **DataTableState**: Client-side State für Tabelle
|
|
- `pagination`: { page: number, pageSize: number }
|
|
- `sorting`: { column: string, direction: 'asc'|'desc' }[]
|
|
- `columnVisibility`: { [columnId: string]: boolean }
|
|
- `columnSizing`: { [columnId: string]: number }
|
|
- `rowSelection`: { [rowId: string]: boolean }
|
|
|
|
- **FilterState**: Filter-Zustand
|
|
- `policyTypes`: string[] (selected policy types)
|
|
- `searchQuery`: string (existing search)
|
|
- `dateRange`: { from?: Date, to?: Date } (optional, Phase 2)
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: Pagination lädt neue Seiten in <500ms (serverseitige Query + Rendering).
|
|
- **SC-002**: Sortierung funktioniert auf allen Spalten ohne Performance-Degradation bei 1000+ Rows.
|
|
- **SC-003**: Column Settings (Visibility, Sizing) bleiben nach Browser-Reload erhalten.
|
|
- **SC-004**: CSV Export für 1000 Selected Rows dauert <2s (client-seitig).
|
|
- **SC-005**: CSV Export für 5000 Filtered Results dauert <5s (server-seitig).
|
|
- **SC-006**: Filter + Suche kombiniert reduziert Results korrekt (AND-Logik).
|
|
- **SC-007**: URL State ist shareable (Copy/Paste URL zeigt identische Filterung).
|
|
- **SC-008**: Detail-Sheet Copy-Buttons funktionieren in allen modernen Browsern (Chrome, Firefox, Safari, Edge).
|
|
|
|
## Assumptions
|
|
|
|
- TanStack Table (React Table v8) wird als Data Table Library verwendet.
|
|
- Shadcn UI Table Komponenten werden erweitert oder mit TanStack Table integriert.
|
|
- Export-Logik nutzt serverseitigen Endpoint für große Datasets (>1000 Rows).
|
|
- Column Settings werden im localStorage gespeichert (keine User-Profile Persistierung).
|
|
- "Open in Intune" Links werden per Policy Type konstruiert (bekannte URL-Pattern).
|
|
|
|
## Nicht-Ziele (Out of Scope)
|
|
|
|
- Kein Policy Editing (read-only view bleibt erhalten).
|
|
- Kein vollständiges RBAC-System (bleibt bei Tenant-Isolation).
|
|
- Kein Conflict Detection (Phase 2).
|
|
- Kein Policy Comparison/Diff (Phase 2).
|
|
- Kein Saved Views (Phase 2).
|
|
- Keine Gruppierung (Group by Policy/Setting) (Phase 2).
|
|
|
|
## Technical Notes
|
|
|
|
### TanStack Table Integration
|
|
|
|
- `@tanstack/react-table` bereits im Projekt vorhanden oder muss installiert werden
|
|
- Server-side Pagination, Sorting, Filtering via Server Actions
|
|
- Column Definitions mit Type-Safety via TypeScript
|
|
- Shadcn Table Primitives als UI Layer
|
|
|
|
### CSV Export Strategy
|
|
|
|
**Client-Side** (Selected Rows):
|
|
- Library: `papaparse` oder native String-Builder
|
|
- Maximal 1000 Rows empfohlen
|
|
- Sofortiger Download ohne Server-Request
|
|
|
|
**Server-Side** (Filtered Results):
|
|
- Neuer Server Action: `exportPolicySettingsCSV(filterState)`
|
|
- Stream-basierter Export für große Datasets
|
|
- Content-Disposition Header für File Download
|
|
- Limit: 5000 Rows (UI Warning bei mehr)
|
|
|
|
### URL State Management
|
|
|
|
- `nuqs` Library für type-safe URL State
|
|
- Query Params:
|
|
- `page`: number
|
|
- `pageSize`: 10|25|50|100
|
|
- `sortBy`: columnId
|
|
- `sortDir`: asc|desc
|
|
- `policyTypes`: comma-separated
|
|
- `q`: search query
|
|
|
|
### Column Configuration
|
|
|
|
Default Columns:
|
|
- Setting Name (visible, pinned left)
|
|
- Setting Value (visible, truncated)
|
|
- Policy Name (visible)
|
|
- Policy Type (visible, badge)
|
|
- Last Synced (visible, relative time)
|
|
- Policy ID (hidden by default)
|
|
|
|
## Dependencies
|
|
|
|
- TanStack Table v8: `@tanstack/react-table`
|
|
- CSV Export: `papaparse` (optional, kann auch nativ gebaut werden)
|
|
- URL State: `nuqs` (optional, kann auch mit useSearchParams gelöst werden)
|
|
- Clipboard API: Native Browser API
|
|
- Icons: Lucide React (bereits vorhanden)
|