diff --git a/docs/superpowers/specs/2026-09-26-guider-design.md b/docs/superpowers/specs/2026-09-26-guider-design.md new file mode 100644 index 0000000..cc784f0 --- /dev/null +++ b/docs/superpowers/specs/2026-09-26-guider-design.md @@ -0,0 +1,145 @@ +# Guider til opsætning: marker og flows — design + +Dato: 2026-09-26 · Status: udkast til godkendelse · Mod: FS25_ADSmartPickup (v1.30.4.0 → v1.31/v1.32) + +Leveres i to etaper, der hver kan testes for sig: +- **Etape A (v1.31):** fælles guide-ramme + Fields-fanen ("Opsæt mark"). +- **Etape B (v1.32):** Flows-fanen på samme ramme ("Opsæt flow"), så de to faner er ens at bruge. + +## Formål + +Fields-fanen er blevet en lang liste af valg, der er svær at overskue (brugerens ord: "uoverskueligt"). +Målet er, at man sætter en mark op med **ét spørgsmål ad gangen**, og at alt, der kan afgøres automatisk, +aldrig bliver spurgt om. En eksisterende opsætning skal kunne rettes uden at gå hele guiden igennem. + +Succes: brugeren kan sætte F22 op fra bunden på under et minut uden at scrolle, og kan rette ét valg +(fx lager) med to tryk. + +## Hvad brugeren ser + +### Oversigt (fanens standardvisning) + +1. Marktabellen som i dag (Mark · Afgrøde · Plan · Kørsel · Status (kort) · Maskiner). +2. Når en mark er valgt: et **resumé** på én linje pr. emne, hver med sin egen række man kan klikke for at + rette det ene trin ("Ret"): + - Afgrøde: `Behold det der gror` / `-> Hvede` + - Afgrødens valg: `Ensilage, river` / `Halm hakkes` + - Klargøring: `Automatisk` / `Plov, kalk` + - Pleje: `Gødning + ukrudt` + - Maskiner: `3 faste` / `Ledige maskiner` · `1 ad gangen, 1 aflæsningsvogn` + - Lager: `Marksilo` / `Automatisk` / `F22 Silo` + - Status (hele teksten, ombrudt) +3. Knapper i bundlinjen (når en mark er valgt): **[Opsæt mark]**, **[Start nu / Stop]**, **[Markflåde]**. + Uden valgt mark: **[Markflåde]**. +4. Den lange detaljeliste og den fælles markflåde nederst forsvinder fra oversigten. + +### Guide (erstatter fanens indhold, mens den er åben) + +Ét trin pr. skærm: overskrift ("Trin 3 af 7 — Græs: ensilage eller hø?"), en kort forklaring, valgene som +rækker, og bundknapperne **[Næste]** (eller **[Gem]** på sidste trin), **[Tilbage]**, **[Annullér]**. +Trin der ikke er relevante for marken springes over, og tællingen følger de viste trin. + +| # | Trin | Vises når | Valg | Standard | +|---|------|-----------|------|----------| +| 1 | Mark | guiden er åbnet uden valgt mark | liste over marker (nr, afgrøde, status) | — | +| 2 | Afgrøde | altid | "Behold det der gror" + afgrøder der kan sås | nuværende plan | +| 3 | Afgrødens valg | slåafgrøde (nu eller mål): ensilage/hø + river ja/nej. Høstafgrøde med halm: hakkes/samles/presses | se "Vises når" | nuværende plan | +| 4 | Klargøring | altid (efter høst / bar mark) | "Automatisk (anbefalet)" / "Vælg selv" → plov, kultivering, kalk, tromle, mulch | Automatisk | +| 5 | Pleje | afgrøde der gror | gødning ja/nej, ukrudt ja/nej | ja/ja | +| 6 | Maskiner | altid | "Faste maskiner til marken?" ja/nej; ja → liste (kun ledige + dem der allerede er faste her); antal ad gangen (1–5); aflæsningsvogne ved høst (1–5) | nej / 1 / 1 | +| 7 | Lager | høst/slåning | marksilo findes: "Brug marksiloen?" ja/nej; ellers/nej: "Automatisk (anbefalet)" / "Vælg selv" → de 8 nærmeste siloer | Automatisk | +| 8 | Oversigt | altid | resumé med [Ret] pr. linje; [Kør automatisk] (Auto) / [Gem uden at starte] (Manual) | — | + +### Redigering + +- **[Opsæt mark]** på en opsat mark åbner guiden med de nuværende valg udfyldt. +- **[Ret]** på en resumé-linje (oversigt eller trin 8) åbner kun det ene trin; **[Gem]** der gemmer og går + tilbage dit man kom fra. +- **[Annullér]** kasserer ændringer i guiden (intet gemmes før [Gem]/[Kør automatisk]). + +### Markflåde + +Egen visning (knap **[Markflåde]**): "Brug alle ledige maskiner" + listen med flueben, "fast på F22", +"i gang på F108", bredde-advarsler. Samme indhold som i dag, flyttet ud af markens detaljer. + +## Hvad der ALDRIG spørges om (automatisk) + +Scanning af marken og markøren, hvornår der høstes/slås/gødes/sprøjtes, påfyldning (eget lager før køb), +tømning ved forkert vare, ventetid ved regn, bredde-kontrol, valg af nærmeste maskine, ruter, gæringssilo ved +ensilage, marksilo-tømning (advarsel hvis intet flow tømmer den). + +## Etape B: Flows-fanen på samme måde + +Brugerens ønske: "det samme for flow opsætningen så det bliver ensrettet". + +**Oversigt:** flow-tavlen som i dag (én linje pr. flow med status). Valgt flow → resumé med [Ret]-linjer +(Retning · Fra · Til/Lager · Varer · Regler · Vent ved · Traktorer · Status) og bundknapperne +**[Opsæt flow]**, **[Start/Stop]**, **[Nyt flow]**, **[Omdøb]**, **[Slet]**, **[Start alle / Stop alle]**. +Den lange detaljeliste forsvinder. + +**Guiden "Opsæt flow"** — samme trin-skærm, knapper og [Ret]/[Annullér] som markguiden: + +| # | Trin | Vises når | Valg | Standard | +|---|------|-----------|------|----------| +| 1 | Navn | nyt flow | tekst (FS25-tekstdialog) | "Flow N" | +| 2 | Retning | altid | Ind til bygning (forsyning) / Ud fra bygning (udkørsel) | nuværende | +| 3 | Fra / Til | altid | bygninger med markør, fast rækkefølge (navn, markør), "Vis alle" | nuværende | +| 4 | Varer | altid | forsyning: "Automatisk (det bygningen mangler)" / "Vælg selv" → varer; udkørsel: pr. vare Sælg / Lager / Begge / Fra | Automatisk / nuværende | +| 5 | Lager | udkørsel med Lager | "Automatisk (nærmeste med plads)" / "Vælg selv" → lagerbygninger | Automatisk | +| 6 | Regler | altid | udkørsel: sælg ved pris-%, lager over %, samlerunde ja/nej; forsyning: antal ture, retur fra Wait under % | nuværende / standard | +| 7 | Vent ved | altid | Wait-puljer | nuværende | +| 8 | Traktorer | altid | ledige traktorer (+ dem i flowet); traktorer i andre flows skjult med linje "N i andre flows" | nuværende | +| 9 | Oversigt | altid | resumé med [Ret]; [Start flow] / [Gem uden at starte] | — | + +Automatisk (spørges aldrig): markør ved bygningen, rutetjek, bedste foder først/parallelt foder, læs-bytte, +kildevalg (mindst/fyldeste først), fordeling på flere mål, hvile af tomme kilder, traktornavne efter flowet. + +## Arkitektur + +- **`adGuide.lua` (ny, ren Lua, testet):** den fælles guide-motor, uafhængig af marker/flows: + trin-liste, aktuelt trin, kladde, næste/tilbage/spring (til [Ret]), "returnér til oversigt", tælling + "Trin 3 af 7" over de synlige trin. Både markguiden og flowguiden er en trin-definition oven på den. +- **`gui/SmartPickupGuide.lua` (ny):** den fælles trin-skærm i menuen (overskrift, forklaring, valgrækker, + bundknapper Næste/Tilbage/Annullér/Gem) — ét sted, så de to guider ser og opfører sig ens. +- **`adFlowGuide.lua` (ny, etape B, ren Lua, testet):** flowguidens trin, valg, standarder og resumé; gemmer + via `ADRunsController.updateRun`/`assignVehicle` som i dag. +- **`adFieldGuide.lua` (ny, ren Lua, testet):** markguidens trin (oven på `ADGuide`). + - `ADFieldGuide.open(field, info, context)` → guide-tilstand `{fieldId, draft, steps, index, returnTo}`; + `draft` er en kopi af markens plan (+ faste maskiner), så intet ændres før gem. + - `ADFieldGuide.steps(draft, info, context)` → listen af synlige trin (tabellen ovenfor). + - `ADFieldGuide.choices(step, draft, info, context)` → rækkerne for trinnet (tekstnøgler + værdier). + - `ADFieldGuide.choose(guide, key, value)` → ny guide med ændret draft (immutabelt). + - `ADFieldGuide.next/back/jump(guide, step)`; `ADFieldGuide.result(guide)` → `{plan, rigIds}` til gem. + - `ADFieldGuide.summary(field, info, context)` → resumé-linjerne `{step, key, args}`. + - `context` = det spil-afhængige: marksilo findes?, siloer i nærheden, maskiner (ledige/faste), afgrøder + der kan sås. Hentes af GUI'et, så modellen kan testes uden spillet. +- **`gui/SmartPickupFieldTab.lua`:** oversigt (tabel + resumé) og guide-visning; bygger rækker ud fra + `ADFieldGuide`, gemmer via `ADFieldJobs.setPlan` og `ADFieldFleet.dedicate`. Fil-størrelse: guide-visningen + lægges i `gui/SmartPickupFieldGuide.lua` (ny), så ingen fil passerer ~800 linjer. +- **`gui/SmartPickupFrame.lua`:** bundknapper for fanen (Opsæt mark, Start/Stop, Markflåde, Næste/Tilbage/ + Annullér/Gem i guiden) og routing af klik. +- **Uændret:** `ADFieldModel` (plan-felter og lagring), `ADFieldJobs`, `ADFieldWork`, gemt XML. Guiden er et + nyt ansigt på de samme data — eksisterende opsætninger virker videre. + +## Fejl og kanttilfælde + +- Mark uden markør: guiden kan køres, men oversigten siger "sæt markøren F22" og [Kør automatisk] gemmer som + Manual indtil markøren findes (samme regel som i dag). +- Maskine der er fast på en anden mark vises ikke i trin 6 (som v1.30.3); linje "N maskiner er faste på + andre marker". +- Marken forsvinder (solgt/bygget over) mens guiden er åben: guiden lukkes, oversigten vises. +- Guiden er åben og menuen lukkes: kladden kasseres. + +## Test + +- `tests/test_adGuide.lua`: motoren — næste/tilbage over skjulte trin, spring+retur, tælling, annullér. +- `tests/test_adFlowGuide.lua` (etape B): trin pr. retning, varer auto/vælg, lager-trin kun ved Lager, resumé. +- `tests/test_adFieldGuide.lua`: synlige trin pr. marktype (slåafgrøde, høst med halm, bar mark, mål-afgrøde), + standardvalg, udfyldning fra eksisterende plan, `choose` ændrer kun kladden, `result` giver plan + rigIds, + [Ret]-spring og tilbage, "Automatisk" vs "Vælg selv" i klargøring og lager, marksilo-spørgsmålet kun når en + findes, resumé-linjerne. +- Hele suiten skal være grøn; GUI-routing verificeres in-game (testplan-punkt). + +## Uden for scope + +Vinmarker (egne roller), genoptagelse af Courseplay efter genstart, fanerne Factories/Silos/Barns/Pallet sheds.