ab0ffff1d1
- Canonical /admin/onboarding entry point; legacy routes 404\n- Tenantless run viewer at /admin/operations/{run} with membership-based 404\n- RBAC UX (disabled controls + tooltips) and server-side 403\n- DB-only rendering/refresh; contract registry enforced\n- Adds migrations + tests + spec artifacts
119 lines
5.3 KiB
Markdown
119 lines
5.3 KiB
Markdown
# Implementation Plan: Managed Tenant Onboarding Wizard V1 (Enterprise)
|
|
|
|
**Branch**: `073-unified-managed-tenant-onboarding-wizard` | **Date**: 2026-02-04 | **Spec**: specs/073-unified-managed-tenant-onboarding-wizard/spec.md
|
|
**Input**: Feature specification from specs/073-unified-managed-tenant-onboarding-wizard/spec.md
|
|
|
|
## Summary
|
|
|
|
Deliver a single onboarding entry point at `/admin/onboarding` that is workspace-first and tenantless until activation. Verification and optional bootstrap actions run asynchronously as `OperationRun`s and are viewable via a tenantless URL `/admin/operations/{run}` with workspace-membership based 404 semantics.
|
|
|
|
This requires:
|
|
- Updating onboarding routing and removing legacy entry points.
|
|
- Making the operations run viewer safe and usable without a selected workspace and without tenant routing.
|
|
- Ensuring RBAC-UX semantics (non-member → 404, member missing capability → 403) while keeping UI discoverability (disabled+tooltip).
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: PHP 8.4 (Laravel 12)
|
|
**Primary Dependencies**: Filament v5, Livewire v4
|
|
**Storage**: PostgreSQL (Sail)
|
|
**Testing**: Pest v4
|
|
**Target Platform**: macOS dev + Sail containers; deployed in containers (Dokploy)
|
|
**Project Type**: Web application
|
|
**Performance Goals**: Wizard + Monitoring pages render DB-only (no external calls); queued work for Graph
|
|
**Constraints**:
|
|
- Canonical entry `/admin/onboarding` only
|
|
- Tenantless operations viewer `/admin/operations/{run}` must not require selected workspace and must not auto-switch workspaces
|
|
- Secrets never rendered after capture; no secrets in operation run failures/audits
|
|
**Scale/Scope**: Multi-workspace admin app; onboarding must be safe, resumable, and regression-tested
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
- Inventory-first: Not directly impacted.
|
|
- Read/write separation: activation + overrides are write paths → audit + tests.
|
|
- Graph contract path: verification/bootstrap Graph calls only via `GraphClientInterface` and `config/graph_contracts.php` (including connectivity probes like `organization` and service-principal permission lookups).
|
|
- Deterministic capabilities: wizard uses canonical capability registry; no role-string checks.
|
|
- RBAC-UX: enforce 404/403 semantics; server-side authorizes all actions; UI disabled state is informational only.
|
|
- Authorization planes: tenant plane (Entra users) only; no platform plane (`/system`) routes or cross-plane behavior.
|
|
- Run observability: verification/bootstrap runs use `OperationRun`; render remains DB-only.
|
|
- Data minimization: never persist secrets in session/state/report/audit.
|
|
- Badge semantics: status chips use centralized badge mapping.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/073-unified-managed-tenant-onboarding-wizard/
|
|
├── plan.md
|
|
├── research.md
|
|
├── data-model.md
|
|
├── quickstart.md
|
|
├── contracts/
|
|
│ ├── http.openapi.yaml
|
|
│ └── onboarding-actions.md
|
|
└── tasks.md
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
app/
|
|
├── Filament/Pages/
|
|
├── Filament/Resources/
|
|
├── Http/Middleware/
|
|
├── Models/
|
|
├── Policies/
|
|
├── Services/
|
|
└── Support/
|
|
|
|
database/migrations/
|
|
tests/Feature/
|
|
```
|
|
|
|
**Structure Decision**: Implement onboarding as a Filament Page under `app/Filament/Pages` and keep operations viewing on `OperationRunResource`, but change authorization/middleware to support tenantless viewing.
|
|
|
|
## Phase 0 — Research
|
|
|
|
See: specs/073-unified-managed-tenant-onboarding-wizard/research.md
|
|
|
|
## Phase 1 — Design & Contracts
|
|
|
|
See:
|
|
- specs/073-unified-managed-tenant-onboarding-wizard/data-model.md
|
|
- specs/073-unified-managed-tenant-onboarding-wizard/contracts/http.openapi.yaml
|
|
- specs/073-unified-managed-tenant-onboarding-wizard/contracts/onboarding-actions.md
|
|
- specs/073-unified-managed-tenant-onboarding-wizard/quickstart.md
|
|
|
|
## Phase 2 — Planning (implementation outline)
|
|
|
|
1) Routing
|
|
- Add `/admin/onboarding` (canonical, sole entry point).
|
|
- Remove legacy entry points (404; no redirects): `/admin/new`, `/admin/managed-tenants/onboarding`, and any tenant-scoped onboarding/create entry points.
|
|
|
|
2) Tenantless operations run viewer
|
|
- Exempt `/admin/operations/{run}` from forced workspace selection (`EnsureWorkspaceSelected`) and from tenant auto-selection side effects when needed.
|
|
- Authorize `OperationRun` viewing by workspace membership derived from the run (non-member → 404).
|
|
|
|
3) OperationRun model + schema alignment
|
|
- Add `operation_runs.workspace_id` and support tenantless runs (`tenant_id` nullable) if onboarding verification/bootstraps start before activation.
|
|
- Preserve DB-level active-run dedupe with partial unique indexes for both tenant-bound and tenantless runs.
|
|
|
|
4) Wizard authorization model
|
|
- Gate wizard actions per canonical capabilities; keep controls visible-but-disabled with tooltip; server-side returns 403 for execution.
|
|
- Activation is owner-only; blocked override requires reason + audit.
|
|
|
|
5) Tests
|
|
- Add/extend Pest feature tests for:
|
|
- canonical `/admin/onboarding` routing
|
|
- legacy entry points 404
|
|
- `/admin/operations/{run}` membership→404 behavior without selected workspace
|
|
- 403 for member action attempts without capability
|
|
- owner-only activation + override audit reason
|
|
|
|
## Complexity Tracking
|
|
|
|
No constitution violations expected; changes are localized and gated by tests.
|