Workflow — Winner Announcement


Module	Winners
Actors	Admin (finalize + veto), System (publish + badges), Winners, Public
SRS refs	UC-11, FR-1000, BR-004/005/009
Status	Planned — ships with v0.9.0

Purpose

Close an event the right way: blend the scores, let the admin decide, audit-lock the result, and have the system announce winners — with badges + shareable "Winner" cards for their social media.

Preconditions

Voting window closed (status=judging → finished path).
Judges submitted (or admin waived).
No pending hard contradictions flagged in audit review.

Main flow

Admin opens Finalize for the event → per-category ranking table:

public votes (70%) + board score (30%) + AI score (informational) + judges' tally.

Admin may veto a candidate (mandatory reason → audit).
Admin picks winner(s) per category → Approve & lock:
- snapshot of the computation stored,
- audit lock written (winner.locked),
- registrations of winners → status=winner, runners-up → finalist.
System publishes:
- public results page (/events/{slug}/winners),
- notifications to winners ("You won 🎉") + claim their badge,
- Winner share cards generated (photo + campaign.winner_text) — "I am a Winner at {event}" for LinkedIn etc.
Losers get a gracious notification + certificates later (enhancement idea, see ROADMAP).

Alternate / error flows

A1 Tie after blending → admin manually breaks the tie; tie-break reason logged.
A2 Re-open after lock → possible only via a new admin action winner.unlocked — fully audit-logged; public page updates.
A3 Vetoed candidate had most votes → public page shows nothing about veto (internal only); count data stays in audit.

Rules applied

BR-004, BR-005, BR-009 (+ BR-006: leaderboard becomes public only at this point).

Data touched

Table	Change
registrations	status → winner / finalist
audit_log	`winner.locked`, `veto.applied`, `winner.unlocked` (meta: snapshot JSON)
notifications	winners + finalists
events	status → finished
storage/cards	winner card PNGs

Sequence

sequenceDiagram
    participant AD as Admin
    participant W as Website
    participant DB as MariaDB
    participant SYS as System/Cards
    participant P as Public
    AD->>W: Finalize → rankings (70/30 + judges)
    AD->>W: select winners → Approve & lock
    W->>DB: statuses + audit lock (snapshot)
    W->>SYS: generate winner badges/cards
    W->>DB: notifications
    P->>W: /events/{slug}/winners → public results