180 lines
10 KiB
Markdown
180 lines
10 KiB
Markdown
# Data Model: Deferred Operator Surfaces Retrofit
|
|
|
|
## Overview
|
|
|
|
This feature introduces no new persisted entity, no new table, and no new state family. It reuses existing `OperationRun` truth plus existing tenant-detail and onboarding presentation state to enforce clearer CTA hierarchy and scope signals.
|
|
|
|
## Entity: OperationRun
|
|
|
|
- **Type**: Existing persisted model
|
|
- **Purpose in this feature**: Canonical record whose existing admin-plane collection/detail routes remain the inspect targets for tenant-detail and onboarding embedded surfaces.
|
|
|
|
### Relevant Fields
|
|
|
|
| Field | Type | Notes |
|
|
|-------|------|-------|
|
|
| `id` | integer | Existing operation identifier used by embedded links and labels. |
|
|
| `type` | string | Continues to determine the operation label and UX guidance. |
|
|
| `workspace_id` | integer nullable | Preserves workspace-context routing and entitlement checks. |
|
|
| `tenant_id` | integer nullable | Preserves tenant-context entitlement and embedded-surface filtering. |
|
|
| `status` | string | Drives whether the current run is still active. |
|
|
| `outcome` | string | Drives blocked/failed/succeeded summary presentation. |
|
|
| `context` | array/json | Already carries target-scope, verification-report, and next-step metadata used by the affected surfaces. |
|
|
| `created_at` | timestamp | Used for recency display on recent-operations surfaces. |
|
|
| `started_at` / `completed_at` | timestamp nullable | Used for in-progress vs completed display and technical details. |
|
|
|
|
### Relationships
|
|
|
|
| Relationship | Target | Purpose |
|
|
|--------------|--------|---------|
|
|
| `tenant` | `Tenant` | Keeps tenant entitlement and tenant detail context explicit. |
|
|
| `workspace` | `Workspace` | Preserves workspace-context authorization for onboarding and admin viewers. |
|
|
| `initiator` | `User` / platform initiator context | Remains unchanged; no notification or lifecycle behavior changes in this feature. |
|
|
|
|
### Feature-Specific Invariants
|
|
|
|
- `/admin/operations` and `/admin/operations/{run}` remain the canonical collection/detail destinations.
|
|
- No new `OperationRun` type, state transition, notification timing, or summary-count behavior is introduced.
|
|
- Embedded surfaces may change CTA hierarchy and nearby scope copy, but not the underlying destination semantics.
|
|
|
|
### State Transitions Used By This Feature
|
|
|
|
| Transition | Preconditions | Result |
|
|
|------------|---------------|--------|
|
|
| Render inspect link for existing record | A covered surface already has a current `OperationRun` reference | No state change; surface exposes a single primary inspect path for that record. |
|
|
| Render workflow-start action | Covered surface has no current `OperationRun` reference and the operator can start the workflow | No state change; surface exposes one next-step CTA such as `Start verification`. |
|
|
|
|
## Derived Surface State: Tenant Detail Recent Operations Summary
|
|
|
|
- **Type**: Existing derived widget state, not persisted
|
|
- **Sources**:
|
|
- `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`
|
|
- `app/Filament/Widgets/Tenant/RecentOperationsSummary.php`
|
|
- `resources/views/filament/widgets/tenant/recent-operations-summary.blade.php`
|
|
- `app/Support/OperationRunLinks.php`
|
|
|
|
### Relevant Fields
|
|
|
|
| Field | Type | Purpose |
|
|
|-------|------|---------|
|
|
| `tenant` | `Tenant` | Provides the current tenant context for filtering and copy. |
|
|
| `runs` | collection of `OperationRun` | Existing recent operation records rendered in the embedded summary. |
|
|
| `operationsIndexUrl` | string | Existing admin-plane collection destination. |
|
|
| `rowOperationUrl` | string derived | Existing admin-plane detail destination per rendered run. |
|
|
| `hasRuns` | boolean derived | Distinguishes empty vs populated summary state. |
|
|
|
|
### Feature-Specific Invariants
|
|
|
|
- Row-level `Open operation` remains the primary inspect affordance for displayed records.
|
|
- Any collection drill-in that remains visible is secondary and must make the broader admin scope explicit through placement or nearby helper text.
|
|
- The table-based recent-operations widget on `/admin/t/{tenant}` remains out of scope for this model.
|
|
|
|
### State Rules
|
|
|
|
| State | Preconditions | Primary CTA | Secondary CTA |
|
|
|-------|---------------|-------------|---------------|
|
|
| Empty summary | `runs` is empty | None or a single next-step/collection affordance if retained | Admin-scope collection link only if clearly secondary |
|
|
| Populated summary | `runs` is not empty | Per-row `Open operation` for each visible record | One secondary collection affordance at most |
|
|
|
|
## Derived Surface State: Tenant Verification Widget
|
|
|
|
- **Type**: Existing derived widget state, not persisted
|
|
- **Sources**:
|
|
- `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`
|
|
- `app/Filament/Widgets/Tenant/TenantVerificationReport.php`
|
|
- `resources/views/filament/widgets/tenant/tenant-verification-report.blade.php`
|
|
|
|
### Relevant Fields
|
|
|
|
| Field | Type | Purpose |
|
|
|-------|------|---------|
|
|
| `run` | `OperationRun` nullable | Current verification-backed operation, if one exists. |
|
|
| `runUrl` | string nullable | Canonical inspect path for the current run. |
|
|
| `report` | array nullable | Stored verification report payload displayed read-only. |
|
|
| `isInProgress` | boolean | Distinguishes active vs completed run state. |
|
|
| `showStartAction` | boolean | Whether the embedded surface may expose a workflow-start CTA in empty-state conditions. |
|
|
| `canStart` | boolean | Whether the current actor can start verification. |
|
|
| `startTooltip` | string nullable | Existing permission helper text for disabled start states. |
|
|
| `lifecycleNotice` | string nullable | Existing archived/inactive-tenant explanation when starting work is not allowed. |
|
|
|
|
### Feature-Specific Invariants
|
|
|
|
- When no run exists and the tenant can be operated, the widget exposes one primary `Start verification` CTA.
|
|
- When a run exists, the widget exposes one primary inspect CTA for that run and does not compete with an inline rerun CTA.
|
|
- The existing tenant-detail header action remains the rerun/start path when the page still needs one outside the embedded widget.
|
|
- Archived or inoperable tenants may show explanation text, but no new inspect or start path is introduced by this feature.
|
|
|
|
### State Matrix
|
|
|
|
| State | Preconditions | Primary CTA | Secondary Inline CTA |
|
|
|-------|---------------|-------------|----------------------|
|
|
| No run / start allowed | `run` is null and `showStartAction && canStart` | `Start verification` | None |
|
|
| No run / cannot start | `run` is null and `! canStart` | None | None |
|
|
| Active run | `run` exists and `isInProgress` | `Open operation` | None |
|
|
| Completed or stale run | `run` exists and `! isInProgress` | `Open operation` | None |
|
|
| Archived / inactive tenant | `showStartAction` is false and `lifecycleNotice` is present | None | None |
|
|
|
|
## Derived Surface State: Onboarding Verification Surface
|
|
|
|
- **Type**: Existing guided-flow report state, not persisted
|
|
- **Sources**:
|
|
- `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
|
- `resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php`
|
|
- `resources/views/filament/modals/onboarding-verification-technical-details.blade.php`
|
|
- `managed_tenant_onboarding_sessions.state[verification_operation_run_id]`
|
|
|
|
### Relevant Fields
|
|
|
|
| Field | Type | Purpose |
|
|
|-------|------|---------|
|
|
| `verification_operation_run_id` | integer nullable | Existing onboarding-session pointer to the current verification run. |
|
|
| `run` | array nullable | Read-only operation data rendered in the onboarding report. |
|
|
| `runUrl` | string nullable | Canonical inspect path for the current run. |
|
|
| `previousRunUrl` | string nullable | Secondary link to the previously relevant run, when retained. |
|
|
| `report` | array nullable | Stored verification report payload rendered in the onboarding step. |
|
|
| `workflowPrimaryAction` | derived string nullable | Existing step-level CTA such as `Start verification` or `Refresh`. |
|
|
| `technicalDetailsVisible` | boolean derived | Controls whether advanced monitoring/context affordances are available. |
|
|
|
|
### Feature-Specific Invariants
|
|
|
|
- The wizard step owns workflow-next-step controls such as `Start verification` and `Refresh`.
|
|
- The embedded report/technical-details surfaces may expose one inspect CTA for the current run, but previous-run and monitoring links remain diagnostics-secondary only.
|
|
- Any advanced monitoring/admin destination is visible only when the destination is legitimate for the current operator and remains explicitly labeled as advanced.
|
|
- No new onboarding state, session field, or workflow branch is introduced.
|
|
|
|
### State Matrix
|
|
|
|
| State | Preconditions | Workflow CTA | Inspect CTA | Diagnostics CTA |
|
|
|-------|---------------|--------------|-------------|-----------------|
|
|
| No run | onboarding session has no current verification run | `Start verification` | None | None |
|
|
| Active run | current verification run exists and is not completed | `Refresh` | One current-run inspect link if retained on the report surface | Advanced monitoring only in technical details |
|
|
| Completed run | current verification run exists and is completed | None or existing step progression controls | One current-run inspect link | Previous-run and monitoring links remain secondary |
|
|
|
|
## Governance Artifact: Deferred Surface Exemption And Conformance Coverage
|
|
|
|
- **Type**: Existing registry and test coverage, not persisted
|
|
- **Sources**:
|
|
- `app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php`
|
|
- `tests/Feature/Guards/ActionSurfaceContractTest.php`
|
|
- focused widget/onboarding feature tests listed in the plan
|
|
|
|
### Relevant Fields
|
|
|
|
| Field | Type | Purpose |
|
|
|-------|------|---------|
|
|
| `className` | string | Exempted page/component class still outside declaration-backed discovery. |
|
|
| `reason` | string | Concrete justification for the current exemption. |
|
|
| `focusedTests` | derived list | Dedicated conformance coverage that protects the exempted surface behavior. |
|
|
|
|
### Feature-Specific Invariants
|
|
|
|
- `ManagedTenantOnboardingWizard` may remain baseline-exempt if the reason continues to point to dedicated conformance tests.
|
|
- This feature does not introduce a new widget declaration system or a new validator mode.
|
|
- Governance for the retrofitted surfaces should become narrower and more explicit, not broader.
|
|
|
|
## Persistence Impact
|
|
|
|
- **Schema changes**: None
|
|
- **Data migration**: None
|
|
- **New indexes**: None
|
|
- **Retention impact**: None |