chore: bootstrap api-go scaffold

This commit is contained in:
Noel Sabia committed 2026-11-14 04:16:22 +01:00
1 parent aa26549bd1
commit 907164f972
18 files changed
+1919

No files matched your search

+248
View File
@@ -0,0 +1,248 @@
// Package model contains the wire types shared by the HTTP handlers, the
// baked-data store and the FastAPI client. JSON tags mirror CONTRACT.md.
package model
import "time"
// Horizons and enums from CONTRACT.md §1.
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"`
}
// 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"`
}