comment model.

internal/models/ticket.go

@@ -1,31 +1,50 @@
+// Package models
+// Path: internal/models/
+// File: ticket.go
+//
+// Purpose
+//   Canonical persistence model for tickets as stored in DB,
+//   plus display helpers populated at read time.
+//
+// Responsibilities
+//   - Represents input values for ticket creation
+//   - Stores normalized draw fields for comparison
+//   - Optional fields (bonus, syndicate) use pointer types
+//
+// Notes
+//   - Read-only display fields must not be persisted directly
+//   - TODO: enforce UserID presence once per-user tickets are fully enabled
+
 package models
 
 import "time"
 
 type Ticket struct {
-	Id             int
+	Id          int       // Persistent DB primary key
-	UserId         int
+	UserId      int       // FK to users(id) when multi-user enabled
-	SyndicateId    *int
+	SyndicateId *int      // Optional FK if purchased via syndicate
-	GameType       string
+	GameType    string    // Lottery type (e.g., Lotto)
-	DrawDate       time.Time
+	DrawDate    time.Time // Stored as UTC datetime to avoid timezone issues
-	Ball1          int
+	Ball1       int
-	Ball2          int
+	Ball2       int
-	Ball3          int
+	Ball3       int
-	Ball4          int
+	Ball4       int
-	Ball5          int
+	Ball5       int
-	Ball6          int
+	Ball6       int // Only if game type requires
+
+	// Optional bonus balls
 	Bonus1         *int
 	Bonus2         *int
 	PurchaseMethod string
-	PurchaseDate   string
+	PurchaseDate   string // TODO: convert to time.Time
 	ImagePath      string
-	Duplicate      bool
+	Duplicate      bool // Calculated during insert
 	MatchedMain    int
 	MatchedBonus   int
 	PrizeTier      string
 	IsWinner       bool
 
-	// Used only for display these are not stored in the DB, they mirror MatchTicket structure but are populated on read.
+	// Non-DB display helpers populated in read model
 	Balls       []int
 	BonusBalls  []int
 	MatchedDraw DrawResult