models

package
v7.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 11, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CreditAdjustmentReasonPrefixMigration = "Migration"
	//nolint:gosec // String is not sensitive
	CreditAdjustmentReasonPrefixMonthlyTopup = "Monthly free credit top-up"
	CreditAdjustmentReasonPrefixPurchase     = "Purchase"
	CreditAdjustmentReasonPrefixAdmin        = "Admin"
	CreditAdjustmentReasonPrefixGift         = "Gift"
)

Credit adjustment reason prefixes.

View Source
const (
	CreditPurchaseStatusPending   = "pending"
	CreditPurchaseStatusCompleted = "completed"
	CreditPurchaseStatusFailed    = "failed"
	CreditPurchaseStatusCancelled = "cancelled"
)

Credit purchase status constants.

View Source
const (
	CompletionAll     = game.CompletionAll
	CompletionMinimum = game.CompletionMinimum
)
View Source
const (
	RouteStrategyRandomised = game.RouteStrategyRandomised
	RouteStrategyFreeRoam   = game.RouteStrategyFreeRoam
	RouteStrategyOrdered    = game.RouteStrategyOrdered
	RouteStrategySecret     = game.RouteStrategySecret
)
View Source
const (
	NavigationMap         = game.NavigationMap
	NavigationLabelledMap = game.NavigationLabelledMap
	NavigationList        = game.NavigationList
	NavigationCustom      = game.NavigationCustom
	NavigationTasks       = game.NavigationTasks
)

Variables

This section is empty.

Functions

func Slugify

func Slugify(s string) string

Slugify converts a string to a URL-safe slug.

Types

type Block

type Block struct {
	ID                 string            `bun:"id,pk,notnull"`
	OwnerID            string            `bun:"owner_id,notnull"`
	Type               string            `bun:"type,type:int"`
	Context            game.BlockContext `bun:"context,type:string"`
	Data               json.RawMessage   `bun:"data,type:jsonb"`
	Ordering           int               `bun:"ordering,type:int"`
	Points             int               `bun:"points,type:int"`
	ValidationRequired bool              `bun:"validation_required,type:bool"`
}

type CheckIn

type CheckIn struct {
	InstanceID      string    `bun:"instance_id,notnull"`
	TeamID          string    `bun:"team_code,pk,type:string"`
	LocationID      string    `bun:"location_id,pk,type:string"`
	TimeIn          time.Time `bun:"time_in,type:datetime"`
	TimeOut         time.Time `bun:"time_out,type:datetime"`
	MustCheckOut    bool      `bun:"must_check_out"`
	Points          int       `bun:"points,"`
	BlocksCompleted bool      `bun:"blocks_completed,type:int"`

	Location Location `bun:"rel:has-one,join:location_id=id"`
	// contains filtered or unexported fields
}

type CompletionType

type CompletionType = game.CompletionType

Type alias — CompletionType is defined in game/ and re-exported here.

type CreditAdjustments

type CreditAdjustments struct {
	CreatedAt time.Time `bun:"created_at,nullzero,notnull,default:current_timestamp"`

	ID               string         `bun:"id,unique,pk,type:varchar(36)"`
	UserID           string         `bun:"user_id,notnull,type:varchar(36)"`
	Credits          int            `bun:"credits,type:int,notnull"`
	Reason           string         `bun:"reason,type:varchar(255),notnull"`
	CreditPurchaseID sql.NullString `bun:"credit_purchase_id,type:varchar(36),nullzero"`

	CreditPurchase *CreditPurchase `bun:"rel:belongs-to,join:credit_purchase_id=id"`
}

type CreditPurchase

