TenantAtlas/specs/058-tenant-ui-polish/spec.md

Feature Specification: Tenant UI Polish (Dashboard + Inventory Hub + Operations)

Feature Branch: 058-tenant-ui-polish
Created: 2026-01-20
Status: Draft
Input: User description: "Feature 058 — Tenant UI Polish: Dashboard + Inventory Hub + Operations "Orders-style" (v1)"

User Scenarios & Testing (mandatory)

User Story 1 - Drift-first tenant dashboard (Priority: P1)

As a tenant admin, I can open a tenant-scoped dashboard that immediately surfaces drift risk and operations health, without triggering any remote calls.

Why this priority: This is the primary entry point for day-to-day operations and should be actionable at a glance.

Independent Test: Visiting the dashboard shows drift + operations KPIs, a “needs attention” list with working CTAs, and recent lists, while confirming no outbound HTTP happens during render and any background UI updates.

Acceptance Scenarios:

1. Given I am signed in to a tenant, When I open the Dashboard, Then I see tenant-scoped drift KPIs, operations health KPIs, and recent lists.
2. Given there are urgent drift issues (e.g., high severity open findings), When I view the Dashboard, Then they appear in the “Needs Attention” section with a CTA that navigates to a filtered view.
3. Given drift generation has a recent failed run, When I view the Dashboard, Then I can navigate from “Needs Attention” to the related operation run details.
4. Given there is no drift data yet, When I view the Dashboard, Then the dashboard renders calmly with empty-state messaging and no errors.

---

User Story 2 - Inventory becomes a hub module (Priority: P2)

As a tenant admin, I can use Inventory as a “hub” with consistent sub-navigation and a shared KPI header across Inventory subpages.

Why this priority: Inventory is a high-traffic area; a hub layout reduces cognitive load and makes it easier to find the right view quickly.

Independent Test: Navigating Inventory Items / Sync Runs / Coverage keeps the same shared KPI header, the left sub-navigation is consistent, and all data remains tenant-scoped and DB-only.

Acceptance Scenarios:

1. Given I am signed in to a tenant, When I open Inventory, Then I see hub navigation (Items / Sync Runs / Coverage) and a shared KPI header.
2. Given I switch between Inventory subpages, When I navigate Items → Sync Runs → Coverage, Then the KPI header remains visible and consistent.
3. Given the tenant has an inventory sync run history, When I open “Sync Runs”, Then I see only sync runs relevant to inventory synchronization.

---

User Story 3 - Operations index “Orders-style” (Priority: P3)

As a tenant admin, I can view Operations in an “orders-style” overview (KPIs + status tabs + table) to quickly assess activity and failures.

Why this priority: Operations is the canonical place to investigate work; better scanning and filtering reduces time-to-triage.

Independent Test: Visiting Operations index shows KPI cards and status tabs that correctly filter the table without introducing polling churn or any remote calls.

Acceptance Scenarios:

1. Given I am signed in to a tenant, When I open Operations, Then I see KPIs, status tabs, and the operations table.
2. Given there are active runs, When I click the “Active” tab, Then the table filters to queued + running runs only.
3. Given there are failed runs, When I click the “Failed” tab, Then the table filters to failed runs only.
4. Given I navigate away and back, When I return to Operations, Then the UI remains calm (no refresh loops) and loads quickly.

---

[Add more user stories as needed, each with an assigned priority]

Edge Cases

• No data yet: dashboard/inventory/operations render with empty states and helpful CTAs.
• Large tenants: KPI calculations remain fast enough to keep pages responsive.
• Mixed outcomes: partial/failed/succeeded runs are correctly categorized and discoverable via tabs/filters.
• Tenant switching: no cross-tenant leakage of KPIs, lists, or links.
• Time windows: KPI windows (e.g., last 7/30 days) handle timezones consistently.
• “Unknown” states: missing duration/end time renders gracefully (e.g., avg duration excludes non-terminal runs).

Requirements (mandatory)

Constitution alignment (required): If this feature introduces any Microsoft Graph calls, any write/change behavior, or any long-running/queued/scheduled work, the spec MUST describe contract registry updates, safety gates (preview/confirmation/audit), tenant isolation, run observability (OperationRun type/identity/visibility), and tests. If security-relevant DB-only actions intentionally skip OperationRun, the spec MUST describe AuditLog entries.

Functional Requirements

• FR-001 (Tenant scope): System MUST ensure the Dashboard, Inventory hub, and Operations views are tenant-scoped, with no cross-tenant visibility.
• FR-002 (DB-only surfaces): System MUST keep Dashboard, Inventory hub header, and Operations index DB-only during render and any background UI updates.
• FR-003 (Placement policy): System MUST show KPI cards only on these entry-point pages: Dashboard, Inventory hub (shared header), and Operations index.
• FR-004 (Inventory hub layout): System MUST provide an Inventory hub with left sub-navigation for Items, Sync Runs, and Coverage.
• FR-005 (Inventory KPIs): Inventory hub MUST show a shared KPI header across Inventory subpages with:
  • Total Items
  • Coverage % (covered items / total items)
  • Last Inventory Sync (status + timestamp)
  • Active Operations (queued + running)
• FR-006 (Inventory sync runs view): System MUST provide a “Sync Runs” view that lists only inventory synchronization runs.
• FR-007 (Coverage chips): System MUST standardize coverage chips to this set only: Restorable, Partial, Risk, Dependencies.
• FR-008 (Operations index KPIs): Operations index MUST show tenant-scoped KPIs:
  • Total Runs (30 days)
  • Active Runs (queued + running)
  • Failed/Partial (7 days)
  • Avg Duration (7 days, terminal runs only)
• FR-009 (Operations tabs): Operations index MUST provide status tabs that filter the operations table: All, Active, Succeeded, Partial, Failed.
• FR-010 (Canonical terminology): System MUST use “Operations” as the canonical label (no legacy naming on these surfaces).
• FR-011 (Canonical links): “View run” links MUST always navigate to the canonical operation run detail view.
• FR-012 (Calm UI rules): System MUST avoid polling/churn in modals and avoid refresh loops; background updates should be used only where clearly necessary.

Assumptions:

• Drift findings, inventory items, and operation runs already exist as tenant-scoped data sources.
• “Coverage %” defaults to covered/total; if total is 0, coverage shows as not available.
• Creating/generating drift is out of scope unless it can be performed as an explicit, enqueue-only user action that results in an operation run.

Key Entities (include if feature involves data)

• Tenant: The scope boundary for all dashboards and lists in this feature.
• Operation Run: A tenant-scoped record of work execution, including status, timestamps, and outcomes used for Operations KPIs and recent lists.
• Drift Finding: A tenant-scoped record representing detected drift, including severity and state (open/closed) used for Dashboard KPIs and “Needs Attention”.
• Inventory Item: A tenant-scoped record representing inventory coverage and totals used in the Inventory hub.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001 (Task speed): A tenant admin can reach “what needs attention” (drift/ops) from the dashboard within 30 seconds.
• SC-002 (Discoverability): A tenant admin can find inventory sync runs within 2 clicks from Inventory.
• SC-003 (Triage efficiency): A tenant admin can filter Operations to “Active” or “Failed” within 1 click and identify a run to investigate within 60 seconds.
• SC-004 (Calm UI): No refresh loops are observed on Dashboard, Inventory hub pages, or Operations index during normal navigation.
• SC-005 (Safety): Viewing Dashboard, Inventory hub pages, and Operations index does not trigger any outbound HTTP.