# UDS Projektkarte

Stand: 2026-07-07

Diese Datei ist der Startpunkt fuer die technische Projektdokumentation. Ziel ist, dass zentrale Funktionen nur einmal implementiert werden und spaeter Code, API, DB und Prozesse nachvollziehbar dokumentiert werden koennen.

## Zentrale Frontend-Bausteine

- `public/uds/common.js`
  - API-Wrapper mit CSRF
  - Login/Admin-Pruefung
  - zentrale Topbar: Fabrikat, Health, Lead, Benachrichtigung, Nachrichten, Admin-Update, Profil
  - zentraler Signatur-Handoff `showSignatureHandoff`
  - globaler MVP-Assistent `MACS Coach` unten rechts mit Chatfenster und Prozess-Hervorhebung
  - Session-Heartbeat

- `public/uds/workshop-renderers.js`
  - gemeinsames Auftrags-ViewModel fuer WS-Auftrag
  - Renderer fuer Kundenauftrag/PDF und Werkstatt-Tabletansicht
  - gruppiert Arbeitswerte, Textpositionen und Teilepositionen fuer verstaendliche Kundenkommunikation

- `public/uds/workshop-doc.css`
  - Druck-/PDF-Layout fuer Kundenauftrag
  - Touch-Layout fuer Werkstatt-Tablet

- `public/uds/navigation.js`
  - DMS- und Admin-Menue
  - zentrale Seitenliste fuer Schnellzugriffe

- `public/uds/profile-ui.js`
  - Profilmenue-Erweiterungen und mobile Profilbedienung

## Signatur

- API: `api/signature-handoff.php`
- Kunden-/Tablet-Seite: `public/sign-pad.html`
- Uebersicht: `public/signatures.html`
- Zentrale UI-Funktion: `showSignatureHandoff` in `public/uds/common.js`
- Bestehende Signatur-Links erneut anzeigen: `showSignatureHandoffLink` in `public/uds/common.js`
- Eingebunden in:
  - `public/workshop-order-detail.html`
  - `public/workshop-order-customer.html`
  - `public/workshop-tablet.html`
  - `public/wizard-ws-order.html`
  - `public/sales-orders.html`
  - `api/sales-document-preview.php`
- WS-Auftraege uebergeben beim Signatur-Handoff eine Dokument-Momentaufnahme. Dadurch kann `public/sign-pad.html` den Kundenauftrag anzeigen, ohne die interne DMS-Maske als iFrame zu verwenden.
- `public/signatures.html` bietet Statusfilter, Suche nach Kunde/Auftragsnummer/Kennzeichen/VIN und Aktionen fuer offene oder unterschriebene Dokumente.

## UDS Assistent

- Zentrale Implementierung: `public/uds/common.js`
- MVP-Name: MACS Coach
- Funktion: Prozessfragen beantworten, relevante Menuepunkte hervorheben, spaeter KI-/Voice-/Guided-Workflow-Anbindung.
- Aktuelle Regelantworten: WS-Auftrag anlegen, Unterschriften finden, Support oeffnen.

Naechster Ausbau:
- lokale QR-Code-Erzeugung statt externer QR-Bilddienst
- eIDAS-/fortgeschrittene Signaturstrategie
- Verbindung mit Dokumentenarchiv und finaler PDF-Version

## Dokumentenmanagement

- API: `api/documents.php`
- UI: `public/documents.html`
- Online-Check-in: `public/online-checkin.html`

MVP-Fokus:
- Dokumentindex
- Prozess-/Kunden-/Fahrzeugbezug
- Hash und Audit-Metadaten
- Aufbewahrungslogik als Feld
- spaetere Storage-Adapter fuer lokal, NAS, S3/Azure/Cloud

Produktiv-Ziele fuer Deutschland:
- DSGVO: Berechtigungen, Zweckbindung, Auskunft, Loeschkonzept
- Revisionssicherheit: unveraenderbare Versionen, Audit-Trail, Exportfaehigkeit
- DATEV-Pro-Export mit Beleg-Link
- keine Inselloesung, sondern Bestandteil von Kunde, Fahrzeug, Auftrag, Signatur und Kommunikation

