ahmido
6fdd45fb02
Some checks failed
Main Confidence / confidence (push) Failing after 53s
## Summary - keep stale active operation runs visible in the tenant progress overlay and polling state - align tenant and canonical operation surfaces around the shared stale-active presentation contract - add Spec 233 artifacts and clean the promoted-candidate backlog entries ## Validation - browser smoke: `/admin/t/18000000-0000-4000-8000-000000000180` -> stale dashboard CTA -> `/admin/operations?tenant_id=7&activeTab=active_stale_attention&problemClass=active_stale_attention` -> `/admin/operations/15` - verified healthy vs likely-stale tenant cards, canonical stale list row, and canonical run detail consistency ## Notes - local smoke fixture seeded with one fresh and one stale running `baseline_compare` operation for browser validation - Pest suite was not re-run in this session before opening this PR Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #269
80 lines
6.1 KiB
Markdown
80 lines
6.1 KiB
Markdown
# Quickstart: Operation Run Active-State Visibility & Stale Escalation
|
|
|
|
## Preconditions
|
|
|
|
1. Start the application stack:
|
|
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail up -d`
|
|
2. Work from branch `233-stale-run-visibility`.
|
|
3. Keep the scope bounded to existing admin-plane monitoring and progress surfaces.
|
|
|
|
## Primary Files To Review First
|
|
|
|
- `apps/platform/app/Models/OperationRun.php`
|
|
- `apps/platform/app/Support/Operations/OperationRunFreshnessState.php`
|
|
- `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`
|
|
- `apps/platform/app/Support/OpsUx/ActiveRuns.php`
|
|
- `apps/platform/app/Livewire/BulkOperationProgress.php`
|
|
- `apps/platform/app/Filament/Widgets/Tenant/RecentOperationsSummary.php`
|
|
- `apps/platform/app/Filament/Widgets/Dashboard/RecentOperations.php`
|
|
- `apps/platform/app/Filament/Resources/OperationRunResource.php`
|
|
- `apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php`
|
|
- `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
|
|
## Recommended Implementation Order
|
|
|
|
1. **Lock the truth source**
|
|
- Confirm no surface-local stale thresholds exist outside `OperationRunFreshnessState` and `OperationRun::problemClass()`.
|
|
- Reuse `OperationUxPresenter::decisionZoneTruth()`, `lifecycleAttentionSummary()`, and `surfaceGuidance()` wherever possible.
|
|
|
|
2. **Fix tenant progress visibility first**
|
|
- Update `ActiveRuns` and `BulkOperationProgress` so stale-active runs still count as active work for visibility and polling.
|
|
- Keep terminal runs disappearing on the next refresh cycle.
|
|
- Render stale-active elevation through the shared operation status badge and `OperationUxPresenter` guidance path.
|
|
|
|
3. **Converge tenant and workspace summary surfaces**
|
|
- Align `RecentOperationsSummary`, `Dashboard\RecentOperations`, `Dashboard\NeedsAttention`, `DashboardKpis`, and `WorkspaceOverviewBuilder` on the same compact/detailed stale-active semantics.
|
|
- Do not create a new dashboard surface family.
|
|
|
|
4. **Tighten canonical monitoring consistency last**
|
|
- Preserve `OperationRunResource` and `TenantlessOperationRunViewer` as the authoritative diagnostic surfaces.
|
|
- Adjust top-level explanation or row emphasis only where it improves consistency with the compact surfaces.
|
|
|
|
5. **Update focused tests in the same slice**
|
|
- Flip stale-hidden assertions in the tenant progress tests.
|
|
- Extend monitoring, widget, and visibility-safety tests to prove fresh versus stale boundaries, terminal transitions, and hidden-tenant/non-member isolation.
|
|
|
|
## Focused Test Matrix
|
|
|
|
| Scenario | Expected Result | Likely Test Family |
|
|
|---|---|---|
|
|
| Fresh queued/running run on tenant surface | Visible as healthy active work, no stale escalation | `tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php`, `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php` |
|
|
| Stale queued/running run on tenant surface | Still visible as active work, but clearly elevated | `tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php`, `tests/Feature/OpsUx/ProgressWidgetFiltersTest.php` |
|
|
| Stale run on workspace summaries | Scanable as attention-worthy, not collapsed into calm recency | `tests/Feature/Filament/WorkspaceOverviewOperationsTest.php`, `tests/Feature/Monitoring/MonitoringOperationsTest.php` |
|
|
| Stale run on canonical list/detail | Same active-state meaning preserved after drill-through | `tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php`, `tests/Feature/Operations/TenantlessOperationRunViewerTest.php`, `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php` |
|
|
| Terminal transition after refresh | Removed from active-only overlays and no longer presented as active | `tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php` |
|
|
| Hidden or out-of-scope runs during summary rendering | Remain invisible and do not alter visible active-state summaries | `tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php`, `tests/Feature/RunAuthorizationTenantIsolationTest.php` |
|
|
|
|
## Minimum Validation Commands
|
|
|
|
```bash
|
|
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php tests/Feature/OpsUx/ProgressWidgetFiltersTest.php tests/Feature/OpsUx/ProgressWidgetOverflowTest.php
|
|
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php tests/Feature/Filament/DashboardKpisWidgetTest.php tests/Feature/Filament/NeedsAttentionWidgetTest.php tests/Feature/Filament/WorkspaceOverviewOperationsTest.php tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php tests/Feature/Monitoring/MonitoringOperationsTest.php tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php
|
|
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RunAuthorizationTenantIsolationTest.php tests/Feature/OpsUx/NonLeakageWorkspaceOperationsTest.php
|
|
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
|
|
```
|
|
|
|
## Manual Smoke Checklist
|
|
|
|
1. Seed one fresh running run and one stale queued/running run for the same tenant.
|
|
2. Open the tenant dashboard and confirm the stale run is visible and clearly elevated without making the fresh run look unhealthy.
|
|
3. Confirm the tenant progress surface keeps polling while only stale-active work remains.
|
|
4. Open `/admin/operations` and verify the same run is distinguishable at row level.
|
|
5. Drill into `/admin/operations/{run}` and confirm the top summary preserves the same active-state meaning before raw diagnostics.
|
|
|
|
## Out Of Scope Guardrails
|
|
|
|
- Do not add retry, cancel, reconcile-now, or worker-control actions.
|
|
- Do not add new notifications or queued/running DB notifications.
|
|
- Do not add new persisted run summary data or new `OperationRun` status values.
|
|
- Do not widen the work into a new operations workbench or cross-workspace fleet view.
|