Merge pull request #381 from trakrf/feat/tra-794-bb69-asset-locations-exclusion-rule

TRA-794 F1 — document never-scanned exclusion on /reports/asset-locations

Author: mikestankavich

backend/internal/handlers/reports/current_locations.go

@@ -35,6 +35,8 @@ type ListCurrentLocationsResponse struct {
 // @Summary List current asset locations
 // @Description Snapshot of each asset's most recent location, filterable by either side of the join. Filter by location (`location_id` / `location_external_key`) to retrieve everything currently at a place; filter by asset (`asset_id` / `asset_external_key`, repeatable) to resolve a batch of assets from a master system to their current locations in one round-trip. Within each pair the surrogate and natural-key forms are mutually exclusive (400 `ambiguous_fields` if both are supplied); the asset and location filter pairs are independent and intersect when combined. Because this view is derived from immutable scan history, it can resolve references for assets that have since been deleted. By default those rows are excluded; pass `include_deleted=true` to include them, and check `asset_deleted_at` to distinguish deleted from live.
 // @Description
+// @Description Rows are produced from `scan_event` history and reflect the most recent observed location per asset. **Assets that have never been scanned do not appear in this report** — they exist in `/api/v1/assets` but have no derived location row until at least one scan event has been observed, so this endpoint's `total_count` can lag `/api/v1/assets` `total_count` for newly-onboarded inventory. Use `/api/v1/assets` directly if you need a complete asset roster including never-scanned assets.
+// @Description
 // @Description Temporal validity is applied to both joined entities. Assets whose effective window is past or future are excluded entirely. Locations whose effective window is past or future surface with null `location_id` / `location_external_key` while the parent asset row remains visible. Soft-deleted locations are projected the same way here — null on the report row — even though the identifier still lives on the location row; reports endpoints intentionally hide tombstoned anchor points from scan-derived summaries. Use the locations endpoint with `include_deleted=true` to retrieve the underlying identifier.
 // @Tags reports,public
 // @ID reports.asset-locations

docs/api/openapi.public.json

@@ -7494,7 +7494,7 @@
     },
     "/api/v1/reports/asset-locations": {
       "get": {
-        "description": "**Required scope:** `tracking:read`\n\nSnapshot of each asset's most recent location, filterable by either side of the join. Filter by location (`location_id` / `location_external_key`) to retrieve everything currently at a place; filter by asset (`asset_id` / `asset_external_key`, repeatable) to resolve a batch of assets from a master system to their current locations in one round-trip. Within each pair the surrogate and natural-key forms are mutually exclusive (400 `ambiguous_fields` if both are supplied); the asset and location filter pairs are independent and intersect when combined. Because this view is derived from immutable scan history, it can resolve references for assets that have since been deleted. By default those rows are excluded; pass `include_deleted=true` to include them, and check `asset_deleted_at` to distinguish deleted from live.\n\nTemporal validity is applied to both joined entities. Assets whose effective window is past or future are excluded entirely. Locations whose effective window is past or future surface with null `location_id` / `location_external_key` while the parent asset row remains visible. Soft-deleted locations are projected the same way here — null on the report row — even though the identifier still lives on the location row; reports endpoints intentionally hide tombstoned anchor points from scan-derived summaries. Use the locations endpoint with `include_deleted=true` to retrieve the underlying identifier.",
+        "description": "**Required scope:** `tracking:read`\n\nSnapshot of each asset's most recent location, filterable by either side of the join. Filter by location (`location_id` / `location_external_key`) to retrieve everything currently at a place; filter by asset (`asset_id` / `asset_external_key`, repeatable) to resolve a batch of assets from a master system to their current locations in one round-trip. Within each pair the surrogate and natural-key forms are mutually exclusive (400 `ambiguous_fields` if both are supplied); the asset and location filter pairs are independent and intersect when combined. Because this view is derived from immutable scan history, it can resolve references for assets that have since been deleted. By default those rows are excluded; pass `include_deleted=true` to include them, and check `asset_deleted_at` to distinguish deleted from live.\n\nRows are produced from `scan_event` history and reflect the most recent observed location per asset. **Assets that have never been scanned do not appear in this report** — they exist in `/api/v1/assets` but have no derived location row until at least one scan event has been observed, so this endpoint's `total_count` can lag `/api/v1/assets` `total_count` for newly-onboarded inventory. Use `/api/v1/assets` directly if you need a complete asset roster including never-scanned assets.\n\nTemporal validity is applied to both joined entities. Assets whose effective window is past or future are excluded entirely. Locations whose effective window is past or future surface with null `location_id` / `location_external_key` while the parent asset row remains visible. Soft-deleted locations are projected the same way here — null on the report row — even though the identifier still lives on the location row; reports endpoints intentionally hide tombstoned anchor points from scan-derived summaries. Use the locations endpoint with `include_deleted=true` to retrieve the underlying identifier.",
         "operationId": "listAssetLocations",
         "parameters": [
           {

docs/api/openapi.public.yaml

@@ -5013,6 +5013,8 @@ paths:
 
                 Snapshot of each asset's most recent location, filterable by either side of the join. Filter by location (`location_id` / `location_external_key`) to retrieve everything currently at a place; filter by asset (`asset_id` / `asset_external_key`, repeatable) to resolve a batch of assets from a master system to their current locations in one round-trip. Within each pair the surrogate and natural-key forms are mutually exclusive (400 `ambiguous_fields` if both are supplied); the asset and location filter pairs are independent and intersect when combined. Because this view is derived from immutable scan history, it can resolve references for assets that have since been deleted. By default those rows are excluded; pass `include_deleted=true` to include them, and check `asset_deleted_at` to distinguish deleted from live.
 
+                Rows are produced from `scan_event` history and reflect the most recent observed location per asset. **Assets that have never been scanned do not appear in this report** — they exist in `/api/v1/assets` but have no derived location row until at least one scan event has been observed, so this endpoint's `total_count` can lag `/api/v1/assets` `total_count` for newly-onboarded inventory. Use `/api/v1/assets` directly if you need a complete asset roster including never-scanned assets.
+
                 Temporal validity is applied to both joined entities. Assets whose effective window is past or future are excluded entirely. Locations whose effective window is past or future surface with null `location_id` / `location_external_key` while the parent asset row remains visible. Soft-deleted locations are projected the same way here — null on the report row — even though the identifier still lives on the location row; reports endpoints intentionally hide tombstoned anchor points from scan-derived summaries. Use the locations endpoint with `include_deleted=true` to retrieve the underlying identifier.
             operationId: listAssetLocations
             parameters: