chore: bootstrap api-go scaffold
This commit is contained in:
1 parent
aa26549bd1
commit
907164f972
18 files changed
+1919
No files matched your search
@@ -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)
|
||||
}
|
||||
Reference in new issue
Block a user