ahmido
3030dd9af2
Summary Kurz: Implementiert Feature 054 — canonical OperationRun-flow, Monitoring UI, dispatch-safety, notifications, dedupe, plus small UX safety clarifications (RBAC group search delegated; Restore group mapping DB-only). What Changed Core service: OperationRun lifecycle, dedupe and dispatch helpers — OperationRunService.php. Model + migration: OperationRun model and migration — OperationRun.php, 2026_01_16_180642_create_operation_runs_table.php. Notifications: queued + terminal DB notifications (initiator-only) — OperationRunQueued.php, OperationRunCompleted.php. Monitoring UI: Filament list/detail + Livewire pieces (DB-only render) — OperationRunResource.php and related pages/views. Start surfaces / Jobs: instrumented start surfaces, job middleware, and job updates to use canonical runs — multiple app/Jobs/* and app/Filament/* updates (see tests for full coverage). RBAC + Restore UX clarifications: RBAC group search is delegated-Graph-based and disabled without delegated token; Restore group mapping remains DB-only (directory cache) and helper text always visible — TenantResource.php, RestoreRunResource.php. Specs / Constitution: updated spec & quickstart and added one-line constitution guideline about Graph usage: spec.md quickstart.md constitution.md Tests & Verification Unit / Feature tests added/updated for run lifecycle, notifications, idempotency, and UI guards: see tests/Feature/* (notably OperationRunServiceTest, MonitoringOperationsTest, OperationRunNotificationTest, and various Filament feature tests). Full test run locally: ./vendor/bin/sail artisan test → 587 passed, 5 skipped. Migrations Adds create_operation_runs_table migration; run php artisan migrate in staging after review. Notes / Rationale Monitoring pages are explicitly DB-only at render time (no Graph calls). Start surfaces enqueue work only and return a “View run” link. Delegated Graph access is used only for explicit user actions (RBAC group search); restore mapping intentionally uses cached DB data only to avoid render-time Graph calls. Dispatch wrapper marks runs failed immediately if background dispatch throws synchronously to avoid misleading “queued” states. Upgrade / Deploy Considerations Run migrations: ./vendor/bin/sail artisan migrate. Background workers should be running to process queued jobs (recommended to monitor queue health during rollout). No secret or token persistence changes. PR checklist Tests updated/added for changed behavior Specs updated: 054-unify-runs-suitewide docs + quickstart Constitution note added (.specify) Pint formatting applied Co-authored-by: Ahmed Darrazi <ahmeddarrazi@adsmac.local> Reviewed-on: #63
74 lines
2.8 KiB
Markdown
74 lines
2.8 KiB
Markdown
# Data Model: Unified Operations Runs
|
|
|
|
## Entities
|
|
|
|
### `OperationRun`
|
|
Canonical record for all long-running tenant operations.
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `id` | BigInt | Yes | Primary Key |
|
|
| `tenant_id` | BigInt | Yes | FK to Tenants |
|
|
| `user_id` | BigInt | No | FK to Users (Initiator). Null for system/scheduler. |
|
|
| `initiator_name` | String | Yes | Snapshot of user name or "System". |
|
|
| `type` | String | Yes | stable taxonomy e.g., `inventory.sync`. |
|
|
| `status` | String | Yes | Lifecycle state: `queued`, `running`, `completed`. |
|
|
| `outcome` | String | Yes | Result bucket: `pending`, `succeeded`, `partially_succeeded`, `failed`, `cancelled`. |
|
|
| `run_identity_hash` | String | Yes | Deterministic hash for idempotency. |
|
|
| `summary_counts` | JSONB | No | `{ "total": 10, "success": 8, "failed": 2, "skipped": 0 }` |
|
|
| `failure_summary` | JSONB | No | List of sanitized errors: `[{ "code": "graph.throttled", "message": "Throttled (retrying)", "count": 1 }]` |
|
|
| `context` | JSONB | No | Run-specific metadata. e.g., `{ "restore_run_id": 123, "selection": [...] }` |
|
|
| `started_at` | Timestamp | No | When execution began. |
|
|
| `completed_at` | Timestamp | No | When execution finished. |
|
|
| `created_at` | Timestamp | Yes | |
|
|
| `updated_at` | Timestamp | Yes | |
|
|
|
|
**Indexes**:
|
|
- `(tenant_id, run_identity_hash)` UNIQUE WHERE status IN ('queued', 'running')
|
|
- `(tenant_id, type, created_at)` for filtering/sorting
|
|
- `(tenant_id, created_at)` for default sort
|
|
|
|
### `RestoreRun` (Existing)
|
|
Remains the domain source of truth for Restore.
|
|
- Linked via `OperationRun.context['restore_run_id']`.
|
|
- Adapter row is created/visible only once `RestoreRunStatus=previewed` (or later).
|
|
- When `RestoreRunStatus=previewed`, the adapter uses `OperationRun.status=queued` and `OperationRun.outcome=pending`.
|
|
- `OperationRun` mirrors the restore execution lifecycle for Monitoring visibility (restore domain history remains owned by `RestoreRun`).
|
|
|
|
## Enums
|
|
|
|
### `OperationRunStatus`
|
|
- `queued`
|
|
- `running`
|
|
- `completed`
|
|
|
|
### `OperationRunOutcome`
|
|
- `pending` (default when running/queued)
|
|
- `succeeded`
|
|
- `partially_succeeded`
|
|
- `failed`
|
|
- `cancelled` (reserved/future; MUST NOT be produced by 054)
|
|
|
|
**UI label mapping** (display-only):
|
|
|
|
- `pending` → “Pending”
|
|
- `succeeded` → “Succeeded”
|
|
- `partially_succeeded` → “Partially succeeded”
|
|
- `failed` → “Failed”
|
|
- `cancelled` → “Cancelled” (reserved)
|
|
|
|
## State Transitions
|
|
|
|
`OperationRun.status` transitions:
|
|
|
|
- `queued` → `running` → `completed`
|
|
|
|
`OperationRun.outcome` transitions:
|
|
|
|
- `pending` while `status` is `queued` or `running`
|
|
- one of `succeeded`, `partially_succeeded`, `failed`, `cancelled` when `status` is `completed`
|
|
|
|
## Relationships
|
|
- `OperationRun` belongs to `Tenant`.
|
|
- `OperationRun` belongs to `User` (optional).
|