Zum Hauptinhalt springen

Flow-Refactor-Plan — Auftrags-Flow „Phasen first-class" (OP-R3-1)

Typ: Refactor-/Umsetzungsplan (Entscheidungsgrundlage). Setzt die Empfehlung aus Flow-Analyse.md konkret um. Bezug: OP-R3-1 (Standard-Prozess & Klärfälle), OP-R4-3 (Pflicht-Doku je Schrittwechsel), Lastenheft §5.1. True North: schärft Frage 2 („Wo stehen die Fahrzeuge — auch in der Bearbeitung?"). Status: ✅ PR 1–7 alle umgesetzt (06-25, Branch claude/workflow-reservation-pickup-6m2q37). Folge-Ausbau (Klärungs-Workflow-Engine, Foto/Perspektiven/KI-Doku, Lifecycle-Status abholbereit, „Aufbereiten starten" ins Flow-Band, Gantt-Legende auf Phase) als eigene OPs.

Context​

Die Analyse hat als Kernursache identifiziert: Das System mischt zwei orthogonale Achsen — Lifecycle/Reservierung (Zustand) und fachliche Phase (wo im Werkstatt-Prozess) — in eine gefühlte Kette; es kollabiert Anlieferung ≠ Annahme auf einen Status und modelliert QS doppelt (Status fertiggestellt + Teilschritt ts-qm) bzw. verwechselt End- und Nachkontrolle. Ziel des Refactors: die fachliche Phase als First-Class-Konzept, sauber aus den Teilschritten abgeleitet (kein Derived State gespeichert), und eine konsistente visuelle Sprache über alle Ansichten.

Zielmodell (Leitentscheidung)​

  • Achse 1 — Lifecycle/Reservierung bleibt (geplant…archiviert, reservierungsmodus()), unverändert in der Bedeutung. Reservierung wird NIE als „Flow-Schritt" dargestellt, sondern als orthogonale Härte-Anzeige.
  • Achse 2 — Fachliche Phase wird First-Class: neues Enum Phase = 'annahme' | 'aufbereitung' | 'produktion' | 'qs' als Tag am Teilschritt-Master. „Abholung" ist kein Arbeits-Phasen-Tag, sondern der Lifecycle-Übergang fertiggestellt → abgeschlossen (so wird die Doppeldeutigkeit aufgelöst).
  • Aktuelle Phase wird abgeleitet, nicht gespeichert: aus dem laufenden bzw. nächsten offenen Teilschritt + dessen phase-Tag (Erweiterung von bearbeitungsphase(), server/src/insights/insights.ts:120). Die fragile erledigt?-Heuristik im Flow-Band entfällt (client/src/app/leitstand/flow-band.component.ts:28-43).
  • Anlieferung ≠ Annahme: angeliefert bleibt = „Fahrzeug physisch da" (Lifecycle). Annahme wird ein echter erster Standard-Teilschritt (Phase annahme, mit Doku-Pflicht). „Da, aber noch nicht angenommen" = angeliefert ∧ Annahme-Schritt noch nicht erledigt.
  • End- vs. Nachkontrolle: Endkontrolle/QS = Teilschritt mit Phase qs (vor Abholung); Nachkontrolle = Lifecycle kontrolliert (nach Abholung). Flow-Band-Mapping kontrolliert ↔ Abholung wird korrigiert.

Umsetzung in PRs (inkrementell, jeweils CI-grün)​

PR 1 — Phase als Teilschritt-Tag (Datenmodell, additiv & risikoarm) — ✅ UMGESETZT​

  • server/src/model/types.ts:188 (interface Teilschritt): Feld phase?: Phase (F-Feld, z. B. R3b-F13) + Enum Phase (taxonomieartig, aber logik-tragend für die Ableitung → fix, G-1-Ausnahme analog zu abhaengigkeit).
  • server/src/model/seed.ts: bestehende Standard-Teilschritte taggen (ts-wash=aufbereitung, Produktionsschritte=produktion, ts-qm=qs).
  • Migration: SCHEMA_VERSION 10→11 in server/party/leitstand.ts:620; idempotenter Remap, der untaggte persistierte Teilschritte anhand bekannter IDs/Namen auf eine Phase setzt (Fallback produktion). Muster wie bestehende v3/v9-Migrationen (leitstand.ts:769, :801).
  • Verifikation: npm run test:teilplan + Server-Smoke; keine Client-Änderung.

