Reporting

Reporting

A dedicated Reporting sidebar section (collapsible, between Operations and Engineering) with five read-only screens at /reporting/*, accessible to ADMIN, SUPERVISOR, and VIEWER roles. History accumulates from deployment day (daily counters and snapshots); 90-day windows fill progressively, and 14-day forecasts use a weekday-seasonal moving average rendered as a dashed continuation.

Spec: docs/reportingScope.md (product minimum set + research enrichment).

Material Flow — /reporting/material-flow

Covers scan-point quality, scanner health prediction, and conveyor traffic.

Report	Detail	Status
Scan quality	Stacked bars — good reads, no-reads, and unknowns per scan point per day; window summary chips (total scans, errors, error rate). Live — GET /api/flow/reports/scan-quality?warehouseId=&days=	✅
Scanners needing attention	Regression-based table: each scan point's overall error rate, daily-rate trend (slope), and a sparkline. Flagged at > 2 % error rate or a rising trend. Live (derived client-side from scan-quality data)	✅
Traffic heatmap	Conveyor edges tinted by throughput count on the reused 3D topology scene (log scale). Live — GET /api/flow/reports/traffic?warehouseId=&days=	✅
Transit times	Daily p50 / p95 transport times in seconds. Live — GET /api/flow/reports/transit-times?warehouseId=&days=	✅
Routing decision latency	Per-scan routing decision latency of one flow replica: {count, p50Ms, p95Ms, p99Ms, maxMs} over the last 4096 decisions (in-memory ring buffer; resets on restart) — the live gauge for the hard-real-time ~10 ms scan-answer budget. API only for now. Live — GET /api/flow/reports/decision-latency	✅ (endpoint)
Throughput per scan point	Current and historical pieces per hour per scan point.	planned
Recirculation rate	Per sorter / divert per day — percentage of totes that loop back.	planned

Equipment

Covers device-level workload and utilisation across all equipment families.

Report	Detail	Status
Task throughput + failure rate	Completed vs. failed tasks per equipment per day. Currently surfaced inside the ASRS screen for ASRS devices — GET /api/flow/reports/device-movements?warehouseId=&days=	✅ (ASRS screen)
Utilisation proxy	Active-task time share per equipment family (conveyor, shuttle, crane, AMR, etc.).	planned

ASRS — /reporting/asrs

Covers automated storage density, movement history, and device-level throughput.

Report	Detail	Status
Storage density	Occupied vs. total cells in figures and %, 90-day history + dashed 14-day weekday-seasonal forecast, per-block table (latest day). Live — GET /api/inventory/reports/storage-density?warehouseId=&days=	✅
Movement heatmap	Rack cells coloured by stores + retrieves over the window in the 3D twin scene at actual cell positions (log scale); daily totals chart + 14-day forecast. Live — GET /api/flow/reports/storage-movements?warehouseId=&days=	✅
Movements per device	Completed / failed device-task counts per shuttle, crane, or equivalent ASRS device — stacked bars and sortable table. Live — GET /api/flow/reports/device-movements?warehouseId=&days=	✅

Stock — /reporting/stock

Report	Detail	Status
Stock per SKU	Current-state snapshot: single-quantity per SKU split into available, allocated, and unavailable (UNKNOWN-location stock counts as unavailable). SKU codes resolved via master data. Live — GET /api/inventory/reports/stock-by-sku?warehouseId=	✅

Related: Inbound and Inventory.

Inbound — /reporting/inbound

Report	Detail	Status
Expected / started / active	Expected = received from host, not yet stock. Started and active chips.	✅
90-day history	Received, started, and completed orders per day. Live — GET /api/orders/reports/flow?warehouseId=&direction=INBOUND&days=90	✅
Peak profile (day map)	90-day window compiled into the 24 hours of the day; cells at ≥ 85 % of the busiest hour are outlined as peaks.	✅

Outbound — /reporting/outbound

Report	Detail	Status
Expected / started / active	Expected = received from host, not yet released for picking.	✅
90-day history	Received, started, and completed orders per day. Live — GET /api/orders/reports/flow?warehouseId=&direction=OUTBOUND&days=90	✅
Peak profile (day map)	Hour-of-day heat strip from 90 days of data; peaks show carrier cut-off rush patterns.	✅

Note: the outbound "completed" series approximates with the order's last update timestamp — no separate dispatch timestamp exists yet (tracked as a follow-up).

GTP (later phase)

Report	Detail
Station throughput	Cycles and puts per hour per GTP station.
Queue depth over time	Pending presentations queued at each station.

Related: Goods-to-Person Stations.

Implementation notes

• Access — all five /reporting/* routes are registered with default roles ADMIN, SUPERVISOR, VIEWER in auth/screens.ts. Access can be overridden per role or user via the Access Control screen.
• History window — counters and daily snapshots accumulate from the deployment date; 90-day windows fill progressively and show whatever data is available until the window is complete. Empty states are shown honestly rather than hiding charts.
• Forecasting — 14-day outlook (ASRS density and movement totals) uses a weekday-seasonal moving average implemented in reporting/forecast.ts; rendered as a dashed line. Method is intentionally simple and explainable to operators.
• Heatmaps — reuse the existing 3D digital-twin scene via a lazy-loaded ReportScene3D (reporting/ReportScene3D.tsx): conveyor edges tinted by traffic intensity, ASRS rack cells by movement count at the same cell positions the Hardware Visualisation uses. See Hardware Visualisation.
• Charts — rendered with recharts (ui/src/reporting/charts.tsx exports shared primitives: DailyChart, StackedBars, StatChip, HeatLegend).
• Live reporting counters — scan_stat (scans / no-reads / unknowns per scan-point + day) and edge_traffic (route answers per directed edge + day) are written by atomic INSERT … ON CONFLICT upserts, fed asynchronously from RoutingService.decide() via the in-process ScanSideEffects FIFO queue (one background thread; failures WARN and drop, the scan answer is never blocked). Storage movements aggregate from device_task (completed STORE/RETRIEVE) per locationId. Transit times derive from INDUCTED → ARRIVED pairs in hu_transport_trace with p50/p95 computed in Java. All flow endpoints accept warehouseId (required) + days (default 90). Storage density is served by the inventory service.
• Demo mode — demo-mode reset purges the flow counters so reports stay consistent after a reset.

Related: Transport Overview · Hardware Visualisation · Inbound and Inventory · Outbound Flow.