feat: ADSupplyPlanner — behovsrangering og ingrediensliste-tilstand

2026-09-21 12:51:04 +02:00
parent 7e42b93b4f
commit a7d7d7815f
3 changed files with 343 additions and 0 deletions
@@ -0,0 +1,221 @@
+# Behovsstyret forsyning Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Én AutoDrive-traktor holder alle input i en produktion (fx TMR-blander) fyldt ved selv at vælge vare + kilde-silo pr. tur.
+
+**Architecture:** Den eksisterende wrapper om `ADMultipleTargetsManager.getNextPickup` udvides: ved >1 valgt vare i AD læses aflæsningsmålets lager, ingredienserne rangeres efter behov (rene funktioner i ny fil), og en kilde findes blandt alle AD-markører. AD's varevalg indsnævres til én vare pr. tur og gendannes når AD stopper.
+
+**Tech Stack:** Lua 5.1 (FS25 mod-sandbox), luajit til tests med håndskrevne mocks, AutoDrive 3.0.1.2 via global `FS25_AutoDrive`.
+
+**Spec:** `docs/superpowers/specs/2026-09-21-behovsstyret-forsyning-design.md`
+
+## Global Constraints
+
+- Rør aldrig `FS25_AutoDrive.zip`; al adgang via den globale `FS25_AutoDrive`-tabel.
+- Enhver fejl i spil-/AD-API → `Logging.warning` + AutoDrives originale `getNextPickup`. Aldrig crash.
+- Præcis én valgt vare → opførsel uændret; de 11 eksisterende tests forbliver grønne.
+- Markør↔station-tærskel: 40 m (`MAX_MARKER_TO_TRIGGER_DISTANCE`). `MIN_FREE_LITERS = 1000`.
+- Rene funktioner muterer ikke input (returnér nye tabeller).
+- Tests køres fra repo-roden: `luajit tests/<fil>.lua`. Commits uden Co-Authored-By.
+- Verificerede AD-fakta: `selectedFillTypes` er et array-felt på stateModule og gemmes i savegame; `setFillType(ft)` bevarer valget hvis `ft` er i det; `isActive()`, `getSecondMarker()`, `raiseDirtyFlag()` findes; `ADGraphManager:getMapMarkers()` returnerer array indekseret på `markerIndex`.
+
+---
+
+### Task 1: `adSupplyPlanner.lua` — rene funktioner
+
+**Files:**
+- Create: `FS25_ADSmartPickup/adSupplyPlanner.lua`
+- Test: `tests/test_adSupplyPlanner.lua`
+
+**Interfaces:**
+- Produces (global tabel `ADSupplyPlanner`):
+  - `MIN_FREE_LITERS` (number)
+  - `scoreNeed(level, capacity, freeSpace) -> number` (højere = mere trængende)
+  - `rankNeeds(needs) -> ranked` hvor `needs = {{fillType, level, capacity}, …}` og `ranked = {{fillType, level, capacity, freeSpace, score}, …}` sorteret mest trængende først, uden dem med `freeSpace < MIN_FREE_LITERS`
+  - `resolveIngredients(state, selected) -> ingredients|nil` hvor `state = nil | {ingredients = {ft…}, narrowedTo = ft}`
+  - `copyList(list) -> ny liste`
+
+- [ ] **Step 1: Skriv fejlende test** — `tests/test_adSupplyPlanner.lua`:
+
+```lua
+-- Kør: luajit tests/test_adSupplyPlanner.lua   (fra repo-roden)
+dofile("FS25_ADSmartPickup/adSupplyPlanner.lua")
+
+local HAY, GRASS, SILAGE = 20, 21, 22
+local failures = 0
+local function check(name, actual, expected)
+    if actual == expected then
+        print("OK   " .. name)
+    else
+        failures = failures + 1
+        print(string.format("FAIL %s: forventede %s, fik %s", name, tostring(expected), tostring(actual)))
+    end
+end
+
+-- scoreNeed: tommere lager scorer højere; ugyldig kapacitet giver 0
+check("tomt scorer højere end halvfuldt", ADSupplyPlanner.scoreNeed(0, 1000, 1000) > ADSupplyPlanner.scoreNeed(500, 1000, 500), true)
+check("kapacitet 0 giver score 0", ADSupplyPlanner.scoreNeed(0, 0, 0), 0)
+
+-- rankNeeds: mest trængende først, fulde springes over, input muteres ikke
+local needs = {
+    {fillType = HAY, level = 80000, capacity = 100000},
+    {fillType = GRASS, level = 20000, capacity = 100000},
+    {fillType = SILAGE, level = 99500, capacity = 100000},
+}
+local ranked = ADSupplyPlanner.rankNeeds(needs)
+check("fuld ingrediens springes over", #ranked, 2)
+check("mest trængende først", ranked[1].fillType, GRASS)
+check("dernæst næstmest trængende", ranked[2].fillType, HAY)
+check("freeSpace beregnes", ranked[1].freeSpace, 80000)
+check("input muteres ikke", needs[1].freeSpace, nil)
+check("tom liste giver tom liste", #ADSupplyPlanner.rankNeeds({}), 0)
+
+-- rankNeeds: deterministisk ved lige score (laveste fillType først)
+local tie = ADSupplyPlanner.rankNeeds({
+    {fillType = SILAGE, level = 0, capacity = 5000},
+    {fillType = HAY, level = 0, capacity = 5000},
+})
+check("lige score -> laveste fillType først", tie[1].fillType, HAY)
+
+-- resolveIngredients
+local multi = {HAY, GRASS}
+local resolved = ADSupplyPlanner.resolveIngredients(nil, multi)
+check("multi-valg bliver ingrediensliste", #resolved, 2)
+check("listen er en kopi", resolved ~= multi, true)
+check("enkelt-valg uden tilstand -> nil", ADSupplyPlanner.resolveIngredients(nil, {HAY}), nil)
+local state = {ingredients = {HAY, GRASS, SILAGE}, narrowedTo = GRASS}
+check("indsnævret valg genbruger gemt liste", #ADSupplyPlanner.resolveIngredients(state, {GRASS}), 3)
+check("bruger valgte andet -> nil", ADSupplyPlanner.resolveIngredients(state, {HAY}), nil)
+check("nyt multi-valg erstatter gemt liste", #ADSupplyPlanner.resolveIngredients(state, {HAY, SILAGE}), 2)
+check("ugyldigt valg -> nil", ADSupplyPlanner.resolveIngredients(state, nil), nil)
+
+print(failures == 0 and "\nALLE TESTS OK" or ("\n" .. failures .. " FEJL"))
+os.exit(failures == 0 and 0 or 1)
+```
+
+- [ ] **Step 2: Kør og se den fejle** — `luajit tests/test_adSupplyPlanner.lua` → fejler med "cannot open FS25_ADSmartPickup/adSupplyPlanner.lua".
+
+- [ ] **Step 3: Implementér** — `FS25_ADSmartPickup/adSupplyPlanner.lua`:
+
+```lua
+-- AD Supply Planner
+-- Rene funktioner (ingen spil-API) til behovsstyret forsyning: hvilken ingrediens
+-- har aflæsningsmålet mest brug for, og hvilken ingrediensliste gælder for køretøjet.
+
+ADSupplyPlanner = {}
+
+-- Mindre fri plads end dette i målet regnes som "fuldt" (undgår ture med læs der ikke kan komme af).
+ADSupplyPlanner.MIN_FREE_LITERS = 1000
+
+function ADSupplyPlanner.copyList(list)
+    local copy = {}
+    for index, value in ipairs(list) do
+        copy[index] = value
+    end
+    return copy
+end
+
+-- Hvor meget trænger målet til denne ingrediens? Højere = hentes først.
+-- Alle tal er liter i aflæsningsmålets lager. Standard: relativ tomhed (0..1),
+-- så en lille næsten-tom tank vinder over en stor halvfuld.
+function ADSupplyPlanner.scoreNeed(level, capacity, freeSpace)
+    if capacity <= 0 then
+        return 0
+    end
+    return freeSpace / capacity
+end
+
+-- needs: {{fillType, level, capacity}, ...}. Returnerer NY liste, mest trængende først;
+-- ingredienser uden plads i målet er sorteret fra.
+function ADSupplyPlanner.rankNeeds(needs)
+    local ranked = {}
+    for _, need in ipairs(needs) do
+        local freeSpace = need.capacity - need.level
+        if freeSpace >= ADSupplyPlanner.MIN_FREE_LITERS then
+            table.insert(ranked, {
+                fillType = need.fillType,
+                level = need.level,
+                capacity = need.capacity,
+                freeSpace = freeSpace,
+                score = ADSupplyPlanner.scoreNeed(need.level, need.capacity, freeSpace),
+            })
+        end
+    end
+    table.sort(ranked, function(a, b)
+        if a.score ~= b.score then
+            return a.score > b.score
+        end
+        return a.fillType < b.fillType
+    end)
+    return ranked
+end
+
+-- state: nil eller {ingredients, narrowedTo} fra forrige tur. selected: AD's aktuelle varevalg.
+-- >1 valgt = (ny) ingrediensliste. Præcis den vare vi selv indsnævrede til = gemt liste.
+-- Alt andet = brugeren har valgt noget andet -> nil (behovsstyring fra).
+function ADSupplyPlanner.resolveIngredients(state, selected)
+    if type(selected) ~= "table" then
+        return nil
+    end
+    if #selected > 1 then
+        return ADSupplyPlanner.copyList(selected)
+    end
+    if state ~= nil and #selected == 1 and selected[1] == state.narrowedTo then
+        return ADSupplyPlanner.copyList(state.ingredients)
+    end
+    return nil
+end
+```
+
+- [ ] **Step 4: Kør tests** — `luajit tests/test_adSupplyPlanner.lua` → `ALLE TESTS OK`.
+
+- [ ] **Step 5: Commit** — `git add FS25_ADSmartPickup/adSupplyPlanner.lua tests/test_adSupplyPlanner.lua && git commit -m "feat: ADSupplyPlanner — behovsrangering og ingrediensliste-tilstand"`
+
+---
+
+### Task 2: Integration i `adSmartPickup.lua`
+
+**Files:**
+- Modify: `FS25_ADSmartPickup/adSmartPickup.lua` (hele filen omstruktureres let; se kode)
+- Test: `tests/test_adSmartPickup.lua`
+
+**Interfaces:**
+- Consumes: `ADSupplyPlanner.rankNeeds`, `.resolveIngredients`, `.copyList` (Task 1).
+- Produces: `ADSmartPickup.choosePickup(adEnv, driver) -> choice|nil` med `choice = {markerIndex, markerName, group, level, fillType?, need?}`; `ADSmartPickup.findLeastFilledPickup` returnerer nu samme `choice`-tabel (uden `fillType`).
+
+- [ ] **Step 1: Udvid test-mocks og skriv fejlende tests** i `tests/test_adSmartPickup.lua`:
+  - `dofile("FS25_ADSmartPickup/adSupplyPlanner.lua")` før `adSmartPickup.lua`.
+  - `unloadStations`-liste + `getUnloadingStations` i `g_currentMission.storageSystem`; nulstilles i `resetWorld()`.
+  - `getMapMarkers = function() return markers end` i `ADGraphManager`-mock.
+  - `getSecondMarker = function() return nil end` i `makeDriver` (rigtig AD har den altid).
+  - Nye helpers `makeUnloadStation(node, x, z, levels, capacities, placeable, isBroken)` og `makeSupplyDriver(firstMarker, secondMarker, fillTypes)` (muterbar stateModule-mock med `setFillType`, `raiseDirtyFlag`, `isActive`).
+  - Tests S1–S9 (se Step 1-koden i implementeringen; dækker spec'ens testliste).
+
+- [ ] **Step 2: Kør og se de nye fejle** — `luajit tests/test_adSmartPickup.lua` → S-tests FAIL, de 11 gamle OK.
+
+- [ ] **Step 3: Implementér** — i `adSmartPickup.lua`:
+  - `supplyState = setmetatable({}, {__mode = "k"})` (køretøj → `{ingredients, narrowedTo}`).
+  - `getDistanceToTriggers(triggers, nodeFields, x, z)` + `getClosestStation(stations, triggersField, nodeFields, wayPoint, farmId)`; `getLoadStationAtMarker` (felt `loadTriggers`, node `triggerNode`) og `getUnloadStationAtMarker` (felt `unloadTriggers`, noder `exactFillRootNode`, `triggerNode`, `aiNode`).
+  - `collectMarkerStations(adEnv, candidateMarkers, farmId, excludedPlaceable)` → `{{marker, station}, …}`; `findLeastFilled(markerStations, fillTypes, farmId)` → `choice|nil` (eksisterende eget-lager-først-rangering).
+  - `getTargetNeeds(station, ingredients, farmId)`: pr. understøttet ingrediens summeres `storage:getFillLevel(ft)` og `storage:getFreeCapacity(ft)` over `station.targetStorages`; `capacity = level + free`. Ingen storages → `station:getFreeCapacity(ft, farmId)` som `capacity`, `level = 0`.
+  - `ADSmartPickup.findSupplyPickup(adEnv, driver, ingredients)`, `applySupplyChoice(driver, ingredients, choice)` (`setFillType`, `selectedFillTypes = {ft}`, `raiseDirtyFlag`, gem tilstand), `ADSmartPickup.choosePickup` (supply → ellers mappe-logik → ellers nil).
+  - Hook bruger `choice.group` til AD's rotations-bogføring og logger vare + behov ved supply-valg.
+  - `restoreStoppedVehicles()` kaldt fra `update` (pcall): når `not stateModule:isActive()` og valget stadig er `{narrowedTo}` → `selectedFillTypes = kopi af ingredients` + dirty-flag; tilstand slettes.
+
+- [ ] **Step 4: Kør alle tests** — `luajit tests/test_adSupplyPlanner.lua && luajit tests/test_adSmartPickup.lua` → begge `ALLE TESTS OK`.
+
+- [ ] **Step 5: Commit** — `git add -A && git commit -m "feat: behovsstyret forsyning — én traktor holder alle input fyldt"`
+
+---
+
+### Task 3: Pakning, docs, deploy
+
+**Files:**
+- Modify: `FS25_ADSmartPickup/modDesc.xml` (version `1.1.0.0`, `<sourceFile filename="adSupplyPlanner.lua"/>` FØR `adSmartPickup.lua`, beskrivelse), `README.md`
+
+- [ ] **Step 1:** Opdatér modDesc + README (betjening: multi-vælg varer; begrænsninger fra spec).
+- [ ] **Step 2:** Byg: `cd FS25_ADSmartPickup && zip -qr ../FS25_ADSmartPickup.zip . && cd ..`; verificér med `unzip -l` at begge .lua + modDesc + icon er med.
+- [ ] **Step 3:** Deploy atomisk (spillet kan køre): `cp FS25_ADSmartPickup.zip ~/FS25-data/mods/.FS25_ADSmartPickup.zip.tmp && mv ~/FS25-data/mods/.FS25_ADSmartPickup.zip.tmp ~/FS25-data/mods/FS25_ADSmartPickup.zip`.
+- [ ] **Step 4:** Code-review (ecc:code-reviewer) af diff; ret CRITICAL/HIGH.
+- [ ] **Step 5:** Commit + `git push gitea`. Opdatér memory + Obsidian-noten `projekter/FS25 silo-patches + AD Smart Pickup.md`.