# KZDD: Excel-Datenquelle am Windows-PC anbinden

**Paketstand 1.1:** Die lokale Ordnerabsicherung verändert nur die Zugriffsrechte. Besitzer und Windows-Überwachungseinstellungen werden nicht angefasst. Dadurch benötigt dieser Schritt keine besondere `SeSecurityPrivilege`-Berechtigung. Bei einer abgebrochenen Einrichtung das neue Paket frisch entpacken und `Installieren.cmd` unter demselben Windows-Konto erneut starten.

**Vorbereitet, noch nicht auf eurem PC installiert.** Von hier aus ist kein Zugriff auf `\\dc1kzdd\daten` möglich. Der tatsächliche Windows-, Netzwerk- und Dauerbetriebstest muss nach der Installation bei euch erfolgen.

Die verbindliche Quelle ist:

`\\dc1kzdd\daten\AAverkauf\Lagerabverkauf\Eingabe-Datenbank.xlsx`

Der PC prüft die gespeicherte Datei jede Minute. Ein neuer Datenstand wird per HTTPS an den Katalog übertragen; der erste Stand und konflikthafte Änderungen bleiben dort zunächst zur Administrator-Prüfung. `pending` bedeutet ausdrücklich **noch nicht aktiv**. Ungültige/teilweise gelesene Dateien werden nicht übertragen. Bestehende Online-Buchungen dürfen nicht durch den Excel-Import überschrieben werden.

## Installation

1. Das Paket in einen lokalen Ordner entpacken. Nur **einen** PC für den automatischen Abgleich einrichten.
2. Unter dem Windows-Konto anmelden, das die Netzwerkfreigabe lesen kann. Die Excel-Datei einmal über den Explorer öffnen und den vollständigen Dateinamen prüfen.
3. Im Katalog als Administrator **Datenabgleich → PC-Zugangsschlüssel erstellen** öffnen. Dieses Token ist ein technischer Zugang und kein Mitarbeiterpasswort.
4. `Installieren.cmd` doppelt anklicken. Katalogadresse und Dateipfad mit Enter übernehmen oder korrigieren. Das Token unsichtbar eingeben.
5. Die Einrichtung prüft und überträgt die Datei einmal. Nur nach erfolgreicher Quelldaten-Prüfung richtet sie die Windows-Aufgabe ein. Einen gemeldeten Fehler beim separaten Buchungsabruf zusätzlich beheben.
6. `Abgleich-Status.html` über den angezeigten Pfad öffnen. Im Katalog den ersten Datenstand kontrollieren und freigeben. Danach den Abgleich mit einer kleinen, nachvollziehbaren Änderung in Excel erneut prüfen.

Für einen manuellen Test nach der Installation: `Start-Test.cmd`. Der Test verwendet dieselbe Anmeldung und kann ebenfalls einen neuen Datenstand zur Prüfung übertragen.

## Wann läuft der Abgleich?

- Jede Minute und nach der Anmeldung des installierenden Windows-Benutzers.
- Nur solange dieser Benutzer angemeldet und der PC eingeschaltet ist. Ein gesperrter Bildschirm beendet die Anmeldung nicht.
- Bei ausgeschaltetem PC, abgemeldetem Benutzer oder fehlender Netzwerkverbindung läuft keine verlässliche Synchronisierung. Nach Wiederherstellung wird erneut geprüft.
- Keine Parallelverarbeitung: Windows ignoriert zusätzliche Starts während eines laufenden Vorgangs; eine lokale Dateisperre schützt auch manuelle Starts.
- Keine Excel- oder Python-Installation für den Leser erforderlich. Voraussetzung: Windows PowerShell 5.1, übliche .NET-/Windows-Aufgabenplanungsfunktionen und eine lesbare, unverschlüsselte XLSX-Datei.

## Regeln für die Excel-Datei

Das Blatt muss exakt **Eingabe-Datenbank** heißen. Die erste nichtleere Zeile muss die eindeutigen Spaltenüberschriften enthalten, ohne leere Zwischenüberschriften und ohne Rand-Leerzeichen:

