pcvisit-filetracker/specs.md

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.