ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9870f5d102
TenantAtlas/specs/042-inventory-dependencies-graph/tasks.md
ahmido da18d3cb14 feat/042-inventory-dependencies-graph (#50) 
Dieses PR liefert den Inventory Dependencies Graph end-to-end: Abhängigkeiten (Edges) werden aus Inventory-Sync-Daten extrahiert, tenant-sicher gespeichert und in der Inventory Item Detailansicht angezeigt.

Ziel: Admins können Prerequisites + Blast Radius (direct) schnell erkennen, ohne Snapshot/Restore anzufassen.

⸻

Was ist drin?

Dependency Graph (Edges)
	•	inventory_links Schema + Indizes + idempotentes Upsert (Unique Key)
	•	Relationship Types (u.a.):
	•	assigned_to_include, assigned_to_exclude
	•	uses_assignment_filter
	•	scoped_by_scope_tag
	•	UI: Inventory Item → Dependencies Section
	•	Direction Filter: All / Inbound / Outbound
	•	Relationship Filter: All + spezifische Relationship Types
	•	Missing-Badge + sicheres Tooltip (safe subset)

Safety / Observability
	•	Unknown/unsupported Shapes erzeugen keine Edges, sondern:
	•	Warning in InventorySyncRun.error_context.warnings[]
	•	optional info-log (ohne Secrets)
	•	Limit-only Semantik (MVP): bis zu 50 Edges pro Richtung (max 100 bei “All”)
	•	Blast Radius in MVP = direct only (kein depth>1 traversal)

Name Resolution (lokal, ohne Entra Calls)
	•	Resolver/DTO Layer für deterministische Labels (kein “Unknown” mehr)
	•	Auflösung aus lokaler DB nur für Foundations, wenn vorhanden:
	•	scope_tag → roleScopeTag
	•	assignment_filter → assignmentFilter
	•	aad_group bleibt bewusst external ref: “Group (external): …” (keine Graph/Entra Lookups im UI)
	•	Zentraler FoundationTypeMap als Source-of-Truth (keine Hardcodings)

⸻

Out of Scope / Follow-up
	•	Entra Group Name Resolution (braucht eigenes “Group Inventory” Modul + Permissions)
	•	Foundations als Inventory Items / Coverage Tab (Scope Tags / Assignment Filters sichtbar & syncbar)
→ folgt als separater PR (Inventory Core/UI), damit 042 sauber “Edges-only” bleibt.

⸻

Tests / Verifikation
	•	Targeted Pest Tests (Unit + Feature + UI smoke) für:
	•	deterministische Edge-Erzeugung + idempotent upsert
	•	tenant isolation (UI/Query)
	•	warnings auf Run Record
	•	resolver/name rendering + links (wo möglich)
	•	pint --dirty ausgeführt

⸻

Manual QA (UI)
	1.	Inventory Sync Run mit include_dependencies=true starten
	2.	Inventory Item öffnen → Dependencies prüfen:
	•	include/exclude + filter + scoped_by sichtbar (wenn vorhanden)
	•	Relationship/Direction Filter funktionieren
	•	keine “Unknown” Labels mehr, sondern deterministische Labels

Co-authored-by: Ahmed Darrazi <ahmeddarrazi@adsmac.local>
Reviewed-on: #50
2026-01-10 12:50:08 +00:00

173 lines
10 KiB
Markdown
Raw Blame History

# Tasks: Inventory Dependencies Graph (042)
**Input**: Design documents in `specs/042-inventory-dependencies-graph/` (plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md)
**Notes**
- Tasks are grouped by user story so each story is independently testable.
- Tests are included because this feature affects runtime behavior.
- MVP constraints (direct only, limit-only, 50 per direction, warnings-on-run-record, no warnings tables) must remain enforced.
## Phase 1: Setup (Shared)
**Purpose**: Ensure feature docs and scope constraints are locked before code changes.
- [x] T001 Validate MVP constraints in `specs/042-inventory-dependencies-graph/plan.md` remain aligned with `specs/042-inventory-dependencies-graph/spec.md`
- [x] T002 Validate scope + NFR checkboxes in `specs/042-inventory-dependencies-graph/checklists/requirements.md` cover all accepted MVP constraints
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Storage + extraction + query services that all UI stories rely on.
**Checkpoint**: After Phase 2, edges can be extracted and queried tenant-safely with limits.
- [x] T003 [P] Ensure relationship types and labels are centralized in `app/Support/Enums/RelationshipType.php`
- [x] T004 Ensure `inventory_links` schema (unique key + indexes) matches spec in `database/migrations/2026_01_07_150000_create_inventory_links_table.php`
- [x] T005 [P] Ensure `InventoryLink` casts and tenant-safe query patterns in `app/Models/InventoryLink.php`
- [x] T006 [P] Ensure factory coverage for dependency edges in `database/factories/InventoryLinkFactory.php`
- [x] T007 Align idempotent upsert semantics for edges in `app/Services/Inventory/DependencyExtractionService.php` (including hydrated assignments when not present in list payloads)
- [x] T008 Implement warning-only handling for unknown/unsupported reference shapes in `app/Services/Inventory/DependencyExtractionService.php`
- [x] T009 Persist warnings on the sync run record at `InventorySyncRun.error_context.warnings[]` via `app/Services/Inventory/InventorySyncService.php`
- [x] T010 Implement limit-only inbound/outbound queries with optional relationship filter in `app/Services/Inventory/DependencyQueryService.php` (ordered by `created_at DESC`)
- [x] T011 [P] Add determinism + idempotency tests in `tests/Unit/DependencyExtractionServiceTest.php`
- [x] T012 [P] Add tenant isolation tests for queries in `tests/Feature/DependencyExtractionFeatureTest.php`
---
## Phase 3: User Story 1 — View Dependencies (Priority: P1) 🎯 MVP
**Goal**: As an admin, I can view direct inbound/outbound dependencies for an inventory item.
**Independent Test**: Opening an Inventory Item shows a Dependencies section that renders within limits and supports direction filtering.
- [x] T013 [P] [US1] Wire dependencies section into Filament item view in `app/Filament/Resources/InventoryItemResource.php`
- [x] T014 [P] [US1] Render edges grouped by relationship type in `resources/views/filament/components/dependency-edges.blade.php`
- [x] T015 [US1] Add direction filter (querystring-backed) in `resources/views/filament/components/dependency-edges.blade.php`
- [x] T016 [US1] Parse/validate `direction` and pass to query service in `app/Filament/Resources/InventoryItemResource.php`
- [x] T017 [US1] Add UI smoke test for dependencies rendering + direction filter in `tests/Feature/InventoryItemDependenciesTest.php`
---
## Phase 4: User Story 2 — Identify Missing Prerequisites (Priority: P2)
**Goal**: As an admin, I can clearly see when a referenced prerequisite object is missing.
**Independent Test**: A missing target renders a red “Missing” badge and safe tooltip using `metadata.last_known_name`/`metadata.raw_ref`.
- [x] T018 [US2] Ensure unresolved targets create `target_type='missing'` edges with safe metadata in `app/Services/Inventory/DependencyExtractionService.php`
- [x] T019 [US2] Display “Missing” badge + tooltip for missing edges in `resources/views/filament/components/dependency-edges.blade.php`
- [x] T020 [US2] Add feature test for missing edge creation + metadata in `tests/Feature/DependencyExtractionFeatureTest.php`
- [x] T021 [US2] Add UI test asserting missing badge/tooltip is visible in `tests/Feature/InventoryItemDependenciesTest.php`
---
## Phase 5: User Story 3 — Filter By Relationship Type (Priority: P2)
**Goal**: As an admin, I can filter dependencies by relationship type to reduce noise.
**Independent Test**: Selecting a relationship type shows only matching edges; default “All” shows everything.
- [x] T022 [US3] Add relationship-type dropdown filter (querystring-backed) in `resources/views/filament/components/dependency-edges.blade.php`
- [x] T023 [US3] Parse/validate `relationship_type` and pass to query service in `app/Filament/Resources/InventoryItemResource.php`
- [x] T024 [US3] Add UI smoke test verifying relationship filter limits edges in `tests/Feature/InventoryItemDependenciesTest.php`
---
## Phase 6: User Story 4 — Zero Dependencies (Priority: P3)
**Goal**: As an admin, I get a clear empty state when no dependencies exist.
**Independent Test**: When queries return zero edges, the UI shows “No dependencies found” and does not error.
- [x] T025 [US4] Render zero-state message in `resources/views/filament/components/dependency-edges.blade.php`
- [x] T026 [US4] Add UI test for zero-state rendering in `tests/Feature/InventoryItemDependenciesTest.php`
---
## Phase 7: Polish & Cross-Cutting Concerns
**Purpose**: Tighten docs/contracts and run quality gates.
- [x] T027 [P] Align filter docs + URLs in `specs/042-inventory-dependencies-graph/quickstart.md`
- [x] T028 [P] Ensure schema reflects metadata requirements in `specs/042-inventory-dependencies-graph/contracts/dependency-edge.schema.json`
- [x] T029 Update requirement-gate checkboxes in `specs/042-inventory-dependencies-graph/checklists/pr-gate.md`
- [x] T030 Run Pint and fix formatting in `app/`, `resources/views/filament/components/`, and `tests/` (touching `app/Support/Enums/RelationshipType.php`, `resources/views/filament/components/dependency-edges.blade.php`, `tests/Feature/InventoryItemDependenciesTest.php`)
- [x] T031 Run targeted tests: `tests/Feature/InventoryItemDependenciesTest.php`, `tests/Feature/DependencyExtractionFeatureTest.php`, `tests/Unit/DependencyExtractionServiceTest.php`
---
## Phase 8: Consistency & Security Coverage (Cross-Cutting)
**Purpose**: Close remaining spec→tasks gaps (ordering, masking, auth expectations, logging severity).
- [x] T032 [P] Add test asserting inbound/outbound query ordering by `created_at DESC` + limit-only behavior in `tests/Feature/DependencyExtractionFeatureTest.php` (or `tests/Unit/DependencyExtractionServiceTest.php` if more appropriate)
- [x] T033 [US2] Implement masked/abbreviated identifier rendering when `metadata.last_known_name` is null in `resources/views/filament/components/dependency-edges.blade.php`
- [x] T034 [US2] Add UI test for masked identifier behavior in `tests/Feature/InventoryItemDependenciesTest.php`
- [x] T035 [P] Add auth behavior test for the inventory item dependencies view (guest blocked; authenticated tenant user allowed) in `tests/Feature/InventoryItemDependenciesTest.php`
- [x] T036 [P] Ensure unknown/unsupported reference warnings are logged at `info` severity in `app/Services/Inventory/DependencyExtractionService.php` and add a unit test using `Log::fake()` in `tests/Unit/DependencyExtractionServiceTest.php`
- [x] T037 Document how to verify the <2s dependency section goal (manual acceptance check) in `specs/042-inventory-dependencies-graph/quickstart.md`
---
## Phase 9: 042.2 — Dependency Target Name Resolution (Resolver + Batch) 🎯
**Goal**: Remove UI-level "Unknown" logic by rendering a stable DTO per edge target, and resolve names from the local DB when possible.
**Constraints**:
- No Entra/Graph lookups in the Dependencies UI (DB-only).
- No new tables.
- Deterministic, tenant-scoped, batch queries (no N+1).
- [x] T038 Introduce DTO + resolver registry (batch) for dependency targets (e.g., `DependencyTargetDto`, `DependencyTargetResolver`)
- [x] T039 Implement DB-based resolvers for scope tags and assignment filters; keep AAD groups as external refs (no resolution)
- [x] T040 Wire resolver into the Dependencies view (attach DTO to each edge) and simplify Blade rendering to DTO-only
- [x] T041 Add linking for resolved targets (tenant-scoped Inventory Item view URL)
- [x] T042 Add tests: unit (batch + determinism + tenant isolation) and feature/UI (resolved names + external group label)
---
## Dependencies & Execution Order
### Phase Dependencies
- Phase 1 (Setup) → Phase 2 (Foundational) → US1 (MVP) → US2/US3 → US4 → Polish
### User Story Dependencies
- US1 depends on Phase 2.
- US2 depends on Phase 2 and US1 (needs the Dependencies view).
- US3 depends on Phase 2 and US1 (needs the Dependencies view).
- US4 depends on US1 (zero-state is part of the Dependencies view).
## Parallel Execution Examples
### Phase 2 (Foundational)
- [P] `app/Support/Enums/RelationshipType.php` and `database/migrations/2026_01_07_150000_create_inventory_links_table.php`
- [P] `database/factories/InventoryLinkFactory.php` and `tests/Unit/DependencyExtractionServiceTest.php`
### User Story 1 (US1)
- [P] Update `app/Filament/Resources/InventoryItemResource.php` while implementing rendering in `resources/views/filament/components/dependency-edges.blade.php`
### User Story 2 (US2)
- [P] Implement missing-edge extraction in `app/Services/Inventory/DependencyExtractionService.php` while updating UI rendering in `resources/views/filament/components/dependency-edges.blade.php`
### User Story 3 (US3)
- [P] Implement relationship dropdown in `resources/views/filament/components/dependency-edges.blade.php` while wiring query parsing in `app/Filament/Resources/InventoryItemResource.php`
### User Story 4 (US4)
- [P] Implement zero-state UI in `resources/views/filament/components/dependency-edges.blade.php` while writing the UI assertion in `tests/Feature/InventoryItemDependenciesTest.php`
## Implementation Strategy
### MVP First (US1 Only)
1. Complete Phase 1 and Phase 2.
2. Implement US1 and validate with `tests/Feature/InventoryItemDependenciesTest.php`.
3. Stop and demo MVP UI before proceeding to US2/US3.
### Incremental Delivery
1. Phase 1 + Phase 2 → foundation ready.
2. US1 → demo dependency view.
3. US2 → add missing-prerequisite trust signals.
4. US3 → add relationship filtering for readability.
5. US4 → refine empty-state UX.
Reference in New Issue View Git Blame Copy Permalink