From 0fd87014b4532b357ea57039b664d7574e93fc08 Mon Sep 17 00:00:00 2001 From: fbuettner Date: Thu, 26 Oct 2017 10:05:32 +0200 Subject: [PATCH] Updated README according to eInvoice configuration (only German still) --- README.md | 235 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 212 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 32eb262..686ab0b 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,85 @@ -## Inhaltsverzeichnis +% Prüftool und Prüftool-Konfiguration XRechnung -- [Über das Prütool](#über-das-prüftool) -- [Status](#status) -- [Verwendung](#verwendung) -- [Build-Anweisungen](#build-anweisungen) -- [Konfiguration xRechnung](#konfiguration-xrechnung) +Autor: Fabian Büttner (KoSIT) + +Stand: 21.09.2017 + +Status: draft + +# Über das Prüftool und die Prüftool-Konfiguration XRechnung +Das Prüftool ist ein Programm, welches XML-Dateien (Dokumente) in Abhängigkeit von ihren Dokumenttypen gegen verschiedene +Validierungsregeln (XML Schema und Schematron) prüft und das Ergebnis zu einem Konformitätsbericht (Konformitätsstatus +*valid* oder *invalid*) mit einer Empfehlung zur Weiterverarbeitung (*accept*) oder Ablehnung (*reject*) aggregiert. Mittels Konfiguration kann bestimmt werden, welche der Konformitätsregeln durch ein Dokument, das zur Weiterverarbeitung empfohlen (*accept*) wird, verletzt sein dürfen. -## Über das Prüftool - * macht die KoSIT -## Status +Das Prüftool selbst ist fachunabhängig und kennt keine spezifischen Dokumenttypen. +Diese werden im Rahmen einer [Prüftool-Konfiguration](#konfiguration-des-prüftools) definiert, welche zur Anwendung des Prüftools +erforderlich ist. +Mit ausgeliefert wird in diesem Kontext eine Entwurfsversion der [Prüftool-Konfiguration +XRechnung](#die-konfiguration-xrechnung), welche die Prüfartefakte der EN16931 und die Prüfartefakte des Standards +[XRechnung](http://www.xoev.de/de/xrechnung) in ihren aktuellen Entwurfsversionen beinhaltet. +# Status der Bestandteile +Das Prüftool hat den Status "proposal". Sofern keine Rückmeldungen aus der Pilotierungsphase eingehen, wird diese +Fassung zur finalen Version "1.0.0". Der geregelte Betrieb dieser Referenzimplementierung des Prüftools wird im Rahmen des Betriebs des Standards XRechnung erfolgen. + +Die Prüftool-Konfiguration XRechnung hat den Status "draft", da auch die darin enthaltenen Prüfartefakte der EN16931 und +des Standards XRechnung aktuell nur als "draft" vorliegen. + +Alle Bestandteile des Pakets werden unter der Apache License Version 2.0, January 2004 (http://www.apache.org/licenses/) bereitgestellt. + +# Grundsätzlicher Ablauf der Prüfung +Eine zu prüfende Datei durchläuft die folgenden Schritte + +1. *Grundsätzliche XML-Prüfung*: Es muss sich bei der zu prüfenden Datei um wohlgeformtes XML handeln, andernfalls + werden keine weiteren Prüfungen durchgeführt und ein [Prüfbericht] mit Status *invalid* und Empfehlung + *reject* generiert. +2. *Identifikation des anzuwendenden Prüfszenarios*: Für den Dokumenttyp der zu prüfenden XML-Datei muss in der + [Konfigurationsdatei](#konfiguration-des-prüftools) ein Prüfszenario definiert sein (die Identifikation des + Dokumenttyps erfolgt durch einen XPath-Test), andernfalls werden keine weiteren Prüfungen durchgeführt und ein + [Prüfbericht] mit Status *invalid* und Empfehlung *reject* generiert. +3. *Prüfung gegen das XML-Schema des identifizierten Dokumenttyps*: Das zu prüfende Dokument muss valide bzgl. des + Schemas sein, andernfalls werden keine weiteren Prüfungen durchgeführt und ein [Prüfbericht] mit Status *invalid* + und Empfehlung *reject* generiert. +4. *Prüfung gegen die Schematron-Regeln des identifizierten Dokumenttyps* +5. *Aggregation und Bewertung der einzelnen Prüfungen zu einem [Prüfbericht]: Die Ergebnisse der + vorherigen Schritte werden in einem einheitlichen Berichtsformat zusammengefasst und bewertet: + * Sofern mindestens einer der zuvor durchgeführten Prüfschritte einen Fehler (*error*) oder eine Warnung (*warning*) + geliefert hat, erhält der Prüfbericht den Status *invalid*, andernfalls erhält er den Status *valid*. + * Sofern einer der Prüfschritte einen Fehler geliefert hat, erhält der Prüfbericht grundsätzlich die Empfehlung + *reject*, andernfalls erhält er die Empfehlung *accept*. + * In der [Konfigurationsdatei](#konfiguration-des-prüftools) kann für einzelne Prüfregeln festgelegt werden, dass + sie für die Bewertung einer [anderen Meldungsart](#anpassung-der-fehlergrade-für-die-bewertung) zuzuordnen sind + (z. B. *warning* anstelle von *error*). + * Der Prüfbericht ist ein für die maschinelle Auswertung geeignetes XML-Dokument (hier ein + [Beispiel](xrechnung/test/reports/ubl002-report.xml)). Darin eingebettet ist auch eine + für menschliche Leser bestimmte HTML-Aufbereitung des Prüfergebnisses (hier ein + [Beispiel](xrechnung/test/reports/ubl002-report.html)). Die Details dieser HTML-Aufbereitung können + bei Bedarf [angepasst](#anpassung-der-html-ausgabe) werden. + ## Verwendung Das Prüftool steht in zwei Varianten zur Verfügung: -- als [**Standalone-Version**](#verwendung-als-anwendung), die von der Kommandozeile aus aufgerufen werden kann -- als [**Bibliothek**](#verwendung-als-bibliothek), die in eigene Anwendungen integriert werden kann +- als [Standalone-Version](#verwendung-als-anwendung), die von der Kommandozeile aus aufgerufen werden kann +- als [Bibliothek](#verwendung-als-bibliothek), die in eigene Anwendungen integriert werden kann ### Verwendung als Standalone-Anwendung -```java -jar validationtool--standalone.jar -s [OPTIONS] [FILE]...``` +```java -jar validationtool--standalone.jar -s [OPTIONS] [FILE] [FILE] [FILE] ...``` -Eine Liste der möglichen Optionen kann der Hilfe entnommen werden. Diese steht mit folgendem Projektaufruf zur Verfügung +Eine Liste der möglichen Optionen kann mit den Schalter `--help` angezeigt werden. -```java -jar validationtool--standalone.jar --help``` +Aufruf, um die mitgelieferten Test-Dokumente zu validieren und dabei neben den XML-Prüfberichten auch die eingebetteten +HTML-Dokumente als eingeständige Dateien auszugeben: + +``` +cd xrechnung +java -jar ../validationtool--standalone.jar -s scenarios.xml -o test/reports -h test/instances/*.xml +``` + +Der Aufruf erzeugt im Verzeichnis [xrechnung/test/reports](xrechnung/test/reports/) für jede validierte Eingabedatei +einen gleichnamige [Prüfbericht]-Datei. +Eine Übersicht über die Eigenschaften der Testdateien in +[xrechnung/test/instances](xrechnung/test/instances/) findet sich in +[xrechnung/test/assertions.xlsx](xrechnung/test/assertions.xlsx). ### Verwendung als Bibliothek Daneben kann das Prüftool auch in eigene Anwendungen integriert werden. @@ -44,7 +102,8 @@ dependencies { ``` Voraussetzung für die Verwendung ist eine valide Prüfszenarien-Definition (xml-Datei) und das dazugehörige Repository -mit den von den definierten Szenarien benötigten Artefakten. Der folgende Quellcode zeigt die Erzeugung einer neuen Prüf-Instanz: +mit den von den definierten Szenarien benötigten Artefakten. Der folgende Quellcode zeigt die Erzeugung einer neuen +Prüf-Instanz: ```java //Vorbereitung der Konfiguration @@ -52,12 +111,12 @@ URI scenarios = URI.create("scenarios.xml"); CheckConfiguration config = new CheckConfiguration(); config.setScenarioDefinition(scenarios); -//Instantiierung der DefaultCheck-Implementierung +//Instanziierung der DefaultCheck-Implementierung Check check = new DefaultCheck(config); ``` Weitere Konfigurationsoption ist der Pfad zum Repository. Standardmäßig wird das Repository relativ zur Szenarien-Defintion -aufgelöst. +unter "repository" gesucht. Die so erzeugte Prüfinstanz initialisiert sämtliche Szenarien und deren Prüfartefakte. Ein etwaiger Konfigurationsfehler wird frühzeitig mitgeteilt. @@ -79,26 +138,156 @@ List reports = pruefer.check(toCheck); ``` -Eine einmal initialisierte Prüfinstanz ist **threadsafe** und kann beliebig oft wieder verwendet +Eine einmal initialisierte Prüfinstanz ist *threadsafe* und kann beliebig oft wieder verwendet werden. XML-Artefakte wie Schema oder XSLT-Executables werden bei Instantiierung des `DefaultCheck` initialisiert und wiederverwendet. Da diese Objekte relativ aufwändig zu Erzeugen sind, empfielt sich die Wiederverwendung der `Check`-Instanz. -Die Batch-Verarbeitung erfolgt grundsätzlich seriell. Der `DefaultCheck` implementiert **keine Parallelverarbeitung**. +Die Batch-Verarbeitung erfolgt grundsätzlich seriell. Der `DefaultCheck` implementiert *keine Parallelverarbeitung*. Einziges Eingabeobjekt ist `Input`, welches sich mit den verschiedenen Methoden der `InputFactory` aus div. Eingabe-Resourcen erzeugen lässt. Die InputFactory erzeugt für jedes Eingabe-Objekt eine Prüfsumme, die im Report mitgeführt wird. Der verwendete Algorithmus ist über die `read`-Methoden der `InputFactory` definierbar. Standardmäßig wird _SHA-256_ des JDK verwendet -### Build-Anweisungen + +## Build-Anweisungen Das Projekt wird mit Apache Maven gebaut. Mittels `mvn install` wird standardmäßig die Bibliotheks-Variante gebaut. Diese enthält nur die Klassen und Komponenten für die Prüfung. Abhängigkeiten müssen durch die einbindende Anwendung aufgelöst werden (maven). Ein `mvn install -Pstandalone` baut die Standalone-Variante. Diese Variante enthält zusätzlich Klassen zur Verarbeitung -von Eingaben aus der Kommandozeile, sowie für Ausgabeoptionen für Ergebnisse. Darüberhinaus ist diese als sog. +von Eingaben aus der Kommandozeile, sowie für Ausgabeoptionen für Ergebnisse. Darüber hinaus ist diese als sog. Uber-Jar gebaut, sodass sämtliche Abhängigkeiten im Jar gebundlet sind und das Jar-File somit 'lauffähig' ist. -### Konfiguration xRechnung - \ No newline at end of file +## Konfiguration des Prüftools +Eine Konfiguration besteht aus einer Konfigurationsdatei (XML-Dokument im Namensraum +http://www.xoev.de/de/validator/framework/1/scenarios) sowie Resourcen (XML Schemata und XSLT-Dateien), auf welche die +Konfigurationsdatei verweist. + +Der Aufbau der Konfigurationsdatei ist im entsprechenden Schema [scenarios.xsd](doc/xsd/scenarios.html) erläutert. + + +## Prüfbericht +Der Aufbau des Prüfberichts ist im entsprechenden Schema [report.xsd](doc/xsd/report.html) erläutert. +Die für die maschinelle Auswertung des Prüfberichts wesentlichsten Angaben sind + +* der [Konformitätsstatus](doc/xsd/report_xsd.html#report_valid) des geprüften Dokuments - *valid* oder *invalid* +* die Empfehlung zur Annahme ([accept](doc/xsd/report_xsd.html#AssessmentType_accept)) oder Ablehnung + ([reject](doc/xsd/report_xsd.html#AssessmentType_reject)) des geprüften + Dokuments. + + +# Die Konfiguration XRechnung +Die Konfiguration XRechnung findet sich im Verzeichnis [xrechnung/](xrechnung/). +Für den produktiven Betrieb benötigt werden die Konfigurationsdatei [xrechnung/scenarios.xml](xrechnung/scenarios.xml) und das +Ressourcen-Verzeichnis [xrechnung/resources/](xrechnung/resources/). + +Die Konfiguration beinhaltet Prüfszenarien für die folgenden Dokumenttypen: + +* EN16931 CIUS XRechnung (UBL Invoice) +* EN16931 CIUS XRechnung (UBL CreditNote) +* EN16931 CIUS XRechnung (CII) + +Jedes Szenario prüft die Konformität zu der zugrunde liegenden XML-Schema-Datei, den Schematron-Regeln der EN16931 und +den Schematron-Regeln der XRechnung CIUS. + +## Anpassung der Fehlergrade für die Bewertung +Grundsätzlich werden für die Verarbeitungen alle Meldungen, welche aus den einzelnen +[Prüfschritten](#grundsätzlicher-ablauf-der-prüfung) resultieren, in die Rollen *error*, +*warning* und *information* übersetzt. Der Prüfbericht erhält den Konformitätstatus *valid* genau dann, wenn in der +Konfiguration ein Prüfszenario für den Dokumenttyp des zu testenden Dokuments gefunden wurde und keine Meldung mit +Status *error* oder *warning* vorliegt. + +Die Erstellung dieser Bewertung ist nicht konfigurierbar. + +In der Standardkonfiguration erhält der Prüfbericht genau dann die Empfehlung *accept*, wenn in der Konfiguration ein +Prüfszenario für den Dokumenttyp des zu testenden Dokuments gefunden wurde und keine Meldung mit Status *error* vorliegt. + +Die Erstellung dieser Empfehlung kann *je Prüfszenario* konfiguriert werden, in dem im jeweiligen Prüfszenario in +`createReport` ein `customLevel` aufgenommen wird: + +``` + + EN16931 CIUS XRechnung (UBL Invoice) + ... + + + Prüfbericht für XRechnung + resources/xrechnung/xrechnung-report.xsl + + BR-15 BR-DE-3 + + +``` + +In diesem Beispiel werden die Fehlercodes `BR-15` (Teil der EN) und `BR-DE-3` (Teil der CIUS XRechnung) für den +Bewertungsschritt von ihrem eigentlicher Rolle *error* auf *warning* geändert. Ein Dokument, welches eine oder +beide dieser Regeln verletzt (und ansonsten keine *error*-Meldungen erzeugt) erhielte damit abweichend vom +Standardverhalten die Bewertung *accept*. + +## Anpassung der HTML-Ausgabe +Die Konfiguration XRechnung erstellt XML-Prüfberichte, welche für jede Bewertung (*accept* oder *reject*-Kindelement im +Prüfbericht) genau eine HTML5-Darstellung enthalten. + +Diese wird durch das XSLT-Skript `xrechnung-report.xsl` erstellt. Dieses Skript kann überschrieben werden um die +HTML-Ausgabe anzupassen. Dazu ist eine neue XSTL-Datei (z. B. `my-xrechnung-report.xsl`) zu erstellen, welche +`xrechnung-report.xsl` per `xsl:import` einbindet. Die neue XSLT-Datei ist anstelle von `xrechnung-report.xsl` in der +Konfigurationsdatei einzutragen. In der neuen XSLT-Datei kann nun das XSLT-Template `html:html` oder eines der von +diesem eingebundenen Unter-Templates `html:*` überschrieben werden. + +Für weiterführende Erläuterungen wird auf die Dokumentation in der XSLT `xrechung\resources\default-report.xsl` +verwiesen. + +# Qualitätssicherung + +## Umgesetzte QS-Maßnahmen + +### Automatische Unit-Tests (Java-Code) +* Die korrekte Funktionsweise des Prüftools wird durch mehr als 60 Unit-Test überprüft. +* Die Unit-Tests sind Teil des bereitgestellten Codes und werden durch den Maven-Build automatisch ausgeführt. +* Die Unit-Tests decken alle grundsätzlichen Funktionen des Prüftools ab. Daneben wird das korrekte Verhalten der + Anwendung bei verschiedenen Fehleingaben überprüft und nachgewiesen. +* Die Testabdeckung (Coverage) liegt derzeit bei ca. 85% des Java-Codes. + Diese Abdeckung wird mittels der Bibliothek jacoco automatisch ermittelt und zeigt, dass alle wesentlichen Funktionen + durch Tests überprüft werden. + Die verbleibenden 15% lassen sich fast ausschließlich auf Fehlerbedingungen (Exceptions) zurückführen, + die in der Praxis auch bei Fehleingaben nicht auftreten können und entsprechend durch keine Unit-Tests durchlaufen + werden. + +### Automatische Code-Analyse (Java-Code) +* Der Quellcode wird dauerhaft und automatisch durch das weit verbreitete System [Sonar](https://www.sonarqube.org/) zur + statischen Code-Analyse geprüft. +* Das Prüftool wird von Sonar mit aktuell ca 1.800 Zeilen Quellcode als klein (S) eingestuft. +* Es existieren aktuelle 7 "Code Smells" und 3 "False Positives". +* Sämtliche „Code Smells“ sind auf nicht abgetestete Bedingungen (siehe oben) zurückzuführen. +* Ein Beispiel für ein "False Positive" ist "Illegale Ausgabe auf STDout", was jedoch eine konkrete Anforderung an das + Prüftool ist. +* In den Aspekten "Reliability", "Security" und "Maintainability" wird der Quellcode jeweils mit dem bestmöglichen + [Rating](https://docs.sonarqube.org/display/SONAR/Metric+Definitions) "A" bewertet. + +### Berücksichtigung von Best Practices für XML-Security +* Es wurden explizit Best Practices für die sichere XML-Verarbeitung mit Java (XML, XML Schema, XSLT) berücksichtigt, um + beispielsweise XXE (XML eXternal Entity) Attacken und allgemein externe Referenzierungen (Entities, XIncludes) + auzuschließen. + +### End-to-End-Testsuite für die Prüftool-Konfiguration XRechnung +* Um die korrekte Funktion der Prüftool-Konfiguration XRechnung zu testen, wurde eine Suite aus 10 Testdokumenten und + insgesamt 310 prüfbaren Aussagen (Assertions) über die resultierenden Prüfberichte erstellt. +* Durch diese Testsuite werden, ausgehend von dem Prüfbericht-Schemas alle möglichen Optionen und Auswahlmöglichkeiten + mindestens je einmal positiv und einmal negativ getestet. +* Diese Zusicherungen können vom Prüftool selbst mittels des Schalter `--check-assertions` automatisch geprüft werden. +* Zudem wird die Integrität aller erstellten Prüfberichte automatisch gegen das Schema (XML Schema und + Schematron-Regeln) des Prüfberichts getestet. +* Für weitere Details siehe [xrechnung/test/readme.txt](xrechnung/test/readme.txt). + + +## Noch nicht umgesetzte QS-Maßnahmen + +### Internes Security-Audit (Java-Code) +Ein abschließendes Security Audit durch den Dienstleister läuft noch und wird voraussichtlich in der KW40 abgeschlossen sein. + +### Fachlicher Test der Prüftool-Konfiguration XRechnung +Die Korrektheit der in der Prüftool-Konfiguration XRechnung enthaltenen Schematron-Dateien bzw. der aus ihnen erstellten +XSLT-Kompilate wurde noch nicht systematisch geprüft, da weder die Schematron-Dateien der EN16931 noch die +Schematron-Dateien des Standards XRechnung in finalen Fassungen vorlagen.