docs: design-spec for flow-tavle (bygningsbaseret opsætning, v1.13)

docs/superpowers/specs/2026-09-23-flow-tavle-design.md

@@ -0,0 +1,92 @@
+# Flow-tavle — design
+
+Dato: 2026-09-23 · Status: godkendt af bruger (grundform valgt: flow-tavle) · Version: v1.13
+
+## Problem
+
+Opsætningen er markør-baseret: brugeren vælger AD-markører som kilder og mål, og moden gætter
+bygningen ud fra markørens geometri (trigger bag næsen, 40 m, 12 m). Fejl viser sig som
+"kilde-markør 10873 er ikke …" i stedet for "Kostald 1", først når run'et starter. Forsyning og
+Udkørsel er to faner med hver sin lange rulleside, Oversigt er en tredje. Brugeren: "det er noget rod".
+
+## Løsning
+
+Én tavle med ét flow pr. række: **Vare · Fra · Til · Regel · Traktorer · Status**. Fra og Til vælges
+som **bygninger**; moden finder selv markøren ved bygningens læsse-/aflæsningstrigger og viser den.
+Redigering sker i en detail-blok under tavlen for det valgte flow. Faner: **Flows** · **Lagre**.
+Motoren (planlægger, hooks, XML-model) er uændret: et flow ER et run; bygninger oversættes til
+markører når run'et startes og planlægges.
+
+Fravalgt: "Bygninger først" (runs implicit → svært at se hvad der kører) og "Sætnings-run"
+(mindst ændring, men fanerne forbliver adskilte).
+
+## 1. Bygninger (`adBuildings.lua`, spil-adapter)
+
+`ADBuildings.list(adEnv, farmId)` → liste af bygninger gården kan bruge:
+
+```
+{ id, name, kind = "factory"|"silo"|"husbandry"|"objectStorage"|"sell",
+  placeable, loadMarker = {id, name, distance} | nil, unloadMarker = {…} | nil,
+  canBeSource = bool, canBeTarget = bool, canSell = bool }
+```
+
+- Kilde: fabrik, silo, stald (læssestation), objektlager. Mål (forsyning): stald, fabrik.
+  Salg: SellingStation der er et rigtigt salgssted (ikke fabrikkers/staldes indleveringer).
+  Siloer og palleskure er automatiske lagermål (som i dag) og vælges ikke.
+- `id` = `placeable.uniqueId`; mangler det, `"pos:" .. afrundet x/z`.
+- Markør-opslag: for hver AD-markør (Wait-markører udelukket) afstanden til bygningens
+  læsse-triggere (loadTriggers.triggerNode) og aflæsnings-triggere (unloadTriggers exactFillRootNode/
+  triggerNode/aiNode) samt objektlagerets/pallespawnerens node; nærmeste ≤ 40 m vinder.
+  Siloer bruger det strenge opslag (bag næsen) for læssemarkøren, som i dag.
+- Én scanning pr. sekund højst (cache), da fanen spørger ved hver opdatering.
+- `ADBuildings.find(adEnv, farmId, id)`, `ADBuildings.byMarker(adEnv, farmId, wayPointId)` (omvendt
+  opslag til migration).
+
+## 2. Model
+
+Run får `sourceBuildingIds` og `targetBuildingIds` (lister af bygnings-id). De eksisterende
+`sourceWayPointIds`/`targetWayPointIds` bevares som **afledte** felter: controlleren udfylder dem fra
+bygningerne ved Start og ved hver plan (`ADRunsController.resolveMarkers(adEnv, run)`), så
+planlægger og hooks er uændrede. XML-version 3 skriver `#sourceBuildings`/`#targetBuildings`;
+version 2-filer læses, og bygninger udledes fra markørerne ved første indlæsning
+(`ADBuildings.byMarker`); kan en markør ikke oversættes, beholdes den som rå markør.
+
+Forsyning: Fra = "alle siloer" (ingen valg; sources er alle markører som i dag). Til = bygninger.
+Udkørsel: Fra = bygninger. Til = politik pr. vare (Lager/Salg/Salg, ellers lager) — målet vælges
+automatisk pr. tur som i dag.
+
+## 3. Fanen Flows
+
+**Tavle** (øverst, tekstrækker, én pr. run, den valgte markeret med "▶"):
+`Mælk · Kostald 1 + Kostald 2 → Mejeri (salg) · pris ≥ 90 % · Virtus · venter: 42 % af top`
+- Vare: run'ets varer (forsyning auto = "behov"), Fra/Til = bygningsnavne (+ "!" hvis en bygning
+  mangler markør), Regel = kort tekst, Traktorer = navne, Status = én linje (som Oversigt i dag:
+  kører/holder/venter/begrundelse/advarsel).
+- Under tavlen: Wait-puljer (som i dag) og en linje "Vælg flow ovenfor for at rette".
+
+**Detail-blok for valgt flow** (efter tavlen; run-vælgeren `Flow:` er en MultiTextOption):
+- *Retning*: Ind til bygning / Ud fra bygning (klonet Ja/Nej-række).
+- *Fra* (kun Ud): afkrydsning pr. bygning der kan være kilde: `Kostald 1 (stald) — markør 'cow 1 milk' 12 m` eller `— INGEN MARKØR inden for 40 m`.
+- *Til* (kun Ind): afkrydsning pr. stald/fabrik med samme markørtekst.
+- *Varer*: Ind: Auto/Vælg + afkrydsning; Ud: politik pr. vare med mængde og pris-% (som i dag).
+- *Regler*: Ind: ture, kør hjem under; Ud: sælg fra, lager over, saml op.
+- *Vent ved*: Wait-pulje.
+- *Traktorer*: som i dag (låst når vognen ikke passer).
+- Knapper: Nyt flow / Omdøb / Slet / Start-Stop (som i dag). Nyt flow spørger navn og starter som "Ind".
+
+Fanen **Lagre** uændret. Oversigt og de to gamle faner udgår.
+
+## 4. Validering og fejl
+
+- Bygning uden markør: rækken siger det, tavlen viser "!" ved navnet, Start afviser med
+  `noMarker:<bygning>` i statuslinjen ("Kostald 2 mangler en AD-markør ved mælketanken").
+- Bygning der er forsvundet (solgt): udgår af listen; run'et beholder id'et og viser "(mangler)".
+- Alle eksisterende afvisningsgrunde uændrede.
+
+## 5. Tests
+
+- `adBuildings`: kind pr. placeable, markør-opslag (nærmeste ≤ 40 m, Wait udelukket, silo strengt),
+  byMarker, id-fallback.
+- model: v3 roundtrip, v2-migration med byMarker-oversættelse, rå markør bevares.
+- controller: resolveMarkers udfylder waypoint-lister; noMarker-validering; Start med bygninger.
+- GUI in-game (savegame 3 og 2).