TenantAtlas/specs/133-detail-page-template/spec.md

# Feature Specification: View Page Template Standard for Enterprise Detail Screens

**Feature Branch**: `133-detail-page-template`  
**Created**: 2026-03-10  
**Status**: Draft  
**Input**: User description: "Spec 133 — View Page Template Standard for Enterprise Detail Screens"

## Spec Scope Fields

- **Scope**: canonical-view
- **Primary Routes**:
  - Workspace-scoped baseline snapshot detail at the existing BaselineSnapshot resource view route in the admin panel
  - Tenant-scoped backup set detail at the existing BackupSet resource view route
  - Tenant-scoped directory group detail at the existing EntraGroup resource view route
  - Workspace-context operation-run detail at the existing canonical Operations run viewer route
- **Data Ownership**:
  - Workspace-owned or workspace-context surfaces: the shared detail-page standard itself, BaselineSnapshot detail, and OperationRun detail when surfaced through workspace-context Monitoring
  - Tenant-owned surfaces rendered through the standard: BackupSet detail and EntraGroup detail, plus tenant-bound related context surfaced from OperationRun detail
  - No new business entities, storage tables, or route semantics are introduced; this feature standardizes interpretation and presentation of existing records
- **RBAC**:
  - Existing workspace membership and capability rules continue to govern BaselineSnapshot and workspace-context OperationRun detail
  - Existing tenant membership and capability rules continue to govern BackupSet and EntraGroup detail
  - Related links, related context, and technical detail remain permission-aware and must not disclose inaccessible records or fields

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: The shared detail template must not broaden scope. Workspace-scoped pages remain workspace-scoped even if a tenant was previously active, and tenant-scoped pages remain limited to the currently established tenant context. The template may surface related context from adjacent scopes only when that relationship is already authorized and canonical for the current viewer.
- **Explicit entitlement checks preventing cross-tenant leakage**: Every summary item, KPI, status badge, related-context entry, and quick action must be assembled through existing scope-aware authorization paths. Non-members remain 404 deny-as-not-found. Members lacking a capability for a target action or related destination receive 403 at that protected target, and the detail page itself must not leak inaccessible linked records through labels, counts, or hints.

## User Scenarios & Testing

### User Story 1 - Understand the record quickly (Priority: P1)

As an operator opening a core enterprise record, I want the detail page to explain what the record is, what state it is in, and why it matters before I read low-level fields.

**Why this priority**: The feature only succeeds if detail pages stop behaving like schema dumps and become immediately interpretable operational workspaces.

**Independent Test**: Can be fully tested by opening each target detail page and confirming that title, status, high-signal summary, and core context appear before technical detail or raw metadata.

**Acceptance Scenarios**:

1. **Given** an operator opens a target detail page, **When** the page loads, **Then** the top of the page identifies the record, its current state, and its most important business context without requiring the operator to scan raw fields.
2. **Given** a target page contains both business-critical and technical fields, **When** the operator follows the default reading path, **Then** technical detail appears only after the primary summary and operational context.
3. **Given** two different target resources, **When** the operator moves between them, **Then** both pages feel like the same product family because they share the same top-level structure and reading order.

---

### User Story 2 - Triage and navigate from related context (Priority: P2)

As an operator investigating a record, I want related records, current state signals, and next actions to appear in predictable places so I can decide what to inspect next without hunting through fields.

**Why this priority**: Enterprise detail pages need to support interpretation and next-step navigation, not only record viewing.

**Independent Test**: Can be fully tested by verifying that each target page exposes a dedicated related-context region, predictable action placement, and compact state or KPI information in the aside or equivalent supporting zone.

**Acceptance Scenarios**:

1. **Given** a target record has important linked context, **When** its detail page renders, **Then** the links appear in a dedicated related-context area instead of being scattered through unrelated metadata.
2. **Given** a target page offers page-level and contextual actions, **When** the operator scans the page, **Then** primary actions appear in the header and secondary actions appear in a consistent supporting region.
3. **Given** a target resource has meaningful status or KPI data, **When** the page renders, **Then** that state is visually elevated and easy to compare across pages.

---

