72 lines
5.6 KiB
Markdown
72 lines
5.6 KiB
Markdown
# Research — Spec 139 (Verify Access Required Permissions Assist)
|
||
|
||
## Decisions
|
||
|
||
### 1) Use a page action slideover on the existing onboarding wizard
|
||
- Decision: Implement the contextual assist as a Filament action on `ManagedTenantOnboardingWizard` that opens a slideover from the existing Verify Access step.
|
||
- Rationale:
|
||
- The page already uses Filament v5 `Action::make(...)->slideOver()` successfully for other in-place workflows.
|
||
- This preserves wizard continuity, satisfies the no-new-route requirement, and keeps the assist visually subordinate to the main step progression.
|
||
- Alternatives considered:
|
||
- Full-page navigation only: rejected because it breaks onboarding continuity and duplicates the exact problem this spec is meant to solve.
|
||
- A separate onboarding-only page or route: rejected because the spec explicitly forbids new routes and parallel surfaces.
|
||
|
||
### 2) Reuse the existing Required Permissions builder as the source of compact diagnostics
|
||
- Decision: Reuse `TenantRequiredPermissionsViewModelBuilder` as the canonical source for summary counts, overall status, freshness, missing application permissions, missing delegated permissions, and copy payloads.
|
||
- Rationale:
|
||
- The builder already provides DB-only permission diagnostics and copy payload semantics.
|
||
- Reusing it avoids forking permission summary logic and keeps the onboarding assist consistent with the full-page deep dive.
|
||
- Alternatives considered:
|
||
- Recomputing a second onboarding-specific summary from verification-report evidence alone: rejected because it would drift from the Required Permissions page and violate the additive-only intent.
|
||
|
||
### 3) Classify deep-dive links by behavior, not only by absolute URL scheme
|
||
- Decision: Harden Verify Access next-step link rendering with a shared internal-vs-deep-dive classification rule so relevant internal diagnostic links also open in a new tab.
|
||
- Rationale:
|
||
- The current Blade template opens only absolute external URLs in a new tab.
|
||
- Spec 139 requires internal diagnostic links from the verification report to stop replacing the onboarding tab, including pages other than Required Permissions.
|
||
- Alternatives considered:
|
||
- Hardcoding `Open required permissions` as the only new-tab internal link: rejected because the spec explicitly calls out other internal diagnostic links.
|
||
- Opening every internal `/admin/*` link in a new tab: rejected because not every internal link is a deep-dive escape hatch, and broad behavior changes would be too risky.
|
||
|
||
### 4) Keep the full-page Required Permissions page as the only deep-dive surface
|
||
- Decision: The assist will expose `Open full page` as a clearly secondary action that points to the existing `TenantRequiredPermissions` page via `RequiredPermissionsLinks::requiredPermissions()`.
|
||
- Rationale:
|
||
- This preserves the current product role of the page and avoids route sprawl.
|
||
- The deep dive remains available for advanced investigation while the onboarding tab stays on task.
|
||
- Alternatives considered:
|
||
- Replacing the full page with the slideover: rejected because the spec accepts that some advanced investigation still belongs on the full page.
|
||
|
||
### 5) Copy feedback should follow an explicit visible confirmation pattern
|
||
- Decision: Copy actions will only render when the relevant copy payload exists, and each copy action will provide explicit confirmation through a visible copied state, toast, or equivalent inline acknowledgement.
|
||
- Rationale:
|
||
- The spec requires clear feedback and safe handling when no copyable data exists.
|
||
- Reusing an existing clipboard feedback pattern is lower risk than inventing a new one.
|
||
- Alternatives considered:
|
||
- Silent clipboard copy: rejected because it gives poor operator feedback.
|
||
- Always-rendered disabled copy buttons for empty payloads: rejected because omitted or replaced actions are clearer in degraded states.
|
||
|
||
### 6) Extend existing onboarding verification tests instead of creating a separate test pyramid
|
||
- Decision: Add focused coverage in the existing onboarding verification feature, Livewire, and browser test areas.
|
||
- Rationale:
|
||
- The current repository already has strong seams around verification report rendering, slideover actions, stale verification continuity, and clustered checks.
|
||
- Extending those tests gives the best regression value with minimal new scaffolding.
|
||
- Alternatives considered:
|
||
- Creating a new isolated end-to-end-only suite for the assist: rejected because visibility rules and degraded-state rendering are faster and more deterministically covered in feature/Livewire tests.
|
||
|
||
## Resolved Clarifications
|
||
|
||
### How should the assist determine whether it is relevant?
|
||
- Decision: Relevance is driven by the stored verification report plus the existing permission diagnostics summary for the selected tenant.
|
||
- Rationale:
|
||
- The verification report already communicates permission-related blockers and next steps.
|
||
- The Required Permissions builder already exposes the underlying permission state needed for compact rendering.
|
||
|
||
### What should happen when permission detail is incomplete or stale?
|
||
- Decision: The assist still renders but degrades to safe fallback messaging, surfaces freshness/needs-attention context when available, and preserves rerun/deep-dive options instead of showing broken controls.
|
||
- Rationale:
|
||
- This matches the spec’s degraded-state requirements and keeps the recovery surface trustworthy.
|
||
|
||
### Does this feature need new backend persistence?
|
||
- Decision: No. The feature is computed entirely from existing onboarding draft state, the stored verification report, and existing permission diagnostics services.
|
||
- Rationale:
|
||
- This keeps the implementation additive and low risk. |