ahmido
b0a724acef
## Summary - harden the canonical operation run viewer so mismatched, missing, archived, onboarding, and selector-excluded tenant context no longer invalidates authorized canonical run viewing - extend canonical route, header-context, deep-link, and presentation coverage for Spec 144 and add the full spec artifact set under `specs/144-canonical-operation-viewer-context-decoupling/` - harden onboarding draft provider-connection resume logic so stale persisted provider connections fall back to the connect-provider step instead of resuming invalid state - add architecture-audit follow-up candidate material and prompt assets for the next governance hardening wave ## Testing - `vendor/bin/sail bin pint --dirty --format agent` - `vendor/bin/sail artisan test --compact tests/Feature/144/CanonicalOperationViewerContextMismatchTest.php tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php tests/Feature/OpsUx/OperateHubShellTest.php tests/Feature/Monitoring/OperationsTenantScopeTest.php tests/Feature/RunAuthorizationTenantIsolationTest.php tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php tests/Feature/Monitoring/HeaderContextBarTest.php tests/Feature/Monitoring/OperationRunResolvedReferencePresentationTest.php tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php` - `vendor/bin/sail artisan test --compact tests/Feature/ManagedTenantOnboardingWizardTest.php tests/Unit/Onboarding/OnboardingDraftStageResolverTest.php tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php` ## Notes - branch: `144-canonical-operation-viewer-context-decoupling` - base: `dev` Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #173
64 lines
3.6 KiB
Markdown
64 lines
3.6 KiB
Markdown
# Route Contracts: Canonical Operation Viewer Context Decoupling
|
|
|
|
## Scope
|
|
|
|
These contracts describe the expected request and response behavior for the canonical operations routes affected by Spec 144.
|
|
|
|
## Canonical Routes
|
|
|
|
### GET /admin/operations
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| Route name | `admin.operations.index` |
|
|
| Purpose | Workspace-level operations index with optional tenant-context convenience filtering |
|
|
| Auth | Requires authenticated admin-plane user plus valid workspace membership |
|
|
| Selected tenant behavior | May default filters and return affordances when an active entitled tenant exists |
|
|
| Legitimacy rule | Index remains valid even when there is no selected tenant |
|
|
| Forbidden state | Not primary for this route; out-of-scope access is deny-as-not-found |
|
|
| Not found state | Non-member workspace access resolves as deny-as-not-found |
|
|
|
|
### GET /admin/operations/{run}
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| Route name | `admin.operations.view` |
|
|
| Purpose | Canonical workspace-level record viewer for one operation run |
|
|
| Primary subject | `OperationRun` |
|
|
| Auth | Requires authenticated admin-plane user, workspace membership for the run's workspace, direct tenant entitlement when `tenant_id` is present, and any resolved capability for the run type |
|
|
| Selected tenant behavior | Selected or remembered tenant context may affect informational banners and convenience navigation only |
|
|
| Success state | 200 when the run exists and the actor is authorized |
|
|
| Not found state | 404 when the run does not exist, the actor is not a workspace member, or the actor lacks entitlement to the run's linked tenant |
|
|
| Forbidden state | 403 only when the actor is otherwise in scope but lacks the capability resolved for the run type |
|
|
| Prohibited behavior | The route must not require the selected header tenant to match the run's tenant |
|
|
|
|
## Canonical Deep-Link Contract
|
|
|
|
- All in-product run links in this scope must resolve through `admin.operations.view`.
|
|
- Canonical run links from tenant pages, notifications, verification surfaces, and monitoring surfaces must be self-sufficient: if the run is viewable, the route must open regardless of the selected tenant context in the header.
|
|
- A generating page's tenant context must not be required to reproduce the same result when the link is opened later.
|
|
|
|
## Presentation Contract
|
|
|
|
### Canonical Viewer Banner States
|
|
|
|
| State | Required Behavior |
|
|
|-------|-------------------|
|
|
| Matching selected header tenant | Viewer may omit mismatch banner |
|
|
| Different selected header tenant | Viewer remains valid and shows a non-blocking mismatch message |
|
|
| No selected tenant | Viewer remains valid and may show workspace-level framing |
|
|
| Run linked to onboarding, archived, or another selector-excluded tenant under existing availability rules | Viewer remains valid and shows lifecycle-aware framing |
|
|
| Tenantless run | Viewer remains valid and clearly indicates workspace-level scope |
|
|
|
|
### Follow-Up Navigation
|
|
|
|
- Related links or actions may be reduced, disabled, or absent when the run's tenant is not entitled or when lifecycle rules make follow-up surfaces unavailable.
|
|
- Follow-up affordances must be evaluated independently from canonical viewer legitimacy when the run tenant is onboarding, archived, or otherwise excluded from the selector by existing availability rules.
|
|
- Missing follow-up links must not be interpreted as run invalidity and must not block the canonical viewer.
|
|
|
|
## Non-Goals For This Contract
|
|
|
|
- No change to `OperationRun` ownership
|
|
- No new route family
|
|
- No automatic tenant-context switching during run viewing
|
|
- No change to operation start, progress, or completion notification contracts |