TenantAtlas/specs/046-inventory-sync-button/data-model.md

Phase 1 Design: Data Model (046)

Entities

InventorySyncRun

Existing table: inventory_sync_runs

Purpose: Observable record of one inventory sync execution for a tenant + selection.

Existing fields (selected)

• id
• tenant_id (FK)
• selection_hash (sha256)
• selection_payload (jsonb)
• status (running|success|partial|failed|skipped)
• had_errors (bool)
• error_codes (jsonb)
• error_context (jsonb)
• started_at, finished_at
• items_observed_count, items_upserted_count, errors_count

Planned additions (to satisfy FR-008)

• user_id (nullable FK to users.id)
  • Meaning: initiator of the run (UI-triggered). null allowed for system/scheduled runs.

Relationships

• InventorySyncRun belongsTo Tenant
• InventorySyncRun belongsTo User (new, nullable)

Validation rules (selection payload)

• policy_types: list of strings; filtered through PolicyTypeResolver::filterRuntime(...)
• categories: list of strings (optional; currently not used for the UI-triggered “full inventory” run)
• include_foundations: boolean
• include_dependencies: boolean

BulkOperationRun

Existing table: bulk_operation_runs

Purpose: Generic progress tracking for background operations. Used by the bottom-right progress widget.

Relevant fields

• tenant_id, user_id
• resource, action (used for display)
• status (pending|running|completed|completed_with_errors|failed|aborted)
• Counters: total_items, processed_items, succeeded, failed, skipped
• audit_log_id (FK)

Usage for Inventory Sync

• resource = 'inventory', action = 'sync'
• total_items = 1
• item_ids = [selection_hash] (or [inventory_sync_run_id] after creation)

AuditLog

Existing table: audit_logs

Purpose: Immutable audit trail with actor identity snapshot.

Usage for Inventory Sync

• Emit inventory.sync.dispatched and a terminal event like inventory.sync.completed / inventory.sync.failed.
• resource_type = 'inventory_sync_run', resource_id = (string) $run->id
• Actor fields filled from authenticated user.

State transitions

InventorySyncRun

• running → success|partial|failed
• running → skipped (lock/concurrency)

BulkOperationRun

• pending → running → completed|completed_with_errors|failed|aborted