demo/validator
1
0
Fork 0
mirror of https://github.com/itplr-kosit/validator.git synced 2026-05-25 16:55:39 +00:00
Code Issues Projects Releases Packages Wiki Activity

Updated README according to eInvoice configuration (only German still)

Browse source
This commit is contained in:
fbuettner 2017-10-26 10:05:32 +02:00
parent 2382445b7a
commit 0fd87014b4
1 changed files with 212 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

231
README.md
View file

@ -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-<version>-standalone.jar -s <scenario-config-file> [OPTIONS] [FILE]...```
```java -jar validationtool-<version>-standalone.jar -s <scenario-config-file> [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-<version>-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-<version>-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,18 +138,19 @@ List<Document> 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
@ -100,5 +160,134 @@ Ein `mvn install -Pstandalone` baut die Standalone-Variante. Diese Variante enth
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
## 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:
```
<scenario>
<name>EN16931 CIUS XRechnung (UBL Invoice)</name>
...
<createReport>
<resource>
<name>Prüfbericht für XRechnung</name>
<location>resources/xrechnung/xrechnung-report.xsl</location>
</resource>
<customLevel level="warning">BR-15 BR-DE-3</customLevel>
</createReport>
</scenario>
```
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.