`Id-Nr#`, `Bezeichnung`, `Hersteller`, `Artikelbezeichnung`, `Warengruppe`, `Lager bzw# Zustand`, `Lagerplatz`, `Unser Preis`, `Eknetto`, `Stück Ist`, `Freigeben Verkauf`, `KV-Nr#`, `Name`, `Warenausgang`.

Weitere Spalten bleiben erhalten. Optional ist **Online-Buchungs-ID** für die ausdrückliche Zuordnung einer Online-Verkaufsposition. Bei einer nachweislich ausgebuchten Mehrstückposition ist zusätzlich **Online-Buchungsmenge** möglich; bei positiver Ist-Menge muss sie exakt der Ist-Menge entsprechen.

- `Id-Nr#`: stabile, positive und eindeutige Ganzzahl. Bestehende IDs nicht neu vergeben.
- `Stück Ist`: ausdrücklich eingetragene Ganzzahl ab 0. Leere Mengen sind Fehler; es gibt keinen Rückfall auf alte Mengen. Ein vollständig leerer Datenstand wird nicht übertragen.
- `Freigeben Verkauf`: steuert die Freigabe der freien Menge zum Verkauf. Nicht freigegebene Quellenmengen bleiben als interner Bestand erhalten.
- Artikelnummern (`Bezeichnung`) und KV-Nummern vorzugsweise als **Text** speichern. Text-Nullen und reine Zahlenformate wie `000000` bleiben erhalten. Nullen, die Excel bereits entfernt hat, lassen sich nicht rekonstruieren.
- Datumszellen werden aus dem Excel-Datumssystem in ein eindeutiges ISO-Datum umgewandelt. Gespeicherte Formelergebnisse werden gelesen. Fehlende Ergebnisse oder Excel-Fehler stoppen den Import. Vor dem Speichern Formeln in Excel vollständig berechnen lassen.
- Änderungen müssen **gespeichert** sein. Noch nicht gespeicherte Excel-Eingaben stehen dem Abgleich nicht zur Verfügung.

Der Leser erstellt eine temporäre lokale Kopie und vergleicht Dateigröße und Änderungszeit davor/danach. Wird währenddessen gespeichert, versucht er es bis zu dreimal kurz erneut. Er verändert oder überschreibt die Excel-Datei nicht.

## Online-Buchungen am PC prüfen

Nach jeder Prüfung wird unabhängig von der Quelldatei der Online-Buchungsstand abgerufen. Im lokalen Rechnerordner liegen:

| Datei | Zweck |
|---|---|
| `Online-Buchungen.csv` | Schreibgeschützter Prüfauszug mit Verkäufen und Ausbuchungen, Menge, KV, Zeitpunkt, Bearbeiter und Online-Buchungs-ID. Wird bei erfolgreichem Abruf neu erstellt. |
| `Prüfbericht.json` | Strukturierte Serverantwort, Quellenfehler und getrennte Fehler des Buchungsabrufs. |
| `Abgleich-Status.html` | Lesbare Statusanzeige mit aktiver/wartender Revision. Für neue Werte Browser aktualisieren. |
| `Abgleich.log` | Ablauf-/Fehlerprotokoll, UTC-Zeit. Ein älteres Log wird bei etwa 5 MB als `.alt` aufbewahrt. |

Ordner: `%LOCALAPPDATA%\KZDD-Lagerabgleich\Rechner\<PC-Name>`.

**Die CSV ist keine zweite Bestandsquelle und wird nicht zurück in Excel geschrieben.** Prüfe neue Online-Verkäufe anhand ihrer Buchungs-ID. Soll ein Online-Verkauf in der Excel-Kommission übernommen werden, muss die passende Verkaufspositions-ID ausdrücklich in `Online-Buchungs-ID` der entsprechenden Kommissionszeile stehen, mit passender Artikelzuordnung und KV-Nummer. Eine ähnliche Stückzahl oder bloße Mengenänderung ist keine Bestätigung. Die Katalog-Prüfung entscheidet über Konflikte; nicht einfach Bestände erhöhen, um Abweichungen auszugleichen.

