ahmido
c0f4587d90
## Summary - standardize the shared verification report family across operation detail, onboarding, and tenant verification widget hosts - standardize normalized settings and normalized diff family wrappers across policy, policy version, and finding detail hosts - add parity and guard coverage plus the full Spec 197 artifacts, including recorded manual smoke evidence ## Testing - focused Sail regression pack from `specs/197-shared-detail-contract/quickstart.md` - local integrated-browser manual smoke for SC-197-003 and SC-197-004 Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #237
110 lines
6.4 KiB
Markdown
110 lines
6.4 KiB
Markdown
# Quickstart: Shared Detail Micro-UI Contract
|
||
|
||
## Goal
|
||
|
||
Validate that the same verification and normalized detail concepts now render through family-owned contracts across their covered hosts, without adding persistence, Graph calls, or a generic UI framework.
|
||
|
||
## Prerequisites
|
||
|
||
1. Start Sail.
|
||
2. Ensure you have a tenant with at least one completed verification run and one onboarding session that can resume on the verify step.
|
||
3. Ensure you have policy and policy-version data that exercises both settings-catalog and standard-settings rendering.
|
||
4. Ensure you have at least one drift finding with an available normalized diff and one drift finding with missing version references.
|
||
5. Ensure the current user can open the covered hosts in tenant and workspace-safe contexts.
|
||
|
||
## Implementation Validation Order
|
||
|
||
### 1. Run verification-family regression coverage
|
||
|
||
```bash
|
||
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
|
||
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Verification/VerificationReportViewerDbOnlyTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantVerificationReportWidgetTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/MonitoringOperationsTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Spec085/DenyAsNotFoundSemanticsTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingDraftAccessTest.php
|
||
./vendor/bin/sail artisan test --compact --filter=SharedVerificationReportFamilyContract
|
||
```
|
||
|
||
Expected outcome:
|
||
|
||
- Operation detail, onboarding, and tenant widget all expose the same verification-family core.
|
||
- Verification rendering stays DB-only and does not dispatch outbound work.
|
||
- Onboarding-only assist and acknowledge actions remain available as bounded host variations.
|
||
- Workspace-context and tenant-context verification hosts keep deny-as-not-found and capability-safe behavior after the shared viewer refactor.
|
||
|
||
### 2. Run normalized detail-family regression coverage
|
||
|
||
```bash
|
||
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
|
||
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Filament/PolicyVersionSettingsTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Filament/SettingsCatalogPolicyNormalizedDiffTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Filament/GroupPolicyConfigurationNormalizedDiffTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Drift/DriftFindingDiffUnavailableTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Filament/PolicyResourceAdminTenantParityTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Filament/PolicyVersionAdminTenantParityTest.php
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingRbacTest.php
|
||
./vendor/bin/sail artisan test --compact --filter=NormalizedDetailFamilyContract
|
||
```
|
||
|
||
Expected outcome:
|
||
|
||
- Policy and policy-version settings use the same family-owned wrapper with explicit subtype behavior.
|
||
- Policy-version diff and finding diff use the same normalized diff family semantics for available, unavailable, and zero-diff cases.
|
||
- No host still relies on a sibling top-level settings view or a host-only diff unavailable message for the same concept.
|
||
- Tenant-scoped policy, policy-version, and finding detail hosts preserve existing deny-as-not-found and capability semantics.
|
||
|
||
### 3. Run the fork guard and targeted parity checks
|
||
|
||
```bash
|
||
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
|
||
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform
|
||
./vendor/bin/sail artisan test --compact tests/Feature/Guards/SharedDetailFamilyContractGuardTest.php
|
||
./vendor/bin/sail artisan test --compact --filter=FamilyContract
|
||
```
|
||
|
||
Expected outcome:
|
||
|
||
- Guard coverage blocks reintroduction of direct host forks.
|
||
- Parity tests prove the same family zones and the same unavailable-state semantics across hosts.
|
||
|
||
### 4. Format touched files
|
||
|
||
```bash
|
||
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
|
||
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas/apps/platform
|
||
./vendor/bin/sail bin pint --dirty --format agent
|
||
```
|
||
|
||
Expected outcome:
|
||
|
||
- All touched PHP files conform to the repo’s Pint rules.
|
||
|
||
## Manual Smoke Check
|
||
|
||
1. Open the operation run detail that shows a verification report and confirm you can immediately identify summary, issues, passed, and technical details zones.
|
||
2. Open the onboarding wizard verify step for the same or equivalent verification payload and confirm the same core verification surface appears, with onboarding-only assist or acknowledge behavior layered on top instead of a different tab model.
|
||
3. Open the tenant verification widget and confirm the completed-state core matches the other verification hosts while no-run and in-progress framing stays widget-specific.
|
||
4. Open a policy-version detail view and a policy detail view that both show normalized settings and confirm warnings, empty-state behavior, and subtype structure feel like one family.
|
||
5. Open a policy-version detail view that shows normalized diff and confirm summary, grouped sections, and availability messaging match the same shared diff-family contract used elsewhere.
|
||
6. Open a drift finding with missing referenced versions and confirm the diff area uses a family-consistent unavailable state.
|
||
7. Open a drift finding with an available normalized diff and confirm the grouped diff surface feels like the same family as policy-version diff, not a new host-specific micro-app.
|
||
|
||
## Release Acceptance Recording
|
||
|
||
1. Update `specs/197-shared-detail-contract/migration-note.md` with the migrated hosts actually touched by the implementation.
|
||
2. Record the consciously allowed remaining variations that still differ by host.
|
||
3. Capture reviewer, review date, and pass or fail notes for SC-197-003 and SC-197-004 in the migration note.
|
||
4. Record any shell, monitoring-state, or other intentionally out-of-scope follow-ups in the migration note instead of expanding this feature silently.
|
||
|
||
## Non-Goals For This Slice
|
||
|
||
- No database migration.
|
||
- No new public API.
|
||
- No new Graph call path or `OperationRun` lifecycle change.
|
||
- No new Filament asset registration or `filament:assets` deployment change.
|
||
- No shell, workspace context bar, or monitoring page-state refactor. |