tenantpilot/specs/004-policy-explorer-v2/spec.md

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)