ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
dev
TenantAtlas/specs/138-managed-tenant-onboarding-draft-identity/tasks.md
ahmido 3f6f80f7af feat: refine onboarding draft flow and RBAC diff UX (#171) 
## 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
2026-03-14 20:09:54 +00:00

174 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Tasks: Managed Tenant Onboarding Draft Identity & Resume Semantics
**Input**: Design documents from `/specs/138-managed-tenant-onboarding-draft-identity/`
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `quickstart.md`, `contracts/onboarding-draft-resume.openapi.yaml`
**Tests**: Tests are REQUIRED because this feature changes routing, wizard resume behavior, lifecycle handling, authorization, and hard-refresh behavior.
**RBAC**: Tasks include workspace-scoped access checks, draft visibility rules, lifecycle authorization, deny-as-not-found behavior, and positive plus negative coverage.
**UI Naming**: Tasks include aligning operator copy for draft start, resume, attribution, and non-resumable states.
**Filament UI Action Surfaces**: Tasks include landing-state UX, multi-draft picker UX, wizard header orientation, and confirmed destructive lifecycle actions.
**Organization**: Tasks are grouped by user story so each story can be implemented and validated independently once foundational work is complete.
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: Establish common draft-state semantics, helpers, and test fixtures.
- [X] T001 [P] Add onboarding draft lifecycle constants or value objects in `app/Support/Onboarding/OnboardingDraftStatus.php`, `app/Support/Onboarding/OnboardingDraftStage.php`, and related helper classes if needed
- [X] T002 [P] Extend onboarding session factory and shared test helpers for resumable, completed, and cancelled drafts in `database/factories/TenantOnboardingSessionFactory.php` and `tests/Pest.php`
- [X] T003 [P] Add or extend onboarding capability helpers for draft resume and cancel checks, including explicit `404` versus `403` semantics, in `app/Support/Auth/Capabilities.php`, `app/Policies`, and related authorization helpers as needed
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Build the route, persistence, and resume derivation infrastructure required before story work can start.
**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
- [X] T004 Add explicit lifecycle and attribution support to onboarding drafts while preserving workspace-scoped ownership and the nullable-tenant workflow exception in `database/migrations/*managed_tenant_onboarding_sessions*`, `app/Models/TenantOnboardingSession.php`, and `database/factories/TenantOnboardingSessionFactory.php`
- [X] T005 [P] Add draft query helpers or scopes for resumable workspace drafts in `app/Models/TenantOnboardingSession.php`
- [X] T006 [P] Create a draft stage derivation service or helper in `app/Services/Onboarding/OnboardingDraftStageResolver.php`
- [X] T007 [P] Create a draft access loader or resolver for canonical route binding in `app/Services/Onboarding/OnboardingDraftResolver.php` and route binding definitions
- [X] T008 [P] Add route definitions and route-model resolution for `/admin/onboarding` and `/admin/onboarding/{onboardingDraft}` in `routes/web.php` and related page registration code
- [X] T009 [P] Add audit event IDs or payload conventions for draft creation, explicit resume, explicit selection, confirmed draft updates, provider connection changes, verification start and result persistence, bootstrap initiation, blocked activation override use, cancellation, and completion in `app/Enums/AuditActionId.php` or the relevant audit registry
**Checkpoint**: Foundation ready. User stories can now proceed.
---
## Phase 3: User Story 1 - Deterministic draft identity and routing (Priority: P1) 🎯 MVP
**Goal**: Give each onboarding draft a canonical URL and remove implicit resume as the primary mechanism.
**Independent Test**: Create or resume a draft from `/admin/onboarding`, confirm redirect to `/admin/onboarding/{draft}`, refresh, and verify the same draft still loads.
### Tests for User Story 1
- [X] T010 [P] [US1] Add landing-route and concrete draft-route feature coverage in `tests/Feature/Onboarding/OnboardingDraftRoutingTest.php`
- [X] T011 [P] [US1] Add draft access coverage for non-existent drafts, cross-workspace requests, non-member `404`, and in-scope member `403` behavior in `tests/Feature/Onboarding/OnboardingDraftAccessTest.php`
- [X] T012 [P] [US1] Add unit coverage for stage derivation and canonical draft loading in `tests/Unit/Onboarding/OnboardingDraftStageResolverTest.php` and `tests/Unit/Onboarding/OnboardingDraftResolverTest.php`
### Implementation for User Story 1
- [X] T013 [US1] Refactor `ManagedTenantOnboardingWizard` to accept an explicit draft parameter and load confirmed state from the resolved draft in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
- [X] T014 [US1] Replace heuristic-only single-session resume with landing-route redirect logic in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` or the landing controller or page wrapper
- [X] T015 [US1] Redirect to the canonical draft URL immediately after Step 1 creates or attaches a draft in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
- [X] T016 [US1] Persist draft attribution and current-step diagnostics on confirmed step saves in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `app/Models/TenantOnboardingSession.php`
**Checkpoint**: User Story 1 is complete when every active draft has a canonical URL and refresh stays anchored to the same draft.
---
## Phase 4: User Story 2 - Clear resume and multi-draft behavior (Priority: P1)
**Goal**: Make landing behavior deterministic, ambiguity explicit, and resume context visible.
**Independent Test**: Seed multiple drafts, visit `/admin/onboarding`, confirm picker UX, resume one draft, and verify the orientation banner and derived stage.
### Tests for User Story 2
- [X] T017 [P] [US2] Add multi-draft landing, picker, and explicit summary or detail access coverage in `tests/Feature/Onboarding/OnboardingDraftPickerTest.php`
- [X] T018 [P] [US2] Add Livewire coverage for resume banner, picker actions, and duplicate-draft warnings in `tests/Feature/ManagedTenantOnboardingWizardTest.php`
### Implementation for User Story 2
- [X] T019 [US2] Build landing zero-, single-, and multi-draft behavior in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and related views or schema sections
- [X] T020 [US2] Add draft picker metadata, resume action, explicit view summary or detail access, and explicit start-new action in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
- [X] T021 [US2] Add resume orientation banner and current-stage projection in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
- [X] T022 [US2] Add duplicate-draft warning and resume-first flow when the same target tenant already has a resumable draft in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
**Checkpoint**: User Story 2 is complete when ambiguity is explicit and operators always understand whether they are starting or resuming a draft.
---
## Phase 5: User Story 3 - Enterprise lifecycle, visibility, and safety (Priority: P2)
**Goal**: Formalize resumable versus non-resumable behavior, shared workspace visibility, attribution, and cancel authority.
**Independent Test**: Resume another operator’s draft, cancel a draft with authorization, and verify that completed or cancelled drafts do not reopen in edit mode.
### Tests for User Story 3
- [X] T023 [P] [US3] Add lifecycle and non-resumable route coverage in `tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php`
- [X] T024 [P] [US3] Add authorization coverage for shared workspace resume and cancel semantics, including member `403` versus non-member `404`, in `tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php`
- [X] T025 [P] [US3] Add audit coverage for draft creation, explicit resume, explicit selection, confirmed draft updates, provider connection changes, verification start and result persistence, bootstrap initiation, blocked activation override use, cancellation, and completion in `tests/Feature/Audit/OnboardingDraftAuditTest.php`
### Implementation for User Story 3
- [X] T026 [US3] Add or formalize `draft`, `completed`, and `cancelled` lifecycle handling in `app/Models/TenantOnboardingSession.php` and related persistence paths
- [X] T027 [US3] Implement non-editable handling and summary or detail access for completed and cancelled drafts in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
- [X] T028 [US3] Add authorized cancel-draft action with confirmation in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
- [X] T029 [US3] Surface started-by and last-updated-by attribution in picker and wizard header in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
**Checkpoint**: User Story 3 is complete when lifecycle state and attribution are explicit and non-resumable drafts cannot silently return to edit mode.
---
## Phase 6: User Story 4 - Verified refresh and resume behavior under real browser conditions (Priority: P2)
**Goal**: Add regression coverage for hard refresh, stale verification, and same-draft multi-tab behavior.
**Independent Test**: Browser tests create or resume a draft, reload the concrete draft URL, and verify confirmed state and non-rehydrated secrets remain correct.
### Tests for User Story 4
- [X] T030 [P] [US4] Add browser coverage for hard-refresh resume on the canonical draft route in `tests/Browser/OnboardingDraftRefreshTest.php`
- [X] T031 [P] [US4] Add browser coverage for stale verification, bootstrap revisit behavior, and activation-guard persistence after refresh in `tests/Browser/OnboardingDraftVerificationResumeTest.php`
- [X] T032 [P] [US4] Add deterministic same-draft multi-tab coverage in `tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php`
### Implementation for User Story 4
- [X] T033 [US4] Preserve verification and bootstrap references across reload and stage derivation in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `app/Services/Onboarding/OnboardingDraftStageResolver.php`
- [X] T034 [US4] Ensure secret inputs remain transient and are never rehydrated from draft state in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
- [X] T035 [US4] Add stale-verification projection, activation-guard persistence, and resume-safe messaging in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
**Checkpoint**: User Story 4 is complete when real browser refresh and revisit behavior is covered and trusted.
---
## Phase 7: Polish & Cross-Cutting Concerns
**Purpose**: Final naming alignment, focused validation, and cleanup.
- [X] T036 [P] Align onboarding draft terminology across wizard, headers, notifications, and actions in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and related UI copy sources
- [X] T037 [P] Validate focused quickstart scenarios from `specs/138-managed-tenant-onboarding-draft-identity/quickstart.md` using the targeted onboarding and browser suites as a quality gate
- [X] T038 Run formatting and final cleanup with `vendor/bin/sail bin pint --dirty --format agent` after implementation changes
- [X] T039 [P] Hide the `All onboarding drafts` header action when the current draft is the only resumable draft and add focused routing regression coverage in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `tests/Feature/Onboarding/OnboardingDraftRoutingTest.php`
- [X] T040 [P] Align tenant-list onboarding entry labels with landing semantics (`Add tenant` / `Continue onboarding` / `Choose onboarding draft`) in `app/Filament/Resources/TenantResource/Pages/ListTenants.php` and `tests/Feature/Filament/CreateCtaPlacementTest.php`
- [X] T041 [P] Redirect cancelled onboarding drafts back to their canonical draft URL and assert the immediate non-editable cancelled summary in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and `tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php`
---
## Dependencies & Execution Order
### Phase Dependencies
- **Setup (Phase 1)**: No dependencies; can start immediately.
- **Foundational (Phase 2)**: Depends on Setup completion and blocks all user stories.
- **User Story 1 (Phase 3)**: Depends on Foundational completion.
- **User Story 2 (Phase 4)**: Depends on Foundational completion and should follow immediately because it completes the landing and ambiguity model.
- **User Story 3 (Phase 5)**: Depends on Foundational completion and benefits from the canonical route model established in US1 and US2.
- **User Story 4 (Phase 6)**: Depends on earlier story behavior stabilizing so browser tests cover final semantics.
- **Polish (Phase 7)**: Depends on the desired stories being complete.
### Parallel Opportunities
- T001-T003 can run in parallel.
- T005-T009 can run in parallel once T004 is defined.
- Test tasks marked `[P]` can run in parallel within each user story.
## Implementation Strategy
### MVP First
Deliver **Setup + Foundational + User Story 1** first so every active onboarding draft gets a canonical URL and refresh-safe identity.
### Resume Trust Second
Deliver **User Story 2** next so multi-draft ambiguity becomes explicit and operators get reliable resume orientation.
### Lifecycle and Browser Hardening Last
Finish with **User Story 3** and **User Story 4** to formalize cancel and non-resumable behavior and to lock the experience down with browser-level regression coverage.
Reference in New Issue View Git Blame Copy Permalink