From 283daeab3356360b638a2c09299534a63dc4d40d Mon Sep 17 00:00:00 2001 From: Ahmed Darrazi Date: Tue, 20 Jan 2026 23:44:00 +0100 Subject: [PATCH] spec: tenant ui polish v1 --- .../checklists/requirements.md | 35 +++++ specs/058-tenant-ui-polish/spec.md | 144 ++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 specs/058-tenant-ui-polish/checklists/requirements.md create mode 100644 specs/058-tenant-ui-polish/spec.md diff --git a/specs/058-tenant-ui-polish/checklists/requirements.md b/specs/058-tenant-ui-polish/checklists/requirements.md new file mode 100644 index 0000000..e4bf746 --- /dev/null +++ b/specs/058-tenant-ui-polish/checklists/requirements.md @@ -0,0 +1,35 @@ +# Specification Quality Checklist: Tenant UI Polish (v1) + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-01-20 +**Feature**: [specs/058-tenant-ui-polish/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 + +- Validation run: 2026-01-20 +- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan` diff --git a/specs/058-tenant-ui-polish/spec.md b/specs/058-tenant-ui-polish/spec.md new file mode 100644 index 0000000..079ad1c --- /dev/null +++ b/specs/058-tenant-ui-polish/spec.md @@ -0,0 +1,144 @@ +# 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.