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

+323
View File
@@ -0,0 +1,323 @@
// Package staffing implements the deterministic decision heuristic from
// CONTRACT.md §5. It never calls the model: it consumes forecast points and
// turns them into an explainable shift plan.
package staffing
import (
"fmt"
"math"
"sort"
"time"
"pulsecast/api/internal/model"
)
// Build creates a plan for one sensor/scenario/standard.
func Build(sensor, scenario, standard string, points []model.ForecastPoint, ctx model.ContextData) (model.StaffingResponse, error) {
perStaff, ok := visitorsPerStaff(standard)
if !ok {
return model.StaffingResponse{}, fmt.Errorf("unknown standard %q", standard)
}
loc, err := time.LoadLocation(model.StoreHours.TZ)
if err != nil {
return model.StaffingResponse{}, fmt.Errorf("load timezone: %w", err)
}
days, err := groupStoreHours(points, loc)
if err != nil {
return model.StaffingResponse{}, err
}
assumptions := model.StaffingAssumptions{
VisitorsPerStaffHour: perStaff,
SafetyFactor: model.SafetyFactor,
MinStaff: model.MinStaff,
ShiftLengthH: model.ShiftLengthHours,
LaborCostEURH: model.LaborCostEURPerHour,
StoreHours: model.StoreHoursSpec{
Open: "10:00",
Close: "20:00",
TZ: model.StoreHours.TZ,
},
}
var hours []model.StaffingHour
var shifts []model.Shift
requiredByDate := make(map[string][]int)
totalCost := 0.0
for _, day := range days {
// Required staff per hour first; blocks need maxima across the day.
required := make(map[int]int, len(day.hours))
for _, h := range day.hours {
req := int(math.Ceil(math.Max(0, h.point.V) / float64(perStaff) * model.SafetyFactor))
if req < model.MinStaff {
req = model.MinStaff
}
required[h.hour] = req
requiredByDate[day.date] = append(requiredByDate[day.date], req)
}
scheduled := make(map[int]int, len(day.hours))
for _, block := range blocks(day.hours) {
staff := 0
for _, h := range block.hours {
if req := required[h.hour]; req > staff {
staff = req
}
}
for _, h := range block.hours {
scheduled[h.hour] = staff
}
shifts = append(shifts, model.Shift{
Date: day.date,
Start: clock(block.start),
End: clock(block.end),
Staff: staff,
})
totalCost += float64(staff) * float64(block.minutes()) / 60 * model.LaborCostEURPerHour
}
for _, h := range day.hours {
req := required[h.hour]
sched := scheduled[h.hour]
coverage := "ok"
switch {
case sched < req:
coverage = "under"
case sched > req:
coverage = "over"
}
hours = append(hours, model.StaffingHour{
T: h.point.T.UTC(),
Footfall: h.point.V,
RequiredStaff: req,
ScheduledStaff: sched,
Coverage: coverage,
})
}
}
if len(hours) == 0 {
return model.StaffingResponse{}, fmt.Errorf("no store-hour forecast points")
}
summary := summarise(hours, requiredByDate, totalCost, loc)
why := explain(days, ctx, scenario, loc)
return model.StaffingResponse{
Sensor: sensor,
Scenario: scenario,
Standard: standard,
Assumptions: assumptions,
Hours: hours,
Shifts: shifts,
Summary: summary,
Why: why,
}, nil
}
func visitorsPerStaff(standard string) (int, bool) {
switch standard {
case "relaxed":
return model.VisitorsPerStaffRelaxed, true
case "standard":
return model.VisitorsPerStaffStandard, true
case "premium":
return model.VisitorsPerStaffPremium, true
default:
return 0, false
}
}
type hourPoint struct {
hour int
point model.ForecastPoint
}
type dayPlan struct {
date string
hours []hourPoint
}
// groupStoreHours keeps only points that fall inside 10:00–20:00 local time,
// first seven local dates, sorted chronologically.
func groupStoreHours(points []model.ForecastPoint, loc *time.Location) ([]dayPlan, error) {
type key struct {
date string
hour int
}
seen := make(map[key]model.ForecastPoint)
var dates []string
dateSet := make(map[string]bool)
for _, point := range points {
local := point.T.In(loc)
if local.Hour() < model.StoreHours.Open || local.Hour() >= model.StoreHours.Close {
continue
}
k := key{date: local.Format("2006-01-02"), hour: local.Hour()}
seen[k] = point
if !dateSet[k.date] {
dateSet[k.date] = true
dates = append(dates, k.date)
}
}
sort.Strings(dates)
if len(dates) > 7 {
dates = dates[:7]
}
days := make([]dayPlan, 0, len(dates))
for _, date := range dates {
day := dayPlan{date: date}
for hour := model.StoreHours.Open; hour < model.StoreHours.Close; hour++ {
if point, ok := seen[key{date: date, hour: hour}]; ok {
day.hours = append(day.hours, hourPoint{hour: hour, point: point})
}
}
// A day is only usable if every store hour has a forecast point.
if len(day.hours) == model.StoreHours.Close-model.StoreHours.Open {
days = append(days, day)
}
}
if len(days) == 0 {
return nil, fmt.Errorf("no complete store-day in forecast")
}
return days, nil
}
type block struct {
start int // local hour
end int // local hour, exclusive
hours []hourPoint
}
func (b block) minutes() int { return (b.end - b.start) * 60 }
// blocks walks the store day in 4-hour chunks; the final chunk is shorter
// (18:00–20:00) rather than extending past closing time.
func blocks(hours []hourPoint) []block {
var out []block
for start := model.StoreHours.Open; start < model.StoreHours.Close; start += model.ShiftLengthHours {
end := start + model.ShiftLengthHours
if end > model.StoreHours.Close {
end = model.StoreHours.Close
}
var inBlock []hourPoint
for _, h := range hours {
if h.hour >= start && h.hour < end {
inBlock = append(inBlock, h)
}
}
if len(inBlock) > 0 {
out = append(out, block{start: start, end: end, hours: inBlock})
}
}
return out
}
func summarise(hours []model.StaffingHour, requiredByDate map[string][]int, totalCost float64, loc *time.Location) model.StaffingSummary {
covered := 0
over := 0
under := 0
for _, h := range hours {
switch {
case h.ScheduledStaff >= h.RequiredStaff:
covered++
}
if h.ScheduledStaff > h.RequiredStaff {
over++
}
if h.ScheduledStaff < h.RequiredStaff {
under++
}
}
maxRequired := 0
for _, reqs := range requiredByDate {
for _, req := range reqs {
if req > maxRequired {
maxRequired = req
}
}
}
flatCost := float64(maxRequired) * float64(len(hours)) * model.LaborCostEURPerHour
coveragePct := 0.0
if len(hours) > 0 {
coveragePct = math.Round(float64(covered)/float64(len(hours))*1000) / 10
}
return model.StaffingSummary{
CoveragePct: coveragePct,
CostEUR: int(math.Round(totalCost)),
FlatScheduleCostEUR: int(math.Round(flatCost)),
OverstaffedHours: over,
UnderstaffedHours: under,
}
}
// explain names the observable weather/holiday context and the scenario
// assumptions. It does not claim causality.
func explain(days []dayPlan, ctx model.ContextData, scenario string, loc *time.Location) []string {
if len(days) == 0 {
return nil
}
first, _ := time.ParseInLocation("2006-01-02", days[0].date, loc)
last, _ := time.ParseInLocation("2006-01-02", days[len(days)-1].date, loc)
var why []string
for _, holiday := range ctx.Holidays {
hDate, err := time.ParseInLocation("2006-01-02", holiday.Date, loc)
if err != nil {
continue
}
if !hDate.Before(first) && !hDate.After(last) {
why = append(why, "Public holiday: "+holiday.Name+" ("+holiday.Date+")")
}
}
var precip float64
var tempSum float64
var n int
for _, point := range ctx.Weather.Forecast {
local := point.T.In(loc)
day := local.Format("2006-01-02")
if day < days[0].date || day > days[len(days)-1].date {
continue
}
precip += point.PrecipMM
tempSum += point.TempC
n++
}
if n > 0 {
avg := tempSum / float64(n)
switch {
case precip >= 5:
why = append(why, fmt.Sprintf("Wet week in the forecast (%.1f mm)", precip))
case precip >= 0.5:
why = append(why, fmt.Sprintf("Some rain in the forecast (%.1f mm)", precip))
default:
why = append(why, "Mostly dry week in the forecast")
}
why = append(why, fmt.Sprintf("Average forecast temperature %.0f°C", avg))
}
switch scenario {
case "sunny-saturday-market":
why = append(why, "Scenario assumes a sunny Saturday market uplift")
case "rainy-saturday":
why = append(why, "Scenario assumes a rainy Saturday")
case "weekday-event":
why = append(why, "Scenario assumes a weekday evening event uplift")
default:
why = append(why, "Base scenario: no weather delta or event uplift")
}
return why
}
func clock(hour int) string {
return fmt.Sprintf("%02d:00", hour)
}