type CreditPurchase struct {
	CreatedAt time.Time `bun:"created_at,nullzero,notnull,default:current_timestamp"`
	UpdatedAt time.Time `bun:"updated_at,nullzero,notnull,default:current_timestamp"`

	ID               string         `bun:"id,unique,pk,type:varchar(36)"`
	UserID           string         `bun:"user_id,notnull,type:varchar(36)"`
	Credits          int            `bun:"credits,type:int,notnull"`
	AmountPaid       int            `bun:"amount_paid,type:int,notnull"` // Amount in cents
	StripePaymentID  sql.NullString `bun:"stripe_payment_id,type:varchar(255),nullzero"`
	StripeSessionID  string         `bun:"stripe_session_id,type:varchar(255),notnull,unique"`
	StripeCustomerID sql.NullString `bun:"stripe_customer_id,type:varchar(255),nullzero"`
	ReceiptURL       sql.NullString `bun:"receipt_url,type:varchar(500),nullzero"`
	Status           string         `bun:"status,type:varchar(20),notnull,default:'pending'"`

	User User `bun:"rel:belongs-to,join:user_id=id"`
}

CreditPurchase represents a record of credit purchases via Stripe.

type FacilitatorToken

type FacilitatorToken struct {
	Token      string    `bun:"token,pk"`
	InstanceID string    `bun:"instance_id,notnull"`
	Locations  StrArray  `bun:"locations,type:text"`
	ExpiresAt  time.Time `bun:"expires_at,type:datetime"`
}

type GameContext

type GameContext struct {
	Structure *GameStructure
	// contains filtered or unexported fields
}

GameContext wraps a GameStructure with its service for easy template usage This allows passing a single object that has both data and behavior.

func NewGameContext

func NewGameContext(structure *GameStructure, service GameStructureServiceInterface) *GameContext

NewGameContext creates a new GameContext with structure and service.

func (*GameContext) Color

func (gc *GameContext) Color() string

Color returns the structure's color.

func (*GameContext) CompletionType

func (gc *GameContext) CompletionType() CompletionType

CompletionType returns the structure's completion type.

func (*GameContext) GetAllLocationIDs

func (gc *GameContext) GetAllLocationIDs() []string

GetAllLocationIDs returns all location IDs recursively for this context's structure.

func (*GameContext) GetNextGroup

func (gc *GameContext) GetNextGroup(completedGroups map[string]bool) *GameContext

GetNextGroup returns the next group for this context's structure.

func (*GameContext) GetNextItemType

func (gc *GameContext) GetNextItemType(
	completedLocationIDs map[string]bool,
	completedGroupIDs map[string]bool,
) interface{}

GetNextItemType returns what type of item should be next.

func (*GameContext) GetNextLocation

func (gc *GameContext) GetNextLocation(completedLocationIDs map[string]bool, teamID string) string

GetNextLocation returns the next location for this context's structure.

func (*GameContext) GetSubGroupContext

func (gc *GameContext) GetSubGroupContext(groupID string) *GameContext

GetSubGroupContext returns a GameContext for a specific subgroup by ID.

func (*GameContext) GetSubGroupContexts

func (gc *GameContext) GetSubGroupContexts() []*GameContext

GetSubGroupContexts returns GameContexts for all direct subgroups.

func (*GameContext) ID

func (gc *GameContext) ID() string

ID returns the structure's ID.

func (*GameContext) IsCompleted

func (gc *GameContext) IsCompleted(completedCount int) bool

IsCompleted checks if this context's structure is completed.

func (*GameContext) IsRoot

func (gc *GameContext) IsRoot() bool

IsRoot returns whether this is the root group.

func (*GameContext) Locations

func (gc *GameContext) Locations() []*Location

Locations returns the loaded locations.

func (*GameContext) MinimumRequired

func (gc *GameContext) MinimumRequired() int

MinimumRequired returns the minimum required count.

func (*GameContext) Name

func (gc *GameContext) Name() string

Name returns the structure's name.

func (*GameContext) Navigation

func (gc *GameContext) Navigation() NavigationMode

Navigation returns the structure's navigation method.

func (*GameContext) Routing

func (gc *GameContext) Routing() RouteStrategy

Routing returns the structure's routing mode.

func (*GameContext) SubGroups

func (gc *GameContext) SubGroups() []GameStructure

SubGroups returns the direct subgroups (use GetSubGroupContexts for contexts).

type GameStatus

type GameStatus int
const (
	Scheduled GameStatus = iota
	Active
	Closed
)

func ParseGameStatus

func ParseGameStatus(s string) (GameStatus, error)

