99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# Implementation Plan: Unified Operations Runs Suitewide (054)
|
|
|
|
**Branch**: `feat/054-unify-operations-runs-suitewide` | **Date**: 2026-01-17 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/054-unify-runs-suitewide/spec.md` ([spec.md](spec.md))
|
|
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/054-unify-runs-suitewide/spec.md`
|
|
|
|
**Note**: This plan is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts.
|
|
|
|
## Summary
|
|
|
|
Eliminate “run sprawl” by adopting a single tenant-scoped canonical run record (`operation_runs`) for long-running and
|
|
operationally relevant actions across the product, surfaced consistently in Monitoring → Operations (list + detail).
|
|
|
|
Key behaviors:
|
|
- Start surfaces are enqueue-only: authorize → create/reuse canonical run (dedupe) → dispatch → confirm + “View run”.
|
|
- Legacy per-module run tables remain in parallel where they exist; Monitoring/Operations uses canonical runs.
|
|
- Restore remains a domain workflow record, but is mirrored into canonical runs via an adapter row (`restore.execute`)
|
|
created from `RestoreRunStatus=previewed` onward (`status=queued`, `outcome=pending` until execution begins).
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: PHP 8.4.15 (Laravel 12)
|
|
**Primary Dependencies**: Filament v4, Livewire v3
|
|
**Storage**: PostgreSQL (`operation_runs` + JSONB for summary/failures/context; partial unique index for active-run dedupe)
|
|
**Testing**: Pest v4 (PHPUnit v12)
|
|
**Target Platform**: Web application (Sail-first locally, Dokploy-first deploy)
|
|
**Project Type**: web
|
|
**Performance Goals**: Start surfaces confirm within 2 seconds and provide a “View run” link; Monitoring/Operations list is usable with default last-30-days window and filters.
|
|
**Constraints**: Tenant isolation is non-negotiable; Monitoring is DB-only at render time; no remote work inline; failures are stable codes + sanitized messages (no secrets/tokens/raw payload dumps).
|
|
**Scale/Scope**: Tenant-scoped run history across modules; retention defaults to 90 days.
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
- Inventory-first: PASS (Monitoring uses persisted run records; does not redefine Inventory semantics).
|
|
- Read/write separation: PASS (Monitoring/Operations is view-only; writes remain in their owning UIs with explicit confirmation/audit where applicable).
|
|
- Graph contract path: PASS (Monitoring makes no Graph calls; start surfaces MUST NOT perform remote work inline).
|
|
- Deterministic capabilities: N/A (no new capability resolver introduced in this feature).
|
|
- Tenant isolation: PASS (all run access is tenant-scoped; cross-tenant access is forbidden).
|
|
- Run observability: PASS (queued/remote/scheduled work is tracked as canonical runs and links to a single Monitoring hub).
|
|
- Automation: PASS (active-run de-duplication via deterministic identity + partial unique index).
|
|
- Data minimization: PASS (failure summaries are sanitized and stable; no secrets/tokens/raw payload dumps in persisted failures/notifications).
|
|
|
|
**Gate status (pre-Phase 0)**: PASS (no violations).
|
|
**Gate status (post-Phase 1)**: PASS (design artifacts present: `research.md`, `data-model.md`, `contracts/`, `quickstart.md`).
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/054-unify-runs-suitewide/
|
|
├── plan.md # This file (/speckit.plan command output)
|
|
├── spec.md # Feature specification (input)
|
|
├── checklists/
|
|
│ └── requirements.md # Spec quality checklist
|
|
├── research.md # Phase 0 output
|
|
├── data-model.md # Phase 1 output
|
|
├── quickstart.md # Phase 1 output
|
|
├── contracts/ # Phase 1 output
|
|
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
app/
|
|
├── Filament/
|
|
│ ├── Pages/
|
|
│ └── Resources/
|
|
├── Jobs/
|
|
│ └── Middleware/
|
|
├── Listeners/
|
|
├── Models/
|
|
├── Notifications/
|
|
├── Observers/
|
|
├── Policies/
|
|
├── Services/
|
|
└── Support/
|
|
|
|
database/
|
|
└── migrations/
|
|
|
|
routes/
|
|
└── console.php
|
|
|
|
tests/
|
|
├── Feature/
|
|
└── Unit/
|
|
```
|
|
|
|
**Structure Decision**: Laravel web application. Implement canonical runs via Eloquent (`OperationRun`) + a small service layer for idempotent creation and lifecycle updates, instrument background jobs via middleware, and surface runs in Filament Monitoring/Operations (tenant-scoped, view-only).
|
|
|
|
## Complexity Tracking
|
|
|
|
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
|-----------|------------|-------------------------------------|
|
|
| None | | |
|