ahmido
3f6f80f7af
## Summary - add the RBAC role definition diff UX upgrade as the first concrete consumer of the shared diff presentation foundation - refine managed tenant onboarding draft routing, CTA labeling, and cancellation redirect behavior - tighten related Filament and diff rendering regression coverage ## Testing - updated focused Pest coverage for onboarding draft routing and lifecycle behavior - updated focused Pest coverage for shared diff partials and RBAC finding rendering ## Notes - Livewire v4.0+ compliance is preserved within the existing Filament v5 surfaces - provider registration remains unchanged in bootstrap/providers.php - no new Filament assets were added; existing deployment practice still relies on php artisan filament:assets when assets change Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #171
127 lines
12 KiB
Markdown
127 lines
12 KiB
Markdown
# Feature Specification: RBAC Role Definition Diff UX Upgrade
|
|
|
|
**Feature Branch**: `142-rbac-role-definition-diff-ux-upgrade`
|
|
**Created**: 2026-03-14
|
|
**Status**: Draft
|
|
**Input**: User description: "Upgrade the RBAC role definition diff experience on the finding detail screen by adopting the shared diff presentation foundation from Spec 141 as its first concrete consumer. Make changed rows immediately obvious, de-emphasize unchanged rows, render Allowed Actions as meaningful add/remove inline diffs, keep the implementation tightly scoped to the RBAC consumer, and do not migrate unrelated diff screens."
|
|
|
|
## Spec Scope Fields *(mandatory)*
|
|
|
|
- **Scope**: workspace
|
|
- **Primary Routes**: Existing Findings resource detail surface for RBAC role definition findings, including the current finding view page under the admin panel; no new routes are introduced.
|
|
- **Data Ownership**: Existing `Finding` records and their RBAC evidence remain authoritative. This feature only changes how already-available RBAC comparison evidence is presented on the finding detail screen.
|
|
- **RBAC**: Existing finding detail membership and capability checks remain unchanged. The feature must only render data already available to authorized viewers and must not widen access.
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### User Story 1 - Spot Real RBAC Changes Fast (Priority: P1)
|
|
|
|
An operator reviewing an RBAC role definition finding can immediately see which fields changed without manually comparing every baseline and current value.
|
|
|
|
**Why this priority**: Faster triage is the primary business value. If the changed field is not immediately obvious, the screen remains operationally slow even if the underlying data is correct.
|
|
|
|
**Independent Test**: Can be fully tested by rendering an RBAC finding with a small number of changed fields and many unchanged fields, then verifying that the changed fields are explicitly emphasized and the summary counts align with what is shown.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** an RBAC finding where only a small subset of fields changed, **When** the operator opens the finding detail page, **Then** the changed rows are immediately distinguishable from unchanged rows.
|
|
2. **Given** an RBAC finding with changed, added, and removed fields, **When** the operator reviews the diff region, **Then** each row clearly communicates its change state without relying on color alone.
|
|
|
|
---
|
|
|
|
### User Story 2 - Understand Permission List Differences (Priority: P2)
|
|
|
|
An operator reviewing Allowed Actions can tell which permissions were added or removed without reading large before-and-after text blobs.
|
|
|
|
**Why this priority**: Permission-list changes are the highest-friction part of RBAC review today and create the most avoidable operator effort.
|
|
|
|
**Independent Test**: Can be tested by rendering representative Allowed Actions differences and confirming that added and removed actions appear as meaningful inline differences rather than as broad side-by-side value blocks.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** an RBAC finding where Allowed Actions differs between baseline and current, **When** the diff region renders, **Then** added actions and removed actions are shown with explicit list-difference semantics.
|
|
2. **Given** an RBAC finding where some actions are unchanged, **When** the permission list is rendered, **Then** unchanged actions remain readable without visually overwhelming the added and removed actions.
|
|
|
|
---
|
|
|
|
### User Story 3 - Reuse the Shared Diff Language Safely (Priority: P3)
|
|
|
|
A product team can treat RBAC as the first real consumer of the shared diff presentation foundation from Spec 141 without forcing unrelated compare screens to migrate at the same time.
|
|
|
|
**Why this priority**: The feature should validate the shared foundation in a real operator workflow while staying narrow enough to avoid accidental platform-wide churn.
|
|
|
|
**Independent Test**: Can be tested by confirming that the RBAC finding detail surface adopts the shared presentation language and that unrelated diff screens remain unchanged after delivery.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the shared diff presentation foundation from Spec 141 exists, **When** the RBAC finding detail screen is upgraded, **Then** it uses the shared change vocabulary and summary/detail semantics.
|
|
2. **Given** another diff surface outside RBAC is not part of this feature, **When** this feature is released, **Then** that unrelated surface remains unchanged.
|
|
|
|
### Edge Cases
|
|
|
|
- What happens when an RBAC finding contains no meaningful differences? The summary and detail region must clearly communicate that no changes were detected and must not imply missing data is a change.
|
|
- What happens when a field exists only in baseline or only in current evidence? The screen must distinguish one-sided fields from ordinary changed rows and present them as explicit added or removed values.
|
|
- What happens when Allowed Actions or another list-like value is empty, sparse, or medium length? The screen must remain readable and must not collapse into ambiguous empty or noisy text states.
|
|
- What happens when optional RBAC metadata is absent from the evidence payload? The diff region must remain stable, legible, and safe to render.
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
This feature is presentation-only. It introduces no Microsoft Graph calls, no write workflow, no queued or scheduled work, and no `OperationRun` usage.
|
|
|
|
This feature does not change authorization rules. Existing server-side finding access controls remain authoritative, and the upgraded diff region must only render evidence already loaded for the authorized finding detail page.
|
|
|
|
This feature modifies an existing Filament view surface within the Findings resource. The Action Surface Contract remains satisfied because no new actions, destructive flows, or audit-producing mutations are introduced. UX-001 remains satisfied because the finding detail page continues to use the existing View page and infolist structure; this feature only upgrades one RBAC diff region inside that layout.
|
|
|
|
This feature changes diff-state badges inside the RBAC finding detail region. Badge semantics must remain centralized through the shared change-state vocabulary from Spec 141 rather than ad hoc local meanings, and tests must verify that summary badges match rendered row states.
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: The RBAC role definition diff region on the finding detail screen MUST adopt the shared change-state vocabulary from Spec 141: changed, unchanged, added, and removed.
|
|
- **FR-002**: The RBAC diff region MUST use the shared diff presentation language for both summary badges and row-level detail so the same change states mean the same thing in both places.
|
|
- **FR-003**: Changed rows MUST receive stronger visual emphasis than unchanged rows, and that emphasis MUST be understandable without relying on color alone.
|
|
- **FR-004**: Unchanged rows MUST remain available for audit context but MUST be presented in a quieter way so they do not dominate the screen.
|
|
- **FR-005**: Summary badges MUST accurately reflect the states of the rows rendered in the RBAC diff region.
|
|
- **FR-006**: If the summary indicates only a small number of changed fields, the detailed rows MUST make those changed fields easy to identify at first read.
|
|
- **FR-007**: Allowed Actions MUST render as meaningful list differences that explicitly show added and removed actions instead of only broad before-and-after value blocks.
|
|
- **FR-008**: The RBAC diff region MAY show unchanged actions in a muted form when that improves readability, but unchanged actions MUST NOT overshadow added or removed actions.
|
|
- **FR-009**: Fields that exist only in baseline evidence MUST render as removed, and fields that exist only in current evidence MUST render as added.
|
|
- **FR-010**: One-sided rows MUST be visually and semantically distinct from ordinary changed rows.
|
|
- **FR-011**: Null values, boolean values, simple scalar values, and list-like values MUST follow the shared value-display behavior established by Spec 141 so RBAC does not introduce ad hoc formatting drift.
|
|
- **FR-012**: The RBAC consumer MUST preserve a stable, deterministic row order that supports operator review instead of arbitrary noise.
|
|
- **FR-013**: The upgraded diff region MUST remain legible in both light and dark mode.
|
|
- **FR-014**: The RBAC consumer MUST render safely when there are no changes, when values are empty, and when optional RBAC metadata is sparse or missing.
|
|
- **FR-015**: Any optional local “show only changes” behavior is allowed only if it remains local to the RBAC consumer, is not required for core comprehension, and does not add disproportionate interaction fragility.
|
|
- **FR-016**: This feature MUST remain limited to the RBAC role definition diff region on the finding detail screen and MUST NOT migrate unrelated diff screens.
|
|
- **FR-017**: The feature MUST establish RBAC as the first validated consumer of the shared diff presentation foundation from Spec 141.
|
|
- **FR-018**: Developer-facing guidance for this feature MUST identify RBAC as the first consumer, note which RBAC fields are treated as list-like, and explain any deliberate consumer-local choices that future adopters should understand.
|
|
|
|
## UI Action Matrix *(mandatory when Filament is changed)*
|
|
|
|
| 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 |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| Findings resource view page | `app/Filament/Resources/FindingResource.php` and the existing RBAC diff entry view on the finding detail page | Unchanged | Existing record view from the Findings list | None introduced | None | None introduced | Existing view-page header actions remain unchanged | Not applicable | No | Presentation-only upgrade inside an existing infolist entry. No new actions, mutations, confirmations, or authorization surfaces are added. |
|
|
|
|
### Key Entities *(include if feature involves data)*
|
|
|
|
- **RBAC Diff Row**: One operator-facing field in the role definition comparison, including its label, its current change state, and the values needed to explain the difference.
|
|
- **RBAC Diff Summary**: The compact set of counts and labels that tells the operator how many rows are changed, unchanged, added, or removed.
|
|
- **List Difference**: The operator-facing explanation of list-like RBAC fields, especially Allowed Actions, showing which items were added, removed, or retained.
|
|
- **RBAC Comparison Evidence**: The existing finding evidence payload that already contains the baseline and current RBAC values used by the finding detail screen.
|
|
|
|
## Assumptions
|
|
|
|
- The existing RBAC comparison evidence already contains enough structured baseline, current, and changed-field information to support a presentation upgrade without changing the authoritative diff producer.
|
|
- Allowed Actions is the primary list-like field that needs meaningful add/remove rendering in this feature, while any other simple list-like RBAC fields may adopt the same presentation if they fit cleanly.
|
|
- Existing finding detail authorization, record loading, tenant isolation, and routing remain unchanged.
|
|
- Spec 141 remains the source of truth for the shared diff vocabulary and shared presentation behavior used by this consumer.
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: In acceptance review with representative RBAC findings, 100% of rendered RBAC diff rows are classified using the shared change vocabulary of changed, unchanged, added, or removed.
|
|
- **SC-002**: In representative RBAC findings that contain mixed row states, summary badge counts match the rendered detailed rows with zero mismatches.
|
|
- **SC-003**: In representative RBAC findings where only 1 to 5 fields differ, the changed fields are identifiable at first read without requiring operators to inspect every unchanged row manually.
|
|
- **SC-004**: In representative Allowed Actions comparisons containing up to 25 actions, operators can identify added and removed permissions directly from the rendered list-difference view without switching to raw evidence.
|
|
- **SC-005**: Representative no-change and sparse-payload RBAC findings render a stable explanatory state with no broken layout, ambiguous empty values, or misleading change labels.
|