175 lines
18 KiB
Markdown
175 lines
18 KiB
Markdown
# Feature Specification: Structured Snapshot Rendering & Type-Agnostic Item Browser
|
|
|
|
**Feature Branch**: `130-structured-snapshot-rendering`
|
|
**Created**: 2026-03-09
|
|
**Status**: Draft
|
|
**Input**: User description: "Spec 130 — Structured Snapshot Rendering & Type-Agnostic Item Browser"
|
|
|
|
## Spec Scope Fields *(mandatory)*
|
|
|
|
- **Scope**: workspace
|
|
- **Primary Routes**:
|
|
- Workspace admin: `/admin/baseline-snapshots`
|
|
- Workspace admin: `/admin/baseline-snapshots/{record}`
|
|
- Existing baseline-profile navigation paths that open snapshot detail remain in scope only where they lead to the same snapshot detail surface
|
|
- **Data Ownership**:
|
|
- Workspace-owned: baseline snapshots and baseline snapshot items remain the source records rendered on this page
|
|
- Workspace-owned presentation only: this feature adds no new tenant-owned records and does not change snapshot immutability
|
|
- Existing policy version references and evidence metadata remain read-only supporting context for snapshot inspection
|
|
- **RBAC**:
|
|
- Workspace membership remains the visibility boundary for snapshot pages
|
|
- Authorized workspace users with existing baseline snapshot view capability can inspect the structured page
|
|
- Non-members or users outside the active workspace scope must receive deny-as-not-found behavior
|
|
- In-scope members lacking the required capability must continue to receive forbidden behavior for protected data or affordances
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### User Story 1 - Review captured state by policy type (Priority: P1)
|
|
|
|
As a workspace governance operator, I want a snapshot page that immediately summarizes what was captured by policy type so I can understand coverage and inspection priority without reading raw payloads.
|
|
|
|
**Why this priority**: The page fails its core purpose if operators cannot tell what a snapshot contains within the first screen.
|
|
|
|
**Independent Test**: Can be fully tested by opening a mixed-policy snapshot and verifying that the first meaningful content block is a structured summary with one row per captured policy type.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a snapshot that contains multiple captured policy types, **When** an authorized user opens the snapshot detail page, **Then** the page shows a summary-first table with one row per policy type before any technical payload is shown.
|
|
2. **Given** a snapshot that includes groups with different rendering quality, **When** the summary is shown, **Then** each row clearly displays item count, fidelity state, and gap state rather than implying completeness through omission.
|
|
3. **Given** a snapshot that contains only one captured policy type, **When** the page loads, **Then** the same summary structure still appears and does not switch to a one-off special-case layout.
|
|
|
|
---
|
|
|
|
### User Story 2 - Drill into any captured type consistently (Priority: P1)
|
|
|
|
As a workspace governance operator, I want every captured policy type to appear in a grouped browser with the same baseline inspection contract so I can inspect snapshots consistently even when a type has limited enrichment.
|
|
|
|
**Why this priority**: Enterprise trust breaks if only one favored type is inspectable while others are hidden behind counts or JSON.
|
|
|
|
**Independent Test**: Can be fully tested by opening a snapshot containing RBAC, compliance, and an unsupported type and verifying that all three appear as grouped sections with visible items and stable minimum metadata.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a snapshot containing supported and unsupported policy types, **When** the grouped browser renders, **Then** every type appears as an expandable group and none are suppressed because bespoke rendering is missing.
|
|
2. **Given** a group with no rich enrichment available, **When** the user expands it, **Then** the item rows still show a readable label, identity hint, status, fidelity, and source-reference context.
|
|
3. **Given** a group with rich enrichment available, **When** the user expands it, **Then** the extra detail appears inside the shared inspection shell rather than replacing the common structure.
|
|
|
|
---
|
|
|
|
### User Story 3 - Understand fidelity, gaps, and degraded states safely (Priority: P2)
|
|
|
|
As a reviewer or auditor, I want incomplete or degraded rendering to be explicit so I can judge how much confidence to place in the snapshot without having to infer missing detail from raw data dumps.
|
|
|
|
**Why this priority**: Governance pages must expose evidence quality and known gaps directly, otherwise operators will misread incomplete evidence as complete.
|
|
|
|
**Independent Test**: Can be fully tested by loading snapshots with complete, partial, reference-only, unsupported, empty, and renderer-failure conditions and verifying that the page remains usable and explains the degraded state.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a partially renderable group, **When** the page is displayed, **Then** the group shows fidelity and gap indicators that explain the degraded state without hiding the affected items.
|
|
2. **Given** a snapshot with no items, **When** the page is displayed, **Then** the page shows a clear empty state instead of an empty JSON block or broken layout.
|
|
3. **Given** a technical payload disclosure is available, **When** the page first loads, **Then** that disclosure is collapsed and visually secondary to the structured summary and grouped browser.
|
|
|
|
### Edge Cases
|
|
|
|
- A snapshot may contain no items at all and must show an explicit empty-state explanation.
|
|
- A snapshot may contain items but no type-specific enrichment, and those items must still render through the common minimum contract.
|
|
- A newly added or unknown policy type must appear in the summary and grouped browser even if no type-specific renderer exists.
|
|
- One policy type group may fail to build structured detail while the rest of the snapshot remains renderable.
|
|
- A group may include only reference-level metadata, and the UI must label that state clearly rather than implying full fidelity.
|
|
- Large snapshots must not load as a wall of expanded cards; grouped sections remain collapsed by default.
|
|
- Related source references may be missing for some items, and the UI must show that absence explicitly rather than dropping the field silently.
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
**Constitution alignment (required):** This feature is a read-only presentation-layer redesign over existing workspace-owned baseline snapshot data. It adds no new Microsoft Graph calls, no new capture or compare writes, no new queue or scheduled behavior, and no new mutable snapshot semantics. Snapshot immutability, workspace isolation, and evidence-readability remain mandatory. If technical detail disclosure remains available, it must not broaden access beyond the existing authorized surface.
|
|
|
|
**Constitution alignment (OPS-UX):** No new or changed `OperationRun` flow is introduced. Existing capture and compare operations remain out of scope. This feature must not add inline remote work or operational side effects to the snapshot detail surface.
|
|
|
|
**Constitution alignment (RBAC-UX):** This feature affects the Tenant/Admin plane workspace-admin surface under `/admin` only. Snapshot detail remains workspace-scoped and must continue to enforce server-side authorization through the existing workspace membership and capability checks. Non-members or actors outside the active workspace scope must receive 404 deny-as-not-found behavior. In-scope members who lack the required baseline-view entitlement must continue to receive 403 semantics where protected detail execution paths exist. The feature must add at least one positive authorization test for authorized snapshot inspection and one negative authorization test proving non-members or under-entitled users cannot access structured snapshot detail. No raw capability strings or role-string checks may be introduced.
|
|
|
|
**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. This feature introduces no authentication handshake behavior and must not add outbound work to render-time pages.
|
|
|
|
**Constitution alignment (BADGE-001):** Fidelity and gap indicators are status-like badges and must use centralized semantics so the same fidelity state or gap condition is rendered consistently across the snapshot summary and grouped browser. Tests must cover the allowed fidelity states and degraded-state badges.
|
|
|
|
**Constitution alignment (Filament Action Surfaces):** This feature modifies an existing Filament resource detail surface and list-to-detail inspection flow. The Action Surface Contract remains satisfied through the existing immutable-resource exemptions: list inspection remains available, no new destructive actions are introduced, and the detail page remains informational. The grouped browser and technical disclosure must fit inside a sectioned detail experience rather than creating ad hoc action-heavy cards.
|
|
|
|
**Constitution alignment (UX-001 — Layout & Information Architecture):** The snapshot detail page must remain a sectioned view experience rather than a disabled edit form. The information hierarchy must read as header and metadata, structured summary, grouped item browser, then optional technical detail. The list page keeps its existing search, sort, and filter behavior. Any empty state added to the detail page must use a specific title, explanation, and a single clear next-step message where applicable.
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-130-01 Structured primary experience**: The system must replace raw JSON or raw summary payloads as the primary snapshot detail experience with a structured, human-readable layout.
|
|
- **FR-130-02 Technical detail demotion**: If raw technical payloads remain available, they must be clearly labeled as technical detail, visually secondary, and collapsed by default.
|
|
- **FR-130-03 Summary-first layout**: The first meaningful data block on the snapshot detail page must be a structured summary grouped by policy type.
|
|
- **FR-130-04 Stable summary columns**: Each summary row must show, at minimum, policy type label, item count, fidelity state, gap state, and observed or captured timing when meaningful.
|
|
- **FR-130-05 Grouped browser**: The page must provide a grouped item browser below the summary that organizes all snapshot items by policy type.
|
|
- **FR-130-06 Predictable default state**: Policy type groups in the browser must be collapsed by default and ordered consistently so large snapshots remain scannable.
|
|
- **FR-130-07 Minimum item contract**: Every rendered snapshot item must show the best available human-readable label, policy type, capture or reference status, fidelity indicator, timing metadata when available, source-reference hint when available, and a stable identity hint suitable for operator inspection.
|
|
- **FR-130-08 Universal visibility**: Every captured policy type must satisfy the minimum rendering contract even when no type-specific enrichment exists.
|
|
- **FR-130-09 Fallback rendering**: Unsupported or newly added policy types must still produce a valid summary row and visible grouped item entries using the best available metadata.
|
|
- **FR-130-10 Type-specific enrichment layering**: Richer policy-type detail may be added for selected types, but it must layer on top of the shared inspection contract rather than bypassing it.
|
|
- **FR-130-11 RBAC parity improvement**: `intuneRoleDefinition` may remain the richest type, but it must no longer be the only type with meaningful structured inspection.
|
|
- **FR-130-12 Compliance first-class visibility**: `deviceCompliancePolicy` items must appear as first-class grouped entries with structured minimum detail instead of being visible only through counts or raw payloads.
|
|
- **FR-130-13 Explicit fidelity states**: The page must visibly represent rendering fidelity states for groups and items using the approved conceptual states of full, partial, reference-only, and unsupported.
|
|
- **FR-130-14 Explicit gap states**: The page must surface missing interpretation fields, degraded rendering, or evidence gaps explicitly at group and or item level instead of silently omitting them.
|
|
- **FR-130-15 Group-level aggregation**: The presentation model must support group-level aggregation for item count, fidelity state, gap presence or count, and timing summary where meaningful.
|
|
- **FR-130-16 Item-level attributes**: The presentation model must support item-level label, type, identity hint, fidelity state, gap summary, key structured attributes, and source reference.
|
|
- **FR-130-17 Extensible renderer contract**: The snapshot detail experience must use a centralized renderer or presenter contract so new policy types can become visible without bespoke page-template changes.
|
|
- **FR-130-18 Renderer failure isolation**: A rendering failure for one policy type group must degrade that group safely without breaking the rest of the snapshot page.
|
|
- **FR-130-19 Empty-state clarity**: The page must provide clear states for snapshots with no items, snapshots with only fallback rendering, partially renderable groups, and per-group rendering failures.
|
|
- **FR-130-20 Safe related references**: Items may show minimal safe references to related records, such as policy-version labels or identifiers, but the page must not expand into a broader navigation redesign.
|
|
- **FR-130-21 Structured sectioning**: The page must use a stable section structure consisting of snapshot metadata, summary, grouped browser, and optional technical detail rather than one-off card mixtures.
|
|
- **FR-130-22 Backward compatibility**: Existing snapshots must continue to render even when only fallback structured detail is available.
|
|
- **FR-130-23 Regression safety**: Tests must prevent regressions where non-RBAC types disappear, unknown types are silently ignored, or raw JSON becomes the primary experience again.
|
|
|
|
### Non-Goals
|
|
|
|
- Baseline compare result redesign
|
|
- Findings UI redesign
|
|
- Product-wide cross-resource navigation overhaul beyond minimal safe references inside the snapshot page
|
|
- GUID context resolution across the wider product
|
|
- Audit log redesign or new audit storage
|
|
- Export or report generation changes
|
|
- Editing snapshots or changing snapshot immutability rules
|
|
- Reworking baseline capture pipeline semantics
|
|
- Building a universal renderer for every other product surface in this release
|
|
|
|
### Assumptions
|
|
|
|
- Existing baseline snapshots and snapshot items already contain enough metadata to support a useful minimum structured rendering contract for most captured types.
|
|
- Rich enrichment can ship incrementally as long as the fallback path makes every type visible and inspectable.
|
|
- The current baseline snapshot resource remains the canonical workspace-owned inspection surface for this information.
|
|
- Technical payload disclosure, if retained, is a debugging aid and not the primary operator workflow.
|
|
|
|
### Dependencies
|
|
|
|
- Existing workspace-owned baseline snapshots and baseline snapshot items
|
|
- Existing workspace authorization and capability enforcement for baseline resources
|
|
- Existing badge or label centralization patterns for status-like semantics
|
|
- Existing baseline evidence metadata, including policy-version references and timing fields when present
|
|
|
|
## UI Action Matrix *(mandatory when Filament is changed)*
|
|
|
|
| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| Baseline Snapshots resource | Workspace admin governance snapshot list and detail | None new | Snapshot inspection moves to clickable rows or a primary linked column so the list no longer relies on a lone View action | None | None | Existing list empty state remains informational with no create CTA because snapshots are immutable capture outputs | None new | N/A | No new writes | The Action Surface Contract remains satisfied through explicit immutable-resource exemptions. This feature changes detail rendering only, upgrades the list inspect affordance to match the constitution, and introduces no destructive actions. |
|
|
|
|
### Key Entities *(include if feature involves data)*
|
|
|
|
- **Snapshot Presentation Summary**: The normalized overview of one snapshot, including page-level metadata and one row per captured policy type.
|
|
- **Policy Type Group Presentation**: The grouped representation of snapshot items for a single policy type, including aggregate counts, fidelity state, gap state, and expandable item rows.
|
|
- **Snapshot Item Presentation**: The normalized per-item inspection model that exposes the minimum readable contract for any captured item.
|
|
- **Fidelity State**: The explicit rendering-quality indicator that tells operators whether a type or item is fully rendered, partially rendered, reference-only, or unsupported.
|
|
- **Gap Indicator**: The explicit signal that known interpretation, evidence, or rendering detail is missing or degraded.
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-130-01 Immediate comprehension**: In acceptance testing, an authorized user can identify every captured policy type present in a snapshot from the summary section without opening technical payloads.
|
|
- **SC-130-02 Universal visibility**: In mixed-type test scenarios, 100% of captured policy types appear in both the summary and the grouped browser, including unsupported or newly added types.
|
|
- **SC-130-03 Degraded-state clarity**: In degraded-rendering scenarios, 100% of affected groups display an explicit fidelity or gap signal rather than disappearing or falling back silently to counts alone.
|
|
- **SC-130-04 Scalable default state**: In large-snapshot test scenarios, the default page load shows the summary immediately and keeps grouped detail collapsed so the initial screen remains scannable.
|
|
- **SC-130-05 Failure isolation**: In test scenarios where one renderer fails, the rest of the snapshot page remains usable and the unaffected policy type groups continue to render.
|
|
|