Draw Winner Reveal Feature - Implementation Details

Overview

This document details the implementation of the draw winner reveal countdown feature.

Feature Requirements (from issue)

1. Add a new status revealed after completed
2. Transition from completed to revealed via cron function
3. Admin inputs reveal date/time when completing draw
4. Return winner details to admin when selected
5. Return winning ticket number to mobile only when revealed
6. Add admin view for winner details
7. For completed draws, return reveal date to mobile
8. For revealed draws, return winner ticket to mobile

Implementation Details

Database Changes

• Schema: Added revealed enum value and reveal_at column
• Queries: Added query to fetch completed draws ready for reveal
• Query: Added query to update status and reveal_at together

Backend Services

• CompleteDraw(): Now accepts optional revealAt *time.Time parameter
• RevealDraw(): New method to transition draw to revealed status
• ProcessCompletedDrawsReadyForReveal(): Cron function to auto-reveal draws

API Endpoints

Admin

• PUT /admin/draws/:id/status - Complete draw with reveal date

  POST body: { "action": "complete", "reveal_at": "2026-02-25T10:00:00Z" }
  

• GET /admin/draws/:id/winner - Get winner details (new endpoint)

  Response: { "id", "key", "name", "dateOfBirth", "email", "ticketId" }
  

• POST /admin/draws/:id/select - Now returns winner in response

Mobile

• GET /mobile/draws/:id - Includes reveal_at for completed, winner_ticket_id for revealed
• GET /mobile/draws/:id/winner - Returns 403 if not revealed, winner if revealed

Cron Jobs

• process_draw_winner_reveal_schedule: Runs every minute to reveal completed draws

Frontend Components

• CompleteDrawDialog: Date/time picker for setting reveal time
• WinnerDetailsDialog: Display winner information for admin

Status Transition Matrix

Data Visibility

Admin Access

• selected/completed/revealed: Full winner details (user info + ticket ID)

Mobile Access

• selected: No winner information
• completed: Reveal date only (countdown)
• revealed: Winning ticket number only

Security Considerations

• Authorization checks on all endpoints
• Parameterized SQL queries
• Status validation before transitions
• Access control based on reveal status
• No vulnerabilities introduced

See SECURITY_SUMMARY.md for detailed security analysis.

Testing

See TESTING.md for comprehensive testing guide.

Database Schema

The database schema in api/common/infra/database/schema/public.sql includes:

• revealed value in the draw_status enum
• reveal_at timestamptz column in the draws table

These changes are part of the base schema and will be automatically applied when the database is initialized.