setup-go@v5 aborts when go.sum is missing, and this stdlib-only module has none. Disable the action cache and cap the job at 10 minutes. Lead the README with what the service does and a runnable quick start, fix stale contract and cache comments, and remove comments that only restate the code.
281 lines
8.6 KiB
Go
281 lines
8.6 KiB
Go
// Package model contains the wire types shared by the HTTP handlers, the
|
|
// in-memory snapshot cache and the FastAPI client. JSON tags mirror the API
|
|
// contract.
|
|
package model
|
|
|
|
import "time"
|
|
|
|
// Horizons and enums from the API contract.
|
|
var (
|
|
Horizons = []string{"15m", "1h", "48h", "7d"}
|
|
Scenarios = []string{"base", "sunny-saturday-market", "rainy-saturday", "weekday-event"}
|
|
Standards = []string{"relaxed", "standard", "premium"}
|
|
)
|
|
|
|
// Contains reports whether v is in list.
|
|
func Contains(list []string, v string) bool {
|
|
for _, item := range list {
|
|
if item == v {
|
|
return true
|
|
}
|
|
}
|
|
return false
|
|
}
|
|
|
|
// Sensor is one row of GET /api/sensors.
|
|
type Sensor struct {
|
|
ID string `json:"id"`
|
|
Name string `json:"name"`
|
|
Lat float64 `json:"lat"`
|
|
Lon float64 `json:"lon"`
|
|
Mean float64 `json:"mean"`
|
|
P95 float64 `json:"p95"`
|
|
Battery *int `json:"battery"`
|
|
}
|
|
|
|
// Point is one observed series point.
|
|
type Point struct {
|
|
T time.Time `json:"t"`
|
|
V float64 `json:"v"`
|
|
}
|
|
|
|
// ForecastPoint is one forecast point with its 80% band.
|
|
type ForecastPoint struct {
|
|
T time.Time `json:"t"`
|
|
V float64 `json:"v"`
|
|
Lo float64 `json:"lo"`
|
|
Hi float64 `json:"hi"`
|
|
}
|
|
|
|
// Coverage describes the training/observation window.
|
|
type Coverage struct {
|
|
Sensors int `json:"sensors"`
|
|
From string `json:"from"`
|
|
To string `json:"to"`
|
|
CadenceMin int `json:"cadence_min"`
|
|
}
|
|
|
|
// Metrics is the model card headline block exposed by GET /api/meta.
|
|
type Metrics struct {
|
|
Model string `json:"model"`
|
|
MAE float64 `json:"mae"`
|
|
WAPE float64 `json:"wape"`
|
|
R2 float64 `json:"r2"`
|
|
BaselineMAE float64 `json:"baseline_mae"`
|
|
BaselineWAPE float64 `json:"baseline_wape"`
|
|
}
|
|
|
|
// Meta is GET /api/meta.
|
|
type Meta struct {
|
|
DataVersion string `json:"data_version"`
|
|
ModelVersion string `json:"model_version"`
|
|
ContextVersion string `json:"context_version"`
|
|
Coverage Coverage `json:"coverage"`
|
|
Metrics Metrics `json:"metrics"`
|
|
Limits []string `json:"limits"`
|
|
Cache CacheStatus `json:"cache"`
|
|
}
|
|
|
|
// CacheStatus is the runtime snapshot state exposed by GET /api/meta.
|
|
// LastError, LastSuccessAt and NextRetryAt are null when they do not apply.
|
|
type CacheStatus struct {
|
|
Source string `json:"source"`
|
|
LastSuccessAt *time.Time `json:"last_success_at"`
|
|
LastError *string `json:"last_error"`
|
|
NextRetryAt *time.Time `json:"next_retry_at"`
|
|
Failures int `json:"failures"`
|
|
}
|
|
|
|
// BootstrapMeta is the nested meta block of FastAPI GET /bootstrap.
|
|
type BootstrapMeta struct {
|
|
Coverage Coverage `json:"coverage"`
|
|
Metrics Metrics `json:"metrics"`
|
|
Limits []string `json:"limits"`
|
|
}
|
|
|
|
// Bootstrap is the snapshot FastAPI serves at GET /bootstrap and Go keeps in
|
|
// memory. Forecasts are deliberately absent: they come from /predict and are
|
|
// cached separately as they are requested.
|
|
type Bootstrap struct {
|
|
DataVersion string `json:"data_version"`
|
|
ModelVersion string `json:"model_version"`
|
|
ContextVersion string `json:"context_version"`
|
|
Sensors []Sensor `json:"sensors"`
|
|
Series map[string][]Point `json:"series"`
|
|
Context ContextData `json:"context"`
|
|
Meta BootstrapMeta `json:"meta"`
|
|
}
|
|
|
|
// WeatherNow is the current conditions block.
|
|
type WeatherNow struct {
|
|
T time.Time `json:"t"`
|
|
TempC float64 `json:"temp_c"`
|
|
PrecipMM float64 `json:"precip_mm"`
|
|
CloudPct int `json:"cloud_pct"`
|
|
WindKMH float64 `json:"wind_kmh"`
|
|
HumidityPct int `json:"humidity_pct"`
|
|
}
|
|
|
|
// WeatherPoint is one forecast hour.
|
|
type WeatherPoint struct {
|
|
T time.Time `json:"t"`
|
|
TempC float64 `json:"temp_c"`
|
|
PrecipMM float64 `json:"precip_mm"`
|
|
CloudPct int `json:"cloud_pct"`
|
|
WindKMH float64 `json:"wind_kmh"`
|
|
HumidityPct int `json:"humidity_pct"`
|
|
}
|
|
|
|
// Weather groups current conditions and the hourly forecast.
|
|
type Weather struct {
|
|
Now WeatherNow `json:"now"`
|
|
Forecast []WeatherPoint `json:"forecast"`
|
|
}
|
|
|
|
// Holiday is one public holiday (Baden-Württemberg).
|
|
type Holiday struct {
|
|
Date string `json:"date"`
|
|
Name string `json:"name"`
|
|
}
|
|
|
|
// ContextData is the stored context artifact.
|
|
type ContextData struct {
|
|
Weather Weather `json:"weather"`
|
|
Holidays []Holiday `json:"holidays"`
|
|
UpdatedAt time.Time `json:"updated_at"`
|
|
}
|
|
|
|
// ContextResponse is GET /api/context.
|
|
type ContextResponse struct {
|
|
Weather Weather `json:"weather"`
|
|
Holidays []Holiday `json:"holidays"`
|
|
UpdatedAt time.Time `json:"updated_at"`
|
|
Cached bool `json:"cached"`
|
|
}
|
|
|
|
// WeatherInput is the scenario weather override.
|
|
type WeatherInput struct {
|
|
TempDeltaC float64 `json:"temp_delta_c"`
|
|
PrecipMM float64 `json:"precip_mm"`
|
|
}
|
|
|
|
// EventInput is the scenario event override.
|
|
type EventInput struct {
|
|
Type string `json:"type"`
|
|
Uplift float64 `json:"uplift"`
|
|
}
|
|
|
|
// ScenarioInput is the scenario body from POST /api/scenario.
|
|
type ScenarioInput struct {
|
|
Scenario string `json:"scenario"`
|
|
Weather WeatherInput `json:"weather"`
|
|
Event EventInput `json:"event"`
|
|
}
|
|
|
|
// ScenarioState is the current scenario plus its version.
|
|
type ScenarioState struct {
|
|
Version int `json:"version"`
|
|
Scenario ScenarioInput `json:"scenario"`
|
|
At time.Time `json:"at"`
|
|
}
|
|
|
|
// ForecastResponse is GET /api/forecast.
|
|
type ForecastResponse struct {
|
|
Sensor string `json:"sensor"`
|
|
Horizon string `json:"horizon"`
|
|
Scenario string `json:"scenario"`
|
|
Points []ForecastPoint `json:"points"`
|
|
Cached bool `json:"cached"`
|
|
DataVersion string `json:"data_version"`
|
|
ModelVersion string `json:"model_version"`
|
|
ContextVersion string `json:"context_version"`
|
|
}
|
|
|
|
// Staffing assumptions, echoed in every plan.
|
|
const (
|
|
VisitorsPerStaffRelaxed = 35
|
|
VisitorsPerStaffStandard = 25
|
|
VisitorsPerStaffPremium = 18
|
|
SafetyFactor = 1.15
|
|
MinStaff = 1
|
|
ShiftLengthHours = 4
|
|
LaborCostEURPerHour = 16
|
|
)
|
|
|
|
// StoreHours are local Europe/Berlin opening hours.
|
|
var StoreHours = struct {
|
|
Open int
|
|
Close int
|
|
TZ string
|
|
}{Open: 10, Close: 20, TZ: "Europe/Berlin"}
|
|
|
|
// StaffingAssumptions is echoed in the plan so the UI can show them.
|
|
type StaffingAssumptions struct {
|
|
VisitorsPerStaffHour int `json:"visitors_per_staff_hour"`
|
|
SafetyFactor float64 `json:"safety_factor"`
|
|
MinStaff int `json:"min_staff"`
|
|
ShiftLengthH int `json:"shift_length_h"`
|
|
LaborCostEURH int `json:"labor_cost_eur_h"`
|
|
StoreHours StoreHoursSpec `json:"store_hours"`
|
|
}
|
|
|
|
// StoreHoursSpec is the display form of the opening hours.
|
|
type StoreHoursSpec struct {
|
|
Open string `json:"open"`
|
|
Close string `json:"close"`
|
|
TZ string `json:"tz"`
|
|
}
|
|
|
|
// StaffingHour is one hour of the plan.
|
|
type StaffingHour struct {
|
|
T time.Time `json:"t"`
|
|
Footfall float64 `json:"footfall"`
|
|
RequiredStaff int `json:"required_staff"`
|
|
ScheduledStaff int `json:"scheduled_staff"`
|
|
Coverage string `json:"coverage"`
|
|
}
|
|
|
|
// Shift is one contiguous shift block.
|
|
type Shift struct {
|
|
Date string `json:"date"`
|
|
Start string `json:"start"`
|
|
End string `json:"end"`
|
|
Staff int `json:"staff"`
|
|
}
|
|
|
|
// StaffingSummary is the plan headline block.
|
|
type StaffingSummary struct {
|
|
CoveragePct float64 `json:"coverage_pct"`
|
|
CostEUR int `json:"cost_eur"`
|
|
FlatScheduleCostEUR int `json:"flat_schedule_cost_eur"`
|
|
OverstaffedHours int `json:"overstaffed_hours"`
|
|
UnderstaffedHours int `json:"understaffed_hours"`
|
|
}
|
|
|
|
// StaffingResponse is GET /api/staffing.
|
|
type StaffingResponse struct {
|
|
Sensor string `json:"sensor"`
|
|
Scenario string `json:"scenario"`
|
|
Standard string `json:"standard"`
|
|
Assumptions StaffingAssumptions `json:"assumptions"`
|
|
Hours []StaffingHour `json:"hours"`
|
|
Shifts []Shift `json:"shifts"`
|
|
Summary StaffingSummary `json:"summary"`
|
|
Why []string `json:"why"`
|
|
Cached bool `json:"cached"`
|
|
DataVersion string `json:"data_version"`
|
|
ModelVersion string `json:"model_version"`
|
|
ContextVersion string `json:"context_version"`
|
|
}
|
|
|
|
// ErrorBody is the canonical error envelope.
|
|
type ErrorBody struct {
|
|
Error ErrorDetail `json:"error"`
|
|
}
|
|
|
|
// ErrorDetail is the inner error object.
|
|
type ErrorDetail struct {
|
|
Code string `json:"code"`
|
|
Message string `json:"message"`
|
|
}
|