ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

spec(046): add async progress + notifications requirements

Browse Source
This commit is contained in:
Ahmed Darrazi 2026-01-09 00:34:50 +01:00
parent 31527bd381
commit 3fd9856247
1 changed files with 14 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
specs/046-inventory-sync-button/spec.md
View File

@ -22,7 +22,7 @@ ## User Scenarios & Testing *(mandatory)*
### User Story 1 - Run Inventory Sync from UI (Priority: P1) ### User Story 1 - Run Inventory Sync from UI (Priority: P1)
As an admin, I want a button in the admin UI to start an Inventory Sync for the currently selected tenant, so I can refresh inventory data without needing CLI/queues. As an admin, I want a button in the admin UI to start an Inventory Sync for the currently selected tenant, so I can refresh inventory data without needing CLI.
**Why this priority**: Inventory is a core admin surface; the ability to refresh on-demand reduces troubleshooting time and improves trust in the data. **Why this priority**: Inventory is a core admin surface; the ability to refresh on-demand reduces troubleshooting time and improves trust in the data.
@ -30,8 +30,9 @@ ### User Story 1 - Run Inventory Sync from UI (Priority: P1)
**Acceptance Scenarios**: **Acceptance Scenarios**:
1. **Given** I am viewing Inventory for a tenant, **When** I click "Run Inventory Sync", **Then** a new Inventory Sync Run is created for that tenant. 1. **Given** I am viewing Inventory for a tenant, **When** I click "Run Inventory Sync", **Then** a new Inventory Sync Run is created for that tenant and work is started asynchronously.
2. **Given** a sync run is started, **When** I refresh the page, **Then** I can see the run listed with status updates until it finishes. 2. **Given** a sync run is started, **When** I view in-app notifications and the progress widget, **Then** I can see the sync progress and final outcome.
3. **Given** a sync run finishes (success/partial/failed), **When** I open the Inventory Sync Runs list, **Then** the run is visible with its terminal status and error summary (if any).
--- ---
@ -76,6 +77,7 @@ ### Edge Cases
- What happens when tenant credentials are missing/invalid and the sync fails early? - What happens when tenant credentials are missing/invalid and the sync fails early?
- What happens when the user clicks the button multiple times quickly? - What happens when the user clicks the button multiple times quickly?
- What happens when a sync is started but the UI is closed (should still finish and be observable later)? - What happens when a sync is started but the UI is closed (should still finish and be observable later)?
- What happens when queue workers are down and the sync does not progress?
## Requirements *(mandatory)* ## Requirements *(mandatory)*
@ -92,10 +94,13 @@ ### Functional Requirements
- **FR-001**: System MUST provide an admin UI action to start an Inventory Sync for the currently selected tenant. - **FR-001**: System MUST provide an admin UI action to start an Inventory Sync for the currently selected tenant.
- **FR-002**: System MUST scope the sync to the currently selected tenant and MUST NOT allow cross-tenant initiation. - **FR-002**: System MUST scope the sync to the currently selected tenant and MUST NOT allow cross-tenant initiation.
- **FR-003**: System MUST create an observable Inventory Sync Run record when a sync is started. - **FR-003**: System MUST create an observable Inventory Sync Run record when a sync is started.
- **FR-004**: System MUST enforce existing concurrency/lock rules and MUST NOT start overlapping runs for the same tenant/selection. - **FR-004**: System MUST start the Inventory Sync asynchronously (queued/background execution), not inline in the request.
- **FR-005**: System MUST show a clear success message when a run is started and a clear informational message when a run cannot be started due to locks/concurrency. - **FR-005**: System MUST enforce existing concurrency/lock rules and MUST NOT start overlapping runs for the same tenant/selection.
- **FR-006**: System MUST enforce authorization for starting sync runs. - **FR-006**: System MUST show a clear success message when a run is started and a clear informational message when a run cannot be started due to locks/concurrency.
- **FR-007**: System MUST record who initiated the sync run (user identity) on the run record AND in the audit trail for auditability. - **FR-007**: System MUST enforce authorization for starting sync runs.
- **FR-008**: System MUST record who initiated the sync run (user identity) on the run record AND in the audit trail for auditability.
- **FR-009**: System MUST provide in-app visibility into sync progress and outcome via a DB-backed notifications panel.
- **FR-010**: System MUST provide in-app visibility into sync progress and outcome via a bottom-right progress widget, consistent with the Policy Sync experience.
### Assumptions ### Assumptions
@ -106,6 +111,7 @@ ### Dependencies
- Tenant context switching is available so the action always targets the current tenant. - Tenant context switching is available so the action always targets the current tenant.
- Existing concurrency/lock rules are enforced consistently for all sync starts (UI-triggered or otherwise). - Existing concurrency/lock rules are enforced consistently for all sync starts (UI-triggered or otherwise).
- The application has an existing mechanism for DB-backed in-app notifications and a progress widget (used by Policy Sync).
*Example of marking unclear requirements:* *Example of marking unclear requirements:*
@ -128,5 +134,5 @@ ### Measurable Outcomes
- **SC-001**: An authorized admin can start an Inventory Sync from the UI in under 10 seconds (time to find + click action). - **SC-001**: An authorized admin can start an Inventory Sync from the UI in under 10 seconds (time to find + click action).
- **SC-002**: In a normal tenant, 95% of sync start attempts either create a run or provide a clear lock/concurrency explanation within 2 seconds. - **SC-002**: In a normal tenant, 95% of sync start attempts either create a run or provide a clear lock/concurrency explanation within 2 seconds.
- **SC-003**: In usability testing, at least 90% of admins can successfully start a sync and locate the resulting run without guidance. - **SC-003**: In usability testing, at least 90% of admins can successfully start a sync and locate the resulting run and its progress without guidance.
- **SC-004**: Support/debug time for "inventory looks stale" issues is reduced (measured as fewer repeated sync/troubleshooting requests), after rollout. - **SC-004**: Support/debug time for "inventory looks stale" issues is reduced (measured as fewer repeated sync/troubleshooting requests), after rollout.