131 lines
7.1 KiB
Markdown
131 lines
7.1 KiB
Markdown
# Data Model: Operations Naming Consolidation
|
|
|
|
## Overview
|
|
|
|
This feature introduces no new persisted entity, no new table, and no new state family. It reuses existing `OperationRun` truth and aligns the derived labels emitted by existing helpers, notifications, Filament surfaces, and Blade partials.
|
|
|
|
## Entity: OperationRun
|
|
|
|
- **Type**: Existing persisted model
|
|
- **Purpose in this feature**: Canonical record whose visible names, identifiers, and related links must read as `Operation` / `Operations` on covered non-system surfaces.
|
|
|
|
### Relevant Fields
|
|
|
|
| Field | Type | Notes |
|
|
|-------|------|-------|
|
|
| `id` | integer | Rendered as `Operation #<id>` or referenced by `Operation ID` on covered surfaces. |
|
|
| `type` | string | Human label continues to come from `OperationCatalog::label(...)`. |
|
|
| `workspace_id` | integer nullable | Preserves workspace-context routing and summary copy scope. |
|
|
| `tenant_id` | integer nullable | Preserves tenant-context and tenantless routing choices. |
|
|
| `status` | string | Used by summary/helper copy but not renamed semantically by this feature. |
|
|
| `outcome` | string | Used by summary/helper copy but not renamed semantically by this feature. |
|
|
| `summary_counts` | array/json | Existing count payload used by summary banners and helper text; count semantics stay unchanged. |
|
|
| `context` | array/json | Holds wizard, verification, and route-selection context already used by embedded surfaces. |
|
|
| `created_at` | timestamp | Used for recency copy on widgets and viewers. |
|
|
|
|
### Relationships
|
|
|
|
| Relationship | Target | Purpose |
|
|
|--------------|--------|---------|
|
|
| `workspace` | `Workspace` | Keeps workspace context explicit in related links and summaries. |
|
|
| `tenant` | `Tenant` | Keeps tenant context explicit in related links and summaries. |
|
|
| `user` | `User` or `PlatformUser` via notification context | Preserves initiator-specific notification routing; unchanged by this feature. |
|
|
|
|
### Feature-Specific Invariants
|
|
|
|
- Existing `OperationRun` routes remain the only canonical destinations for operation history.
|
|
- Visible operator nouns for covered existing records use `Operation` / `Operations`, while internal implementation names may remain `run`.
|
|
- System-plane interaction semantics remain owned by Spec 170 even if a shared label source is reused.
|
|
- No new `OperationRun` state transition, audit behavior, or notification timing is introduced.
|
|
|
|
### State Transitions Used By This Feature
|
|
|
|
| Transition | Preconditions | Result |
|
|
|------------|---------------|--------|
|
|
| Render existing record link | Existing `OperationRun` is already available on a covered surface | No state change; visible link/identifier copy changes to `Operation` terminology. |
|
|
| Render summary/helper copy | Existing `OperationRun` collection or counts are already available | No state change; plural nouns become `operations` where the subject is existing operation history. |
|
|
|
|
## Derived Label Source: Shared Operation Link And Reference Emitters
|
|
|
|
- **Type**: Existing derived helper layer, not persisted
|
|
- **Sources**:
|
|
- `app/Support/OperationRunLinks.php`
|
|
- `app/Support/OpsUx/OperationUxPresenter.php`
|
|
- `app/Notifications/OperationRunCompleted.php`
|
|
- `app/Notifications/OperationRunQueued.php`
|
|
- `app/Support/Navigation/RelatedActionLabelCatalog.php`
|
|
- `app/Support/Navigation/RelatedNavigationResolver.php`
|
|
- `app/Support/References/ReferenceTypeLabelCatalog.php`
|
|
- `app/Support/References/Resolvers/OperationRunReferenceResolver.php`
|
|
|
|
### Relevant Outputs
|
|
|
|
| Output | Current Role | Target Rule |
|
|
|--------|--------------|-------------|
|
|
| Detail action label | Opens a specific existing record | Use `Open operation` or a panel-appropriate equivalent, not `View run`. |
|
|
| Collection action label | Opens the operations collection | Use `Operations` wording, such as `Open operations` or `View in Operations`. |
|
|
| Identifier label | Displays one record identifier | Use `Operation #<id>` or `Operation ID`, not `Run #<id>` or `Run ID`. |
|
|
| Reference class label | Names an `OperationRun` in reference summaries | Use `Operation`, not `Operation run`. |
|
|
|
|
### Feature-Specific Invariants
|
|
|
|
- Existing URL generation helpers remain canonical.
|
|
- Context badges such as `Tenant context` and `Workspace` stay unchanged.
|
|
- Shared emitters must not regress Spec 170 system-surface naming while fixing non-system surfaces.
|
|
|
|
## Derived Surface: Embedded Operation Report Surface
|
|
|
|
- **Type**: Existing derived UI surface, not persisted
|
|
- **Sources**:
|
|
- `app/Filament/Widgets/Tenant/TenantVerificationReport.php`
|
|
- `resources/views/filament/widgets/tenant/tenant-verification-report.blade.php`
|
|
- `resources/views/filament/components/verification-report-viewer.blade.php`
|
|
- `resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php`
|
|
- `resources/views/filament/modals/onboarding-verification-technical-details.blade.php`
|
|
- `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
|
|
|
### Relevant Fields
|
|
|
|
| Field | Type | Purpose |
|
|
|-------|------|---------|
|
|
| `runUrl` | string nullable | Existing operation-detail destination for the rendered record. |
|
|
| `run.id` | integer | Visible identifier that becomes `Operation ID` or `Operation #<id>`. |
|
|
| `lifecycleNotice` | string nullable | Helper copy that may reference the record collection in plural form. |
|
|
| `showStartAction` / workflow CTA | boolean/string | Keeps task verbs such as `Start verification` intact when the UI is about starting new work. |
|
|
|
|
### Feature-Specific Invariants
|
|
|
|
- Workflow verbs may remain task-oriented when they describe starting work.
|
|
- Any link or identifier for an already-created record uses `Operation` terminology.
|
|
- Empty-state copy must not fall back to `verification run` or `Run #...` for the future record on covered surfaces.
|
|
|
|
## Derived Surface: Operation Summary Copy
|
|
|
|
- **Type**: Existing derived UI text, not persisted
|
|
- **Sources**:
|
|
- `app/Support/Workspaces/WorkspaceOverviewBuilder.php`
|
|
- `app/Support/Baselines/BaselineCompareSummaryAssessor.php`
|
|
- `resources/views/filament/pages/monitoring/operations.blade.php`
|
|
- `resources/views/filament/widgets/tenant/recent-operations-summary.blade.php`
|
|
- `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
|
|
|
|
### Relevant Fields
|
|
|
|
| Field | Type | Purpose |
|
|
|-------|------|---------|
|
|
| Count values | integer | Existing counts stay numerically identical while the visible plural noun changes to `operations`. |
|
|
| Status helper strings | string | Existing status or lifecycle summaries retain meaning but stop describing historical records as `run(s)`. |
|
|
| Drill-in URL | string nullable | Existing navigation to operation collections or detail remains unchanged. |
|
|
|
|
### Feature-Specific Invariants
|
|
|
|
- Plural references to historical, failed, active, or stuck `OperationRun` records use `operations` on covered surfaces.
|
|
- No new status dimension, badge taxonomy, or presenter layer is introduced.
|
|
- Collection drill-ins may still use panel-appropriate wording such as `View in Operations` where they open the operations collection.
|
|
|
|
## Persistence Impact
|
|
|
|
- **Schema changes**: None
|
|
- **Data migration**: None
|
|
- **New indexes**: None
|
|
- **Retention impact**: None |