ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
64b4d7417e
TenantAtlas/specs/170-system-operations-surface-alignment/quickstart.md
Ahmed Darrazi 64b4d7417e feat: align system operations surfaces
2026-03-30 20:34:01 +02:00

3.6 KiB
Raw Blame History

Quickstart: System Operations Surface Alignment

Goal

Bring the system-panel Operations surfaces into conformance with the declared read-only registry contract by removing inline triage from the list rows, standardizing visible naming to Operations / Operation, adding explicit list CTAs, and keeping triage on the canonical operation detail page.

Prerequisites

  1. Start the local stack:
vendor/bin/sail up -d
  1. Work on branch 170-system-operations-surface-alignment.

Implementation Steps

  1. Update the three list pages:
    • app/Filament/System/Pages/Ops/Runs.php
    • app/Filament/System/Pages/Ops/Failures.php
    • app/Filament/System/Pages/Ops/Stuck.php
  2. Remove the retry, cancel, and mark_investigated table actions from each list page.
  3. Keep recordUrl() row-click navigation intact for each list page.
  4. Update visible navigation labels, headings, empty-state copy, and page CTA behavior so the changed surfaces use Operations / Operation vocabulary.
  5. Update each list page's actionSurfaceDeclaration() explanation text so it reflects detail-owned triage rather than row-level triage.
  6. Update app/Filament/System/Pages/Ops/ViewRun.php and resources/views/filament/system/pages/ops/view-run.blade.php so the detail page keeps triage ownership, uses Operation #... copy, and exposes Show all operations.
  7. Leave app/Services/SystemConsole/OperationRunTriageService.php unchanged unless a small refactor is needed to support the page move without changing behavior.

Tests To Update

  1. tests/Feature/System/Spec114/OpsTriageActionsTest.php
    • Replace row-action execution assertions on Runs with detail-page action visibility/execution assertions on ViewRun.
    • Keep view-only versus manage-capable separation explicit.
    • Add assertions for visible Operations / Operation copy and the Show all operations return path.
  2. tests/Feature/Guards/ActionSurfaceContractTest.php
    • Replace the three expectations for direct row triage with expectations that the row action set is empty while recordUrl() still points to SystemOperationRunLinks::view($run).
    • Assert the list CTA behavior and canonical Operations naming on the changed surfaces.
  3. Keep the existing page-access tests for failures/stuck passing.

Focused Verification

Run the smallest relevant test set first:

vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsTriageActionsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php

If implementation touches other platform-ops behavior, add the page access tests:

vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsFailuresViewTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsStuckViewTest.php

Formatting

After code changes, run:

vendor/bin/sail bin pint --dirty --format agent

Manual Review Checklist

  1. The Runs, Failures, and Stuck tables still navigate by row click.
  2. None of the three lists exposes inline triage actions.
  3. The changed system surfaces use Operations / Operation as the visible noun.
  4. The Operations list exposes Go to runbooks, while Failed operations and Stuck operations expose Show all operations as the single header and empty-state CTA.
  5. The system operation detail page still shows Retry, Cancel, and Mark investigated only for manage-capable operators and exposes Show all operations as the return path.
  6. Cancel still requires confirmation.
  7. Retry still produces the existing queued toast with a View run link.