Zum Inhalt springen

Änderungen von Dokument Digitale Mitgliederverwaltung

Zuletzt geändert von Daniel Herrmann am 2026/02/22 21:17
Von Version Icon 38.1 Icon
bearbeitet von Daniel Herrmann
am 2025/08/23 16:13
Änderungskommentar: Es gibt keinen Kommentar für diese Version
Auf Version Icon 34.1 Icon
bearbeitet von Daniel Herrmann
am 2025/08/22 18:14
Änderungskommentar: Es gibt keinen Kommentar für diese Version

Zusammenfassung

Details

Icon Seiteneigenschaften
Inhalt
... ... @@ -806,230 +806,55 @@
806 806  
807 807  Paperless unterstützt die automatische Zuordnung von Metadaten basierend auf festen Strings. So kann man beispielsweise angeben, dass ein Dokumententyp "Haftungsausschluss" zugewiesen werden soll, wenn der String "Haftungsausschluss" irgendwo im Dokument vorkommt. Dies ist allerdings auf eine korrekte Funktion der Texterkennung angewiesen und funktioniert erfahrungsgemäß nur in manchen Fällen, sodass mindestens eine manuelle Überprüfung trotzdem notwendig kommt. Wenn beispielsweise ein Brief mit dem Satz "ich dachte, ich hätte den Haftungsausschluss bereits abgegeben, könntet ihr dies bitte prüfen" erfasst wird, würde der basierend auf der Regel ebenfalls kategorisiert werden.
808 808  
809 -**Aus diesem Grund wird auf jedes Dokument einen spezieller QR Code aufgedruckt**. Der QR code wird vom Post-Consume Script verwendet um die Metadaten in Paperless zuzuordnen. Weiterhin können Daten übermittelt werden, die dann mittels Webhook an N8n übermittelt werden und dort im Workflow verwendet werden können. Der Aufbau orientiert sich an dem Aufbau eines **JSON Web Tokens (JWT).**
809 +Aus diesem Grund nutzen wir einen speziellen QR Code in einem für den Makerspace spezifischen Format, welches nachstehend detailliert beschrieben wird.
810 810  
811 -=== {{id name="DigitaleMitgliederverwaltung-Barcodeerzeugen"/}}(% style="color:var(--ds-text-accent-purple-bolder,#352c63);" %)Barcode erzeugen(%%) ===
811 +{{code language="json"}}
812 +{
813 + "payload": {
814 +        "timestamp": "YYYY-MM-DDTHH:mm:ss",
815 + "uuid": "260171c3-c71c-4da2-b13e-bf1386fe9eac",
816 + "correspondent": "Daniel Herrmann (#250)",
817 + "type": "mksp-doc-sepamandat",
818 + "tags": [
819 + "tag1",
820 + "tag2"
821 + ],
822 +"storage_path": "Mitgliederverwaltung"
823 + },
824 + "sig": "signature over the entire payload block"
825 +}
826 +{{/code}}
812 812  
813 -(% style="color:var(--ds-text-accent-purple-bolder,#352c63);" %)Der Prozess zur Erzeugung eines QR Codes ist wie folgt:
828 +Die beiden Einträge **payload** und **sig** sind **Pflichtfelder**. Innerhalb der Payload müssen der **timestamp** **und die UUID** **vorhanden** sein, alle anderen Felder sind optional, jedoch muss mindestens eins angegeben werden. Der QR Code kann dann - insbesondere bei der Digitalen Unterschrift oder bei Workflows, wo die Formulare ohnehin on demand erzeugt werden bereits mit allen Daten bestückt werden. In Paperless gibt es dann ein Postconsume Script, welches den QR Code ausliest, die Signatur prüft und - falls die Signatur korrekt ist - automatisch die Meta-Daten übernimmt.
814 814  
815 -* **Payload (Daten) festlegen**. Einige Werte sind verpflichtend, andere können nach Bedarf optional hinzugefügt werden.
816 -* JWT erzeugen und signieren. der JWT besteht aus drei Teilen:
817 -** **Header**: **alg** (Algorithmus) und **typ** (JWT) sind verpflichtend. Zusätzlich fügen wir einen Timestamp, eine eindeutige ID und eine Gültigkeitsdauer hinzu.
818 -** **Body**: beinhaltet die eigentlichen Daten.
819 -** **Signature**: Mit Hilfe eines Secrets und wird die Signatur erzeugt und automatisch angehängt.
820 -* PDF417 code erzeugen: ein JWT ist per Definition URL safe und kann daher einfach in ein QR code umgewandelt werden.
830 +=== {{id name="DigitaleMitgliederverwaltung-Signatur"/}}Signatur ===
821 821  
822 -=== {{id name="DigitaleMitgliederverwaltung-Header"/}}Header ===
832 +Die Signatur wird kryptographisch mit Hilfe asymmetrischen Verschlüsselung erzeugt. Wir erzeugen ein RSA 2048 Key Pair. Der öffentliche Schlüssel steht Paperless zur Verfügung, sodass Paperless die Signaturen verifizieren kann. Der private Teil des Schlüssels wird von den Makerspace-Systemem verwendet, welche die Formulare erzeugen. Im Detail:
823 823  
824 -Der Header enthält wichtige Meta-Daten, diese werden von der JWT Library automatisch erzeugt und beschreiben in der Regel den verwendeten Key-Typ.
834 +* **Key-Pair**: 2048 bit Schlüssellänge, RSA, 65537 Exponent
835 +* **Signatur**: SHA256 Signatur, PKCS1v15 Padding
836 +* (((
837 +**Payload**: Als Payload wird nur der Inhalt der Payload verwendet, als **JSON String ohne Whitespaces, byte encoded in UTF-8.** Das oben genannte Beispiel würde die Signatur über den folgenden String erstellen:
838 +\\
825 825  
826 -=== {{id name="DigitaleMitgliederverwaltung-Body"/}}Body ===
840 +{{code language="json"}}
841 +{"payload":{"correspondent":"Daniel Herrmann (#250)","type":"SEPA Mandat","tags":["tag1","tag2"]},"timestamp":"YYYY-MM-DDTHH:mm:ss","sig":"this-would-be-the-signature-appended-to-the-data"}
842 +{{/code}}
827 827  
828 -Die folgenden Claims sind im Body verfügbar:
829 829  
830 -(% class="" %)|=(((
831 -Claim
832 -)))|=(((
833 -Type
834 -)))|=(((
835 -Pflicht
836 -)))|=(((
837 -Beschreibung
838 -)))
839 -|(((
840 -id
841 -)))|(((
842 -UUID4
843 -)))|(((
844 -✅️
845 -)))|(((
846 -Eindeutige ID dieses Dokuments
847 -)))
848 -|(((
849 -time
850 -)))|(((
851 -Zahl
852 -)))|(((
853 -✅️
854 -)))|(((
855 -UTC Linux-Timestamp an dem das Dokument und der QR Code erzeugt wurden
856 -)))
857 -|(((
858 -exp
859 -)))|(((
860 -Zahl
861 -)))|(((
862 -✅️
863 -)))|(((
864 -UTC Linux-Timestamp der angibt, bis wann das Dokument gültig ist.
865 -)))
866 -(% class="" %)|(((
867 -(% class="code" %)
868 -(((
869 -typ
870 -)))
871 -)))|(((
872 -String
873 -)))|(((
874 -✅️
875 -)))|(((
876 -Typ des Dokuments basierend auf der unten definierten Liste.
877 -)))
878 -(% class="" %)|(((
879 -(% class="code" %)
880 -(((
881 -cor
882 -)))
883 -)))|(((
884 -String
885 -)))|(((
886 -❌️
887 -)))|(((
888 -Optional: Name des Korrespondenten, dem das Dokument zugeordnet werden soll
889 -)))
890 -(% class="" %)|(((
891 -tags
892 -)))|(((
893 -List[String]
894 -)))|(((
895 -❌️
896 -)))|(((
897 -Liste an Tags, die dem Dokument zugeordnet werden soll
898 -)))
899 -|(((
900 -spth
901 -)))|(((
902 -String
903 -)))|(((
904 -❌️
905 -)))|(((
906 -Storage Path, das dem Dokument zugeordnet werden soll
907 -)))
908 -|(((
909 -opt
910 -)))|(((
911 -dict
912 -)))|(((
913 -❌️
914 -)))|(((
915 -Optionale Attribute, die mit eincodiert werden und dem N8n Workflow übergeben werden.
916 -)))
845 +Als Referenz, die in Python wäre der Input der Signatur:
846 +\\
917 917  
918 -=== {{id name="DigitaleMitgliederverwaltung-Footer"/}}Footer ===
848 +{{code language="python"}}
849 +import json
919 919  
920 -Der Footer wird automatisch erzeugt und erhält eine Signatur über den Header und den Body, basierend auf einem Algorithmus und einer Signatur.
921 -
922 -{{confluence_tip title="Algorithmus"}}
923 -Von den meisten Libraries werden symmetrische und asymmetrische Signaturen unterstützt. Die Verwendung eines symmetrischen Algorithmus ist für uns einfacher.
924 -
925 -Für diesen Anwendungsfall nutzen wir (% style="text-decoration: none;color:var(--ds-text,#333333);" %)**HS256** (HMAC mit SHA-256 Algorithmus).
926 -{{/confluence_tip}}
927 -
928 -=== {{id name="DigitaleMitgliederverwaltung-AuswahlderLibrary"/}}Auswahl der Library ===
929 -
930 -Die Implementierung für die Erzeugung und das Validieren erfolgt in Python. Dies hat den Hintergrund, dass sowohl unser Backend als auch Paperless NGX (und damit das Post-Consumption Script) in Python implementiert ist. Es gibt verschiedene Libraries, die betrachtet wurden:
931 -
932 -|=(% scope="col" %)(((
933 -Name
934 -)))|=(% scope="col" %)(((
935 -CVE
936 -)))|=(% scope="col" %)(((
937 -Github
938 -)))|=(% scope="col" %)(((
939 -GH⭐
940 -)))|=(% scope="col" %)(((
941 -Letztes Release
942 -)))|=(% scope="col" %)(((
943 -Offene Issues
944 -)))|=(% scope="col" %)(((
945 -Dokumentation
946 -)))|=(% scope="col" %)(((
947 -Qualität Dokumentation
948 -)))|=(% scope="col" %)(((
949 -In Backend vorhanden?
950 -)))|=(% scope="col" %)(((
951 -In Paperless vorhanden?
851 +input_data = {'payload': {'correspondent': 'Daniel Herrmann (#250)', 'type': 'SEPA Mandat', 'tags': ['tag1', 'tag2']}, 'timestamp': 'YYYY-MM-DDTHH:mm:ss', 'sig': 'this-would-be-the-signature-appended-to-the-data'}
852 +signature_data = json.dumps(input_data, separators=(',', ':')).encode('utf-8')
853 +{{/code}}
952 952  )))
953 -|(((
954 -python-jose
955 -)))|(((
956 -3/0
957 -)))|(((
958 -[[https:~~/~~/github.com/mpdavis/python-jose>>url:https://github.com/mpdavis/python-jose||shape="rect"]]
959 -)))|(((
960 -1.7k
961 -)))|(((
962 -28.05.2025
963 -)))|(((
964 -83
965 -)))|(((
966 -[[https:~~/~~/python-jose.readthedocs.io/en/latest/>>url:https://python-jose.readthedocs.io/en/latest/||shape="rect"]]
967 -)))|(((
968 -⛔ Wenige Bespiele, API Dokumentation fehlt komplett
969 -)))|(((
970 -❌️
971 -)))|(((
972 -❌️
973 -)))
974 -|(((
975 -pyJWT
976 -)))|(((
977 -4/0
978 -)))|(((
979 -[[https:~~/~~/github.com/jpadilla/pyjwt>>url:https://github.com/jpadilla/pyjwt||shape="rect"]]
980 -)))|(((
981 -5.4k
982 -)))|(((
983 -28.11.2024
984 -)))|(((
985 -30
986 -)))|(((
987 -[[https:~~/~~/pyjwt.readthedocs.io>>url:https://pyjwt.readthedocs.io||shape="rect"]]
988 -)))|(((
989 -➕️ Gute Dokumentation, API, Beispiele, Changelog
990 -)))|(((
991 -✅️ 2.10.1
992 -Dep von firebase
993 -)))|(((
994 -✅️ 2.10.1
995 -)))
996 -|(((
997 -JWCrypto
998 -)))|(((
999 -5/0
1000 -)))|(((
1001 -[[https:~~/~~/github.com/latchset/jwcrypto>>url:https://github.com/latchset/jwcrypto||shape="rect"]]
1002 -)))|(((
1003 -465
1004 -)))|(((
1005 -06.03.2024
1006 -)))|(((
1007 -8
1008 -)))|(((
1009 -[[https:~~/~~/jwcrypto.readthedocs.io>>url:https://jwcrypto.readthedocs.io||shape="rect"]]
1010 -)))|(((
1011 -➕️ API Doc, einige Beispiele
1012 -)))|(((
1013 -✅️ 1.5.6
1014 -Dep von python-keycloak
1015 -)))|(((
1016 -❌️
1017 -)))
1018 1018  
1019 -Unsere bevorzugte Library ist **pyjwt**. Diese ist auch in **paperless nativ vorhanden**, sodass wir uns für die Implementierung mittels **pyjwt** entschieden haben.
856 +\\
1020 1020  
1021 -=== {{id name="DigitaleMitgliederverwaltung-PDF417Code"/}}PDF417 Code ===
1022 -
1023 -Als Format für den Code wurde PDF417 ausgewählt, da dieser mehr Platz und Fehlerkorrektur bietet. Weiterhin gibt es eine einfach zu nutzende Library für Python (Erzeugung) und PDF417 wird von (% style="text-decoration: none;color:var(--ds-text-accent-purple-bolder,#352c63);" %)ZXING unterstützt, welches in Paperless eingebettet ist. Ein solcher Barcode sieht beispielsweise so aus:
1024 -
1025 -(% style="text-decoration: none;color:var(--ds-text-accent-purple-bolder,#352c63);" %)[[image:attach:barcode.jpg||height="250"]]
1026 -
1027 -(% style="text-decoration: none;color:var(--ds-text-accent-purple-bolder,#352c63);" %)Daraus kann dann eine Base64 basierte Repräsentation berechnet werden, die einfach in Docuseal hochgeladen werden kann.
1028 -
1029 -=== {{id name="DigitaleMitgliederverwaltung-Referenz-Implementierung"/}}Referenz-Implementierung ===
1030 -
1031 -Eine Referenz-Implementierung befindet sich im Makerspace Gitlab: [[https:~~/~~/git.makerspace-darmstadt.de/makerspace-it-infrastructure/paperless-pdf417-reference>>url:https://git.makerspace-darmstadt.de/makerspace-it-infrastructure/paperless-pdf417-reference||shape="rect"]]
1032 -
1033 1033  == {{id name="DigitaleMitgliederverwaltung-TechnischesSetup"/}}Technisches Setup ==
1034 1034  
1035 1035  Owner: zwei Owner
... ... @@ -1038,7 +1038,46 @@
1038 1038  Tag: owner = grp owner, view = jeweilige Gruppe, edit = it admin
1039 1039  Doc Type: owner = grp owner, view = jeweilige Gruppe, edit = it admin
1040 1040  
1041 -= {{id name="DigitaleMitgliederverwaltung-OffenePunkte"/}}Offene Punkte =
866 +TODO
1042 1042  
868 +\\
869 +
870 +=== {{id name="DigitaleMitgliederverwaltung-AusFace2Faceam20.8(DH,YS)"/}}Aus Face 2 Face am 20.8  (DH,YS) ===
871 +
872 +* Schritt 1: Einweisungszettel erzeugen 
873 +** Checkliste in Directus hinterlegen, eine pro Einweisung
874 +** N8n Workflow, welches die Liste aus Directus herunterlädt und Template mit Puppetteer Script Node erzeugen
875 +** Aus diesem Template dann ein DocuSeal Template erstellen
876 +* Schritt 2: Zettel für Einweisungen generieren
877 +** Tablet für Einweiser im makerspace
878 +** Authentifizierung über Token an der Freigabebox
879 +*** Neue Maschine, User schaltet die Maschine "Tablet" frei
880 +*** Datenbank erzeugt JWT und signiert es mit einem RSA Priv Key
881 +*** Wird als Payload in der MQTT unlock message mitgeschickt
882 +** Tablet nutzt dieses Token für API Requests gegen Homepage Backend
883 +** Backend wird um weitere Middleware angepasst, die dieses Token für manche Endpoints akzeptiert
884 +** Einweiser:in bekommt aktive Einweisung angezeigt und kann Teilnehmer Entfernern (no-show) oder hinzufügen (spontan)
885 +*** Option eine Einweisung ohne Rechnungsstellung vorzunehmen
886 +** PDFs werden automatisch ausgedruckt
887 +*** Tablet triggert einen Backend endpoint
888 +**** übergibt teilnehmer als parameter (auth über token) und
889 +**** erzeugt die entsprechenden PDFs in DocuSeal
890 +**** Gibt PDF als Return
891 +*** Tablet kann PDF über Netzwerk print drucken
892 +* Schritt 3: Einweisungen erfassen
893 +** QR code wird in Schritt 2 aufgedruckt und enthält:
894 +*** Einweisung
895 +*** Datum
896 +*** Einweiser
897 +*** Teilnehmer
898 +*** Flag Rechnung
899 +** Dokument wird über ScanSnap eingescannt und automatisch an paperless übergeben
900 +** Paperless Post Consume erkennt den QR Code, validiert ihn und löst über einen Webook einen Flow in N8n aus
901 +** N8n erstellt dann einen temporären Eintrag im Backend, ähnlich dem der heute bei "Einweisung erfassen" sichtbar ist
902 +** Die Mitgliederverwaltung hat dann x Tage Zeit, die Einträge zu korrigieren und zu prüfen (beispielsweise ob Voraussetzungen erfüllt sind)
903 +** Danach werden alle Schritte wie bisher ausgelöst (Berechtigung, Rechnung, Auszahlung an Einweiser, E-Mail Bestätigung, ...)
904 +
905 +TODO:
906 +
1043 1043  * Docuseal Logging + Monitoring
1044 1044  * N8n Error Handling
Icon Confluence.Code.ConfluencePageClass[0]
Id
... ... @@ -1,1 +1,1 @@
1 -205586461
1 +202867281
URL
... ... @@ -1,1 +1,1 @@
1 -https://wiki.makerspace-darmstadt.de/spaces/PROJ/pages/205586461/Digitale Mitgliederverwaltung
1 +https://wiki.makerspace-darmstadt.de/spaces/PROJ/pages/202867281/Digitale Mitgliederverwaltung