diff --git a/specs/057-filament-v5-upgrade/checklists/requirements.md b/specs/057-filament-v5-upgrade/checklists/requirements.md index 3ceac5d..53ae050 100644 --- a/specs/057-filament-v5-upgrade/checklists/requirements.md +++ b/specs/057-filament-v5-upgrade/checklists/requirements.md @@ -1,4 +1,4 @@ -# Specification Quality Checklist: Admin UI Stack Upgrade (Panel + Suite) +# Specification Quality Checklist: Admin UI Framework Upgrade (Panel + Suite) **Purpose**: Validate specification completeness and quality before proceeding to planning **Created**: 2026-01-20 @@ -32,4 +32,4 @@ ## Feature Readiness ## Notes - This is a technical upgrade, but the spec intentionally describes outcomes and guardrails rather than implementation steps. -- Proceed to planning: identify concrete packages, versions, and migration steps in plan/tasks. +- Proceed to planning: identify concrete dependencies, sequencing, and validation steps in plan/tasks. diff --git a/specs/057-filament-v5-upgrade/spec.md b/specs/057-filament-v5-upgrade/spec.md index 06208b0..bfac543 100644 --- a/specs/057-filament-v5-upgrade/spec.md +++ b/specs/057-filament-v5-upgrade/spec.md @@ -1,18 +1,18 @@ -# Feature Specification: Admin UI Stack Upgrade (Panel + Suite) +# Feature Specification: Admin UI Framework Upgrade (Panel + Suite) **Feature Branch**: `057-filament-v5-upgrade` **Created**: 2026-01-20 **Status**: Draft -**Input**: Upgrade the existing admin UI stack to the next supported major release to maintain compatibility and support, and ensure no regressions for tenant isolation and Ops-UX/Monitoring guardrails. +**Input**: Upgrade the existing admin UI framework to the next supported major release to maintain compatibility and support, and ensure no regressions for tenant isolation and Monitoring/Operations safety guardrails. ## Clarifications ### Session 2026-01-20 - Q: What exactly counts as a “remote call” that is forbidden during Monitoring/Operations page render? → A: Any outbound HTTP request. -- Q: Are background/automatic Livewire requests (polling, auto-refresh, hydration) allowed to make outbound HTTP calls on Monitoring/Operations pages? → A: No; Monitoring/Operations must remain DB-only even for polling/auto-refresh/hydration. Remote work is only allowed via explicit user actions that enqueue tracked operations. +- Q: Are background/automatic UI requests (polling, auto-refresh, hydration) allowed to make outbound HTTP calls on Monitoring/Operations pages? → A: No; Monitoring/Operations must remain DB-only even for polling/auto-refresh/hydration. Remote work is only allowed via explicit user actions that enqueue tracked operations. - Q: Which pages count as “Monitoring/Operations” for the DB-only rule? → A: Everything rendered under the Monitoring → Operations navigation section, including all widgets/partials/tabs rendered within that section. -- Q: If a third-party package is incompatible with the upgraded stack, what remediation is allowed? → A: Upgrade/replace the package to preserve functionality. Mixed-version pinning is not allowed. If something is not realistically replaceable, treat it as an explicit scope/decision change. +- Q: If a third-party admin UI extension is incompatible with the upgraded stack, what remediation is allowed? → A: Upgrade/replace the dependency to preserve functionality. Mixed-version pinning is not allowed. If something is not realistically replaceable, treat it as an explicit scope/decision change. - Q: Do we expect this upgrade to require any database schema/data changes? → A: Allowed only if strictly required by dependencies; must be reversible, non-destructive, backward compatible, and called out in release notes. ## User Scenarios & Testing *(mandatory)* @@ -62,43 +62,43 @@ ### User Story 3 - Deployment remains reliable (Priority: P3) ### Edge Cases -- A third-party admin/Live UI package is incompatible with the upgraded stack. +- A third-party admin UI extension is incompatible with the upgraded stack. - Users have stale browser assets after deploy and experience partial UI breakage. -- SPA navigation and global widgets fail to mount or miss events after navigation. +- In-app navigation and global widgets fail to mount or miss events after navigation. - Tenant switching occurs mid-session and cached UI state risks showing stale cross-tenant data. - Monitoring pages accidentally perform remote calls during render (must be prevented/detected). ## Requirements *(mandatory)* **Constitution alignment (required):** This feature is an upgrade. It MUST NOT introduce new Microsoft Graph calls or new Graph write behavior. -All content rendered under the Monitoring → Operations navigation section remains “DB-only” and must not perform any outbound HTTP requests during render or during background/automatic Livewire requests (polling/auto-refresh/hydration). Tenant isolation remains mandatory. +All content rendered under the Monitoring → Operations navigation section remains “DB-only” and must not perform any outbound HTTP requests during render or during background/automatic UI requests (polling/auto-refresh/hydration). Tenant isolation remains mandatory. ### Functional Requirements -- **FR-001**: The application MUST upgrade the admin panel stack to the next supported major release and its required compatible reactive UI layer. -- **FR-002**: The application MUST continue to support the existing styling system without asset build failures. -- **FR-003**: All existing Filament panels MUST load successfully for authorized users and preserve core interactions (navigation, tables, forms, actions, notifications, widgets). -- **FR-004**: SPA-style navigation flows MUST continue to work, including global widget mounting and event delivery across navigation. -- **FR-005**: Everything rendered under the Monitoring → Operations navigation section (including widgets/partials/tabs) MUST remain DB-only: no outbound HTTP requests are permitted during page render or during background/automatic Livewire requests (polling/auto-refresh/hydration). -- **FR-010**: Any remote work initiated from Monitoring/Operations pages MUST be triggered only by explicit user actions (e.g., buttons) and MUST enqueue tracked operations (e.g., `OperationRun`-backed jobs) rather than performing outbound HTTP inline. -- **FR-006**: Tenant isolation MUST be preserved across requests and Live UI interactions: all reads/writes/events/caches MUST scope to the active tenant. -- **FR-007**: Compatibility risks MUST be managed by producing an explicit inventory of affected third-party packages and documenting upgrade/replacement decisions. +- **FR-001**: The application MUST upgrade the admin panel framework to the next supported major release and remain fully functional for all in-scope admin workflows. +- **FR-002**: The application MUST continue to support the existing styling and asset build process without build failures. +- **FR-003**: All existing admin panel pages MUST load successfully for authorized users and preserve core interactions (navigation, lists, forms, actions, notifications, and widgets). +- **FR-004**: In-app navigation between admin pages MUST continue to work reliably, including global widget mounting and event-driven UI behavior. +- **FR-005**: Everything rendered under the Monitoring → Operations navigation section (including widgets/partials/tabs) MUST remain DB-only: no outbound HTTP requests are permitted during page render or during background/automatic UI requests (polling/auto-refresh/hydration). +- **FR-010**: Any remote work initiated from Monitoring/Operations pages MUST be triggered only by explicit user actions (e.g., buttons) and MUST enqueue a tracked operation with a persisted run record rather than performing outbound HTTP inline. +- **FR-006**: Tenant isolation MUST be preserved across requests and interactive UI behavior: all reads/writes/events/caches MUST scope to the active tenant. +- **FR-007**: Compatibility risks MUST be managed by producing an explicit inventory of affected third-party dependencies and documenting upgrade/replacement decisions. - **FR-011**: If a third-party package is incompatible with the upgraded stack, the system MUST preserve equivalent functionality by upgrading or replacing the package; mixed-version pinning is not allowed. Any unavoidable feature loss MUST be handled as an explicit scope/decision change. -- **FR-012**: Database migrations are allowed only if strictly required for compatibility; they MUST be reversible and non-destructive (no data loss). Migrations MUST include a safe `down()` path and avoid drops without an explicit plan, and MUST be mentioned in release notes. +- **FR-012**: Database migrations are allowed only if strictly required for compatibility; they MUST be reversible and non-destructive (no data loss) and MUST be mentioned in release notes. - **FR-008**: The upgrade MUST not introduce new Microsoft Graph read/write behavior; if any Graph-touching behavior changes are required, they MUST be explicitly specified with safety gates and observability updates. - **FR-009**: The upgrade MUST include a documented rollback procedure that restores the previous working state. ### Assumptions & Dependencies -- The current platform runtime versions already meet (or exceed) the minimum requirements for the next major admin UI stack release. -- Third-party UI packages used in the admin panel may need upgrades or replacements to remain compatible. +- The current platform runtime versions already meet (or exceed) the minimum requirements for the next major admin UI framework release. +- Third-party dependencies used in the admin panel may need upgrades or replacements to remain compatible. - Existing tenant isolation and “DB-only render time” guard tests (or equivalent checks) exist and remain authoritative for this upgrade. ### Key Entities *(include if feature involves data)* - **Tenant**: The active tenant context that scopes all data access and UI state. -- **OperationRun**: The persisted record of long-running operations shown in Monitoring/Operations views. -- **AuditLog**: The tenant-scoped audit trail used to retain accountability for sensitive actions. +- **Run Record**: The persisted record of long-running operations shown in Monitoring/Operations views. +- **Audit Log**: The tenant-scoped audit trail used to retain accountability for sensitive actions. ## Success Criteria *(mandatory)* @@ -107,4 +107,4 @@ ### Measurable Outcomes - **SC-001**: An administrator can sign in and reach a usable dashboard within 60 seconds on a fresh deployment. - **SC-002**: In regression testing, Monitoring/Operations pages render without any remote calls during render in 100% of runs. - **SC-003**: 0 critical UI-blocking errors occur in the primary admin journeys (P1 + P2 scenarios) during manual QA. -- **SC-004**: Automated regression checks pass (100% green) for the project’s standard test run. +- **SC-004**: Automated regression checks complete successfully (100% passing) for the project’s standard validation run.