ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
1b88d28739
TenantAtlas/specs/171-operations-naming-consolidation/data-model.md
ahmido 1b88d28739 feat: consolidate operation naming surfaces (#202) 
## Summary
- align operator-visible OperationRun terminology to canonical `Operations` / `Operation` labels across shared links, notifications, verification/onboarding surfaces, summary widgets, and monitoring/detail pages
- add the Spec 171 planning artifacts under `specs/171-operations-naming-consolidation/`
- close the remaining tenant dashboard and admin copy drift found during browser smoke validation

## Validation
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && vendor/bin/sail artisan test --compact tests/Unit/Support/RelatedNavigationResolverTest.php tests/Unit/Support/References/RelatedContextReferenceAdapterTest.php tests/Feature/OpsUx/NotificationViewRunLinkTest.php tests/Feature/Guards/ActionSurfaceContractTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php tests/Feature/Filament/BackupSetResolvedReferencePresentationTest.php tests/Feature/Filament/TenantVerificationReportWidgetTest.php tests/Feature/Onboarding/OnboardingVerificationTest.php tests/Feature/Onboarding/OnboardingVerificationClustersTest.php tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php tests/Feature/Filament/WorkspaceOverviewContentTest.php tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php tests/Feature/Monitoring/OperationLifecycleAggregateVisibilityTest.php tests/Feature/System/Spec114/OpsTriageActionsTest.php tests/Feature/System/Spec114/OpsFailuresViewTest.php tests/Feature/System/Spec114/OpsStuckViewTest.php`
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && vendor/bin/sail artisan test --compact tests/Browser/OnboardingDraftRefreshTest.php`
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && vendor/bin/sail bin pint --dirty --format agent`

## Notes
- no schema or route renames
- Filament / Livewire surface behavior stays within the existing admin and tenant panels
- OperationRunResource remains excluded from global search

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #202
2026-03-30 22:51:06 +00:00

7.1 KiB
Raw Blame History

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