ParseGameStatus returns a GameStatus from a string.

func (GameStatus) Description

func (g GameStatus) Description() string

Description returns the description of the GameStatus.

func (GameStatus) String

func (g GameStatus) String() string

String returns the string representation of the GameStatus.

type GameStatuses

type GameStatuses []GameStatus

func GetGameStatuses

func GetGameStatuses() GameStatuses

GetGameStatuses returns a list of game statuses.

type GameStructure

type GameStructure struct {
	ID              string         `json:"id"`
	Name            string         `json:"name"`                       // Empty for root group, required for visible groups
	Color           string         `json:"color"`                      // Empty for root, required for visible groups (e.g., "primary", "secondary")
	Routing         RouteStrategy  `json:"routing"`                    // ordered, randomised, free_roam, secret
	Navigation      NavigationMode `json:"navigation"`                 // map, labelled_map, location_list, custom, tasks
	CompletionType  CompletionType `json:"completion_type"`            // all, minimum
	MinimumRequired int            `json:"minimum_required,omitempty"` // For minimum completion type
	MaxNext         int            `json:"max_next,omitempty"`         // Max locations to show for random routing (0 = unlimited)
	AutoAdvance     bool           `json:"auto_advance"`               // If true, auto-move to next group when CompletionType met
	IsRoot          bool           `json:"is_root"`                    // true ONLY for the invisible root container

	// Storage: locations first, then subgroups - order preserved in arrays
	LocationIDs []string        `json:"location_ids"` // Ordered list of location IDs
	SubGroups   []GameStructure `json:"sub_groups"`   // Ordered list of nested groups

	// Runtime fields - populated by GameStructureService
	Locations []*Location `json:"-"` // Loaded location pointers
	// contains filtered or unexported fields
}

GameStructure represents the hierarchical game state structure

IMPORTANT ARCHITECTURE NOTES:

Order Invariant:

  • LocationIDs are ALWAYS stored before SubGroups
  • Array order is preserved on save/load
  • No explicit ordering fields needed - position in array = order

Root Group Behavior:

  • Every instance has exactly ONE root group (IsRoot: true)
  • The root group is NEVER rendered in the UI
  • The root group acts as an invisible container for:
  • Visible subgroups (rendered as group cards)
  • Ungrouped locations (rendered directly in the root locations area)
  • Root group Name is always empty ("")
  • Root group Color is always empty ("")

Visible Groups:

  • All visible groups in the UI are SubGroups of the root
  • Visible groups have IsRoot: false
  • Visible groups always have a Name and Color
  • Visible groups are rendered as collapsible group cards

Example Structure:

Root (IsRoot: true, Name: "")
├── LocationIDs: ["loc1", "loc2"]  // Rendered in root locations-area
└── SubGroups:
    ├── Group "Museum Tour" (visible group card)
    │   └── LocationIDs: ["loc3", "loc4"]
    └── Group "Historical Sites" (visible group card)
        └── LocationIDs: ["loc5", "loc6"]

func (*GameStructure) IsPopulated

func (gs *GameStructure) IsPopulated() bool

IsPopulated returns whether this group has been populated with location data.

func (*GameStructure) Scan

func (gs *GameStructure) Scan(value any) error

Scan implements the sql.Scanner interface for database unmarshalling.

func (*GameStructure) SetPopulated

func (gs *GameStructure) SetPopulated(populated bool)

SetPopulated marks this group as populated with location data.

func (GameStructure) Value

func (gs GameStructure) Value() (driver.Value, error)

Value implements the driver.Valuer interface for database marshalling.

type GameStructureServiceInterface

type GameStructureServiceInterface interface {
	// Loading methods
	Load(ctx context.Context, instanceID string, group *GameStructure, recursive bool) error
	LoadByLocationID(ctx context.Context, instanceID string, locationID string) (*GameStructure, error)

	// Validation and persistence
	Validate(group *GameStructure, instanceID string) error
	Save(ctx context.Context, instanceID string, group *GameStructure) error

	// Navigation methods
	FindGroupByID(gameStructure *GameStructure, groupID string) *GameStructure
	GetAllLocationIDs(group *GameStructure) []string
	GetNextItemType(
		group *GameStructure,
		completedLocationIDs map[string]bool,
		completedGroupIDs map[string]bool,
	) interface{}
	GetNextLocation(group *GameStructure, completedLocationIDs map[string]bool, teamID string) string
	GetNextGroup(group *GameStructure, completedGroups map[string]bool) *GameStructure
	IsCompleted(group *GameStructure, completedCount int) bool
}