### User Story 3 - Stay oriented even when data is sparse or partial (Priority: P3)

As an operator viewing an incomplete or degraded record, I want the page to remain readable and intentional so I can tell what is missing and what I can still do.

**Why this priority**: These detail pages are operational surfaces; they must remain usable when linked data is missing, stale, partial, or intentionally unavailable.

**Independent Test**: Can be fully tested by rendering each target page with missing related data, incomplete metadata, or empty secondary sections and confirming that the page still communicates intent, safe fallbacks, and valid next steps.

**Acceptance Scenarios**:

1. **Given** a related record is unavailable or inaccessible, **When** the detail page renders, **Then** the related-context area shows a clear unavailable or empty state instead of a broken or ambiguous field.
2. **Given** a page has no recent activity or no additional context to show, **When** the operator opens it, **Then** the page still renders a complete summary-first layout with explicit empty-state language.
3. **Given** a target record is only partially hydrated, **When** the page renders, **Then** missing subsections do not collapse the whole page into an unstructured field wall.

### Edge Cases

- A target record can have a valid identity but no recent activity, no related context, and no optional sections; the page must still render a complete enterprise layout with meaningful empty states.
- A related record can exist logically but be inaccessible to the current viewer; the detail page must not leak its identity, count, or destination.
- OperationRun detail can include sparse target-scope data or incomplete failure metadata; the page must still explain the run state and what is missing.
- BackupSet or BaselineSnapshot detail can expose large technical metadata blocks; these must remain secondary and must not dominate the initial reading path.
- EntraGroup detail can contain only low-signal provider metadata; the template must still surface group identity, classification, and governance relevance first.
- Some target pages may not need every standard section; omitted sections must disappear cleanly rather than leaving empty shells or placeholder headings.

## Requirements

**Constitution alignment (required):** This feature introduces no new Microsoft Graph calls, no new data writes, no new queued work, and no new route semantics. It standardizes presentation and page composition for existing record detail screens. Existing operational mutations reachable from those pages continue to use their current `OperationRun`, confirmation, and audit behavior. No new `AuditLog` contract is introduced by the template itself.

**Constitution alignment (OPS-UX):** The shared detail-page standard does not create or transition `OperationRun` records. The OperationRun target page continues to reuse existing run data and surfaces. If the page exposes existing run-triggering actions such as resuming work, those actions remain bound to the existing Ops-UX contract and are not redefined by this feature.

**Constitution alignment (RBAC-UX):** This feature touches both the workspace/admin plane and tenant-context detail pages. Non-members remain 404 deny-as-not-found. Members lacking a capability to inspect a related object or execute a contextual action receive 403 only at that protected target, while the detail page suppresses unauthorized linked context and actions. Authorization remains server-side through existing policies, Gates, and capability registries. No raw capability strings or role-string checks may be introduced. Any destructive actions retained on affected screens must continue to require confirmation.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. No authentication handshake behavior changes.

**Constitution alignment (BADGE-001):** Status, outcome, classification, boolean, and health badges shown in the standardized detail template must continue to use centralized badge semantics so that the same state means the same thing on every aligned page. Tests must cover any newly elevated or newly reused badge states on the target pages.

**Constitution alignment (UI-NAMING-001):** Any operator-facing labels introduced or normalized by the template must use domain-first vocabulary. Titles, section labels, actions, empty states, and supporting copy must describe the business object and operator intent, avoid implementation-first terms, and keep similar actions labeled consistently across the aligned pages.

**Constitution alignment (Filament Action Surfaces):** This feature modifies multiple Filament detail pages and one custom Filament page. The UI Action Matrix below applies. The Action Surface Contract remains satisfied because detail pages remain sectioned, actions are consolidated into predictable header or contextual regions, and no new destructive actions are introduced by the template itself.

**Constitution alignment (UX-001 — Layout & Information Architecture):** The aligned pages must comply with UX-001 by using structured sections, no naked field walls, view-style detail composition rather than disabled edit forms, centralized badge semantics, and explicit empty states. Because this feature focuses on view pages, create and edit layouts remain unchanged. Any justified variance from the default main/aside pattern must be documented per page in planning and implementation artifacts.

