ahmido
8f8bc24d1d
What: Upgrade Filament auf v5.2.1 (inkl. composer.lock + veröffentlichte Filament assets unter public), SpecKit-Doku unter specs/102-..., plus kleine Anpassungen in Tests + Tenant-Scoping in BackupSetResource. Verification: vendor/bin/sail bin pint --dirty --format agent (pass) + vendor/bin/sail artisan test --compact [AlertDeliveryViewerTest.php](http://_vscodecontentref_/6) tests/Feature/Filament/BackupSetGraphSafetyTest.php (pass) Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #124
127 lines
8.6 KiB
Markdown
127 lines
8.6 KiB
Markdown
# Feature Specification: Filament v5.2.1 Upgrade
|
||
|
||
**Feature Branch**: `feat/102-filament-5-2-1-upgrade`
|
||
**Created**: 2026-02-20
|
||
**Status**: Draft
|
||
**Input**: User description: "Upgrade the Filament admin panel framework to v5.2.1 (patch-level), with enterprise-grade verification and no feature changes."
|
||
|
||
## Spec Scope Fields *(mandatory)*
|
||
|
||
- **Scope**: workspace
|
||
- **Primary Routes**: Filament panels: Admin (`/admin/*`) and System (`/system/*`, if present)
|
||
- **Data Ownership**: No data model or schema changes are intended (dependency-only change)
|
||
- **RBAC**: No changes intended; existing membership + capability enforcement remains the source of truth
|
||
|
||
## Clarifications
|
||
|
||
### Session 2026-02-20
|
||
|
||
- Q: Which Filament panel(s) are in the verification gate (smoke + no runtime errors)? → A: Admin + System panels (`/admin/*` and `/system/*`, if the System panel exists).
|
||
- Q: How should plugin incompatibilities be handled during the upgrade? → A: Allow plugin version bumps in the same PR, but no application code changes (composer-only).
|
||
- Q: Where must the UI smoke be executed for the verification gate? → A: Staging UI smoke is required (local smoke is optional/early).
|
||
- Q: What must the automated verification gate include beyond the test suite? → A: Full automated regression suite + frontend build.
|
||
|
||
## Assumptions
|
||
|
||
- The current mainline build is green (automated regression suite passing) before the upgrade is applied.
|
||
- The application already meets the upstream framework requirements for Filament v5 (this change is patch-level, not a major migration).
|
||
- No UI/IA changes are intended; any observed behavior change during verification is treated as a regression.
|
||
- If the automated regression suite fails due to upstream test assertion/deprecation changes, test-only updates under `tests/**` are allowed to restore a green baseline; runtime application code remains unchanged.
|
||
|
||
## Dependencies
|
||
|
||
- All currently installed Filament extensions/plugins used by the application are compatible with v5.2.1.
|
||
- If compatibility requires it, Filament plugin/extension packages MAY be upgraded in the same PR as part of this dependency-only change, provided no application code changes are required.
|
||
|
||
## User Scenarios & Testing *(mandatory)*
|
||
|
||
### User Story 1 - Ship the patch upgrade safely (Priority: P1)
|
||
|
||
As a platform engineer, I want the admin UI framework upgraded to v5.2.1 so that we pick up upstream stability and bug fixes without changing product behavior.
|
||
|
||
**Why this priority**: This unblocks maintenance, reduces risk of known upstream issues, and keeps upgrade debt low.
|
||
|
||
**Independent Test**: The change is successful if the automated regression suite is green and the application boots into the admin panel(s) without runtime errors.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** the current mainline build is passing automated verification, **When** the upgrade is applied, **Then** the automated regression suite remains fully passing.
|
||
2. **Given** the upgrade is applied, **When** an authenticated admin user opens the Admin panel landing page and (if present) the System panel landing page, **Then** each page renders without errors and navigation is usable.
|
||
|
||
---
|
||
|
||
### User Story 2 - Validate core admin workflows (Priority: P2)
|
||
|
||
As an operator/QA, I want a short, repeatable UI smoke to confirm that the most critical admin workflows still work after the upgrade.
|
||
|
||
**Why this priority**: Patch upgrades can regress tables/actions/modals; a fast smoke test catches high-impact breakage early.
|
||
|
||
**Independent Test**: A human can complete the smoke checklist in 5–10 minutes without encountering a blocking error.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** an authenticated user in the Admin panel and (if present) the System panel, **When** they navigate between key sections, **Then** navigation loads each page without errors.
|
||
2. **Given** a list/table view, **When** the user selects multiple rows and uses bulk actions (including “select all”), **Then** selections and bulk actions behave correctly and do not affect non-selectable rows.
|
||
3. **Given** create/edit flows, **When** the user opens and confirms modals (including destructive confirmations), **Then** modals display and complete without runtime errors.
|
||
|
||
---
|
||
|
||
### User Story 3 - Roll back confidently if needed (Priority: P3)
|
||
|
||
As a platform engineer, I want a clear rollback so that any unexpected regression can be reversed quickly.
|
||
|
||
**Why this priority**: Dependency upgrades can have transitive compatibility issues; rollback is the safety net.
|
||
|
||
**Independent Test**: Rollback instructions are complete enough that another engineer can restore the previous known-good dependency set.
|
||
|
||
**Acceptance Scenarios**:
|
||
|
||
1. **Given** a regression is found during verification, **When** rollback steps are executed, **Then** the previous dependency set is restored and verification returns to green.
|
||
|
||
### Edge Cases
|
||
- Extension/plugin compatibility breaks at runtime (boot failures, missing classes, broken UI components).
|
||
- Composer-level plugin constraints block resolution to Filament v5.2.1 without bumping one or more plugin versions.
|
||
- Tenancy-related behavior changes (e.g., tenancy not being active where expected, or tenancy being registered when it should not be).
|
||
- Table selection edge cases (select-all, mixed selectable/non-selectable rows) behave inconsistently.
|
||
- Automated regression suite is green but UI smoke finds a blocking runtime error (e.g., modal/action rendering).
|
||
|
||
## Requirements *(mandatory)*
|
||
|
||
**Constitution alignment (required):** This change MUST NOT introduce any new Microsoft Graph calls, new write/change behaviors, or new long-running/queued/scheduled work.
|
||
|
||
**Constitution alignment (RBAC-UX):** No authorization model changes are intended. Any discovered RBAC behavior changes during verification MUST be treated as a regression and resolved before shipping.
|
||
|
||
**Constitution alignment (Filament Action Surfaces):** No Filament Resource / RelationManager / Page behavior is intended to change. If any action surface behavior changes as a side effect of the upgrade, it MUST be documented and explicitly verified as non-regressive.
|
||
|
||
### Functional Requirements
|
||
|
||
- **FR-001**: The system MUST upgrade Filament to version 5.2.1 or newer within the 5.2.x patch line.
|
||
- **FR-002**: The system MUST preserve existing admin panel behavior (no intentional user-facing feature changes).
|
||
- **FR-003**: The system MUST remain compatible with all currently installed Filament extensions/plugins used by the application.
|
||
- **FR-004**: The system MUST pass the full automated regression suite after the upgrade.
|
||
- **FR-005**: The system MUST pass the defined UI smoke checklist without blocking errors.
|
||
- **FR-006**: The system MUST provide a documented rollback procedure that restores the previous dependency set.
|
||
- **FR-007**: The upgrade MUST include a review of upstream release notes from 5.2.0 → 5.2.1, with any relevant behavioral changes mapped to verification steps.
|
||
- **FR-008**: The verification gate MUST include both the Admin panel and (if present) the System panel.
|
||
- **FR-009**: If plugin/extension dependency upgrades are required to achieve Filament v5.2.1 compatibility, they MUST be limited to dependency changes (no application code changes).
|
||
- **FR-010**: The UI smoke verification MUST be executed on staging as part of the go/no-go gate (local smoke is optional/early signal).
|
||
- **FR-011**: The automated verification gate MUST include the full automated regression suite and a successful frontend build.
|
||
|
||
## UI Action Matrix *(mandatory when Filament is changed)*
|
||
|
||
This is a dependency-only upgrade. No specific action surfaces are intentionally added or modified.
|
||
|
||
| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|
||
|---|---|---|---|---|---|---|---|---|---|---|
|
||
| Dependency upgrade only | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | Verify existing surfaces via smoke checklist and regression suite. |
|
||
|
||
## Success Criteria *(mandatory)*
|
||
|
||
### Measurable Outcomes
|
||
|
||
- **SC-001**: 100% of the automated regression suite passes on the upgrade branch.
|
||
- **SC-002**: The UI smoke checklist can be completed on staging in ≤ 10 minutes with 0 blocking errors.
|
||
- **SC-003**: No new “critical” regressions are introduced in admin workflows (0 release-blocking issues found during verification).
|
||
- **SC-004**: Rollback to the previous dependency set can be executed in ≤ 15 minutes on staging (measured from decision-to-rollback to green verification).
|
||
- **SC-005**: The frontend build completes successfully on the upgrade branch.
|