## Mazda Gateway

- Token/OAuth: `api/mazda-token.php`, `api/mazda-oauth-callback.php`, `public/mazda-gateway.html`
- OSB: `api/mazda-osb.php`, `public/bookings.html`
- Teile/Product: `api/mazda-parts.php`, `public/parts.html`, `public/manufacturers.html`
  - Teileauskunft und Preis: `/parts/partnumbers/{part-number}`, `/parts/partnumbers/{part-number}/price`
  - Teilestamm-Download: `/parts/search`
  - Wareneingang/Ladelisten: `/parts/deliveries`
  - Serien/Carlines: `/products/carlines`
- Rueckrufaktionen: `api/mazda-vehicle-campaigns.php`, eingebunden in Fahrzeuge und WS-Auftrag
- SIEBEL: im lokalen Mazda-Swagger-Katalog aktuell nicht als eigener Gateway-Endpunkt gefunden. MACS enthaelt aber Siebel-Felder, z. B. `ADR.SiebelID`, `ADR.SiebelIDTyp` und Kampagnen-Abgleich.

## MACS/Hybrid

- MACS DB-Zugriff zentral ueber API-Dateien mit Firebird-Verbindung aus `api/session.php` und `api/config.php`
- Inventur: `api/inventory-macs.php`, `public/inventory.html`
- Teilebestellung: `api/parts-orders.php`, `public/parts-ordering.html`
- Teilelager Zusatzfunktionen: `public/parts-planstock.html`, `public/parts-valuation.html`; erreichbar ueber `Weitere Funktionen` in `public/parts.html`
- Fahrzeug-Auftraege: `api/vehicle-sales-orders.php`, `public/sales-orders.html`
- WS-Auftraege: `api/workshop-orders.php`, `api/workshop-order-detail.php`, `public/orders.html`, `public/workshop-order-detail.html`
- WS-Kundenauftrag: `public/workshop-order-customer.html`
- WS-Tabletansicht: `public/workshop-tablet.html`

## Mobile Lagerprozesse

- Mobiles Lager Hub: `public/mobileinventory.html`
- Operative Inventur mit MACS-Zaehlliste, Offline-Cache und Scanner: `public/inventory.html`
- Wareneingang: `public/goods-receipt.html`
- Fahrzeugschein Scanner: `public/vehicle-document-scanner.html`
- OCR: Tesseract.js ist im Scanner als Browser-OCR integriert. Fuer echten Offline-Betrieb muss die Bibliothek samt Sprachdaten lokal ueber die PWA gecacht werden.

## PWA und Benachrichtigungen

- Service Worker: `public/service-worker.js`
- PWA-Helper: `public/uds/pwa.js`
- Push-Test MVP: `public/push-test.html`, erreichbar im Admin-Center unter Monitoring.
- Aktuell: lokale Test-Benachrichtigung ueber Service Worker und Notification API.
- Produktiv-Ausbau: Web-Push mit VAPID, Subscription-Speicherung je Benutzer/Geraet, Versand-Queue, Opt-in/Opt-out und Audit.

## Kommunikation

- Kommunikations-Center: `public/communication-center.html`
- API: `api/communication-center.php`
- MVP: Regeln fuer WS-Terminbestaetigung, WS-Erinnerung, Fahrzeug-Angebotsnachkontakt, Probefahrt-Nachfassung und Voicebot-Zielbild.
- Produktiv-Ausbau: Provider-Adapter fuer E-Mail, SMS, WhatsApp Business API, Telefonanlage/Voicebot und eine echte Versand-Warteschlange mit Opt-in/Opt-out, DSGVO-Protokollierung und Fehlermanagement.

## Hilfe und Support

- Support-Zentrale: `public/help.html`
- Alias/Einstieg: `public/support.html`
- API: `api/support-tickets.php`
- MVP: Ticketanlage, Status, Kommentare, offene/geschlossene Filter, AnyDesk-Link, Support-Telefon, E-Mail und Chat-Einstieg.
- Mazda Ticketsystem: im lokalen Gateway-Katalog aktuell kein bestaetigter Ticket-/Support-Endpunkt gefunden; deshalb nur als geplanter Integrationsstatus sichtbar.