PR 2 — Annahme/QS als echte Standard-Teilschritte (OP-R3-1-Kern) — ✅ UMGESETZT (Annahme als Doku-Schritt, nicht solver-geplant)​

  • server/src/model/seed.ts: Standard-Teilschritte ts-annahme (Phase annahme, Default am Prozessanfang) und Bestätigung von ts-qm als Phase-qs-Standardschritt am Ende. Ressourcen/Skill/Zeit minimal modelliert (löst „Annahme/Endausgabe sind keine Teilschritte"-Altvereinfachung auf, vgl. Lastenheft §5.1/:525).
  • Solver-Auswirkung prüfen: Annahme als Park-/Kurzschritt (schedule.ts:407-Parkbedarf bereits vorgesehen) — Annahme soll Buchten nicht unnötig blockieren (G-3: < 15 Min wird nicht verplant → ggf. als nicht-verplanter Doku-Schritt führen).
  • Verifikation: npm run spike|operativ|solve|test:teilplan.

PR 3 — Einheitliche Phasen-Ableitung (eine Quelle der Wahrheit) — ✅ UMGESETZT​

  • server/src/insights/insights.ts:120 bearbeitungsphase() um die Phase-Achse erweitern: zusätzlich zur sprechenden Schritt-Phrase die kanonische Phase des laufenden/nächsten Schritts liefern (z. B. { phase, label }).
  • server/party/leitstand.ts:624 toAuftragDTO: phase: Phase ins DTO aufnehmen (abgeleitet, nicht gespeichert — Prinzip „Derived State nie speichern" gewahrt).
  • Verifikation: npm run operativ + Insights-Demo (insights-demo.ts).

PR 4 — UI: konsistente Flow-Sprache (UX-Kern) — ✅ UMGESETZT (Flow-Band/Orders/Detail lesen DTO-Phase; „Aufbereiten starten" offen)​

  • client/.../flow-band.component.ts:28-110: Heuristik raus, Station aus DTO-phase. Mapping korrigieren: QS-Station = Phase qs aktiv/offen; Abholung-Station = fertiggestellt→abgeschlossen (nicht kontrolliert).
  • Gemeinsame Primitives (Design-System, design/COMPONENTS.md): ein Phasen-Indikator
    • getrennter Status/Reservierung-Badge, wiederverwendet in flow-band, orders.component.ts:95-109 (Timeline), auftrag-detail-panel.component.ts:247-292 und Gantt-Legende. Terminklasse visuell klar von Phase trennen.
  • „Aufbereiten starten" in den Flow holen: Aktion zusätzlich am Flow-Band/Detail-Panel anbieten, nicht nur auf occupancy.component.ts:36.
  • Verifikation: ng build + No-Hex-/Token-Gate (scripts/check-no-hex.sh); visuell gegen lokalen PartyServer (leer + Seed) wie in HANDOFF-Routine.

PR 5 — QS-Freigabe & Nachkontrolle sauber verdrahten — ✅ UMGESETZT (minimal, ohne neuen Status)​

  • client/.../pages/quality.component.ts: „Freigeben" entkoppeln vom direkten abholen-Sprung; kontrolliert (Nachkontrolle) nicht mehr überspringen. Klarstellen: QS = Endkontrolle vor Abholung (Phase qs + bestehende QM-gated-Release/Mängel, leistung.ts:Mangel), kontrollieren = optionale Nachkontrolle nach Abholung.
  • Verifikation: end-to-end PartyServer (fertiggestellt → Freigabe → abgeschlossen → optional kontrolliert).

PR 6 — Klärfälle-Prozess (OP-R3-1, zweiter Teil) — ✅ UMGESETZT (Abbruch + Klärfall-Kontext + Skill; Re-Entry-Routing offen)​

  • server/src/operativ/auftrag.ts:28-48: Aktion abbrechen + Terminal-Status abgebrochen ergänzen (S-6 erweitern); pausiert um Klärfall-Kontext (Eskalations-/Grund-Feld) anreichern.
  • Skill „Klärung" seeden (server/src/model/seed.ts); Wieder-Einstiegs-Routen (zurück / Sprung zu QS / anderer Schritt / Abbruch) auf Teilschritt-Ebene.
  • Migration: SCHEMA_VERSION-Bump; bestehende Aufträge unverändert (additiv).
  • Verifikation: npm run operativ|replan.

PR 7 — Pflicht-Doku-Gates je Phasenwechsel (OP-R4-3) — ✅ UMGESETZT (Kommentar-Gate; Foto/Perspektiven/KI offen)​

  • Gate auf erledige()/Phasenwechsel: mind. 1 Kommentar (+ konfigurierbare Foto-Perspektiven je Teilschritt). Speicherung als Chronik/Protokoll-Eintrag (Auftrag.protokoll, auftrag.ts:157).
  • Verifikation: end-to-end; Gate blockiert Abschluss ohne Doku.

Reihenfolge & Risiko​

  • PR 1–3 sind additiv/abwärtskompatibel (Tag + Ableitung) → niedriges Risiko, sofort Wert (verlässliche Phase statt Heuristik). PR 4–5 sind UX/Verdrahtung. PR 6–7 sind die größeren fachlichen Erweiterungen.
  • Migrationen: jeder schemaverändernde PR bumpt SCHEMA_VERSION mit idempotentem Remap (Muster leitstand.ts:753-801); Altdaten verlustfrei.
  • Nicht-Ziele: keine Änderung an Reservierungs-Semantik (weich/hart/keine), keine Scheduler-Zielfunktionen, keine ungefragten Refactorings (CLAUDE.md).

Audit-Trail bei Umsetzung (verbindlich)​

Je PR: CHANGELOG.md (Datum · PR · Entscheidung), HANDOFF.md (OP-R3-1/OP-R4-3 Status), docs/fachlich/Lastenheft.md §5.1 + OP-Einträge, docs/betrieb/Sanity-Checkliste.md (Frage 2), docs/betrieb/Timesheet.md.

Referenzen​

  • server/src/model/types.ts:188 — Teilschritt-Master (Ziel des phase-Tags)
  • server/src/model/seed.ts — Standard-Teilschritte (Annahme/Aufbereitung/QS)
  • server/src/operativ/auftrag.ts:18-61,238-268 — Lifecycle, transition, reservierungsmodus
  • server/src/insights/insights.ts:120 — bearbeitungsphase() (Ableitungs-Single-Source)
  • server/party/leitstand.ts:620-668,748-818 — DTO + Migrationen
  • client/src/app/leitstand/flow-band.component.ts:28-110 — 5-Stationen-Mapping
  • client/.../pages/quality.component.ts · pages/occupancy.component.ts:16-42

↩ Zurück zur Doku-Landkarte · Lesepfade · Register (alle OPs)