GameStructureServiceInterface defines the methods needed by GameContext.

type ImageSize

type ImageSize struct {
	Breakpoint int    `json:"breakpoint"` // px width for media queries
	URL        string `json:"url"`        // URL to the image
}

ImageSize represents an image variant with a specific breakpoint.

type Instance

type Instance struct {
	CreatedAt time.Time `bun:"created_at,nullzero,notnull,default:current_timestamp"`
	UpdatedAt time.Time `bun:"updated_at,nullzero,notnull,default:current_timestamp"`

	ID                    string        `bun:"id,pk,type:varchar(36)"`
	Name                  string        `bun:"name,type:varchar(255)"`
	UserID                string        `bun:"user_id,type:varchar(36)"`
	IsTemplate            bool          `bun:"is_template,type:bool"`
	TemplateID            string        `bun:"template_id,type:varchar(36),nullzero"`
	StartTime             bun.NullTime  `bun:"start_time,nullzero"`
	EndTime               bun.NullTime  `bun:"end_time,nullzero"`
	Status                GameStatus    `bun:"-"`
	IsQuickStartDismissed bool          `bun:"is_quick_start_dismissed,type:bool"`
	GameStructure         GameStructure `bun:"game_structure,type:string"`

	Teams      []Team           `bun:"rel:has-many,join:id=instance_id"`
	Locations  []Location       `bun:"rel:has-many,join:id=instance_id"`
	Settings   InstanceSettings `bun:"rel:has-one,join:id=instance_id"`
	ShareLinks []ShareLink      `bun:"rel:has-many,join:id=template_id"`
}

Instance represents an entire game state.

func (*Instance) GetStatus

func (i *Instance) GetStatus() GameStatus

GetStatus returns the status of the instance.

type InstanceSettings

type InstanceSettings struct {
	InstanceID        string `bun:"instance_id,pk,type:varchar(36)"`
	MustCheckOut      bool   `bun:"must_check_out,type:bool"`
	ShowTeamCount     bool   `bun:"show_team_count,type:bool"`
	EnablePoints      bool   `bun:"enable_points,type:bool"`
	EnableBonusPoints bool   `bun:"enable_bonus_points,type:bool"`
	ShowLeaderboard   bool   `bun:"show_leaderboard,type:bool"`
	// contains filtered or unexported fields
}

type Location

type Location struct {
	ID           string  `bun:"id,pk,notnull"`
	Name         string  `bun:"name,type:varchar(255)"`
	Slug         string  `bun:"slug,type:varchar(255)"`
	InstanceID   string  `bun:"instance_id,notnull"`
	MarkerID     string  `bun:"marker_id,notnull"`
	Criteria     string  `bun:"criteria,type:varchar(255)"`
	Order        int     `bun:"order,type:int"`
	TotalVisits  int     `bun:"total_visits,type:int"`
	CurrentCount int     `bun:"current_count,type:int"`
	AvgDuration  float64 `bun:"avg_duration,type:float"`
	Points       int     `bun:"points,"`

	Instance Instance `bun:"rel:has-one,join:instance_id=id"`
	Marker   Marker   `bun:"rel:has-one,join:marker_id=code"`
	Blocks   []Block  `bun:"rel:has-many,join:id=owner_id"`
	// contains filtered or unexported fields
}

func (*Location) HasCluesContext

func (l *Location) HasCluesContext() bool

HasCluesContext returns true if the location has any blocks with clues context.

func (*Location) HasCoordinates

func (l *Location) HasCoordinates() bool

HasCoordinates returns true if the location's marker has coordinates.

func (*Location) HasTaskContext

