# 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)"

## Clarifications

### Session 2026-01-20

- Q: Coverage % definition for Inventory KPI header? → A: Coverage % = Restorable / Total (Partial remains a separate chip/number; main % stays conservative)
- Q: Drift stale threshold (last scan older than X days)? → A: 7 days
- Q: Inventory KPI “Active Operations” definition? → A: Show both counts: All active runs (queued + running) and Inventory-active runs (queued + running)
- Q: How many rows in “Recent” lists by default? → A: 10

### Session 2026-01-21

- Q: Operations index "Stuck" tab in v1? -> A: No "Stuck" tab in v1

## User Scenarios & Testing *(mandatory)*

<!--
  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
  you should still have a viable MVP (Minimum Viable Product) that delivers value.
  
  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
  Think of each story as a standalone slice of functionality that can be:
  - Developed independently
  - Tested independently
  - Deployed independently
  - Demonstrated to users independently
-->

### 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.
5. **Given** the last drift scan is older than 7 days, **When** I view the Dashboard, **Then** “Needs Attention” includes a “Drift stale” item with a CTA to investigate.
6. **Given** there are more than 10 drift findings and operation runs, **When** I view the Dashboard, **Then** each “Recent” list shows the 10 most recent items.

---

### 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.

<!--
  ACTION REQUIRED: The content in this section represents placeholders.
  Fill them out with the right functional requirements.
-->

### 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 % (restorable items / total items; partial shown separately)
  - Last Inventory Sync (status + timestamp)
  - Active Operations (queued + running), showing both:
    - All active runs
    - Inventory-active runs
- **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. No "Stuck" tab in v1.
- **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. Auto-refresh on Dashboard and Operations index is allowed only while active runs (queued/running) exist, and MUST stop when there are no active runs.
- **FR-013 (Drift stale rule)**: System MUST flag drift as “stale” when the last drift scan is older than 7 days and surface it in “Needs Attention” with an investigation CTA.
- **FR-014 (Recent list sizing)**: System MUST show 10 rows by default for “Recent Drift Findings” and “Recent Operations”.

### OperationRun status mapping (for tabs and KPIs)

OperationRun uses two canonical fields that drive UI filters:

- `status`: execution lifecycle (e.g., queued/running/completed)
- `outcome`: terminal result (e.g., succeeded/partially_succeeded/failed/cancelled)

Tab filters MUST map exactly as:

- **All**: no status/outcome filter
- **Active**: `status IN (queued, running)`
- **Succeeded**: `status = completed AND outcome = succeeded`
- **Partial**: `status = completed AND outcome = partially_succeeded`
- **Failed**: `status = completed AND outcome = failed`

Notes:

- No “Stuck” tab in v1.
- Runs with `outcome = cancelled` appear under **All** only (unless a future “Cancelled” tab is added).
- Any legacy status/outcome values must already be normalized before reaching this UI (out of scope for this feature).

### KPI window definitions (timestamp basis)

All KPI windows are tenant-scoped and DB-only.

- **Total Runs (30 days)**: count OperationRuns by `created_at` within the last 30 days (includes all statuses/outcomes).
- **Active Runs**: current count where `status IN (queued, running)` (no time window).
- **Failed/Partial (7 days)**: count terminal runs where `status = completed AND outcome IN (failed, partially_succeeded)` and `completed_at` is within the last 7 days.
- **Avg Duration (7 days)**: average of `(completed_at - started_at)` for runs where `status = completed`, `started_at` and `completed_at` are present, and `completed_at` is within the last 7 days.

### Inventory coverage classification (Restorable/Partial/Risk/Dependencies)

Coverage chips and KPI aggregation MUST derive from the existing “policy type meta” and dependency capability signals (DB-only):

- `inventory_items.policy_type`
- `config('tenantpilot.supported_policy_types')` meta fields:
  - `restore` (e.g., enabled / preview-only)
  - `risk` (e.g., medium / medium-high / high)
- Dependency support computed via the existing coverage dependency resolver (based on contracts/config).

Definitions:

- **Restorable**: inventory items whose policy type meta has `restore = enabled`
- **Partial**: inventory items whose policy type meta has `restore = preview-only`
- **Risk**: inventory items whose policy type meta has `risk IN (medium-high, high)`
- **Dependencies**: inventory items whose policy type supports dependencies per the existing dependency capability resolver

Notes:

- This feature does not redefine coverage semantics; it standardizes UI rendering and KPI aggregation based on the existing policy type meta.
- If a policy type is unknown/missing meta, it MUST be treated conservatively (non-restorable) for KPI aggregation.

**Assumptions**:
- Drift findings, inventory items, and operation runs already exist as tenant-scoped data sources.
- “Coverage %” is Restorable/Total; Partial is shown separately (e.g., chips/secondary metric). If total is 0, coverage shows as not available.
- “Drift stale” default threshold is 7 days.
- “Recent” list default size is 10.
- Auto-refresh behavior (DB-only): Dashboard and Operations index auto-refresh only while active runs exist; otherwise it stops.
- 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)*

<!--
  ACTION REQUIRED: Define measurable success criteria.
  These must be technology-agnostic and measurable.
-->

### 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.