Summary
Build the next iteration of the race question system so admins can configure multiple real-world question types, players can submit valid answers, and admins can settle outcomes consistently after race completion.
User Story
As a steward, I want to configure and settle different question formats (H2H, position, order, and numeric gap) so that weekly race questions match the competition format and can be scored fairly.
Background
The initial admin panel story introduces race-level H2H and Bonus metadata storage/display.
This follow-up expands from simple text questions into typed, structured questions with explicit validation and settlement rules.
Scope
In scope:
Typed question definitions
Player answer capture per type
Validation at submit-time
Admin settlement workflow
Scoring output per settled question
Development mockability for all new behavior
Out of scope:
Full migration changes (Cosmos structure remains additive for now)
Advanced AI adjudication automation (manual steward adjudication supported first)
Supported Question Types (v1)
H2H Driver vs Driver
Example: Gasly vs Albon
Outcome: selected winner
H2H Free-Text Named Competitors
Example: Stevens Christmas tree vs Davids Christmas tree
Outcome: steward-selected winner
Adjudication note required
Single Driver at Exact Position
Example: driver to finish 10th or 12th
Multi Position Drivers
Example: drivers to finish 4th, 5th, 6th
Driver Outcome with Status
Example: where will Hamilton finish? (position, DNF, DNS)
Last Place / Last Across Line
Explicitly distinguish classification last vs last across finish line
Ordered Classification Subset
Example: classification order of 4 named drivers
Numeric Gap with Tolerance Scoring
Example: gap in seconds between 1st and 5th, rounded to nearest second
Scoring: max 10 points, minus 2 points per second off, floor at 0
Functional Requirements
Admin question configuration
Admin can add multiple questions for a race
Admin selects question type
Admin fills type-specific config fields
Admin can set source of truth text (for example Sky Sports F1)
Admin can mark question as active/published
Player answer submission
Player can submit one answer per active question
UI renders type-specific controls
API validates answer format and rejects invalid payloads
Settlement workflow
Admin can settle each question after race
Admin enters official outcome per question
For free-text H2H, admin chooses winner manually and enters adjudication note
Settlement timestamp and steward identity are recorded
Scoring
System computes points per player answer once question is settled
Numeric gap rule follows configured formula (v1 fixed formula above)
Re-settlement is allowed with audit log entry
Data persistence
Store additive question definitions, player answers, settlement data, and scoring results
Preserve existing race/results structure
Development mockability
In Development, mock question catalog, mock player answers, and mock settlement paths via config flags
Mock mode supports end-to-end UI testing without live race data dependencies
Acceptance Criteria
Admin can create and publish multiple typed questions per race.
Player form renders controls for each supported question type listed above.
API validates each answer type and returns clear validation errors.
Admin can settle each question with official result data.
System computes and stores points after settlement.
Numeric gap question scoring uses max 10, minus 2 per second off, minimum 0.
Free-text H2H supports steward manual winner selection with mandatory note.
Distinction exists between classification last and last across line question types.
All behavior is mockable in Development via config flags.
Unit and integration tests cover creation, submission, settlement, and scoring paths.
Non-Functional Requirements
Authorization enforced server-side for admin-only operations
Audit trail for create/edit/settle/resettle actions
No sensitive values in logs
Graceful UI behavior when no active questions exist
Testing Requirements
Unit tests:
Type-specific validation rules
Scoring calculations (especially numeric gap penalties)
Settlement state transitions
Re-settlement audit behavior
Integration tests:
Admin create/publish question flow
Player answer submit flow per type
Admin settle flow per type
Score persistence and retrieval
UI tests:
Dynamic form rendering by question type
Validation messaging
Settlement UX
Development mock mode flows
Definition of Done
All supported question types implemented and tested
Settlement and scoring available for each type
Mock mode documented in README with example flags
API docs updated
No regressions in existing player selection flow
Suggested Subtasks
Domain model expansion for typed questions and answers
Admin UI for question creation by type
Player UI components for type-specific answers
Validation and submission API
Settlement API and admin UI
Scoring engine for settled questions
Audit log implementation
Development mock wiring and docs
Test suite updates across API and Web
If you want, I can also draft a third issue that is only for adjudication automation (for example optional AI-assisted H2H free-text decisions) so this story stays lean and shippable.
Summary
Build the next iteration of the race question system so admins can configure multiple real-world question types, players can submit valid answers, and admins can settle outcomes consistently after race completion.
User Story
As a steward, I want to configure and settle different question formats (H2H, position, order, and numeric gap) so that weekly race questions match the competition format and can be scored fairly.
Background
The initial admin panel story introduces race-level H2H and Bonus metadata storage/display.
This follow-up expands from simple text questions into typed, structured questions with explicit validation and settlement rules.
Scope
In scope:
Typed question definitions
Player answer capture per type
Validation at submit-time
Admin settlement workflow
Scoring output per settled question
Development mockability for all new behavior
Out of scope:
Full migration changes (Cosmos structure remains additive for now)
Advanced AI adjudication automation (manual steward adjudication supported first)
Supported Question Types (v1)
H2H Driver vs Driver
Example: Gasly vs Albon
Outcome: selected winner
H2H Free-Text Named Competitors
Example: Stevens Christmas tree vs Davids Christmas tree
Outcome: steward-selected winner
Adjudication note required
Single Driver at Exact Position
Example: driver to finish 10th or 12th
Multi Position Drivers
Example: drivers to finish 4th, 5th, 6th
Driver Outcome with Status
Example: where will Hamilton finish? (position, DNF, DNS)
Last Place / Last Across Line
Explicitly distinguish classification last vs last across finish line
Ordered Classification Subset
Example: classification order of 4 named drivers
Numeric Gap with Tolerance Scoring
Example: gap in seconds between 1st and 5th, rounded to nearest second
Scoring: max 10 points, minus 2 points per second off, floor at 0
Functional Requirements
Admin question configuration
Admin can add multiple questions for a race
Admin selects question type
Admin fills type-specific config fields
Admin can set source of truth text (for example Sky Sports F1)
Admin can mark question as active/published
Player answer submission
Player can submit one answer per active question
UI renders type-specific controls
API validates answer format and rejects invalid payloads
Settlement workflow
Admin can settle each question after race
Admin enters official outcome per question
For free-text H2H, admin chooses winner manually and enters adjudication note
Settlement timestamp and steward identity are recorded
Scoring
System computes points per player answer once question is settled
Numeric gap rule follows configured formula (v1 fixed formula above)
Re-settlement is allowed with audit log entry
Data persistence
Store additive question definitions, player answers, settlement data, and scoring results
Preserve existing race/results structure
Development mockability
In Development, mock question catalog, mock player answers, and mock settlement paths via config flags
Mock mode supports end-to-end UI testing without live race data dependencies
Acceptance Criteria
Admin can create and publish multiple typed questions per race.
Player form renders controls for each supported question type listed above.
API validates each answer type and returns clear validation errors.
Admin can settle each question with official result data.
System computes and stores points after settlement.
Numeric gap question scoring uses max 10, minus 2 per second off, minimum 0.
Free-text H2H supports steward manual winner selection with mandatory note.
Distinction exists between classification last and last across line question types.
All behavior is mockable in Development via config flags.
Unit and integration tests cover creation, submission, settlement, and scoring paths.
Non-Functional Requirements
Authorization enforced server-side for admin-only operations
Audit trail for create/edit/settle/resettle actions
No sensitive values in logs
Graceful UI behavior when no active questions exist
Testing Requirements
Unit tests:
Type-specific validation rules
Scoring calculations (especially numeric gap penalties)
Settlement state transitions
Re-settlement audit behavior
Integration tests:
Admin create/publish question flow
Player answer submit flow per type
Admin settle flow per type
Score persistence and retrieval
UI tests:
Dynamic form rendering by question type
Validation messaging
Settlement UX
Development mock mode flows
Definition of Done
All supported question types implemented and tested
Settlement and scoring available for each type
Mock mode documented in README with example flags
API docs updated
No regressions in existing player selection flow
Suggested Subtasks
Domain model expansion for typed questions and answers
Admin UI for question creation by type
Player UI components for type-specific answers
Validation and submission API
Settlement API and admin UI
Scoring engine for settled questions
Audit log implementation
Development mock wiring and docs
Test suite updates across API and Web
If you want, I can also draft a third issue that is only for adjudication automation (for example optional AI-assisted H2H free-text decisions) so this story stays lean and shippable.