ahmido
f13a4ce409
Implements Spec 110 Ops‑UX Enforcement and applies the repo‑wide “enterprise” standard for operation start + dedup surfaces. Key points - Start surfaces: only ephemeral queued toast (no DB notifications for started/queued/running). - Dedup paths: canonical “already queued” toast. - Progress refresh: dispatch run-enqueued browser event so the global widget updates immediately. - Completion: exactly-once terminal DB notification on completion (per Ops‑UX contract). Tests & formatting - Full suite: 1738 passed, 8 skipped (8477 assertions). - Pint: `vendor/bin/sail bin pint --dirty --format agent` (pass). Notable change - Removed legacy `RunStatusChangedNotification` (replaced by the terminal-only completion notification policy). Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #134
226 lines
11 KiB
Markdown
226 lines
11 KiB
Markdown
---
|
||
|
||
description: "Executable task list for Ops-UX Enforcement & Cleanup"
|
||
|
||
---
|
||
|
||
# Tasks: Ops-UX Enforcement & Cleanup (Enterprise Standard Rollout)
|
||
|
||
**Input**: Design documents from `/specs/110-ops-ux-enforcement/`
|
||
|
||
- plan.md: [specs/110-ops-ux-enforcement/plan.md](specs/110-ops-ux-enforcement/plan.md)
|
||
- spec.md: [specs/110-ops-ux-enforcement/spec.md](specs/110-ops-ux-enforcement/spec.md)
|
||
- research.md: [specs/110-ops-ux-enforcement/research.md](specs/110-ops-ux-enforcement/research.md)
|
||
- data-model.md: [specs/110-ops-ux-enforcement/data-model.md](specs/110-ops-ux-enforcement/data-model.md)
|
||
- contracts/: [specs/110-ops-ux-enforcement/contracts/](specs/110-ops-ux-enforcement/contracts/)
|
||
|
||
**Tests**: REQUIRED (Pest) — both guard tests and focused regressions.
|
||
|
||
## Phase 1: Setup (Shared Test Infrastructure)
|
||
|
||
**Purpose**: Create minimal shared helpers for guard tests and keep failure output consistent.
|
||
|
||
- [X] T001 [P] Add source scanning helper in tests/Support/OpsUx/SourceFileScanner.php
|
||
|
||
---
|
||
|
||
## Phase 2: Foundational (Blocking Prerequisites)
|
||
|
||
**Purpose**: Cross-cutting invariants that must be true before user story work can be considered “done”.
|
||
|
||
- [X] T002 Update queued notification defaults in app/Services/OperationRunService.php (dispatchOrFail + enqueue helpers default emitQueuedNotification=false)
|
||
- [X] T003 Confirm repo-wide call sites do not opt into queued DB notifications (remove/forbid `emitQueuedNotification: true` usages in `app/**`)
|
||
|
||
**Checkpoint**: No queued/running DB notifications can be emitted by default.
|
||
|
||
---
|
||
|
||
## Phase 3: User Story 1 — No Silent Completions (Priority: P1) 🎯 MVP
|
||
|
||
**Goal**: Terminal transitions always go through `OperationRunService`, producing exactly one terminal `OperationRunCompleted` notification for initiators.
|
||
|
||
**Independent Test**: Inventory sync + retention flow transitions to terminal and persists exactly one `OperationRunCompleted` notification for the initiator; system runs persist none.
|
||
|
||
### Tests (write first)
|
||
|
||
- [X] T004 [P] [US1] Add inventory sync terminal notification regression test in tests/Feature/OpsUx/Regression/InventorySyncTerminalNotificationTest.php
|
||
- [X] T005 [P] [US1] Add retention terminal notification regression test in tests/Feature/OpsUx/Regression/BackupRetentionTerminalNotificationTest.php
|
||
|
||
### Implementation
|
||
|
||
- [X] T006 [US1] Refactor terminal transition in app/Services/Inventory/InventorySyncService.php to use OperationRunService::updateRun()
|
||
- [X] T007 [US1] Refactor terminal transition in app/Jobs/ApplyBackupScheduleRetentionJob.php to use OperationRunService::updateRun()
|
||
- [X] T008 [US1] Refactor OperationRun status/outcome update in app/Console/Commands/TenantpilotBackfillWorkspaceIds.php to use OperationRunService::updateRun() (initiator may be null)
|
||
|
||
**Checkpoint**: US1 regressions pass, with no silent completions.
|
||
|
||
---
|
||
|
||
## Phase 4: User Story 2 — No Notification Spam (Priority: P1)
|
||
|
||
**Goal**: Remove job-level queued/completion DB notifications and eliminate queued DB notifications from start surfaces.
|
||
|
||
**Independent Test**: Backup schedule run + representative bulk flow complete with exactly one terminal `OperationRunCompleted` and zero queued/running DB notifications.
|
||
|
||
### Tests (write first)
|
||
|
||
- [X] T009 [P] [US2] Add backup schedule run notification regression test in tests/Feature/OpsUx/Regression/BackupScheduleRunNotificationTest.php
|
||
- [X] T010 [P] [US2] Add bulk job “abort/circuit-break” regression test in tests/Feature/OpsUx/Regression/BulkJobCircuitBreakerTest.php
|
||
|
||
### Implementation (Jobs)
|
||
|
||
- [X] T011 [P] [US2] Remove queued + custom finished DB notifications in app/Jobs/RunBackupScheduleJob.php
|
||
- [X] T012 [P] [US2] Remove completion/abort sendToDatabase branches in app/Jobs/BulkPolicyExportJob.php
|
||
- [X] T013 [P] [US2] Remove completion/abort sendToDatabase branches in app/Jobs/BulkRestoreRunForceDeleteJob.php
|
||
- [X] T029 [P] [US2] Remove completion/abort sendToDatabase branches in app/Jobs/BulkRestoreRunRestoreJob.php
|
||
- [X] T030 [P] [US2] Remove completion/abort sendToDatabase branches in app/Jobs/BulkPolicyUnignoreJob.php
|
||
- [X] T014 [P] [US2] Remove custom completion/failure DB notifications in app/Jobs/AddPoliciesToBackupSetJob.php
|
||
- [X] T015 [P] [US2] Remove custom completion/failure DB notifications in app/Jobs/RemovePoliciesFromBackupSetJob.php
|
||
|
||
### Implementation (Start surfaces / Filament)
|
||
|
||
- [X] T016 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/PolicyResource.php (remove sendToDatabase for queued ops)
|
||
- [X] T017 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/BackupScheduleResource.php (remove sendToDatabase for queued ops)
|
||
- [X] T018 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/TenantResource.php (remove sendToDatabase for queued ops)
|
||
- [X] T019 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/PolicyVersionResource.php (remove sendToDatabase for queued ops)
|
||
- [X] T031 [P] [US2] Replace queued DB notification with toast-only queued feedback in app/Filament/Resources/EntraGroupResource/Pages/ListEntraGroups.php (remove sendToDatabase for queued ops)
|
||
|
||
**Checkpoint**: US2 regressions pass and notifications remain terminal-only.
|
||
|
||
---
|
||
|
||
## Phase 5: User Story 3 — Legacy Notification Removed (Priority: P1)
|
||
|
||
**Goal**: Remove the out-of-system `RunStatusChangedNotification` and rely exclusively on canonical terminal `OperationRunCompleted`.
|
||
|
||
**Independent Test**: Restore run completion produces exactly one `OperationRunCompleted` notification and there are zero references to `RunStatusChangedNotification` in `app/` and `tests/`.
|
||
|
||
### Tests (write first)
|
||
|
||
- [X] T020 [P] [US3] Add restore run terminal notification regression test in tests/Feature/OpsUx/Regression/RestoreRunTerminalNotificationTest.php
|
||
|
||
### Implementation
|
||
|
||
- [X] T021 [US3] Remove legacy notification invocation in app/Jobs/ExecuteRestoreRunJob.php
|
||
- [X] T022 [US3] Delete legacy notification class app/Notifications/RunStatusChangedNotification.php
|
||
|
||
**Checkpoint**: US3 regression passes; no legacy notification remains.
|
||
|
||
---
|
||
|
||
## Phase 6: User Story 4 — Regression Guards Enforce the Constitution (Priority: P1)
|
||
|
||
**Goal**: CI guard tests fail fast when forbidden patterns reappear.
|
||
|
||
**Independent Test**: Guards fail with actionable output on a synthetic violation and pass on a clean codebase.
|
||
|
||
### Guard tests
|
||
|
||
- [X] T023 [P] [US4] Implement Guard A in tests/Feature/OpsUx/Constitution/DirectStatusTransitionGuardTest.php (scan app/** for forbidden status/outcome transitions: ->update([...]) arrays, direct ->status/->outcome assignments, and query/bulk updates; exclude app/Services/OperationRunService.php; print snippet)
|
||
- [X] T024 [P] [US4] Implement Guard B in tests/Feature/OpsUx/Constitution/JobDbNotificationGuardTest.php (scan app/** for OperationRun signal + DB notify emission; allowlist app/Services/OperationRunService.php and app/Notifications/OperationRunCompleted.php)
|
||
- [X] T025 [P] [US4] Implement Guard C in tests/Feature/OpsUx/Constitution/LegacyNotificationGuardTest.php (scan app/** and tests/** for RunStatusChangedNotification)
|
||
|
||
**Checkpoint**: Guard tests pass green and provide clear failure output.
|
||
|
||
---
|
||
|
||
## Phase 7: User Story 5 — Canonical "Already Queued" Toast (Priority: P2)
|
||
|
||
**Goal**: Dedup “already queued” messaging is canonical and consistent.
|
||
|
||
**Independent Test**: Trigger dedup path and confirm toast uses `OperationUxPresenter::alreadyQueuedToast(...)`.
|
||
|
||
- [X] T026 [P] [US5] Add OperationUxPresenter::alreadyQueuedToast(...) helper in app/Support/OpsUx/OperationUxPresenter.php
|
||
- [X] T027 [US5] Migrate dedup toast to canonical helper in app/Livewire/BackupSetPolicyPickerTable.php
|
||
|
||
---
|
||
|
||
## Phase 8: Polish & Cross-Cutting Concerns
|
||
|
||
**Purpose**: Final documentation alignment plus execution validation (guards, regressions, full suite, formatting).
|
||
|
||
- [X] T028 [P] Update quickstart commands/paths if needed in specs/110-ops-ux-enforcement/quickstart.md
|
||
- [X] T032 Run focused Ops-UX regression pack (including `tests/Feature/OpsUx/Regression/*`) and confirm green (SC-006 / DoD)
|
||
- [X] T033 Run constitution guard tests (`tests/Feature/OpsUx/Constitution/*`) and verify actionable failure output on synthetic violation + green on clean codebase (SC-005)
|
||
- [X] T034 Run full test suite (or CI-equivalent command used by this repo) and confirm green (DoD)
|
||
- [X] T035 [P] Run Pint for touched files via Sail (`./vendor/bin/sail bin pint --dirty`) and confirm clean (DoD)
|
||
|
||
---
|
||
|
||
## Phase 9: Follow-up — Repo-wide Start/Dedup Toast Standardization
|
||
|
||
**Purpose**: Ensure all remaining Filament start/dedup surfaces use canonical Ops-UX toasts and trigger immediate progress refresh.
|
||
|
||
- [X] T036 Standardize tenant verification start/dedup toasts + progress refresh (Tenant list row, tenant view header, verification widget)
|
||
- [X] T037 Standardize review pack generation widget to canonical queued/already queued toasts + view-run action
|
||
- [X] T038 Ensure admin roles scan creates/dedupes OperationRun at enqueue time + canonical toasts + progress refresh
|
||
- [X] T039 Standardize backup set removal dedupe notifications to canonical already queued toast + progress refresh
|
||
- [X] T040 Standardize restore run idempotency “already queued” to canonical already queued toast (with view-run when available)
|
||
- [X] T041 Standardize policy bulk delete queued/dedup toast to canonical queued/already queued + progress refresh
|
||
- [X] T042 Standardize onboarding wizard verification + bootstrap start/dedup toasts + progress refresh
|
||
|
||
---
|
||
|
||
## Dependencies & Execution Order
|
||
|
||
### User Story Completion Order
|
||
|
||
- US1 → US2 → US3 → US4 → US5
|
||
|
||
Rationale:
|
||
|
||
- US1–US3 remove known violations so the guard suite (US4) can pass on a clean codebase.
|
||
- US5 is optional polish and can land after enforcement is stable.
|
||
|
||
### Dependency Graph
|
||
|
||
```text
|
||
Phase 1 (Setup) ─┬─> Phase 2 (Foundational) ─┬─> US1 ─┬─> US2 ─┬─> US3 ─┬─> US4 ─┬─> US5
|
||
│ │ │ │ │ └─> Polish
|
||
└───────────────────────────┴────────┴────────┴────────┴───────────────
|
||
```
|
||
|
||
## Parallel Execution Examples
|
||
|
||
### US1 (tests + implementation)
|
||
|
||
```bash
|
||
T004: tests/Feature/OpsUx/Regression/InventorySyncTerminalNotificationTest.php
|
||
T005: tests/Feature/OpsUx/Regression/BackupRetentionTerminalNotificationTest.php
|
||
```
|
||
|
||
### US2 (jobs + start surfaces)
|
||
|
||
```bash
|
||
T011: app/Jobs/RunBackupScheduleJob.php
|
||
T012: app/Jobs/BulkPolicyExportJob.php
|
||
T013: app/Jobs/BulkRestoreRunForceDeleteJob.php
|
||
T014: app/Jobs/AddPoliciesToBackupSetJob.php
|
||
T015: app/Jobs/RemovePoliciesFromBackupSetJob.php
|
||
T016–T019: app/Filament/Resources/*Resource.php
|
||
```
|
||
|
||
### US4 (guards)
|
||
|
||
```bash
|
||
T023: tests/Feature/OpsUx/Constitution/DirectStatusTransitionGuardTest.php
|
||
T024: tests/Feature/OpsUx/Constitution/JobDbNotificationGuardTest.php
|
||
T025: tests/Feature/OpsUx/Constitution/LegacyNotificationGuardTest.php
|
||
```
|
||
|
||
## Implementation Strategy
|
||
|
||
### MVP Scope (recommended)
|
||
|
||
- Foundational (Phase 2) + US1 only.
|
||
|
||
This yields the highest-value guarantee quickly: “no silent completions” and exactly-once terminal notifications for the most critical flows.
|
||
|
||
### Incremental Delivery
|
||
|
||
1. Foundational → US1 → validate
|
||
2. US2 → validate
|
||
3. US3 → validate
|
||
4. US4 guards → enforce
|
||
5. US5 polish
|