Add channel material and downtime analytics

2026-10-01 12:27:47 +02:00
parent 5452dc035b
commit 640ec53330
24 changed files with 2362 additions and 76 deletions
@@ -0,0 +1,36 @@
+# ENLYZE downtime architecture
+
+`GET /v2/downtimes` is the source of downtime events. Its UUID is the durable external
+identity. `end: null` means the source event is currently open. `reason: null` is valid
+and is persisted as `UNKNOWN`; it is never treated as `UNPLANNED`. ENLYZE's
+`updated.timestamp` describes source metadata/reason editing, not finalization.
+
+The reconciliation runner polls each configured machine with a configurable source-start
+lookback (48 hours by default), follows pagination, and upserts by UUID. Every 24 hours by
+default it also scans the full machine source so an old open or UNKNOWN event remains eligible
+for a delayed classification update. It always replaces
+the end time, comment, reason metadata, category, source update timestamp, and attributed
+timing. This is intentionally not append-only because supervisors can classify an event much
+later. Operators can enlarge `lookback_hours` where delayed classification exceeds the normal
+window.
+
+`production_downtime_events` retains ENLYZE source timing separately from FA-attributed
+timing. An event only receives an order while the persisted ERP order boundary is active.
+When ERP reports a new production order, the preceding boundary ends at the new feedback
+timestamp. A boundary also ends when `remaining_quantity_m2 <= completion_tolerance_m2`, or
+when `good_quantity_m2 + tolerance >= order_quantity_m2`. These are the exact fields from
+`CurrentWorkplaceStatus`; `feedback_timestamp` supplies the boundary instant. No equality on
+floating values is required. If neither signal proves completion, attribution stays open.
+
+This protects a completed FA from time in an ENLYZE downtime that remains open after work has
+finished. It does not infer completion from downtime. The durable
+`production_order_attribution_state` makes this clipping survive runner restarts.
+
+There is no machine-readable schedule today. No clock-time, shift, overnight, weekend, or Excel
+planning inference occurs. ENLYZE `reason.category` is the only planned/unplanned source;
+anything absent or unsupported remains `UNKNOWN`. A future SPA schedule provider can refine
+classification or boundaries as a separate input without changing stored source facts.
+
+The resulting fields support totals per order, category and reason, individual source events,
+and open events. Source duration is ENLYZE's `source_start/source_end`; attributed duration is
+only the interval inside the proven FA boundary.