## UDS Betreiber-/Cloud-Ansicht

- Admin-Seite: `public/uds-cloud.html`
- API: `api/uds-cloud-tenants.php`
- Zielbild: DSGVO-konforme Betreiberansicht fuer Cloud-Hosting, Mandanten, Konfiguration, Supportzugriff, Backup- und Update-Status.

## Datenpflege und externe Integrationen

- Datenpflege UI: `public/data-maintenance.html`
- DAT3/SilverDAT: DAT bietet oeffentlich SilverDAT, VIN, Daten via Schnittstelle und Schnittstellenpartnerschaft an. Frei verfuegbare DAT3-API-Details/Credentials liegen im Projekt nicht vor; Integration braucht Partnerunterlagen.
- Adress-/Telefonabgleich: nur mit klarer Rechtsgrundlage, Protokollierung und DSGVO-Konzept produktiv aktivieren.

## Offene Architekturentscheidungen

- QR-Code lokal erzeugen
- DMS Storage-Adapter entwerfen
- Rollen-/Rechtemodell fuer Dokumente und Signatur
- Versionierung von Dokumenten
- API-Kontrakt fuer Online-Check-in und Kundenportal
- spaetere neue UDS-Datenbank und MACS-Migrations-/Hybridstrategie

## Hersteller- und Modulfreischaltung

- Zielmodell: keine separaten Produktivtabellen wie `PARTS_HYUNDAI`, `PARTS_MAZDA` oder `PARTS_KIA`.
- Teile, Preise, Bestaende und Herstellerdaten sollen in gemeinsamen Tabellen mit `manufacturer_id`, `fabricat_id`, `tenant_id`, `source_system` und eindeutigen externen Schluesseln liegen.
- Herstellerfreischaltungen gehoeren in eine Betreiber-/Cloud-Schicht: Mandant, Standort, Hersteller/Fabrikat, aktive Module, Connector-Konfiguration, Laufzeit, Sperrstatus.
- Herstellerspezifische Zusatzdaten sollen als Connector-Konfiguration oder Rohdaten-/Payload-Tabelle gespeichert werden, nicht als kopierte Tabellenstruktur je Marke.
- Vorteil: einheitliche Suche, Reporting, Lagerbewertung, Bestellvorschlag und Migration; die Modularisierung passiert ueber Rechte, Module und API-Adapter.

## Mazda Werkstattprozess Zielbild

- Termin kommt rein, Serviceberater sucht hybrid nach Kunde, Fahrzeug, Kennzeichen oder VIN in UDS und MACS.
- Wenn vorhandene Gateway-Endpunkte existieren, reichert UDS den Auftrag mit Mazda-Daten an: Serviceaktionen, Teile-/Preisinfos, OSB-Kontext und weitere bestaetigte Endpunkte.
- WS-Auftrag wird vor dem Termin angelegt: Kunde, Fahrzeug, Annahme, geplante Fertigstellung, Serviceberater, optionale Monteur-Vorplanung, Arbeitspositionen, Teilebedarf, Mobilitaet, Kunden- und interne Hinweise.
- Teilebedarf wird auf freie Menge gegen Lagerbestand und Reservierungen geprueft. Fehlteile laufen 7 Tage vor Termin in den Bestellvorschlag.
- Mazda-Originalteile sollen im Bestellvorschlag als Planauftrag laufen, sobald die MACS-/Gateway-Auftragsart eindeutig validiert ist.
- Wareneingang bewertet betroffene Auftraege neu: vollstaendig verfuegbar = `Fertig zum Start`, teilweise verfuegbar = `Teile teilweise verfuegbar`, fehlend = `Teiledisposition offen` oder `Teile bestellt`.
- Jede automatische Statusaenderung braucht Audit: alter Status, neuer Status, Zeitpunkt, Benutzer/Systemprozess und Ursache.