ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
f52d52540c
TenantAtlas/specs/177-inventory-coverage-truth/tasks.md
ahmido f52d52540c feat: implement inventory coverage truth (#208) 
## Summary
- implement Spec 177 inventory coverage truth across resolver, badges, KPIs, coverage page, and operation run detail surfaces
- add repo-native spec artifacts for the feature under `specs/177-inventory-coverage-truth`
- add unit, feature, and browser coverage for truth derivation, continuity, and inventory item filter/pagination smoke paths

## Testing
- `vendor/bin/sail bin pint --dirty --format agent`
- focused Spec 177 browser smoke file passed with 2 tests / 57 assertions
- extended inventory-focused test pack passed with 52 tests / 434 assertions

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #208
2026-04-05 12:35:20 +00:00

18 KiB
Raw Blame History

Tasks: Inventory Coverage Truth

Input: Design documents from /specs/177-inventory-coverage-truth/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Required. Use Pest coverage in tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php, tests/Unit/Badges/BadgeCatalogTest.php, tests/Unit/Badges/InventoryCoverageStateBadgesTest.php, tests/Feature/Filament/InventoryCoverageTableTest.php, tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php, tests/Feature/Filament/InventoryPagesTest.php, tests/Feature/Filament/InventoryItemResourceTest.php, tests/Feature/Filament/InventoryCoverageRunContinuityTest.php, tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php, tests/Feature/Inventory/InventorySyncServiceTest.php, tests/Feature/Inventory/InventorySyncStartSurfaceTest.php, tests/Feature/Inventory/RunInventorySyncJobTest.php, tests/Feature/Operations/TenantlessOperationRunViewerTest.php, and tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php. Operations: This feature reuses the existing inventory_sync OperationRun and does not introduce a new run type or change lifecycle ownership. Tasks must keep canonical run links and read-time rendering aligned without changing queued execution semantics. RBAC: Existing workspace membership, tenant entitlement, and 404 vs 403 semantics remain authoritative. Tasks must preserve tenant-safe rendering and ensure basis-run links degrade safely when the current user cannot open the run. Operator Surfaces: The inventory items list KPI header, the inventory coverage page, and canonical inventory-sync run detail must become tenant-coverage-first while keeping low-level diagnostics secondary. Filament UI Action Surfaces: No new destructive actions or new action inventories are added. The existing Run Inventory Sync header action remains capability-gated and non-destructive, and the InventoryCoverage page keeps its derived-row no-detail exception. Filament UI UX-001: No new create or edit screens are introduced. The inventory coverage page remains a searchable, filterable table with a single clear empty-state CTA, and run detail remains an enterprise-detail view surface. Badges: Coverage-state semantics must stay centralized through BadgeDomain, BadgeCatalog, and BadgeRenderer; no page-local badge mappings are allowed.

Organization: Tasks are grouped by user story so each story can be implemented and validated as an independent increment once the shared tenant coverage contract is in place.

Phase 1: Setup (Shared Coverage Truth Scaffolding)

Purpose: Create the narrow runtime and regression entry points required for tenant coverage truth.

  • T001 [P] Create the derived tenant coverage truth scaffolding in app/Support/Inventory/TenantCoverageTruth.php and app/Support/Inventory/TenantCoverageTruthResolver.php
  • T002 [P] Create the focused regression scaffolding in tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php, tests/Unit/Badges/InventoryCoverageStateBadgesTest.php, and tests/Feature/Filament/InventoryCoverageRunContinuityTest.php

Phase 2: Foundational (Blocking Coverage Contract)

Purpose: Build the shared derived coverage contract, basis-run selection, and centralized badge semantics that all user stories depend on.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

  • T003 [P] Extend basis-run and mixed-outcome payload coverage assertions in tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php and tests/Feature/Inventory/RunInventorySyncJobTest.php
  • T004 [P] Add centralized inventory coverage badge mapping assertions in tests/Unit/Badges/BadgeCatalogTest.php and tests/Unit/Badges/InventoryCoverageStateBadgesTest.php
  • T005 [P] Implement the latest completed coverage-bearing inventory-sync selection helper in app/Models/OperationRun.php
  • T006 [P] Implement the derived runtime fields and row contract in app/Support/Inventory/TenantCoverageTruth.php
  • T007 Implement tenant coverage resolution, item-count joins, follow-up classification, and basis-run metadata in app/Support/Inventory/TenantCoverageTruthResolver.php
  • T008 Implement the centralized inventory coverage state badge domain and mapper in app/Support/Badges/BadgeDomain.php, app/Support/Badges/BadgeCatalog.php, and app/Support/Badges/Domains/InventoryCoverageStateBadge.php

Checkpoint: A single derived tenant coverage contract now exists for all supported types, with centralized badge semantics and deterministic basis-run selection.

Phase 3: User Story 1 - Read Truthful Coverage At A Glance (Priority: P1) 🎯 MVP

Goal: Make the inventory KPI header and coverage page answer the tenant coverage question directly instead of implying completeness from restorable-item share or support metadata.

Independent Test: Seed a tenant with a coverage-bearing inventory-sync run that includes succeeded, failed, skipped, and omitted types plus current inventory items, then verify the inventory items list and coverage page show truthful counts, Unknown rows, and follow-up emphasis.

Tests for User Story 1

  • T009 [P] [US1] Rewrite summary-surface expectations for truthful count-based coverage on the inventory items list in tests/Feature/Filament/InventoryPagesTest.php and tests/Feature/Filament/InventoryItemResourceTest.php
  • T010 [P] [US1] Add coverage-table assertions for Succeeded, Failed, Skipped, Unknown, deterministic follow-up priority, no-basis-run messaging, and secondary support, restore, and compare metadata in tests/Feature/Filament/InventoryCoverageTableTest.php and tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php

Implementation for User Story 1

  • T011 [P] [US1] Replace the misleading coverage percentage with count-based tenant coverage facts, explicit no-basis-run messaging, and coverage-only terminology in app/Filament/Widgets/Inventory/InventoryKpiHeader.php
  • T012 [P] [US1] Rewrite KPI supporting badge copy around follow-up counts, top-priority follow-up types, and observed-item counts without implying restore or compare readiness in app/Support/Inventory/InventoryKpiBadges.php
  • T013 [US1] Refactor tenant coverage row assembly, deterministic follow-up ranking, and default-visible columns while keeping support, restore, and compare metadata secondary in app/Filament/Pages/InventoryCoverage.php
  • T014 [US1] Rewrite the coverage page intro and summary copy to tenant-coverage-first language with explicit no-sync fallback guidance in resources/views/filament/pages/inventory-coverage.blade.php
  • T015 [US1] Run the focused truthful-at-a-glance pack in tests/Feature/Filament/InventoryCoverageTableTest.php, tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php, tests/Feature/Filament/InventoryPagesTest.php, and tests/Feature/Filament/InventoryItemResourceTest.php

Checkpoint: The inventory items list and coverage page now show tenant coverage truth first, with capability metadata clearly secondary.

Phase 4: User Story 2 - Move Cleanly From Coverage Truth To Run Truth (Priority: P1)

Goal: Make coverage surfaces cite the exact basis run, provide safe drill-through when authorized, and degrade cleanly when the run cannot be opened.

Independent Test: Seed a tenant with a coverage-bearing basis run and verify the inventory summary surfaces show the basis timestamp and run continuity, then verify a user without run access receives explanatory guidance instead of a dead-end link.

Tests for User Story 2

  • T016 [P] [US2] Add basis-run continuity assertions for linked coverage summaries, explicit no-basis-run fallback, and tenant-scoped operations fallback in tests/Feature/Filament/InventoryPagesTest.php and tests/Feature/Filament/InventoryCoverageRunContinuityTest.php
  • T017 [P] [US2] Add safe degradation assertions for viewers who can see inventory truth but cannot open the basis run in tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php and tests/Feature/Filament/InventoryCoverageRunContinuityTest.php

Implementation for User Story 2

  • T018 [P] [US2] Surface basis-run summary, continuity actions, no-sync fallback, and provider or permission follow-up guidance on the coverage report in app/Filament/Pages/InventoryCoverage.php and resources/views/filament/pages/inventory-coverage.blade.php
  • T019 [P] [US2] Surface basis-run continuity and safe link rendering in the inventory KPI summary using app/Filament/Widgets/Inventory/InventoryKpiHeader.php and app/Support/Inventory/TenantCoverageTruthResolver.php
  • T020 [US2] Run the focused continuity pack in tests/Feature/Filament/InventoryCoverageRunContinuityTest.php, tests/Feature/Filament/InventoryPagesTest.php, and tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php

Checkpoint: Coverage claims are now auditable through the basis run and remain safe when the current user cannot open the run detail.

Phase 5: User Story 3 - Diagnose Per-Type Inventory Sync Results Without Raw JSON (Priority: P2)

Goal: Make canonical inventory-sync run detail render human-readable per-type results and keep execution outcome separate from tenant coverage follow-up.

Independent Test: Seed an inventory-sync run with mixed per-type outcomes and verify the canonical run viewer shows a readable coverage section without relying on raw JSON.

Tests for User Story 3

  • T021 [P] [US3] Add human-readable inventory-sync section assertions, including provider or permission follow-up guidance, in tests/Feature/Operations/TenantlessOperationRunViewerTest.php and tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
  • T022 [P] [US3] Extend mixed-outcome payload expectations for per-type coverage rows in tests/Feature/Inventory/InventorySyncServiceTest.php and tests/Feature/Inventory/RunInventorySyncJobTest.php

Implementation for User Story 3

  • T023 [US3] Add the inventory-sync per-type coverage enterprise-detail section with explicit next-step guidance in app/Filament/Resources/OperationRunResource.php
  • T024 [P] [US3] Create the human-readable per-type run coverage view with provider or permission follow-up cues in resources/views/filament/infolists/entries/inventory-coverage-truth.blade.php
  • T025 [US3] Run the focused inventory-sync run-detail pack in tests/Feature/Operations/TenantlessOperationRunViewerTest.php, tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php, tests/Feature/Inventory/InventorySyncServiceTest.php, and tests/Feature/Inventory/RunInventorySyncJobTest.php

Checkpoint: Inventory-sync run detail now explains per-type outcomes directly and no longer forces operators into raw JSON for core coverage truth.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Align copy, run focused verification, and confirm the feature stayed within the intended no-new-persistence boundary.

  • T026 [P] Align operator-facing coverage labels, restore or compare separation, and helper copy across app/Filament/Widgets/Inventory/InventoryKpiHeader.php, app/Support/Inventory/InventoryKpiBadges.php, app/Filament/Pages/InventoryCoverage.php, and app/Filament/Resources/OperationRunResource.php
  • T027 Run vendor/bin/sail bin pint --dirty --format agent for touched files under app/, resources/views/, and tests/
  • T028 Run the focused Sail verification pack from specs/177-inventory-coverage-truth/quickstart.md against tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php, tests/Unit/Badges/BadgeCatalogTest.php, tests/Unit/Badges/InventoryCoverageStateBadgesTest.php, tests/Feature/Filament/InventoryCoverageTableTest.php, tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php, tests/Feature/Filament/InventoryPagesTest.php, tests/Feature/Filament/InventoryItemResourceTest.php, tests/Feature/Filament/InventoryCoverageRunContinuityTest.php, tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php, tests/Feature/Inventory/InventorySyncServiceTest.php, tests/Feature/Inventory/InventorySyncStartSurfaceTest.php, tests/Feature/Inventory/RunInventorySyncJobTest.php, tests/Feature/Operations/TenantlessOperationRunViewerTest.php, and tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php
  • T029 Validate that the final implementation introduces no schema migration, no inventory-sync backend rewrite, and no new persisted truth by reviewing database/migrations/, app/Services/Inventory/InventorySyncService.php, app/Jobs/RunInventorySyncJob.php, and specs/177-inventory-coverage-truth/plan.md against the final diff
  • T030 [P] Review app/Filament/Resources/InventoryItemResource/Pages/ListInventoryItems.php and app/Filament/Pages/InventoryCoverage.php against docs/product/standards/list-surface-review-checklist.md before final sign-off

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies; start immediately.
  • Foundational (Phase 2): Depends on Setup completion and blocks all user story work.
  • User Story 1 (Phase 3): Depends on Foundational completion and delivers the MVP truth-correction slice.
  • User Story 2 (Phase 4): Depends on User Story 1 because it extends the same summary surfaces with basis-run continuity and safe drill-through.
  • User Story 3 (Phase 5): Depends on Foundational completion and can proceed in parallel with User Story 2 if staffed, since it focuses on canonical run detail.
  • Polish (Phase 6): Depends on all desired user stories being complete.

User Story Dependencies

  • User Story 1 (P1): Depends only on the shared derived coverage contract from Phase 2 and is the recommended MVP.
  • User Story 2 (P1): Depends on User Story 1 because the same inventory summary surfaces must first speak truthful coverage before adding run continuity.
  • User Story 3 (P2): Depends only on the foundational contract and existing canonical run detail infrastructure; it can be delivered after User Story 1 or in parallel with User Story 2, but is lower priority.

Within Each User Story

  • Story tests should be written before or alongside implementation and should fail for the intended reason before the story is considered complete.
  • Shared resolver or badge changes should land before surface refactors that consume them.
  • Surface refactors should land before the focused story-level verification run.

Parallel Opportunities

  • T001 and T002 can run in parallel during Setup.
  • T003, T004, T005, and T006 can run in parallel during Foundational work.
  • T009 and T010 can run in parallel for User Story 1.
  • T011 and T012 can run in parallel for User Story 1 after the foundational resolver is ready.
  • T016 and T017 can run in parallel for User Story 2.
  • T018 and T019 can run in parallel for User Story 2 after basis-run continuity metadata is available.
  • T021 and T022 can run in parallel for User Story 3.
  • T023 and T024 can run in parallel for User Story 3.
  • T026 and T030 can run in parallel during Polish.

Parallel Example: User Story 1

# Launch the inventory truth regressions together before changing summary surfaces:
Task: T009 tests/Feature/Filament/InventoryPagesTest.php and tests/Feature/Filament/InventoryItemResourceTest.php
Task: T010 tests/Feature/Filament/InventoryCoverageTableTest.php and tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php

# Split KPI and helper refactors once the shared resolver is ready:
Task: T011 app/Filament/Widgets/Inventory/InventoryKpiHeader.php
Task: T012 app/Support/Inventory/InventoryKpiBadges.php

Parallel Example: User Story 2

# Write the continuity and degradation assertions together before adding links:
Task: T016 tests/Feature/Filament/InventoryCoverageRunContinuityTest.php and tests/Feature/Filament/InventoryPagesTest.php
Task: T017 tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php and tests/Feature/Filament/InventoryCoverageRunContinuityTest.php

# Split page and widget continuity work after the tests exist:
Task: T018 app/Filament/Pages/InventoryCoverage.php and resources/views/filament/pages/inventory-coverage.blade.php
Task: T019 app/Filament/Widgets/Inventory/InventoryKpiHeader.php and app/Support/Inventory/TenantCoverageTruthResolver.php

Parallel Example: User Story 3

# Lock the run-detail expectations and payload assertions together:
Task: T021 tests/Feature/Operations/TenantlessOperationRunViewerTest.php and tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
Task: T022 tests/Feature/Inventory/InventorySyncServiceTest.php and tests/Feature/Inventory/RunInventorySyncJobTest.php

# Build the section view and enterprise-detail wiring in parallel:
Task: T023 app/Filament/Resources/OperationRunResource.php
Task: T024 resources/views/filament/infolists/entries/inventory-coverage-truth.blade.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 the inventory items list and coverage page with the User Story 1-focused subset of specs/177-inventory-coverage-truth/quickstart.md.

Incremental Delivery

  1. Finish Setup and Foundational work.
  2. Deliver User Story 1 and validate truthful tenant coverage at a glance.
  3. Deliver User Story 2 and validate run continuity plus safe degradation.
  4. Deliver User Story 3 and validate human-readable inventory-sync run detail.
  5. Finish with formatting, the focused Sail pack, and the no-new-persistence review.

Parallel Team Strategy

  1. One developer can complete Phase 1 and the model or resolver side of Phase 2 while another prepares the badge and feature regressions.
  2. After Phase 2, one developer can take User Story 1 while another prepares User Story 3 run-detail tests.
  3. After User Story 1 stabilizes, one developer can handle User Story 2 continuity while another completes User Story 3 UI wiring.
  4. Rejoin for Phase 6 formatting and verification.

Notes

  • Every task follows the required checklist format: checkbox, task ID, optional parallel marker, required story label for story phases, and exact file paths.
  • The suggested MVP scope is Phase 1 through Phase 3 only.
  • No task in this plan introduces new persistence, a new Graph contract, a new Filament panel or provider registration change, or a new destructive action.