Score-Engine Integration (Uplink → Match State)
En resumen
The score-engine integration turns raw scoreboard hardware events into validated match state — applying uplinks to Match documents, enforcing pétanque rules, escalating tampers, raising alerts, automating match-final transitions and streaming live admin views over SSE — so boards on the piste and the digital match in the database stay in sync.
Cómo funciona
Every score change a referee makes on a rented scoreboard fires a ScoreboardEvent uplink. The score-engine service's apply_uplink() function is triggered automatically as soon as the ingest path persists the event, so there is no polling lag. The engine reads the event flags, locates the active Match document, and applies the change with strict validation: scores cap at 13 points (the canonical pétanque finishing score), single-step decrements are allowed (correcting an over-tap) but jumps greater than one are rejected, and any update against a match already marked completed is refused outright.
When a match_final flag arrives, the engine flips the Match to status completed, writes the winner, and dispatches a set_match downlink that primes the same physical scoreboard for the next match in the schedule — the board is back in service for the next pair without an operator touching it. ScoreboardAlert documents capture environmental and tamper conditions with severity (warning/critical): low_battery, over_temp, lost (heartbeat lost), stale (no events in expected window), tamper. Tamper escalation is rule-based — more than three tamper events within five minutes flips severity to critical and increments a tamper_event_count, so persistent attacks are visible in the admin console rather than buried in noise.
Admin endpoints expose assign-next-match, tamper-arm, tamper-disarm and a filterable alerts list. A Server-Sent Events stream (GET /scoreboards/{id}/event-stream) lets the live admin view watch a single board in real time without polling — perfect for incident triage during a televised final.
Capacidades clave
- apply_uplink() service that ingests ScoreboardEvent flags into Match documents
- Strict score validation: max 13, decrement-by-1, no updates on completed matches
- Match-final flow with auto winner-write and set_match downlink for the next match
- ScoreboardAlert model for low_battery, over_temp, lost, stale and tamper events
- Tamper escalation: >3 events within 5 minutes promotes severity to critical
- Admin endpoints: assign-next-match, tamper-arm, tamper-disarm, alerts list
- SSE event stream for real-time per-board live admin views
En la práctica
During a televised final the referee accidentally taps +1 twice on the away team. He immediately hits the correction key on the rented scoreboard. The next uplink decrements by one — the score-engine accepts it because it's a single step.
The board now reads correctly, the live overlay updates within a second, and the Match document in the database matches the board exactly. Two matches later, the away team scores their thirteenth point. The match_final flag fires, the engine completes the match, writes the winner and dispatches set_match for the next pairing on that piste.
Operations watching the SSE stream in the admin console see every transition without refreshing.
Funcionalidades de este subsistema
8| ID | Status | Funcionalidades |
|---|---|---|
| F19.15.01 | Entregado | Score-engine service: apply_uplink() processar ScoreboardEvent-flaggor och uppdaterar Match-dokument ✅ PL-T067 |
| F19.15.02 | Entregado | Score-validering: max 13 poäng, avvisa decrement > 1, avvisa update på completed match ✅ PL-T067 |
| F19.15.03 | Entregado | Match-final-flöde: match_final-flagga → status completed, vinnare satt, set_match-downlink för nästa match ✅ PL-T067 |
| F19.15.04 | Entregado | ScoreboardAlert-modell: low_battery, over_temp, lost, stale, tamper med severity (warning/critical) ✅ PL-T067 |
| F19.15.05 | Entregado | Tamper-eskalering: > 3 events inom 5 min → severity critical, tamper_event_count tracking ✅ PL-T067 |
| F19.15.06 | Entregado | Admin-endpoints: assign-next-match, tamper-arm, tamper-disarm, alerts-lista med filter ✅ PL-T067 |
| F19.15.07 | Entregado | SSE event-stream (GET /scoreboards/{id}/event-stream) för live admin-vy ✅ PL-T067 |
| F19.15.08 | Entregado | Automatisk trigger: score-engine körs efter ingest sparar event ✅ PL-T067 |