Ausgelieferte reservierte Mengen dürfen nicht nochmals vom freien Bestand abgezogen werden. Eine Terminangabe allein bestätigt keine tatsächlich erfolgte Auslieferung. Die vorhandene Ausbuchung und ihr Protokoll bleiben maßgeblich.

Wenn der Buchungsabruf scheitert, bleibt eine ältere CSV erhalten und der Status nennt sie ausdrücklich nicht aktualisiert. Eine erfolgreich übertragene Excel-Datei wird dadurch nicht nachträglich als fehlgeschlagen behandelt.

## Token und Entfernen

Das Token wird mit Windows-DPAPI für den angemeldeten Benutzer verschlüsselt, außerhalb der Netzwerkfreigabe gespeichert und nur beim HTTPS-Aufruf kurz im Arbeitsspeicher entschlüsselt. Lokale Programm-/Konfigurations-/Berichtsordner sind für diesen Benutzer und Windows SYSTEM berechtigt. Das Token nicht per E-Mail verschicken oder in die Excel-Datei schreiben. Die Konfiguration kann nicht auf ein anderes Konto kopiert werden; dort neu einrichten.

`Entfernen.cmd` entfernt die Windows-Aufgabe und die lokale Token-Konfiguration. Berichte bleiben erhalten. Das Token anschließend auch im Katalog widerrufen. Für vollständige lokale Bereinigung kann `Entfernen.ps1 -DeleteLocalData` unter demselben Konto ausgeführt werden. Die Excel-Datei und Katalogdaten werden dabei nicht gelöscht.

## Technische Übergabe an die Agentur

Default-Katalog: `https://kzdd-lagerkatalog.kuechendresden.chatgpt.site`. Die Einrichtung erlaubt eine andere HTTPS-Domain ohne Änderung der Programme.

- `POST /api/sync`, Header `X-KZDD-Sync-Token`.
- Neuer Stand: JSON mit `action: "snapshot"`, `sourceFile`, `fileHash` (SHA-256), `sourceModifiedUtc`, `machine`, `rows` mit allen Originalspalten.
- Unverändert: JSON mit `action: "heartbeat"`, `sourceFile`, `fileHash`, `machine`.
- Erfolgreiche Antwort: `status` = `pending`, `applied` oder `unchanged`; dazu `revision`, `warnings`, `errors`, `summary`.
- Fehler: HTTP-Fehler mit `error` und `errors` bzw. `details`. Kein neuer Hash-Zwischenstand nach fehlgeschlagenem Import.
- `GET /api/sync/ledger`, derselbe Token; Antwort mit `sales`, `dispatches`, `activeRevision`, `pendingRevision`, `status`.
- Der Token muss ausschließlich diese begrenzten Synchronisationsfunktionen erlauben. Kein öffentlich lesbarer Token, keine Umgehung der Mitarbeiterrechte.

Die Skripte wurden statisch geprüft. Ein Windows-/PowerShell-Ausführungstest und Zugriff auf die tatsächliche Netzwerkdatei sind hier nicht erfolgt. Fachliche Übernahme-/Konflikttests gehören zur Abnahme des Katalogs nach der Installation.

## Prüfung vor dem ersten Start

In der bisherigen Excel-Kopie fehlen bei den Inventur-IDs **5138 bis 5145** die Werte in **Stück Ist**. Diese aktuellen Mengen vor der ersten Übertragung vor Ort prüfen und ausdrücklich eintragen. Nicht pauschal 0 oder 1 einsetzen. Auch bereits bestätigte Katalogkorrekturen, insbesondere Nolte AB-1 und Bora XBO, mit der tatsächlichen aktuellen Excel-Datei abgleichen. Mehrere Inventur-IDs derselben Kataloggruppe benötigen einheitliche Stammdaten; widersprüchliche Daten werden abgewiesen. Der erste Stand wird erst nach Prüfung im Katalog aktiv.