81 lines
4.5 KiB
Markdown
81 lines
4.5 KiB
Markdown
# Quickstart: Tenant Governance Aggregate Contract
|
||
|
||
## Goal
|
||
|
||
Validate that one derived tenant-governance aggregate now drives the shared summary posture across the tenant dashboard, the tenant governance banner, and the Baseline Compare landing without adding persistence or reintroducing local findings-count ownership.
|
||
|
||
## Prerequisites
|
||
|
||
1. Start Sail.
|
||
2. Ensure a tenant exists with an assigned baseline profile and a consumable snapshot.
|
||
3. Seed compare-run scenarios for: no result yet, compare in progress, compare failed, trustworthy no-drift, stale no-drift, overdue findings without new drift, and lapsed governance without new drift.
|
||
4. Ensure the current user is a tenant member with access to the tenant dashboard and Baseline Compare landing.
|
||
|
||
## Implementation Validation Order
|
||
|
||
### 1. Run low-level compare and aggregate coverage
|
||
|
||
```bash
|
||
vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareStatsTest.php
|
||
vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareSummaryAssessmentTest.php
|
||
vendor/bin/sail artisan test --compact --filter=TenantGovernanceAggregate
|
||
```
|
||
|
||
Expected outcome:
|
||
- Existing compare truth still resolves the same availability and posture states.
|
||
- The new aggregate contract maps those states into one stable summary object without introducing a second query-backed truth path.
|
||
|
||
### 2. Run focused cross-surface parity coverage
|
||
|
||
```bash
|
||
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php
|
||
vendor/bin/sail artisan test --compact tests/Feature/Filament/NeedsAttentionWidgetTest.php
|
||
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareNowWidgetTest.php
|
||
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareCoverageBannerTest.php
|
||
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php
|
||
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingDuplicateNamesBannerTest.php
|
||
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingRbacLabelsTest.php
|
||
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
|
||
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php
|
||
```
|
||
|
||
Expected outcome:
|
||
- `NeedsAttention`, `BaselineCompareNow`, `BaselineCompareCoverageBanner`, and the landing summary agree on posture family, headline, and next-action intent for the same tenant state.
|
||
- A tenant with zero visible drift but overdue or unhealthy governance still renders as action-needed on every covered surface.
|
||
- The landing keeps `Compare now` confirmation and capability gating unchanged, and diagnostics remain clearly secondary to the shared summary posture.
|
||
|
||
### 3. Run request-local reuse and guard coverage
|
||
|
||
```bash
|
||
vendor/bin/sail artisan test --compact --filter=TenantGovernanceAggregateMemoization
|
||
vendor/bin/sail artisan test --compact tests/Feature/Guards/DerivedStateConsumerAdoptionGuardTest.php
|
||
```
|
||
|
||
Expected outcome:
|
||
- One request stores one governance aggregate per tenant scope.
|
||
- Covered surfaces do not fall back to widget-local ad hoc caches or repeated local findings queries.
|
||
|
||
### 4. Format touched implementation files
|
||
|
||
```bash
|
||
vendor/bin/sail bin pint --dirty --format agent
|
||
```
|
||
|
||
Expected outcome:
|
||
- All touched implementation files conform to the repo’s Pint rules.
|
||
|
||
## Manual Smoke Check
|
||
|
||
1. Open `/admin/t/{tenant}` for a tenant with lapsed governance and no new drift findings.
|
||
2. Confirm the dashboard `Needs Attention` widget and `Baseline Governance` card both show action-needed posture.
|
||
3. Open `/admin/t/{tenant}/baseline-compare-landing` and confirm the landing summary agrees with the dashboard posture while still showing deeper diagnostics below.
|
||
4. Use a tenant with a trustworthy no-drift result and confirm the banner hides, the dashboard falls back to healthy checks, and the landing summary presents the same all-clear posture.
|
||
5. Use a tenant with a queued or running compare and confirm dashboard, banner, and landing all present progress-aware follow-up instead of stale “all clear” messaging.
|
||
6. Switch from one tenant to another and confirm the second tenant does not reuse the first tenant’s summary posture.
|
||
|
||
## Non-Goals For This Slice
|
||
|
||
- No database migration.
|
||
- No new Graph call or provider-contract work.
|
||
- No new assets or Filament panel registration change.
|
||
- No new mutation surface beyond the existing `Compare now` action, which remains unchanged. |