# Technische Spezifikation

Diese Datei fixiert die aktuelle Library- und Technologieauswahl des PC-Visit Filetrackers.

## Laufzeit und Projektverwaltung

- **Programmiersprache:** Python `>=3.13`
- **Paket- und Umgebungsverwaltung:** `uv`
- **Projektdefinition:** `pyproject.toml`
- **Umgebung einrichten:** `uv sync`
- **Programm starten:** `uv run main.py ...`
- **Betriebssystem:** Windows

## Verwendete Libraries

### Externe Libraries

- **Typer `>=0.27.1`**
  - CLI-Einstiegspunkt in `main.py`
  - Commands werden mit `@app.command(...)` registriert.
- **watchdog `>=6.0.0`**
  - Rekursive Überwachung des XML-Verzeichnisses
  - Verwendung von `Observer`, `FileSystemEventHandler` und XML-Eventfiltern

### Python-Standardbibliothek

- `xml.etree.ElementTree` für XML-Verarbeitung
- `csv` für CSV-Dateien
- `pathlib.Path` für Pfade und Dateisystemzugriffe
- `dataclasses.dataclass` für typisierte Rückgabeobjekte
- `datetime` und `decimal.Decimal` für Zeit- und Dauerberechnungen
- `shutil` für Dateioperationen

Weitere externe Libraries werden nur ergänzt, wenn die Standardbibliothek oder die bestehenden Libraries die Aufgabe nicht angemessen lösen können.

## Architektur

- `main.py` ist ausschließlich der Typer-Einstiegspunkt und orchestriert Commands.
- Fachlogik liegt in separaten Modulen:
  - `clients.py`
  - `files.py`
  - `move_files.py`
  - `archive_logs.py`
  - `session_details.py`
  - `summary.py`
  - `watch.py`
  - `info.py`
- `run`-Funktionen liefern Dataclasses statt unbenannter Tupel zurück.
- Gemeinsame Abläufe werden als Python-Funktionen wiederverwendet und nicht über CLI-Aufrufe als Subprozesse verkettet.

## Datenformate

- CSV-Trennzeichen: Semikolon (`;`)
- CSV-Encoding: `latin-1`
- Nicht darstellbare Zeichen beim Schreiben: Ersetzung statt Abbruch
- CSV-Dateien liegen im Ordner `data`:
  - `data/clients.csv`
  - `data/files.csv`
  - `data/session_details.csv`
  - `data/summary.csv`

## XML-Verarbeitung

- Standardverzeichnis:
  `%USERPROFILE%\AppData\Roaming\pcvisit Data\Session History`
- XML-Dateien werden rekursiv durchsucht.
- Dateien mit dem Muster `sessions*.xml` werden ignoriert.
- XML-Dateien ohne erwartetes `Session`-Element werden übersprungen.
- Archivierte Logs liegen unter `Archiv\<Jahr>`.
- `session-details` durchsucht zusätzlich den Archivordner.

## CLI-Commands

- `clients`: erzeugt bzw. aktualisiert `clients.csv`.
- `files`: ermittelt vorhandene `ReceivedFile`-Dateien.
- `move-files`: aktualisiert zuerst `files.csv` und verschiebt Dateien nach `Desktop\PC-Visit\<Kunde>`.
- `archive-logs`: archiviert abgeschlossene bzw. alte XML-Logs.
- `session-details`: sammelt `UserActivity`-Einträge.
- `summary`: aggregiert `session_details.csv` und zeigt eine aktuelle Zeitübersicht.
- `info`: führt `clients`, `archive-logs`, `session-details` und `summary` aus.
- `watch`: überwacht XML-Dateien und startet bei Änderungen den Move-Ablauf.

Neue Commands werden in `main.py` registriert und erhalten ein eigenes Modul für ihre Fachlogik.

## Dateisystemregeln

- `Desktop\PC-Visit` wird bei der Suche nach empfangenen Dateien ausgeschlossen.
- Zielverzeichnisse werden bei Bedarf automatisch erstellt.
- Bei Namenskonflikten wird die bestehende Datei mit ihrem Erstellungszeitpunkt umbenannt.
- Kundenverzeichnisnamen werden NTFS-konform bereinigt.