### Functional Requirements

- **FR-133-01 Shared enterprise detail standard**: The system must define a shared enterprise detail-page standard for important record-view screens so aligned pages follow the same information hierarchy even when their domain content differs.
- **FR-133-02 Summary-first header**: Every aligned detail page must begin with a summary header that presents the record title, current state, high-signal identifying context, and the most important page-level actions before deeper detail.
- **FR-133-03 Stable reading order**: The standard must enforce a default reading order of identity, state, core details, related context, deeper operational detail, and technical detail.
- **FR-133-04 Main and aside discipline**: Every aligned target page must use a consistent main-and-supporting-region layout or a documented justified variant that preserves the same information hierarchy.
- **FR-133-05 Standard section taxonomy**: The standard must define reusable section meanings for summary, current state or KPIs, core details, related context, operational context, recent activity or history, and technical detail.
- **FR-133-06 Status elevation**: Where a record has meaningful state, health, timing, counts, or outcomes, that information must be visually elevated rather than mixed into generic field lists.
- **FR-133-07 Structured related context**: Important linked records and contextual relationships must appear in a dedicated related-context section or supporting card area instead of being scattered through raw metadata rows.
- **FR-133-08 Technical detail is secondary**: Technical identifiers, payload fragments, diagnostic attributes, and storage-oriented metadata must remain available but must be visually secondary and placed after the primary operational content.
- **FR-133-09 Consistent action placement**: The standard must define predictable locations for page-level actions, contextual next steps, and section-specific actions so similar actions appear in similar places across aligned pages.
- **FR-133-10 Operational usefulness over schema order**: Aligned pages must optimize for operator interpretation, triage, and actionability rather than exhaustive model-order field listing.
- **FR-133-11 Degraded-state resilience**: Missing related records, sparse data, incomplete metadata, or empty recent-activity sections must render as clear degraded states without breaking the page structure.
- **FR-133-12 Explicit page composition**: Each aligned page must be assembled from explicit summary, context, and technical-detail sections rather than opportunistically rendering raw model attributes.
- **FR-133-13 Optional section support**: The standard must support optional sections so a page can omit non-applicable content without leaving awkward gaps or placeholder shells.
- **FR-133-14 Permission-aware related context**: Related-context entries, counts, and destinations must remain permission-aware and must not reveal inaccessible records.
- **FR-133-15 BaselineSnapshot alignment**: BaselineSnapshot detail must adopt the standard while emphasizing snapshot identity, capture context, baseline profile, structured contents overview, related governance context, and secondary technical metadata.
- **FR-133-16 BackupSet alignment**: BackupSet detail must adopt the standard while emphasizing backup-set identity, lifecycle state, scope or type, recovery-relevant status, recent related operations, and secondary technical configuration detail.
- **FR-133-17 EntraGroup alignment**: EntraGroup detail must adopt the standard while emphasizing group identity, classification, tenant relevance, governance usage context, and secondary provider identifiers or raw provider attributes.
- **FR-133-18 OperationRun alignment**: OperationRun detail must adopt the standard while emphasizing what ran, current or final state, target scope, outcome summary, failure or retry context, related artifacts, and secondary technical run metadata.
- **FR-133-19 Future adoption path**: The standard must be documented clearly enough that future detail pages can adopt it without inventing new layout rules or one-off hierarchy decisions.
- **FR-133-20 Route and domain stability**: The feature must keep existing resource routes, domain semantics, and underlying data contracts unchanged while standardizing page composition and presentation.
- **FR-133-21 Regression protection**: Automated tests must protect against target pages reverting to flat scaffold-like field walls, losing structured related context, or promoting technical detail above business-critical content.

### Non-Goals

- Redesigning list pages, table layouts, or global navigation information architecture
- Redefining underlying resource semantics, storage models, or domain terminology
- Rebuilding snapshot renderers, GUID resolution, or resolved-reference systems
- Introducing a universal visual design system beyond what is necessary to standardize these detail pages
- Implementing new audit-log behavior, new business workflows, or new operational data models
- Expanding the standard to every resource in the product during this feature

### Assumptions

