ahmido
2f45ff5a84
## Summary - add tenant triage review-state persistence, fingerprinting, resolver logic, service layer, and migration for current affected-set tracking - surface review-state and affected-set progress across tenant registry, tenant dashboard arrival continuity, and workspace overview - extend RBAC, audit/badge support, specs, and test coverage for portfolio triage review-state workflows - suppress expected hidden-page background transport failures in the global unhandled rejection logger while keeping visible-page failures logged ## Validation - targeted Pest coverage added for tenant registry, workspace overview, arrival context, RBAC authorization, badges, fingerprinting, resolver behavior, and logger asset behavior - code formatted with `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` ## Notes - full suite was not re-run in this final step - branch includes the spec artifacts under `specs/189-portfolio-triage-review-state/` Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #220
84 lines
6.0 KiB
Markdown
84 lines
6.0 KiB
Markdown
# Quickstart: Portfolio Triage Review State and Operator Progress
|
|
|
|
## Goal
|
|
|
|
Implement one lightweight, workspace-shared triage-review state so operators can mark current concerns as reviewed or follow-up needed, see changed-since-review detection, and track current affected-set progress without changing posture truth or reusing formal review artifacts.
|
|
|
|
## Implementation Sequence
|
|
|
|
1. Add the persisted triage-review core.
|
|
- Create the `tenant_triage_reviews` migration.
|
|
- Add `TenantTriageReview` and `TenantTriageReviewFactory`.
|
|
- Add the minimal stored-state enum or cast for `reviewed` and `follow_up_needed` only.
|
|
|
|
2. Add deterministic fingerprinting and batch state resolution.
|
|
- Create `TenantTriageReviewFingerprint` under `apps/platform/app/Support/PortfolioTriage/`.
|
|
- Create `TenantTriageReviewStateResolver` that batch-loads active rows for a visible tenant set and combines them with existing backup-health and recovery-evidence truth.
|
|
- Keep `not_reviewed` and `changed_since_review` derived only.
|
|
|
|
3. Add one canonical mutation path.
|
|
- Create `TenantTriageReviewService` for `markReviewed()` and `markFollowUpNeeded()`.
|
|
- Add one capability constant to `Capabilities` and enforce it through `UiEnforcement` plus server-side authorization.
|
|
- Add bounded `AuditActionId` values and record lightweight audit entries through `AuditRecorder`.
|
|
- Require a bounded pre-execution preview plus explicit confirmation on dashboard and registry review-state actions before the write executes.
|
|
|
|
4. Bind the new state into existing operator surfaces.
|
|
- Extend `WorkspaceOverviewBuilder`, `WorkspaceSummaryStats`, and `WorkspaceNeedsAttention` to show current-set progress counts.
|
|
- Extend `TenantResource` and `ListTenants` with a review-state column, all four review-state filters, mixed-family selection driven by the existing worst-first concern priority rules, and overflow actions.
|
|
- Extend `TenantTriageArrivalContinuity` and `TenantDashboard` so triage-arrival sessions can mark reviewed or follow-up needed inline after preview-and-confirmation, while generic tenant browsing suppresses queue-like review-state actions.
|
|
- Add one new badge domain or mapper for centralized review-state labels.
|
|
|
|
5. Add regression coverage.
|
|
- Add fingerprint and resolver unit tests.
|
|
- Add registry rendering, filtering, and action tests.
|
|
- Add tenant-dashboard arrival-action tests.
|
|
- Add workspace-overview progress-count tests.
|
|
- Add RBAC view-versus-mutate tests.
|
|
|
|
## Suggested Test Files
|
|
|
|
- `apps/platform/tests/Unit/Support/PortfolioTriage/TenantTriageReviewFingerprintTest.php`
|
|
- `apps/platform/tests/Unit/Support/PortfolioTriage/TenantTriageReviewStateResolverTest.php`
|
|
- `apps/platform/tests/Feature/Filament/TenantRegistryTriageReviewStateTest.php`
|
|
- `apps/platform/tests/Feature/Filament/TenantDashboardArrivalContextTest.php`
|
|
- `apps/platform/tests/Feature/Filament/WorkspaceOverviewTriageReviewProgressTest.php`
|
|
- `apps/platform/tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php`
|
|
- `apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php`
|
|
|
|
## Existing Suites To Extend Or Keep Green
|
|
|
|
- `apps/platform/tests/Feature/Concerns/BuildsPortfolioTriageFixtures.php`
|
|
- `apps/platform/tests/Feature/Filament/TenantRegistryRecoveryTriageTest.php`
|
|
- `apps/platform/tests/Feature/Filament/TenantDashboardArrivalContextTest.php`
|
|
|
|
## Minimum Verification Commands
|
|
|
|
Run all commands through Sail from `apps/platform`.
|
|
|
|
```bash
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/PortfolioTriage/TenantTriageReviewFingerprintTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/PortfolioTriage/TenantTriageReviewStateResolverTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantRegistryTriageReviewStateTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardArrivalContextTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewTriageReviewProgressTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantRegistryRecoveryTriageTest.php
|
|
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
|
|
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
|
|
```
|
|
|
|
## Manual Acceptance Checklist
|
|
|
|
1. Open a tenant from a backup-health triage slice, trigger `Mark reviewed`, and confirm the preview shows concern family, current review state, target state, and `TenantPilot only` scope before the registry shows `Reviewed` while backup posture remains unchanged.
|
|
2. Open a tenant from a recovery-evidence triage slice, trigger `Mark follow-up needed`, confirm the preview, and verify the workspace progress summary increments the correct bucket.
|
|
3. Change the underlying concern truth for a previously reviewed tenant and confirm the UI shows `Changed since review` instead of the prior manual state.
|
|
4. Open the registry in a mixed-family slice and confirm the review-state badge names the selected concern family and follows the existing worst-first concern priority rules.
|
|
5. Exercise all four registry review-state filters (`not_reviewed`, `reviewed`, `follow_up_needed`, `changed_since_review`) and confirm each filter only returns the current visible affected tenants in that bucket.
|
|
6. Open a tenant directly without portfolio-triage context and confirm no triage-review actions or queue-like review-state progress copy appears.
|
|
7. Use a viewer without mutation capability and confirm review-state truth stays visible while mutation actions are disabled or fail with `403`.
|
|
|
|
## Deployment Notes
|
|
|
|
- One migration is required for `tenant_triage_reviews`.
|
|
- No new assets are expected.
|
|
- No `OperationRun` orchestration or `filament:assets` changes are required beyond the repo's normal deployment process. |