ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/369-baseline-profile-decision-view/plan.md
ahmido 54eb8ca065 feat(ui): implement baseline profile decision view (#440) 
Added a decision-first section to the Baseline Profile detail page. Includes request caching for summary metrics and corresponding browser/feature tests.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #440
2026-06-10 12:11:55 +00:00

12 KiB
Raw Permalink Blame History

Implementation Plan: Spec 369 - Baseline Profile Decision View

Branch: 369-baseline-profile-decision-view | Date: 2026-06-09 | Spec: specs/369-baseline-profile-decision-view/spec.md Input: Feature specification from specs/369-baseline-profile-decision-view/spec.md

Summary

Productize the existing Baseline Profile detail page into a decision-first governance surface. The implementation should keep the existing route, resource, actions, policies, OperationRun start UX, and baseline domain truth intact while changing first-read hierarchy: readiness, reason, impact, snapshot basis, assignment/usefulness, and one safe next action must appear before governed-subject normalization lineage and metadata.

Technical Context

Language/Version: PHP 8.4.15 Primary Dependencies: Laravel 12.52, Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, PostgreSQL via Sail Storage: PostgreSQL, no schema changes expected Testing: Pest Feature/Livewire tests plus bounded Pest Browser smoke if implementation changes rendered layout Target Platform: Laravel Sail local development, Dokploy container deployment later Project Type: Laravel monolith, Filament admin panel Performance Constraints: No new Graph calls or expensive queries during render; reuse existing eager loading and helper methods where possible Constraints: Page-local UI/productization only; no baseline engine, OperationRun lifecycle, provider, shell, route, or migration changes Scale/Scope: Existing Baseline Profile detail route and regression coverage only

Candidate Selection Gate

  • Selected candidate exists in source material: yes, Spec 368 finding UI-AUDIT-368-F03 and Candidate B.
  • Not already covered by active/completed spec: yes. Existing specs cover baseline engine/truth/compare (116, 159, 336) but not the Spec 368 browser-verified Baseline Profile detail signal-to-noise finding.
  • Completed-spec guardrail: Related completed specs are context only and must not be edited.
  • Roadmap/product alignment: yes. This supports the current platform productization direction and closes a high-value governance operator surface gap.
  • Small, reviewable slice: yes. One existing detail page plus focused tests/smoke.
  • Deferred adjacent concerns: Backup Set, OperationRun View, Provider Connections, Diagnostics, and global UI rule pack remain follow-ups.
  • Result: PASS.

Constitution Check

  • Inventory-first, snapshots-second: PASS - the page continues to display existing Baseline Profile/Snapshot truth and does not fetch Graph data.
  • Read/write separation by default: PASS - no new mutation is introduced; existing capture/compare high-impact actions retain confirmation and authorization.
  • Single Contract Path to Graph: PASS - no Graph calls are introduced.
  • Deterministic Capabilities: PASS - existing WorkspaceUiEnforcement, capability resolvers, and policies remain the action truth.
  • Proportionality / Anti-bloat: PASS - no new persistence, status family, or cross-domain UI framework is planned.
  • Workspace isolation: PASS - Baseline Profile remains workspace-owned and workspace-scoped.
  • Tenant isolation: PASS - tenant/environment data appears only through existing assignments, snapshot links, and action targets.
  • RBAC-UX: PASS - UI state remains non-authoritative; server-side action authorization remains required.
  • UI-COV-001: PASS with required page-report/coverage update or explicit no-route-change rationale.
  • TEST-GOV-001: PASS with focused Feature/Browser lane classification.

Existing Repository Surfaces

  • apps/platform/app/Filament/Resources/BaselineProfileResource.php
    • Current infolist sections: Profile, Scope, Baseline truth, Related context, Metadata.
    • Existing helper methods already expose scope summary, support readiness, current snapshot, latest attempt, compare readiness, and next step.
    • protected static bool $isGloballySearchable = false; keep unchanged.
  • apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php
    • Header actions: capture, compare now, More group with compare assigned environments and edit.
    • Capture/compare use ->requiresConfirmation(), shared OperationRun feedback, and workspace capability enforcement.
  • Existing tests:
    • apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php
    • apps/platform/tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php
    • apps/platform/tests/Feature/Baselines/BaselineProfileAuthorizationTest.php
    • apps/platform/tests/Browser/Spec192RecordPageHeaderDisciplineSmokeTest.php
    • apps/platform/tests/Browser/Spec202GovernanceSubjectTaxonomySmokeTest.php
  • UI audit sources:
    • specs/368-platform-ui-signal-to-noise-browser-audit/*
    • docs/ui-ux-enterprise-audit/page-reports/ui-010-baseline-profiles.md
    • docs/ui-ux-enterprise-audit/route-inventory.md
    • docs/ui-ux-enterprise-audit/design-coverage-matrix.md

Technical Approach

  1. Verify the current Baseline Profile detail states that need to drive the decision summary:
    • active with consumable snapshot
    • active without consumable snapshot
    • draft/inactive/archived
    • invalid/unsupported/mixed governed-subject scope
    • assigned and unassigned environments
    • authorized and readonly actor states
  2. Introduce the smallest derived decision summary shape:
    • Prefer existing methods in BaselineProfileResource.
    • Add a page-local helper only if repeated inline TextEntry closures become hard to review.
    • Keep it derived-only and request-scoped.
  3. Recompose the infolist:
    • Add a decision-first section above Profile/Scope.
    • Move normalization lineage and technical metadata below the decision and proof sections.
    • Keep current snapshot/latest attempt/compare readiness and related context accessible.
  4. Preserve action safety:
    • Do not change capture/compare modal behavior except copy/hierarchy if required.
    • Keep confirmation, capability checks, notifications, OperationRun links, and browser events.
  5. Update focused tests and browser smoke:
    • Assert decision content is visible and technical content is secondary.
    • Assert readonly/owner action behavior remains stable.
    • Capture a bounded browser smoke screenshot for the improved detail page.
  6. Update UI audit coverage artifacts:
    • Update page report/coverage note for UI-057 detail work.
    • If route inventory counts are unchanged, document no route change rather than touching route count tables unnecessarily.

Domain / Model Implications

  • No model, migration, table, enum, persisted status, or source-of-truth change.
  • Baseline readiness remains derived from existing Baseline Profile/Snapshot/Assignment/Compare truth.
  • No data backfill or compatibility behavior is needed.

UI / Filament Implications

  • Filament v5 / Livewire v4.1.4 compliance is required.
  • Panel providers remain in apps/platform/bootstrap/providers.php; no provider registration change.
  • BaselineProfileResource global search stays disabled. It already has a View page and $recordTitleAttribute, but global search is intentionally off for this workspace-owned governance surface.
  • Detail page should use native Filament sections/infolist entries where possible.
  • Header action discipline remains: one state-sensitive primary action where possible, secondary actions in More or related context, dangerous/destructive actions confirmed.
  • No asset registration is expected; filament:assets is not newly required by this spec.

RBAC / Policy Implications

  • Workspace member access and baseline capabilities remain source of truth.
  • Non-member/wrong-workspace access stays deny-as-not-found.
  • Readonly members may view but not mutate according to existing tests.
  • High-impact actions must continue to enforce authorization server-side, not only through disabled UI state.

OperationRun / Observability Implications

  • Existing capture/compare actions continue to create/reuse OperationRun values through existing services.
  • Existing OperationUxPresenter, OperationRunLinks, and OpsUxBrowserEvents continue to own queued/already-queued feedback.
  • No new OperationRun type, lifecycle state, queued notification policy, or reconciliation behavior is introduced.

Audit / Evidence Implications

  • No new audit action is expected for pure page render changes.
  • Existing capture/compare/archive audit behavior must remain intact.
  • Current snapshot and compare matrix links remain evidence/proof navigation, not duplicated truth.

Test Strategy

  • Add or update Feature/Livewire tests for:
    • ready profile decision summary
    • blocked/no snapshot decision summary
    • invalid/unsupported scope decision summary
    • readonly/member action state
    • no raw scope JSON or normalization lineage in the primary decision summary
  • Preserve existing tests for:
    • capture start authorization and OperationRun feedback
    • compare start authorization and OperationRun feedback
    • Baseline Profile RBAC 404/403 behavior
    • record-page header discipline
  • Add bounded browser smoke if rendered hierarchy changes:
    • login/fixture using existing helpers
    • visit Baseline Profile detail
    • assert decision summary appears before technical lineage/metadata in visible page order
    • assert no JavaScript errors
    • save screenshot in specs/369-baseline-profile-decision-view/artifacts/screenshots/

Rollout / Deployment Considerations

  • Migrations: none expected.
  • Env vars: none expected.
  • Queues: no new queues or workers; existing capture/compare queue behavior unchanged.
  • Scheduler: none.
  • Storage/volumes: none.
  • Assets: no new Filament assets expected; no deploy-specific filament:assets change.
  • Staging/Production: Validate on staging with focused Baseline Profile view smoke before production promotion once production exists.

UI Audit Close-Out

  • Route/design coverage counts: no count change. Spec 369 recomposes the existing Baseline Profile detail view under the existing Filament resource route; it does not add, remove, or reclassify a route.
  • Design coverage matrix: no count change. UI-010 Baseline Profiles remains a Strategic Surface, with the detail-page hierarchy updated inside the existing coverage row.
  • Page report: docs/ui-ux-enterprise-audit/page-reports/ui-010-baseline-profiles.md records the decision-first detail update.
  • Screenshot evidence: specs/369-baseline-profile-decision-view/artifacts/screenshots/decision-first-detail.png.

Risk Controls

  • Stop implementation if improving the page requires new persistence, a new readiness enum, a generic UI framework, or broad baseline engine changes.
  • Preserve action names and tests unless a naming change is explicitly required by user-facing copy.
  • Keep browser fixture cost bounded; do not create a platform-wide fixture suite inside this spec.
  • Do not rewrite completed specs or Spec 368 audit history.

Implementation Phases

Phase 1 - Repo Truth And Test Baseline

Confirm existing Baseline Profile detail states, helpers, action safety, and current browser evidence. Add failing tests for the desired decision-first first viewport.

Phase 2 - Decision Summary Composition

Recompose the infolist to lead with readiness, reason, impact, snapshot basis, assignment signal, and next action. Demote technical scope/metadata.

Phase 3 - Action Safety And Coverage

Verify capture/compare/archive confirmations, authorization, OperationRun feedback, and global-search posture remain unchanged.

Phase 4 - Browser Smoke And UI Audit Close-Out

Capture before/after proof, update UI audit coverage notes, and record guardrail/smoke outcome.

Spec Readiness Gate

  • spec.md: present and scoped.
  • plan.md: present and repo-aware.
  • tasks.md: generated for later implementation.
  • RBAC, workspace isolation, OperationRun semantics, evidence truth, UI coverage, destructive/high-impact action handling, and test lanes are addressed.
  • No open question blocks safe implementation.
  • Scope is small enough for a bounded implementation loop.
  • Result: PASS after tasks/checklist generation and preparation analysis.