odoo_mqtt/docs/FEATURE_REQUEST_POS_MACHINE_TIME_BILLING.md

Feature Request: PoS Maschinenzeit aus IoT-Sessions übernehmen

Stand: 2026-02-19
Status: Offen (neu)

1) Ziel

In Odoo PoS soll für einen Werkstattnutzer die während seiner Anwesenheit tatsächlich genutzte Maschinenzeit geprüft und in den PoS-Auftrag übernommen werden können, um minutenbasierte Produkte korrekt abzurechnen.

2) Ausgangslage

• Das Modul open_workshop_mqtt erfasst Maschinen-Sessions bereits als ows.mqtt.session inkl. Dauerfeldern (total_duration_min, working_duration_min, standby_duration_min).
• Im PoS wird der Werkstattnutzer bereits erfasst und ein Anwesenheits-Timer gestartet (Zeitfenster vorhanden).
• Es existiert noch kein direkter PoS-Flow zur Übernahme dieser Maschinenzeiten in Orderlines.

3) Fachlicher Scope

In Scope

• Ermittlung passender Maschinen-Sessions pro Werkstattnutzer anhand Zeitüberschneidung:
  • Nutzer-Anwesenheit im PoS ∩ Maschinen-Session (ows.mqtt.session)
• Vorschlagslogik im PoS mit Bestätigung:
  • System schlägt abrechenbare Zeiten vor
  • Nutzer bestätigt und kann den Vorschlag anpassen
• Übernahme in PoS-Orderlines auf Basis minutenbasierter Produkte
• Mehrfachnutzung unterstützen:
  • Bei mehreren passenden Maschinen werden alle passenden Zeiten berücksichtigt (eigene Position pro Maschine/Produkt)

Out of Scope (für diesen Request)

• Vollautomatische, nicht bestätigte Buchung ohne Nutzerinteraktion
• Neuaufbau des Anwesenheits-Timers (gilt als bereits vorhanden)

4) Festgelegte Regeln

1. Abrechnungsbasis: Nur working_duration_min
2. Rundung: Auf Geräte-Abrechnungsintervall runden (z. B. 5 Minuten)
3. Übernahme-UX: Vorschlag + Bestätigung, danach editierbar
4. Zuordnung Nutzer ↔ Session: über Zeitüberschneidung
5. Parallel genutzte Maschinen: alle passenden Maschinen übernehmen

5) Produktzuordnung (Maschine → PoS-Produkt)

• Die Zuordnung soll im Modul gepflegt werden.
• Jedes IoT-Gerät referenziert genau eine „Maschine“ für die Abrechnung.
• Mehrere physische Geräte (z. B. drei 3D-Drucker) dürfen auf dasselbe PoS-Produkt zeigen.

6) Geplantes PoS-Verhalten (MVP)

1. Werkstattnutzer ist im PoS aktiv (Anwesenheitszeitraum vorhanden).
2. Aktion „Maschinenzeit prüfen“ ermittelt Session-Schnittmenge.
3. PoS zeigt Vorschläge je Maschine/Produkt inkl. berechneter Minuten.
4. Nutzer bestätigt/ändert.
5. System erzeugt/aktualisiert PoS-Orderlines mit der finalen Minutenmenge.

UI-Einstieg im PoS (bevorzugt)

• Primärer Einstieg über die Orderline des minutenbasierten Produkts:
  • Doppelklick auf Orderline oder Info-Icon in der Orderline-Liste
  • Öffnet ein vorhandenes PoS-Popup (wiederverwendet/erweitert)
• Im Popup:
  • Vorschläge aus Sessions anzeigen (Maschine, Zeitraum, berechnete Minuten)
  • Sessions auswählen/abwählen
  • Übernehmen in die aktuelle Orderline bzw. Order
• Nach Übernahme bleibt die Orderline normal editierbar im Standard-PoS-Flow.

Optionaler Sekundär-Einstieg

• Produkt-Info-„i“ kann optional als zusätzlicher Einstieg dienen, ist aber nicht der Hauptweg für die tägliche Bedienung.

7) Akzeptanzkriterien

• Für einen Nutzer mit Anwesenheitszeitraum werden passende Maschinen-Sessions korrekt ermittelt.
• Es werden nur working_duration_min für die Abrechnung verwendet.
• Minuten werden gemäß Geräte-Intervall gerundet.
• Vorschläge sind im PoS sichtbar, bestätigbar und modifizierbar.
• Bei mehreren passenden Maschinen entstehen mehrere korrekte Positionen.
• Wenn keine passende Session gefunden wird, entsteht keine automatische Position und der Nutzer erhält einen klaren Hinweis.

8) Technische Hinweise für die Umsetzung

• Bestehende Session-Daten aus ows.mqtt.session wiederverwenden, keine doppelte Zeitlogik aufbauen.
• Produkt-Mapping im Addon modellieren (z. B. Feld/Relation auf Geräte- bzw. Maschinenebene).
• Berechnungslogik für Zeitüberschneidung und Intervall-Rundung zentral kapseln und testbar halten.
• Idempotente Übernahme in PoS berücksichtigen (mehrfaches „Prüfen/Übernehmen“ darf keine unkontrollierten Duplikate erzeugen).

9) Offene Implementierungsdetails (für den Umsetzungsplan)

• Konkrete technische Umsetzung der Orderline-Interaktion (Doppelklick vs. Icon, Touch-Verhalten)
• Exakte Regel, wie bestehende manuelle Orderline-Änderungen bei erneutem Import behandelt werden
• Fehler-/Hinweistexte im PoS bei Konflikten (z. B. überlappende Zeitblöcke mit bereits übernommener Zeit)

10) Modulstrategie und Implementierungsreihenfolge

Option A: Neues Addon für diese Funktion (empfohlen)

• Eigenes Addon nur für Maschinenzeit-Import im PoS (z. B. als Integrationsaddon zwischen MQTT-Sessions und PoS).
• Vorteil:
  • Keine invasive Änderung in bestehendem open_workshop_pos nötig
  • Klarer Scope, kleinere Release-Risiken
  • Schnellere MVP-Lieferung
• Nachteil:
  • Langfristig evtl. Abstimmung mit open_workshop_pos-UX nötig

Option B: Direkt in open_workshop_pos integrieren

• Vorteil:
  • Eine zentrale PoS-Erweiterung
  • Einheitliche UX an einer Stelle
• Nachteil:
  • Höherer Eingriff in bestehende Strukturen
  • Größere Abhängigkeit vom Stand eines externen Repositories

Empfehlung für die Umsetzung jetzt

1. Start mit Option A (neues, kleines Addon) für schnellen MVP.
2. PoS-Orderline-Popup dort implementieren, Session-Vorschläge übernehmen.
3. Später optional in open_workshop_pos konsolidieren, wenn dort ohnehin größere PoS-Refactorings geplant sind.

Konkrete Reihenfolge (MVP)

1. Backend-Service in Odoo: Session-Schnittmenge + Rundung + Mapping liefern.
2. PoS-Frontend: Orderline-Einstieg (Icon/Doppelklick) + Popup zur Auswahl/Übernahme.
3. Idempotenzregeln für wiederholte Übernahme definieren.
4. Tests für Mehrfachmaschinen, Leerfall, Konfliktfall.