ahmido/tenantpilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f592e5f55b
tenantpilot/specs/003-policy-explorer-ux/spec.md
Ahmed Darrazi 06341038ea Add specification for Policy Explorer UX Upgrade 
- Feature 003: Transform global search into full Policy Explorer
- Show 50 newest policies by default (no empty state)
- Filter out null values automatically
- Add clickable rows with detail sheet for JSON formatting
- Improve visual hierarchy with policy type badges
- Consolidate navigation (remove 'All Settings')

Spec includes 4 prioritized user stories (P1/P2/P3), 11 functional requirements, and 6 measurable success criteria. All requirements are testable and technology-agnostic.

Checklist validation: All items pass ✅
2025-12-07 02:06:19 +01:00

8.1 KiB
Raw Blame History

Feature Specification: Policy Explorer UX Upgrade

Feature Branch: 003-policy-explorer-ux
Created: 2025-12-07
Status: Draft
Input: User description: "Policy Explorer UX Upgrade - Improve global search UI with detail view, data filtering, and better UX"

User Scenarios & Testing (mandatory)

User Story 1 - Browse Recent Policies on Page Load (Priority: P1)

Als Intune-Admin möchte ich beim Öffnen des Policy Explorers sofort die neuesten 50 Policy-Einstellungen sehen, ohne erst einen Suchbegriff eingeben zu müssen.

Why this priority: Dies ist die Kernverbesserung des Features. Ein leerer Bildschirm ("Empty State") ist schlechte UX. Der User sollte sofort produktiv sein können und einen Überblick über die neuesten Änderungen erhalten.

Independent Test: Kann vollständig getestet werden durch Öffnen der /policy-explorer Seite ohne Suchbegriff. Liefert sofort Mehrwert, da Admins die neuesten Policies sehen können.

Acceptance Scenarios:

  1. Given der Admin ist eingeloggt, When er die Policy Explorer Seite öffnet (ohne Suchbegriff), Then sieht er sofort eine Tabelle mit den 50 neuesten Policy-Einstellungen (sortiert nach lastSyncedAt DESC).
  2. Given der Admin ist auf der Policy Explorer Seite, When die Seite lädt, Then werden Einträge mit settingValue = "null" oder null automatisch ausgeblendet.
  3. Given es existieren keine Policy-Einstellungen für den Tenant, When die Seite lädt, Then sieht der Admin eine Nachricht "Keine Policies gefunden - Starten Sie einen Sync".

User Story 2 - View Policy Details in Slide-Over Sheet (Priority: P1)

Als Intune-Admin möchte ich auf eine Policy-Zeile klicken können, um eine detaillierte Ansicht mit formatierten JSON-Werten zu sehen, damit ich komplexe OMA-URI Settings verstehen kann.

Why this priority: Dies löst das Hauptproblem des aktuellen Features - komplexe JSON-Werte sind in der Tabelle nicht lesbar. Die Detailansicht ist essenziell für produktive Nutzung.

Independent Test: Kann getestet werden durch Klick auf eine beliebige Tabellenzeile. Funktioniert unabhängig von der Suchfunktion.

