# 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)