ahmido
a4f2629493
## Summary - add the tenant review domain with tenant-scoped review library, canonical workspace review register, lifecycle actions, and review-derived executive pack export - extend review pack, operations, audit, capability, and badge infrastructure to support review composition, publication, export, and recurring review cycles - add product backlog and audit documentation updates for tenant review and semantic-clarity follow-up candidates ## Testing - `vendor/bin/sail bin pint --dirty --format agent` - `vendor/bin/sail artisan test --compact --filter="TenantReview"` - `CI=1 vendor/bin/sail artisan test --compact` ## Notes - Livewire v4+ compliant via existing Filament v5 stack - panel providers remain in `bootstrap/providers.php` via existing Laravel 12 structure; no provider registration moved to `bootstrap/app.php` - `TenantReviewResource` is not globally searchable, so the Filament edit/view global-search constraint does not apply - destructive review actions use action handlers with confirmation and policy enforcement Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #185
245 lines
19 KiB
Markdown
245 lines
19 KiB
Markdown
# Tasks: Tenant Review Layer
|
|
|
|
**Input**: Design documents from `/specs/155-tenant-review-layer/`
|
|
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
|
|
|
|
**Tests**: For runtime behavior changes in this repo, tests are REQUIRED (Pest). Only docs-only changes may omit tests.
|
|
**Operations**: Review composition and executive-pack export reuse the canonical `OperationRun` flow. Publish and archive remain synchronous DB-backed mutations and must emit audit history.
|
|
**RBAC**: Tenant review detail/mutations run in the tenant/admin plane; the workspace review register runs in the workspace-admin canonical plane. Non-members or wrong-scope users must receive `404`; in-scope users lacking capability must receive `403`.
|
|
**UI Naming**: Primary operator-facing verbs remain `Create review`, `Refresh review`, `Publish review`, `Export executive pack`, and `Archive review`.
|
|
**Filament UI Action Surfaces**: Tenant review list/detail and workspace register must honor the spec action matrix, clickable inspection affordances, confirmation for destructive actions, and audit coverage for relevant mutations.
|
|
**Filament UI UX-001**: Create flows must keep inputs inside sections, detail must use an Infolist-style inspection surface, and empty states must provide exactly one CTA.
|
|
**Badges**: Review lifecycle state and completeness state must use `BadgeCatalog` / `BadgeRenderer` with mapping tests.
|
|
|
|
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Introduce the shared enums, capability vocabulary, and operation metadata that every review flow depends on.
|
|
|
|
- [X] T001 Add tenant review state enums and derived publication/export-readiness badge mappings in `app/Support/TenantReviewStatus.php`, `app/Support/TenantReviewCompletenessState.php`, `app/Support/Badges/Domains/TenantReviewStatusBadge.php`, `app/Support/Badges/Domains/TenantReviewCompletenessStateBadge.php`, and `app/Support/Badges/BadgeCatalog.php`
|
|
- [X] T002 [P] Register `tenant_review.view` and `tenant_review.manage` in `app/Support/Auth/Capabilities.php` and `app/Services/Auth/RoleCapabilityMap.php`
|
|
- [X] T003 [P] Reserve tenant-review operation metadata in `app/Support/OperationRunType.php`, `app/Support/OperationCatalog.php`, and `app/Services/SystemConsole/OperationRunTriageService.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Build the data model, policy enforcement, and composition services that block all user stories.
|
|
|
|
**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
|
|
|
|
- [X] T004 Create tenant review persistence schema in `database/migrations/2026_03_20_000000_create_tenant_reviews_table.php`, `database/migrations/2026_03_20_000100_create_tenant_review_sections_table.php`, and `database/migrations/2026_03_20_000200_add_tenant_review_id_to_review_packs_table.php`
|
|
- [X] T005 [P] Add review aggregate models and relationships in `app/Models/TenantReview.php`, `app/Models/TenantReviewSection.php`, `app/Models/ReviewPack.php`, `app/Models/EvidenceSnapshot.php`, and `app/Models/Tenant.php`
|
|
- [X] T006 [P] Enforce tenant review authorization in `app/Policies/TenantReviewPolicy.php` and `app/Providers/AuthServiceProvider.php`
|
|
- [X] T007 [P] Register tenant review ownership with workspace-isolation helpers in `app/Support/WorkspaceIsolation/TenantOwnedModelFamilies.php`
|
|
- [X] T008 Implement core review composition services in `app/Services/TenantReviews/TenantReviewService.php`, `app/Services/TenantReviews/TenantReviewComposer.php`, and `app/Services/TenantReviews/TenantReviewSectionFactory.php`
|
|
- [X] T009 Implement fingerprinting and readiness rules in `app/Services/TenantReviews/TenantReviewFingerprint.php` and `app/Services/TenantReviews/TenantReviewReadinessGate.php`
|
|
|
|
**Checkpoint**: Foundation ready. User story work can now proceed.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Prepare one tenant review from curated evidence (Priority: P1)
|
|
|
|
**Goal**: Allow an entitled operator to create and inspect a tenant review anchored to one chosen evidence snapshot, with explicit completeness and immutable evidence-basis semantics.
|
|
|
|
**Independent Test**: Create a review from an eligible evidence snapshot, verify the review stores the anchored evidence basis and section completeness, then change live source data and confirm the review remains tied to its original basis until explicitly refreshed.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T010 [P] [US1] Add anchored-review creation coverage in `tests/Feature/TenantReview/TenantReviewCreationTest.php`
|
|
- [X] T011 [P] [US1] Add review composition and badge mapping coverage in `tests/Unit/TenantReview/TenantReviewComposerTest.php` and `tests/Unit/TenantReview/TenantReviewBadgeTest.php`
|
|
- [X] T012 [P] [US1] Add compose-run Ops-UX regression coverage in `tests/Feature/TenantReview/TenantReviewOperationsUxTest.php`
|
|
- [X] T013 [P] [US1] Add tenant-scope authorization coverage for create, view, and refresh in `tests/Feature/TenantReview/TenantReviewRbacTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T014 [US1] Implement create and refresh orchestration with immutable evidence anchoring in `app/Services/TenantReviews/TenantReviewService.php`, `app/Services/TenantReviews/TenantReviewComposer.php`, and `app/Jobs/ComposeTenantReviewJob.php`
|
|
- [X] T015 [US1] Create the tenant-scoped Filament resource and list/detail pages in `app/Filament/Resources/TenantReviewResource.php`, `app/Filament/Resources/TenantReviewResource/Pages/ListTenantReviews.php`, and `app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php`
|
|
- [X] T016 [US1] Build the review detail infolist, section completeness rendering, and evidence drill-down links in `app/Filament/Resources/TenantReviewResource.php`
|
|
- [X] T017 [US1] Implement the `Create review` modal, `Refresh review` action, row inspection affordance, and tenant-library empty state in `app/Filament/Resources/TenantReviewResource/Pages/ListTenantReviews.php` and `app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php`
|
|
- [X] T018 [US1] Wire review composition runs to canonical operations UX in `app/Jobs/ComposeTenantReviewJob.php`, `app/Services/OperationRunService.php`, `app/Support/OpsUx/OperationUxPresenter.php`, and `app/Notifications/OperationRunCompleted.php`
|
|
- [X] T019 [US1] Record create and refresh audit events plus stored evidence-basis metadata in `app/Services/TenantReviews/TenantReviewService.php` and `app/Models/TenantReview.php`
|
|
|
|
**Checkpoint**: User Story 1 is independently functional when a tenant review can be created, inspected, refreshed, and audited without leaking live-source changes into the anchored review.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Present an executive-ready tenant review pack (Priority: P1)
|
|
|
|
**Goal**: Present a stakeholder-ready review detail and exportable executive pack derived from the prepared tenant review, with clear readiness gates and immutable published history.
|
|
|
|
**Independent Test**: Open a prepared tenant review, verify the executive sections and disclosures, publish the review, export the executive pack, and confirm the exported artifact matches the same section ordering and summary truth shown in the product.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T020 [P] [US2] Add executive detail and pack-consistency coverage in `tests/Feature/TenantReview/TenantReviewExecutivePackTest.php`
|
|
- [X] T021 [P] [US2] Add publish, archive, and readiness-gate coverage in `tests/Feature/TenantReview/TenantReviewLifecycleTest.php`
|
|
- [X] T022 [P] [US2] Add review-derived export integration coverage in `tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php`
|
|
- [X] T023 [P] [US2] Add export-run Ops-UX guard coverage for lifecycle ownership, summary counts, and terminal notifications in `tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T024 [US2] Implement publish, archive, successor, and duplicate-prevention lifecycle rules in `app/Services/TenantReviews/TenantReviewLifecycleService.php`, `app/Services/TenantReviews/TenantReviewReadinessGate.php`, and `app/Models/TenantReview.php`
|
|
- [X] T025 [P] [US2] Extend review-derived review-pack generation and download flow in `app/Services/ReviewPackService.php`, `app/Jobs/GenerateReviewPackJob.php`, `app/Http/Controllers/ReviewPackDownloadController.php`, and `app/Models/ReviewPack.php`
|
|
- [X] T026 [P] [US2] Add executive summary, disclosure sections, and detail-page header actions in `app/Filament/Resources/TenantReviewResource.php` and `app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php`
|
|
- [X] T027 [US2] Reuse canonical export-run messaging, monitoring links, and summary-count keys for `Export executive pack` in `app/Support/OperationCatalog.php`, `app/Support/OpsUx/OperationUxPresenter.php`, `app/Support/OpsUx/OperationSummaryKeys.php`, and `app/Services/SystemConsole/OperationRunTriageService.php`
|
|
- [X] T028 [US2] Record publish, archive, and export audit history with aligned operator-facing copy in `app/Services/TenantReviews/TenantReviewLifecycleService.php` and `app/Services/ReviewPackService.php`
|
|
- [X] T029 [US2] Surface review-derived export metadata and navigation in `app/Filament/Widgets/Tenant/TenantReviewPackCard.php` and `app/Filament/Resources/ReviewPackResource.php`
|
|
|
|
**Checkpoint**: User Story 2 is independently functional when an operator can inspect a stakeholder-ready review, publish it safely, and export a matching executive pack with readiness failures explained clearly.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Manage recurring tenant reviews over time (Priority: P2)
|
|
|
|
**Goal**: Provide a canonical workspace review register and recurring-cycle workflow that shows only entitled tenants while preserving published review history.
|
|
|
|
**Independent Test**: Create reviews for multiple tenants, open the workspace register, confirm only entitled tenants appear with correct lifecycle and recency signals, then start a new cycle from a published review and verify a successor draft is created instead of mutating history.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T030 [P] [US3] Add workspace review register filtering, positive visibility, and empty-state coverage in `tests/Feature/TenantReview/TenantReviewRegisterTest.php`
|
|
- [X] T031 [P] [US3] Add tenant-context prefilter and authorized filter-option scoping coverage in `tests/Feature/TenantReview/TenantReviewRegisterPrefilterTest.php`
|
|
- [X] T032 [P] [US3] Add canonical register deny-as-not-found and capability coverage in `tests/Feature/TenantReview/TenantReviewRegisterRbacTest.php`
|
|
- [X] T033 [P] [US3] Add successor-cycle history coverage in `tests/Feature/TenantReview/TenantReviewCycleTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T034 [US3] Implement workspace-scoped register queries, entitled-tenant filtering, and tenant-context prefilter initialization in `app/Services/TenantReviews/TenantReviewRegisterService.php` and `app/Models/TenantReview.php`
|
|
- [X] T035 [P] [US3] Create the canonical workspace review register page in `app/Filament/Pages/Reviews/ReviewRegister.php`
|
|
- [X] T036 [P] [US3] Register tenant-review navigation and page discovery in `app/Providers/Filament/TenantPanelProvider.php` and `app/Providers/Filament/AdminPanelProvider.php`
|
|
- [X] T037 [US3] Implement register table filters, authorized filter-option scoping, row navigation, and one-CTA empty-state behavior in `app/Filament/Pages/Reviews/ReviewRegister.php`
|
|
- [X] T038 [US3] Add `Create next review` successor flow on published reviews in `app/Services/TenantReviews/TenantReviewLifecycleService.php` and `app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php`
|
|
|
|
**Checkpoint**: User Story 3 is independently functional when the workspace register safely lists entitled tenant reviews and operators can start the next cycle without mutating published history.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final hardening, performance, and verification across all stories.
|
|
|
|
- [X] T039 [P] Add global-search and record-title decisions for tenant reviews in `app/Filament/Resources/TenantReviewResource.php` and `app/Models/TenantReview.php`
|
|
- [X] T040 [P] Add cross-story audit-log and UI-contract regression coverage in `tests/Feature/TenantReview/TenantReviewAuditLogTest.php` and `tests/Feature/TenantReview/TenantReviewUiContractTest.php`
|
|
- [X] T041 Harden eager loading, list performance, and review-pack query paths in `app/Services/TenantReviews/TenantReviewRegisterService.php`, `app/Filament/Resources/TenantReviewResource.php`, and `app/Jobs/GenerateReviewPackJob.php`
|
|
- [X] T042 Run the feature validation scenarios in `specs/155-tenant-review-layer/quickstart.md`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies; can start immediately.
|
|
- **Foundational (Phase 2)**: Depends on Phase 1; blocks all user stories.
|
|
- **User Story 1 (Phase 3)**: Depends on Phase 2 only.
|
|
- **User Story 2 (Phase 4)**: Depends on Phase 2 and consumes the review aggregate delivered in User Story 1.
|
|
- **User Story 3 (Phase 5)**: Depends on Phase 2 and should land after User Story 1 because it surfaces recurring-cycle state from real review records.
|
|
- **Polish (Phase 6)**: Depends on all desired stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **US1**: Starts after Foundational; no dependency on other stories.
|
|
- **US2**: Starts after Foundational but is most valuable once US1 review creation/detail is working.
|
|
- **US3**: Starts after Foundational but depends on existing review records from US1 for meaningful validation.
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests must be written first and fail before implementation.
|
|
- Models/services before Filament surfaces where practical.
|
|
- Operation-run wiring before exposing async actions broadly.
|
|
- Audit and authorization coverage must ship with each mutation workflow.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- `T002` and `T003` can run in parallel after `T001`.
|
|
- `T005`, `T006`, and `T007` can run in parallel after `T004`.
|
|
- In US1, `T010` through `T013` can run in parallel.
|
|
- In US2, `T020` through `T023` can run in parallel, and `T025` plus `T026` can run in parallel after `T024`.
|
|
- In US3, `T030` through `T033` can run in parallel, and `T035` plus `T036` can run in parallel after `T034`.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Launch the US1 tests together:
|
|
Task: "Add anchored-review creation coverage in tests/Feature/TenantReview/TenantReviewCreationTest.php"
|
|
Task: "Add review composition and badge mapping coverage in tests/Unit/TenantReview/TenantReviewComposerTest.php and tests/Unit/TenantReview/TenantReviewBadgeTest.php"
|
|
Task: "Add compose-run Ops-UX regression coverage in tests/Feature/TenantReview/TenantReviewOperationsUxTest.php"
|
|
Task: "Add tenant-scope authorization coverage for create, view, and refresh in tests/Feature/TenantReview/TenantReviewRbacTest.php"
|
|
|
|
# Build the tenant review Filament surface in parallel after orchestration exists:
|
|
Task: "Create the tenant-scoped Filament resource and list/detail pages in app/Filament/Resources/TenantReviewResource.php, app/Filament/Resources/TenantReviewResource/Pages/ListTenantReviews.php, and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php"
|
|
Task: "Build the review detail infolist, section completeness rendering, and evidence drill-down links in app/Filament/Resources/TenantReviewResource.php"
|
|
```
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Launch the US2 tests together:
|
|
Task: "Add executive detail and pack-consistency coverage in tests/Feature/TenantReview/TenantReviewExecutivePackTest.php"
|
|
Task: "Add publish, archive, and readiness-gate coverage in tests/Feature/TenantReview/TenantReviewLifecycleTest.php"
|
|
Task: "Add review-derived export integration coverage in tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php"
|
|
Task: "Add export-run Ops-UX guard coverage for lifecycle ownership, summary counts, and terminal notifications in tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php"
|
|
|
|
# Implement export surfaces in parallel after lifecycle rules exist:
|
|
Task: "Extend review-derived review-pack generation and download flow in app/Services/ReviewPackService.php, app/Jobs/GenerateReviewPackJob.php, app/Http/Controllers/ReviewPackDownloadController.php, and app/Models/ReviewPack.php"
|
|
Task: "Add executive summary, disclosure sections, and detail-page header actions in app/Filament/Resources/TenantReviewResource.php and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php"
|
|
```
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Launch the US3 tests together:
|
|
Task: "Add workspace review register filtering, positive visibility, and empty-state coverage in tests/Feature/TenantReview/TenantReviewRegisterTest.php"
|
|
Task: "Add tenant-context prefilter and authorized filter-option scoping coverage in tests/Feature/TenantReview/TenantReviewRegisterPrefilterTest.php"
|
|
Task: "Add canonical register deny-as-not-found and capability coverage in tests/Feature/TenantReview/TenantReviewRegisterRbacTest.php"
|
|
Task: "Add successor-cycle history coverage in tests/Feature/TenantReview/TenantReviewCycleTest.php"
|
|
|
|
# Build the canonical register in parallel after register queries exist:
|
|
Task: "Create the canonical workspace review register page in app/Filament/Pages/Reviews/ReviewRegister.php"
|
|
Task: "Register tenant-review navigation and page discovery in app/Providers/Filament/TenantPanelProvider.php and app/Providers/Filament/AdminPanelProvider.php"
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete Phase 1: Setup.
|
|
2. Complete Phase 2: Foundational.
|
|
3. Complete Phase 3: User Story 1.
|
|
4. Validate anchored review creation, completeness rendering, RBAC, and audit history.
|
|
5. Demo tenant review creation/detail before layering exports or workspace register views.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Finish Setup + Foundational to establish the review aggregate.
|
|
2. Deliver US1 for review creation and anchored inspection.
|
|
3. Deliver US2 for publication and executive-pack export.
|
|
4. Deliver US3 for recurring-cycle management and canonical register visibility.
|
|
5. Finish with polish, performance, and regression hardening.
|
|
|
|
### Parallel Team Strategy
|
|
|
|
1. One developer handles persistence/policies/services in Phases 1-2.
|
|
2. After Phase 2, one developer can take US1 Filament surfaces while another prepares US2 export integration tests.
|
|
3. Once US1 data flows exist, a third developer can build US3 register surfaces and RBAC coverage.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- `[P]` tasks touch different files and can run in parallel once their dependencies are complete.
|
|
- `[US1]`, `[US2]`, and `[US3]` map directly to the user stories in `spec.md`.
|
|
- Global search should only remain enabled if `TenantReviewResource` keeps a `View` page; otherwise disable it explicitly.
|
|
- Filament v5 work here remains compatible with Livewire v4, and panel-provider changes belong in `bootstrap/providers.php` only if a new provider is introduced. This feature reuses the existing panel providers.
|