feat(race-hub): trustworthy defaults and fan-facing analysis hierarchy (#75)

Make bare /race-hub resolve to a completed session and never open empty
post-session analysis for a future race.

- Backend: add `default_analysis_session` to the Weekend context. It never
  resolves to a future session (picks the richest completed session, ties
  toward the later one; 0 when everything is upcoming). Existing
  `default_session_key` and deep links are unchanged.
- Frontend default resolution prefers the most recently completed weekend
  (`pickAnalysisFocusMeeting`) and consumes `default_analysis_session`, falling
  back to the switcher when only upcoming sessions exist.
- New `sessionState` lib maps timing + coverage to user language
  (upcoming/live/preparing/partial/ready/cancelled); the session rail, active
  sub-bar, and WeekendSwitcher now label states instead of raw x/11 counts.
- Future sessions render a purpose-built PreSessionView (expected availability +
  countdown) instead of empty Winner/Podium/Pole/Strategy/Compare cards.
- Analysis navigation regrouped into Story / Analysis / Data & Context; every
  existing tab is preserved. Diagnostics (renamed from Data Status) is now a
  secondary action and the raw dataset strip is hidden behind an explicit
  toggle, so operational coverage no longer precedes fan content.
- Loading/error states offer Retry and a path back to Weekend.

Tests: Go query tests for future-exclusion; Vitest for default selection,
future pre-session, partial state, error/retry, grouped nav, and sessionState;
hermetic Playwright for bare/completed/future/return-to-Weekend; new
race-hub-future visual snapshots. Seed adds a far-future session inside the
Monaco meeting (kept in-meeting so Command Center focus is unaffected).

Note: `default_analysis_session` is an additive field on the existing
`/weekend` contract (no new endpoint), per the spec's "context contract" scope.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-07-12 18:29:34 -04:00
parent 84a9a3579f
commit 7c98489b91
30 changed files with 1055 additions and 144 deletions

View File

@@ -3,11 +3,16 @@ package query
import (
"database/sql"
"errors"
"time"
"github.com/AmanTahiliani/box-box/internal/models"
"github.com/AmanTahiliani/box-box/internal/store"
)
// weekendNow is the clock used to decide whether a session has started. It is a
// package var so tests can pin it deterministically.
var weekendNow = time.Now
// ErrMeetingNotFound is returned when a meeting is not in the local store.
var ErrMeetingNotFound = errors.New("meeting not found")
@@ -25,6 +30,10 @@ type Weekend struct {
Meeting models.Meeting `json:"meeting"`
Sessions []WeekendSession `json:"sessions"`
DefaultSessionKey int `json:"default_session_key,omitempty"`
// DefaultAnalysisSession is the session a fan-facing default landing should
// open. Unlike DefaultSessionKey it never resolves to a future session, so
// bare /race-hub never renders empty post-session analysis.
DefaultAnalysisSession int `json:"default_analysis_session,omitempty"`
}
// ListSeasons returns years with ingested meetings, newest first.
@@ -85,6 +94,7 @@ func (s *Service) GetWeekend(meetingKey int) (Weekend, error) {
out.Source = weekendSource(out.Sessions)
}
out.DefaultSessionKey = pickDefaultSession(out.Sessions)
out.DefaultAnalysisSession = pickDefaultAnalysisSession(out.Sessions, weekendNow())
return out, nil
}
@@ -141,6 +151,51 @@ func pickDefaultSession(sessions []WeekendSession) int {
return sessions[bestIdx].Session.SessionKey
}
// pickDefaultAnalysisSession chooses the session a fan should land on by default.
// It never returns a future session: among sessions that have already started
// (or whose start time is unknown) it prefers the one with the richest local
// dataset coverage, breaking ties toward the later session. When every session
// is still upcoming it returns 0 so callers render a pre-session view instead of
// empty analysis.
func pickDefaultAnalysisSession(sessions []WeekendSession, now time.Time) int {
bestKey := 0
bestScore := -1
var bestStart time.Time
for _, sess := range sessions {
start, ok := parseSessionStart(sess.Session.DateStart)
// Skip sessions that are clearly in the future; unknown start times are
// treated as eligible so historical data without timestamps still works.
if ok && start.After(now) {
continue
}
score := datasetScore(sess.Datasets)
if score > bestScore || (score == bestScore && ok && start.After(bestStart)) {
bestScore = score
bestKey = sess.Session.SessionKey
if ok {
bestStart = start
}
}
}
return bestKey
}
func parseSessionStart(value string) (time.Time, bool) {
if value == "" {
return time.Time{}, false
}
if t, err := time.Parse(time.RFC3339, value); err == nil {
return t, true
}
if t, err := time.Parse("2006-01-02T15:04:05", value); err == nil {
return t, true
}
if t, err := time.Parse("2006-01-02", value[:min(len(value), 10)]); err == nil {
return t, true
}
return time.Time{}, false
}
func datasetScore(datasets map[string]DatasetInfo) int {
score := 0
for _, info := range datasets {