func (l *Location) HasTaskContext() bool

HasTaskContext returns true if the location has any blocks with task context.

type Marker

type Marker struct {
	Code         string  `bun:"code,unique,pk"`
	Lat          float64 `bun:"lat,type:float"`
	Lng          float64 `bun:"lng,type:float"`
	Name         string  `bun:"name,type:varchar(255)"`
	TotalVisits  int     `bun:"total_visits,type:int"`
	CurrentCount int     `bun:"current_count,type:int"`
	AvgDuration  float64 `bun:"avg_duration,type:float"`

	Locations []Location `bun:"rel:has-many,join:code=marker_id"`
	// contains filtered or unexported fields
}

func (Marker) IsMapped

func (m Marker) IsMapped() bool

type MediaType

type MediaType string

MediaType represents the type of media being uploaded.

const (
	MediaTypeImage MediaType = "image"
	MediaTypeVideo MediaType = "video"
)
type NavigationMode = game.NavigationMode

func ParseNavigationMode

func ParseNavigationMode(s string) (NavigationMode, error)

ParseNavigationMode returns a NavigationMode from a string.

type NavigationModes []NavigationMode

func GetNavigationModes

func GetNavigationModes() NavigationModes

GetNavigationModes returns a list of navigation modes.

type Notification

type Notification struct {
	ID        string `bun:"id,pk,notnull"`
	Content   string `bun:"content,type:varchar(255)"`
	Type      string `bun:"type,type:varchar(255)"`
	TeamCode  string `bun:"team_code,type:varchar(36)"`
	Dismissed bool   `bun:"dismissed,type:bool"`
	// contains filtered or unexported fields
}

type Provider

type Provider string
const (
	ProviderGoogle Provider = "google"
	ProviderEmail  Provider = ""
)

type RouteStrategies

type RouteStrategies []RouteStrategy

func GetRouteStrategies

func GetRouteStrategies() RouteStrategies

GetRouteStrategies returns a list of route strategies.

type RouteStrategy

type RouteStrategy = game.RouteStrategy

Type aliases — models re-exports game/ vocabulary so existing callers don't need to update imports. Methods (String, Description) are automatically available via the alias.

func ParseRouteStrategy

func ParseRouteStrategy(s string) (RouteStrategy, error)

ParseRouteStrategy returns a RouteStrategy from a string.

type ShareLink struct {
	bun.BaseModel `bun:"table:share_links"`

	ID              string       `bun:"id,pk,type:varchar(36)"`
	TemplateID      string       `bun:"template_id,type:varchar(36),notnull"`
	UserID          string       `bun:"user_id,type:varchar(36),nullzero"` // Owner of the link
	CreatedAt       time.Time    `bun:"created_at,nullzero"`
	ExpiresAt       bun.NullTime `bun:"expires_at,nullzero"`
	MaxUses         int          `bun:"max_uses,type:int,default:0"` // 0 means unlimited
	UsedCount       int          `bun:"used_count,type:int,default:0"`
	RegenerateCodes bool         `bun:"regenerate_codes,type:bool"`

	Template *Instance `bun:"rel:belongs-to,join:template_id=id"`
}

ShareLink represents a link that can be shared to access a template.

func (*ShareLink) IsExpired

func (s *ShareLink) IsExpired() bool

IsExpired checks if the share link is expired.

type StrArray

type StrArray []string

func (*StrArray) Scan

func (s *StrArray) Scan(value any) error

Scan converts a database JSON string back into a StrArray.

func (StrArray) Value

func (s StrArray) Value() (driver.Value, error)

Value converts StrArray to a JSON string for database storage.

type Team

type Team struct {
	ID              string   `bun:"id,pk"`
	Code            string   `bun:"code,unique"`
	Name            string   `bun:"name,"`
	InstanceID      string   `bun:"instance_id,notnull"`
	HasStarted      bool     `bun:"has_started,default:false"`
	MustCheckOut    string   `bun:"must_scan_out"`
	Points          int      `bun:"points,"`
	SkippedGroupIDs []string `bun:"skipped_group_ids,type:text[],array"`

	Instance         Instance         `bun:"rel:has-one,join:instance_id=id"`
	CheckIns         []CheckIn        `bun:"rel:has-many,join:code=team_code"`
	BlockingLocation Location         `bun:"rel:has-one,join:must_scan_out=marker_id,join:instance_id=instance_id"`
	Messages         []Notification   `bun:"rel:has-many,join:code=team_code"`
	Blocks           []TeamBlockState `bun:"rel:has-many,join:code=team_code"`
	// contains filtered or unexported fields
}