- The existing target screens remain the correct initial high-value set for proving the standard: BaselineSnapshot, BackupSet, EntraGroup, and OperationRun.
- The product already has enough domain data on these pages to support summary, related-context, and technical-detail separation without adding new business entities.
- Existing related-context helpers, badge semantics, and authorization helpers can be reused as the authoritative sources for linked context and status meaning.
- Some target pages will remain more operational than others, so the shared standard must preserve domain-specific sections inside a common shell rather than forcing identical content.

### Dependencies

- Existing Filament view pages for BaselineSnapshot, BackupSet, and EntraGroup
- Existing canonical OperationRun detail viewer used from Monitoring or Operations flows
- Existing centralized badge semantics for status-like values
- Existing related-context and canonical-navigation helpers
- Existing workspace and tenant authorization enforcement patterns

## UI Action Matrix

| 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| BaselineSnapshot detail | Existing BaselineSnapshot resource in the admin panel | Unchanged list-header behavior | Existing clickable-row inspect affordance remains | Existing list behavior retained | Unchanged | Unchanged list empty state | `Open related record` plus any future non-destructive context action grouped consistently | N/A | No new audit event | View-page hierarchy changes only; immutable snapshot behavior remains unchanged. |
| BackupSet detail | Existing BackupSet resource detail route | Unchanged list-header behavior | Existing resource inspect affordance remains | Existing list and bulk behavior retained outside this feature | Existing bulk behavior retained | Unchanged list empty state | `Open related record` with any existing backup-set mutation actions grouped consistently and still confirmation-gated where destructive | Existing create flow unchanged | Existing mutation audit behavior retained | The template standardizes the detail page, not list-level restore or delete workflows. |
| EntraGroup detail | Existing EntraGroup resource detail route | Unchanged list-header behavior | Existing clickable-row inspect affordance remains | Existing list behavior retained | None | Unchanged list empty state | No mandatory header action; optional `Open related record` may appear only when a canonical related destination exists | N/A | No new audit event | Read-only directory-group detail remains non-destructive and permission-aware. |
| OperationRun detail | Existing canonical Operations run viewer | N/A | Existing list inspect affordance remains `View run` from operations surfaces | Existing operations list behavior retained | Existing behavior retained | Unchanged list empty state | `Back to Operations`, `Refresh`, `Open`, and existing contextual run actions such as `Resume capture` remain in the header and follow the shared placement rules | N/A | Existing mutation audit behavior retained | This feature standardizes layout and action placement only; any existing run-triggering action keeps its current Ops-UX and confirmation behavior. |

### Key Entities

- **Enterprise Detail Page Standard**: The shared interpretation contract that defines how important record-view pages present identity, state, context, and secondary technical information.
- **Summary Header**: The top-level page region that communicates the record title, current state, high-signal metadata, and primary actions.
- **Related Context Block**: A dedicated presentation area for the most relevant linked records, parent or child relationships, workspace or tenant context, and canonical next destinations.
- **Supporting Region**: The compact companion area that holds state cards, timestamps, contextual actions, and other high-value secondary information.
- **Technical Detail Block**: The intentionally secondary area that contains identifiers, raw metadata, and diagnostics without dominating the default reading path.

## Success Criteria

### Measurable Outcomes

- **SC-133-01 Target-page alignment**: All four initial target pages present a recognizable shared summary-first structure during acceptance review.
- **SC-133-02 Interpretation speed**: In acceptance walkthroughs, an operator can identify the record type, current state, and immediate next step on each target page within 10 seconds of page load.
- **SC-133-03 Reading-order compliance**: In automated regression coverage, 100% of aligned target pages render summary or state content before any technical-detail block.
- **SC-133-04 Context visibility**: In automated and manual review, 100% of aligned target pages either show a dedicated related-context area or an explicit empty-state message describing the absence of related context.
- **SC-133-05 Degraded-state safety**: In degraded-data test scenarios, all aligned target pages continue to render a complete page shell with clear missing-data messaging and no broken or ambiguous sections.
- **SC-133-06 Drift reduction**: Future planning for an additional enterprise detail page can reference this spec without redefining section ordering, action placement, or technical-detail treatment.