Projekt-Metadaten angepasst

README.md

@@ -0,0 +1,130 @@
+# PC-Visit Filetracker
+
+Verarbeitet PC-Visit-Session-XML-Dateien und erzeugt CSV-Auswertungen.
+
+## Installation
+
+### uv installieren
+
+Windows PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Alternativ über WinGet:
+
+```powershell
+winget install --id=astral-sh.uv -e
+```
+
+### Projekt einrichten
+
+Im Projektverzeichnis genügt:
+
+```powershell
+uv sync
+```
+
+Damit werden die Python-Umgebung und alle Abhängigkeiten aus `pyproject.toml` eingerichtet.
+
+## Verwendung
+
+Die allgemeine Hilfe zeigt alle verfügbaren Commands:
+
+```powershell
+uv run main.py
+```
+
+Das XML-Verzeichnis ist bei den XML-bezogenen Commands optional. Standardmäßig wird verwendet:
+
+```text
+%USERPROFILE%\AppData\Roaming\pcvisit Data\Session History
+```
+
+Die CSV-Dateien werden standardmäßig im Ordner `data` abgelegt.
+
+## Commands
+
+### `clients`
+
+Liest Participant- und Client-Daten aus allen XML-Dateien inklusive Unterordnern und schreibt `data/clients.csv`.
+Supporter, unbekannte Rollen und leere Client-Namen werden ignoriert. Pro Participant wird der neueste Eintrag verwendet.
+
+```powershell
+uv run main.py clients
+uv run main.py clients "C:\Pfad\zur\Session History" -o data\clients.csv
+```
+
+### `files`
+
+Sucht `ReceivedFile`-Einträge auf dem lokalen Desktop inklusive Unterordnern. Nur gefundene Dateien werden in `data/files.csv` gespeichert.
+Der Datumsabgleich mit dem Session-Tag kann deaktiviert werden:
+
+```powershell
+uv run main.py files
+uv run main.py files --ignore-timestamp
+```
+
+Der Ordner `Desktop\PC-Visit` wird bei der Suche ignoriert.
+
+### `move-files`
+
+Aktualisiert zuerst `data/files.csv` und verschiebt anschließend die gefundenen Dateien nach:
+
+```text
+%USERPROFILE%\Desktop\PC-Visit\<Kunde>
+```
+
+Bei gleichnamigen Zieldateien wird die vorhandene Datei mit ihrem Erstellungszeitpunkt umbenannt.
+
+```powershell
+uv run main.py move-files
+uv run main.py move-files --ignore-timestamp
+```
+
+### `archive-logs`
+
+Archiviert XML-Dateien mit `Duration` im `Session`-Tag nach `Archiv\<Jahr>`. XML-Dateien ohne `Duration` werden ab einem Alter von 30 Tagen ebenfalls archiviert.
+`sessions*.xml` und bereits archivierte Dateien werden ignoriert. Leere Unterordner werden anschließend entfernt.
+
+```powershell
+uv run main.py archive-logs
+```
+
+### `session-details`
+
+Sammelt `UserActivity`-Einträge inklusive `DateTime`, `Kunde`, `UserActivityType` und `Duration` aus allen XML-Dateien inklusive Archiv und schreibt `data/session_details.csv`.
+
+```powershell
+uv run main.py session-details
+```
+
+### `summary`
+
+Erstellt aus `data/session_details.csv` die Datei `data/summary.csv` mit Datum, Startzeit, Kunde und Dauer.
+Zusätzlich wird standardmäßig eine Übersicht der letzten 14 Tage auf der Konsole ausgegeben. Der Zeitraum ist anpassbar:
+
+```powershell
+uv run main.py summary
+uv run main.py summary --days 30
+```
+
+### `info`
+
+Führt `clients`, `archive-logs`, `session-details` und `summary` nacheinander aus.
+
+```powershell
+uv run main.py info
+uv run main.py info --days 30
+```
+
+### `watch`
+
+Überwacht das XML-Verzeichnis rekursiv mit `watchdog`. Bei Änderungen an XML-Dateien wird der `move-files`-Ablauf ausgeführt.
+
+```powershell
+uv run main.py watch
+```
+
+Die Überwachung läuft dauerhaft. Beenden mit `Strg+C`.

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
-name = "pc-visit-filetracker"
+name = "pcvisit-filetracker"
 version = "0.1.0"
-description = "Add your description here"
+description = "Verarbeitet PC-Visit-Session-Logs und erstellt CSV-Auswertungen."
 readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [

specs.md

@@ -0,0 +1,90 @@
+# 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.

uv.lock

@@ -42,7 +42,7 @@ wheels = [
 ]
 
 [[package]]
-name = "pc-visit-filetracker"
+name = "pcvisit-filetracker"
 version = "0.1.0"
 source = { virtual = "." }
 dependencies = [