Acceptance Scenarios:

  1. Given der Admin sieht die Policy-Tabelle, When er auf eine Zeile klickt, Then öffnet sich ein Slide-Over Sheet von rechts mit den Policy-Details.
  2. Given das Detail-Sheet ist geöffnet, When der settingValue ein JSON-String ist (startet mit { oder [), Then wird der Wert formatiert in einem Code-Block angezeigt.
  3. Given das Detail-Sheet ist geöffnet, When der settingValue ein einfacher String ist, Then wird der Wert als normaler Text angezeigt.
  4. Given das Detail-Sheet ist geöffnet, When der Admin auf "Schließen" (X) oder außerhalb des Sheets klickt, Then schließt sich das Sheet.

User Story 3 - Search with Data Cleaning (Priority: P2)

Als Intune-Admin möchte ich nach Policies suchen können und dabei nur relevante Einträge sehen (ohne "null"-Werte), damit die Ergebnisse übersichtlich bleiben.

Why this priority: Die Suchfunktion existiert bereits (Feature 001-global-policy-search), muss aber nun ebenfalls die Datenfilterung respektieren. Dies ist P2, weil die Basisfunktionalität bereits vorhanden ist.

Independent Test: Kann getestet werden durch Eingabe eines Suchbegriffs und Verifizierung, dass keine "null"-Werte in den Ergebnissen erscheinen.

Acceptance Scenarios:

  1. Given der Admin ist auf der Policy Explorer Seite, When er "USB" in das Suchfeld eingibt, Then sieht er nur Ergebnisse, die "USB" enthalten UND deren settingValue nicht "null" ist.
  2. Given der Admin hat nach "Camera" gesucht, When er das Suchfeld leert, Then kehrt die Ansicht zu den 50 neuesten Einträgen zurück.

User Story 4 - Improved Visual Hierarchy (Priority: P3)

Als Intune-Admin möchte ich Policy-Typen auf einen Blick durch farbige Badges unterscheiden können, damit ich schneller relevante Policies finde.

Why this priority: Dies ist eine visuelle Verbesserung, die die Usability erhöht, aber nicht funktional kritisch ist. Kann nach P1 und P2 implementiert werden.

Independent Test: Kann visuell getestet werden durch Ansehen der Tabelle und Verifizierung der Badge-Farben.

Acceptance Scenarios:

  1. Given der Admin sieht die Policy-Tabelle, When er die policyType Spalte ansieht, Then sieht er farbige Badges (z.B. Compliance = Blau, Configuration = Grau, Security = Rot).
  2. Given der Admin bewegt die Maus über eine Tabellenzeile, When die Zeile gehovered wird, Then ändert sich der Cursor zu pointer und die Zeile hebt sich visuell hervor.

Edge Cases

  • Was passiert, wenn ein settingValue ein sehr langer JSON-String ist (>10KB)? → Im Detail-Sheet scrollen mit max-height und overflow-auto.
  • Wie verhält sich die Seite, wenn der User sehr schnell zwischen Zeilen klickt? → Debouncing oder Loading-State im Sheet.
  • Was passiert, wenn lastSyncedAt fehlt? → Fallback auf createdAt oder "Unbekannt" anzeigen.
  • Wie werden Sonderzeichen in JSON-Werten gehandelt? → Automatisches Escaping durch JSON.parse() und <pre> Tag.

Requirements (mandatory)

Functional Requirements

  • FR-001: System MUSS eine neue Route /policy-explorer bereitstellen (ersetzt /search).
  • FR-002: System MUSS beim Laden der Seite (ohne Suchbegriff) automatisch die 50 neuesten Policy-Einstellungen anzeigen (sortiert nach lastSyncedAt DESC).
  • FR-003: System MUSS Einträge mit settingValue = "null" (String) oder settingValue = null (Wert) aus allen Ergebnissen filtern (Backend-Filter bevorzugt).
  • FR-004: System MUSS die policyType Spalte als farbige Badge darstellen (Shadcn UI Badge Component).
  • FR-005: System MUSS Tabellenzeilen klickbar machen (Cursor: pointer, Hover-Effekt).
  • FR-006: System MUSS eine neue PolicyDetailSheet Komponente bereitstellen (Shadcn Sheet Component, Slide-Over von rechts).
  • FR-007: System MUSS im Detail-Sheet prüfen, ob settingValue ein JSON-String ist (startet mit { oder [).
  • FR-008: System MUSS JSON-Strings formatiert in einem Code-Block anzeigen (<pre> oder Syntax Highlighter).
  • FR-009: System MUSS normale String-Werte als Text im Detail-Sheet anzeigen.
  • FR-010: System MUSS den "All Settings" Menüpunkt entfernen (falls vorhanden) und durch "Policy Explorer" ersetzen.
  • FR-011: System MUSS weiterhin die bestehende Suchfunktion unterstützen (mit Datenfilterung).

Key Entities

  • PolicySetting: Erweitert das bestehende Entity aus Feature 001-global-policy-search
    • Alle bisherigen Attribute bleiben bestehen
    • Keine Datenbankänderungen erforderlich
    • Neue Frontend-Filterlogik: settingValue !== "null" && settingValue !== null

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: Beim Öffnen der Policy Explorer Seite werden innerhalb von 2 Sekunden die 50 neuesten Einträge angezeigt.
  • SC-002: 100% der angezeigten Einträge haben einen gültigen settingValue (nicht "null" oder null).
  • SC-003: Klick auf eine Tabellenzeile öffnet das Detail-Sheet in unter 300ms.
  • SC-004: JSON-Strings im Detail-Sheet sind korrekt formatiert und lesbar (mit Syntax Highlighting oder mindestens Zeilenumbrüchen).
  • SC-005: Die policyType Badges sind visuell unterscheidbar (mindestens 3 verschiedene Farben für Compliance, Configuration, Security).
  • SC-006: Die Navigation enthält nur noch einen Menüpunkt "Policy Explorer" (kein separater "All Settings" Eintrag mehr).

Assumptions

  • Die bestehende Datenbankstruktur aus Feature 001-global-policy-search wird nicht geändert.
  • Die Server Action searchPolicySettings wird erweitert um einen optionalen limit Parameter (Default: 50).
  • Shadcn UI Komponenten (Sheet, Badge) sind bereits im Projekt integriert.
  • Die Route /search wird umbenannt zu /policy-explorer (oder beide bleiben bestehen mit Redirect).
  • Die Filterung von "null"-Werten kann initial im Frontend erfolgen, sollte aber später ins Backend verschoben werden für Performance.
  • Syntax Highlighting ist "Nice-to-have" - eine einfache <pre>-Darstellung reicht für MVP.