ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
bd752bc5c4
TenantAtlas/specs/138-managed-tenant-onboarding-draft-identity/tasks.md

12 KiB
Raw Blame History

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.

  • 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
  • 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
  • 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.

  • 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
  • T005 [P] Add draft query helpers or scopes for resumable workspace drafts in app/Models/TenantOnboardingSession.php
  • T006 [P] Create a draft stage derivation service or helper in app/Services/Onboarding/OnboardingDraftStageResolver.php
  • T007 [P] Create a draft access loader or resolver for canonical route binding in app/Services/Onboarding/OnboardingDraftResolver.php and route binding definitions
  • 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
  • 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

  • T010 [P] [US1] Add landing-route and concrete draft-route feature coverage in tests/Feature/Onboarding/OnboardingDraftRoutingTest.php
  • 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
  • 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

  • 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
  • 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
  • T015 [US1] Redirect to the canonical draft URL immediately after Step 1 creates or attaches a draft in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • 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

  • T017 [P] [US2] Add multi-draft landing, picker, and explicit summary or detail access coverage in tests/Feature/Onboarding/OnboardingDraftPickerTest.php
  • 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

  • T019 [US2] Build landing zero-, single-, and multi-draft behavior in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and related views or schema sections
  • 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
  • T021 [US2] Add resume orientation banner and current-stage projection in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • 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

  • T023 [P] [US3] Add lifecycle and non-resumable route coverage in tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php
  • 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
  • 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

  • T026 [US3] Add or formalize draft, completed, and cancelled lifecycle handling in app/Models/TenantOnboardingSession.php and related persistence paths
  • T027 [US3] Implement non-editable handling and summary or detail access for completed and cancelled drafts in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • T028 [US3] Add authorized cancel-draft action with confirmation in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • 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

  • T030 [P] [US4] Add browser coverage for hard-refresh resume on the canonical draft route in tests/Browser/OnboardingDraftRefreshTest.php
  • T031 [P] [US4] Add browser coverage for stale verification, bootstrap revisit behavior, and activation-guard persistence after refresh in tests/Browser/OnboardingDraftVerificationResumeTest.php
  • T032 [P] [US4] Add deterministic same-draft multi-tab coverage in tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php

Implementation for User Story 4

  • 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
  • T034 [US4] Ensure secret inputs remain transient and are never rehydrated from draft state in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • 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.

  • T036 [P] Align onboarding draft terminology across wizard, headers, notifications, and actions in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and related UI copy sources
  • 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
  • T038 Run formatting and final cleanup with vendor/bin/sail bin pint --dirty --format agent after implementation changes

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.