diff --git a/specs/003-policy-explorer-ux/checklists/requirements.md b/specs/003-policy-explorer-ux/checklists/requirements.md new file mode 100644 index 0000000..0bc7523 --- /dev/null +++ b/specs/003-policy-explorer-ux/checklists/requirements.md @@ -0,0 +1,42 @@ +# Specification Quality Checklist: Policy Explorer UX Upgrade + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2025-12-07 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +All checklist items pass. Specification is complete and ready for planning phase (`/speckit.plan`). + +**Validation Summary**: +- ✅ 4 prioritized user stories (P1, P2, P3) with clear acceptance scenarios +- ✅ 11 functional requirements (FR-001 to FR-011), all testable +- ✅ 6 success criteria (SC-001 to SC-006), all measurable and technology-agnostic +- ✅ Edge cases documented (JSON size, rapid clicks, missing timestamps, special characters) +- ✅ Assumptions section complete (no DB changes, extend existing server actions, UI components available) +- ✅ No [NEEDS CLARIFICATION] markers - all decisions made with reasonable defaults diff --git a/specs/003-policy-explorer-ux/spec.md b/specs/003-policy-explorer-ux/spec.md new file mode 100644 index 0000000..9ba7146 --- /dev/null +++ b/specs/003-policy-explorer-ux/spec.md @@ -0,0 +1,121 @@ +# 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 `
` 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 (`` 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 ``-Darstellung reicht für MVP.