Repository navigation
Releases
Releases · pkr-lab/DocFlowEngine
v2.2.1
v2.2.0
v2.1.0
DocFlowEngine-2.0.0
DocFlowEngine – Release
Überblick
Dieses Release behebt mehrere Fehler, durch die Abgaben nicht oder falsch kopiert wurden. Es führt einen zentralen Pfad-Block in der Konfiguration ein, entfernt den Archiv-Ordner und sichert die Verarbeitung von Abgaben gegen Kopierfehler, doppelte Abgaben und halb hochgeladene Dateien ab.
🐛 Fehlerbehebungen
Whitelist: zusammengeklebte Zeilen
- Endete die geteilte
project-routes.txtohne Zeilenumbruch, wurde der nächste Eintrag an die letzte Zeile angehängt (z. B.suffix=Registrysuffix=Arrays). Dadurch wurden beide Einträge unwirksam, und die betroffenen Abgaben wurden nicht kopiert. - Die Datei wird beim Abgleich jetzt vollständig neu geschrieben. Bereits zusammengeklebte Zeilen werden automatisch getrennt.
- Eine leere Whitelist-Datei führt nicht mehr zum Absturz.
Versionsangabe mit großem V (_V2_)
- Dateien wie
AHf_V2_Java_ArrayList_002wurden zwar kopiert, bekamen aber einen Zeitstempel statt des Datums vorne. Beim Rücklauf ließ sich daraus kein Kürzel mehr lesen, sodass die Korrektur nie beim Schüler ankam. - Alle Namensregeln ignorieren jetzt Groß- und Kleinschreibung:
_V2_wird genauso behandelt wie_v2_.
Korrektur-Markierung mit großem K
_K-ahfbzw._K-AHFwird jetzt genauso als Korrektur erkannt wie_k-ahf.
Fehlgeschlagene Kopien galten als erledigt
- Schlug das Kopieren fehl (Datei gesperrt, noch nicht synchronisiert, keine Rechte), wurde die Datei trotzdem als verarbeitet gespeichert und nie wieder versucht.
- Als verarbeitet gilt eine Datei jetzt erst, wenn die Kopie nachweislich und in voller Größe im Ziel liegt.
✨ Neue Funktionen
Zentraler paths-Block in der Konfiguration
- Alle Pfade werden nur noch ganz oben in
config/docflow-config.psd1festgelegt und überall sonst per{name}verwendet:paths = @{ jahrgang = 'C:/Users/p0*/OneDrive - D*/IT-Ausbildung - Jahrgangsordner' quelle = '{jahrgang}/FI*/Austauschordner/' material = '{jahrgang}/SchuelerMaterial' shared = '{material}/_DocFlowEngine-Shared' }
- Werte dürfen aufeinander aufbauen; die Reihenfolge ist egal.
- Tippfehler und Kreisverweise brechen den Start mit einer klaren Meldung ab.
- Platzhalter in Umbenennungsregeln und Hinweistexten (
{date},{fileName}…) bleiben unberührt.
Kopieren mit Wiederholung (copyRetry)
- Schlägt eine Kopie fehl, wird sie im selben Lauf zweimal wiederholt (jeweils nach 5 Sekunden).
- Scheitern alle drei Versuche, wird ein Fehler geloggt und die Datei beim nächsten Lauf erneut versucht.
- Gilt für den Vorwärtslauf und für den Rücklauf der Korrekturen.
Hinweis bei bereits abgegebener Datei (duplicateHint)
- Lädt ein Schüler eine Datei unter einem bereits abgegebenen Namen hoch, wird sie nicht kopiert. Erkannt werden zwei Fälle: Die alte Datei wurde überschrieben, oder sie wurde gelöscht und neu hochgeladen.
- Der Schüler erhält
<Dateiname>.BEREITS-ABGEGEBEN.txtmit einem Vorschlag für die nächste freie Versionsnummer (z. B.AHf_v2_…oderAHf_v3_…, falls_v2_schon existiert). - Liegt im Ziel bereits genau dieselbe Datei (z. B. nach einem abgebrochenen Lauf), wird sie ohne Hinweis übernommen.
Schutz vor halb hochgeladenen Dateien (minFileAgeMinutes)
- Dateien werden erst verarbeitet, wenn sie seit mindestens 2 Minuten unverändert und nicht gesperrt sind.
- Noch nicht fertige Dateien werden ohne Hinweis im nächsten Lauf erneut geprüft.
Whitelist prüft Präfix und Suffix als Paar
- Ein
suffix=gehört jetzt zumpraefix=direkt darüber:→praefix=Java suffix=Arrays suffix=ArrayList praefix=Zahlensysteme suffix=HexadezimalJava_ArrayListist erlaubt,Java_Hexadezimalnicht. - Derselbe Suffix darf unter mehreren Präfixen stehen (z. B.
Einfuehrung). - Der Abgleich mit dem Startbestand ordnet neue Suffixe dem richtigen Präfix zu, statt sie unten anzuhängen. Einträge, die nur in der geteilten Datei stehen, bleiben erhalten.
Hinweisdateien werden automatisch aufgeräumt
.NAMENSKONVENTION-FEHLER.txtund.BEREITS-ABGEGEBEN.txtwerden entfernt, sobald die betroffene Datei umbenannt, gelöscht oder erfolgreich kopiert wurde..KUERZEL-UNBEKANNT.txtwird entfernt, sobald die Korrektur zurückkopiert werden konnte oder die Datei nicht mehr existiert.- Hinweis-Endungen werden automatisch zu den
excludePatternshinzugefügt, damit Hinweise nie selbst als Abgabe gelten.
Besseres Logging zur Fehlersuche
Whitelist geladen: '<Pfad>' (n Präfixe, m Kombinationen); bei Log-LevelDebugzusätzlich die vollständige Liste.- Pro abgelehnter Datei steht der konkrete Grund im Log: Präfix unbekannt, Suffix für diesen Präfix nicht erlaubt oder Dateiname passt nicht zum Schema.
- Ungültige Zeilen in der Whitelist werden gemeldet.
- Anzahl der Dateien, die bereits in früheren Läufen verarbeitet wurden.
- Meldungen zu Kopierversuchen, Doppelabgaben, gesperrten Dateien und entfernten Hinweisen.
🔄 Änderungen am Verhalten
Archiv-Ordner entfernt
- Es wird kein
docs/archive-Ordner mehr angelegt;targetsist optional und in der mitgelieferten Konfiguration nicht mehr gesetzt. - Dateien, die sich keiner Aufgabe zuordnen lassen, werden nicht mehr irgendwohin kopiert, sondern erhalten einen Hinweis beim Schüler.
- Übersprungene Dateien werden nicht als verarbeitet gespeichert und nach einer Korrektur beim nächsten Lauf normal verarbeitet.
Zustandsdatei erweitert
- Einträge enthalten zusätzlich
lengthundlastWriteUtcSeconds, um überschriebene Abgaben zu erkennen. Abweichungen der Änderungszeit bis 2 Sekunden werden toleriert (OneDrive-Rundung). - Einträge aus älteren Versionen werden beim ersten Lauf automatisch ergänzt, ohne dass Dateien erneut kopiert werden.
⚠️ Hinweise zum Update
- Eigene Konfiguration sichern, bevor die neue Version eingespielt wird. In der neuen Config nur die Werte im
paths-Block anpassen. - Fächer in
config/project-routes.txteintragen, sauber nach Präfix gruppiert, also jeweils alle Suffixe unter ihrem Präfix. - Die geteilte
_DocFlowEngine-Shared/project-routes.txteinmalig löschen. Durch das frühere Anhängen kann dort ein Suffix unter dem falschen Präfix stehen. Die Datei wird beim nächsten Lauf aus dem Startbestand neu angelegt. - Den alten Ordner
docs/archivevon Hand löschen, falls er nicht mehr gebraucht wird. Das Skript löscht keine Ordner. - Neue Config-Einträge
duplicateHint,minFileAgeMinutesundcopyRetryübernehmen. Fehlen sie, gelten die Standardwerte (Hinweis aktiv, 2 Minuten, 2 Wiederholungen à 5 Sekunden). - Erneute Abgaben müssen die Versionsangabe direkt hinter den Initialen tragen:
AHf_v2_Java_ArrayList_002.docx. - Den ersten Lauf nach dem Update mit
-DryRunausführen und das Log prüfen.
📚 Dokumentation
docs/Configuration.md: neue Abschnitte zupaths,duplicateHint,minFileAgeMinutes,copyRetry, zum Aufräumen der Hinweisdateien und zur Zustandsdatei; Whitelist-Format als Paare;targetsoptional.docs/Logging.md: alle neuen Log-Meldungen mit Bedeutung.docs/Module-Reference.md: neue und geänderte Funktionen.docs/Implementation-Notes.md: Begründungen (Größe und Zeit statt Prüfsumme, Zeit-Toleranz, Übernahme identischer Zieldateien, Whitelist-Neuschreiben, Groß-/Kleinschreibung).README.md: Beispiel ohne Archiv, erneute Abgabe mit_v2_, Absicherungen.
✅ Tests
- 67 Pester-Tests, alle grün. Neu sind unter anderem Tests zu Kopierwiederholung, Doppelabgabe und Versionsvorschlag, gesperrten bzw. zu frischen Dateien,
_V2_und_K-, Paar-Whitelist sowie zum Aufräumen der Hinweisdateien.
DocFlowEngine-1.0.0
DocFlowEngine v1.0.0 – Erstes Release
Überblick
DocFlowEngine ist ein PowerShell-basiertes Werkzeug zur automatisierten Überwachung von
Quellordnern, Erkennung neuer Dokumente, regelbasierten Umbenennung und Kopie in
Zielordner. Es wurde primär für die Sortierung von Schülermaterial aus SharePoint
entwickelt, ist aber generisch über die Konfiguration anpassbar.
Features
- Quellordner-Überwachung mit konfigurierbaren Include-/Exclude-Dateimustern
(*.pdf,*.docx,*.xlsx,*.java,*.zip,*.py,*.txt,*.md,*.csv,
*.pptx,*.png,*.jpg,*.jpegu. a.) und optional rekursiver Suche - Regelbasierte Umbenennung über konfigurierbare
namingConventionsmit
Regex-Match/Rename-Templates ({date},{timestamp},{originalName}u. a.),
inkl. Unterstützung optionaler Regex-Gruppen (Platzhalter werden bei fehlendem
Treffer durch leeren String ersetzt) - Aufgaben-Routing: Dateien nach dem Schema
<initialen>[_v<version>]_<praefix>_<suffix>_<aufgabennummer>werden automatisch
nach<aufgabenRoot>/<Präfix>/<Suffix>/einsortiert; optionale Versionsangabe
erlaubt mehrere Abgaben derselben Aufgabe ohne gegenseitiges Überschreiben - Namenskonventions-Hinweis: Dateien, die keinem Schema entsprechen, werden nicht
kopiert – stattdessen wird eine konfigurierbare Hinweis-Textdatei im Quellordner
abgelegt, die zur korrekten Umbenennung auffordert - Projekt-Registry (
config/project-routes.txt): neu erkannte Präfixe/Suffixe
werden automatisch dokumentiert und nachvollziehbar festgehalten - Zustandsverwaltung (
.docflow-state.json): bereits verarbeitete Dateien werden
nicht erneut kopiert; bereits sortierte Dateien unterhalb vontargets/aufgabenRoot
werden beim Scannen automatisch ausgeschlossen - DryRun-Modus (
-DryRun) zur risikofreien Vorschau aller geplanten Aktionen - Logging mit konfigurierbarem Level und Ziel-Logdatei
- Keine externen Abhängigkeiten: Konfiguration liegt als PowerShell-Data-Datei
(.psd1) vor, gelesen über das eingebauteImport-PowerShellDataFile– kein
Install-Modulenötig
Plattform & Kompatibilität
- Gleichwertige Unterstützung für PowerShell 7+ und Windows PowerShell 5.1
(vorinstalliert unter Windows) - Läuft unter Windows, macOS und Linux (PowerShell 7+); Windows PowerShell 5.1 nur
unter Windows - Keine Admin-Rechte erforderlich –
-ExecutionPolicy Bypassgilt nur für den
jeweiligen Prozess, nicht systemweit - Benötigt lediglich Lesezugriff auf Quellordner und Schreibzugriff auf Zielordner
Enthaltene Dateien
config/docflow-config.psd1– Konfiguration (Quellen, Ziele, Umbenennungsregeln)config/project-routes.txt– Registry bekannter Präfixe/Suffixescripts/DocFlowEngine.ps1– Skript-Wrapper zum Aufruf des Modulsscripts/DocFlowEngine.psm1– Kernlogik als PowerShell-ModulLICENSE– MIT-Lizenz inkl. Nutzungs-DisclaimerREADME.md– Projektübersicht, Einstieg, Beispiel-Workflow, Troubleshooting
Erste Schritte
# 1. Vorschau (DryRun)
pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/DocFlowEngine.ps1 -DryRun
# 2. Tatsächliche Ausführung
pwsh -NoProfile -ExecutionPolicy Bypass -File ./scripts/DocFlowEngine.ps1