type TeamBlockState

type TeamBlockState struct {
	TeamCode      string          `bun:"team_code,pk,notnull"`
	BlockID       string          `bun:"block_id,pk,notnull"`
	IsComplete    bool            `bun:"is_complete,type:bool"`
	PointsAwarded int             `bun:"points_awarded,type:int"`
	PlayerData    json.RawMessage `bun:"player_data,type:jsonb"`
	// contains filtered or unexported fields
}

type TeamStartLog

type TeamStartLog struct {
	ID         string    `bun:"id,unique,pk,type:varchar(36)"`
	CreatedAt  time.Time `bun:"created_at,nullzero,notnull,default:current_timestamp"`
	UserID     string    `bun:"user_id,notnull,type:varchar(36)"`
	InstanceID string    `bun:"instance_id,notnull,type:varchar(36)"`
	TeamID     string    `bun:"team_id,notnull,type:varchar(36)"`
}

type Upload

type Upload struct {
	bun.BaseModel `bun:"table:uploads,alias:u"`

	ID          string    `bun:"id,pk,notnull"`
	OriginalURL string    `bun:"original_url,notnull"` // Original file link
	Timestamp   time.Time `bun:"timestamp"`
	LocationID  string    `bun:"location_id,nullzero"`
	InstanceID  string    `bun:"instance_id,nullzero"`
	TeamCode    string    `bun:"team_code,nullzero"`
	BlockID     string    `bun:"block_id,nullzero"`
	Storage     string    `bun:"storage,notnull"`
	DeleteData  string    `bun:"delete_data"`
	Type        MediaType `bun:"type"`
	// contains filtered or unexported fields
}

Upload represents a file that has been uploaded to the system.

func (*Upload) AddSize

func (u *Upload) AddSize(breakpoint int, url string) error

AddSize appends a new image size to the existing sizes.

func (*Upload) GetSizes

func (u *Upload) GetSizes() ([]ImageSize, error)

GetSizes retrieves image sizes as a structured list.

type User

type User struct {
	ID                 string         `bun:"id,unique,pk,type:varchar(36)"`
	Name               string         `bun:"name,type:varchar(255)"`
	DisplayName        sql.NullString `bun:"display_name,type:varchar(255),nullzero"`
	Email              string         `bun:"email,unique,pk"`
	EmailVerified      bool           `bun:"email_verified,type:boolean"`
	EmailToken         string         `bun:"email_token,type:varchar(36)"`
	EmailTokenExpiry   sql.NullTime   `bun:"email_token_expiry,nullzero"`
	Password           string         `bun:"password,type:varchar(255)"`
	Provider           Provider       `bun:"provider,type:varchar(255)"`
	ShareEmail         bool           `bun:"share_email,type:boolean,notnull,default:false"`
	WorkType           sql.NullString `bun:"work_type,type:varchar(100),nullzero"`
	FreeCredits        int            `bun:"free_credits,type:int,default:10"`         // Current free credits balance
	PaidCredits        int            `bun:"paid_credits,type:int,default:0"`          // Purchased credits
	MonthlyCreditLimit int            `bun:"monthly_credit_limit,type:int,default:10"` // Monthly free credit allocation
	StripeCustomerID   sql.NullString `bun:"stripe_customer_id,type:varchar(255),nullzero"`

	Instances         []Instance       `bun:"rel:has-many,join:id=user_id"`
	CurrentInstanceID string           `bun:"-"`
	CurrentInstance   Instance         `bun:"-"`
	CreditPurchases   []CreditPurchase `bun:"rel:has-many,join:id=user_id"`
	// contains filtered or unexported fields
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址