Enterprise edycja

Compliance — szczegółowa referencja

W skrócie

Moduł Compliance kieruje gotowy plik PDF do zewnętrznego sidecara walidacyjnego i zwraca jeden znormalizowany wynik. ComplianceGateway rozwiązuje odpowiedzialny sidecar na podstawie ComplianceProfile, egzekwuje politykę dostępności fail-closed i opakowuje każdy werdykt narzędzia w ExternalValidationResult. Dostarczane są mostki dla veraPDF (PDF/A, PDF/UA, PDF 2.0 Arlington), EU DSS (poziomy PAdES), połączonego sidecara Mustang/KoSIT (ZUGFeRD, Factur-X, EN 16931) oraz samodzielnego demona KoSIT. Moduł udostępnia także stemplowanie gotowości AiReadyCertifier oraz runner dla oficjalnego zestawu testów KoSIT XRechnung.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Powierzchnia Compliance/Evidence jest licencjonowana przez możliwość enterprise.compliance.evidence. Brakujące lub wygasłe uprawnienie odmawia dostępu do funkcji; nie obniża jej działania po cichu.

Poziom	Powierzchnia Compliance
Core	Kontrole strumienia bajtów i gramatyki w obrębie procesu; bez delegacji do zewnętrznego sidecara.
Pro	Walidacja EN 16931 / Factur-X / ZUGFeRD w obrębie procesu; bez zewnętrznego sidecara.
Enterprise	Brama zewnętrznego walidatora (ten moduł) ze znormalizowanym wynikiem i polityką fail-closed.

Walidator e-faktur Pro działający w obrębie procesu oraz zewnętrzny sidecar ZUGFeRD w Enterprise to odrębne powierzchnie. Brama zewnętrznego walidatora jest dostarczana wyłącznie w pakiecie nextpdf/enterprise.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Symbol	Parametry	Domyślne zachowanie	Zwraca	Zgłasza lub kończy się błędem	Uwagi
`ComplianceGateway::__construct`	`list<ExternalValidator> $validators`, `LoggerInterface $logger`, `bool $optional = false`	Indeksuje walidatory według nazwy narzędzia	—	—	Tryb opcjonalny obniża sprawdzenie dostępności do samego ostrzeżenia
`ComplianceGateway::validate`	`string $pdfContent`, `ComplianceProfile $profile`, `array $options = []`	Rozwiązuje walidator przez `ComplianceProfile::toolName()`, sprawdza dostępność, deleguje	`?ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (brak walidatora zarejestrowanego dla narzędzia)	Zwraca `null` tylko w trybie opcjonalnym przy wyłączonym sidecarze
`ComplianceGateway::validateAllProfiles`	`string $pdfContent`, `string $toolName`	Waliduje każdy profil przypisany do narzędzia	`list<ExternalValidationResult>`	Tak samo jak `validate()`	Pomija wyniki `null` (tryb opcjonalny)
`ComplianceGateway::healthCheck`	—	Sonduje punkt końcowy kondycji każdego zarejestrowanego sidecara	`array<string, bool>`	—	Raportuje osiągalność; nie waliduje żadnego dokumentu
`ComplianceGateway::buildComplianceMatrix` (static)	`list<ExternalValidationResult> $results`, `string $commitSha`	Redukuje wyniki do macierzy z wersjonowanym schematem	`array<string, mixed>`	—	Wersja schematu `1.0`; rejestruje dane wyjściowe narzędzia, niczego nie stwierdza
`ComplianceProfile` (enum)	15 przypadków opartych na łańcuchach	Mapuje każdy profil na etykietę standardu i narzędzie	—	—	`standardReference(): string`, `toolName(): string`
`ExternalValidator` (interface)	—	Kontrakt mostka sidecara nad PSR-18	—	`validate()` zgłasza `ComplianceSidecarUnavailableException` przy błędzie transportu	`getToolName()`, `isAvailable()`, `validate()`
`VeraPdfValidator::validate`	Sygnatura interfejsu	POST multipart do sidecara REST veraPDF; parsowanie raportu JSON	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (nieobsługiwany profil)	PDF/A, PDF/UA, Arlington; parsuje wyłącznie JSON, nigdy XML
`DssValidator::validate`	Sygnatura interfejsu	POST JSON w base64 do sidecara REST EU DSS	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (nieobsługiwany profil)	PAdES od B-B po B-LTA; konstruktor odrzuca limity czasu poniżej jednej sekundy
`ZugferdExternalValidator::validate`	Sygnatura interfejsu	POST multipart do połączonego sidecara Mustang/KoSIT	`ExternalValidationResult`	`ComplianceSidecarUnavailableException` (także przy otwartym wyłączniku obwodu); `InvalidArgumentException` (nieobsługiwany profil)	ZUGFeRD 2.4, Factur-X 1.08, EN 16931; opcjonalnie wstrzyknięty wyłącznik obwodu
`KoSitValidator::validate`	Sygnatura interfejsu	Surowy POST XML do samodzielnego demona KoSIT	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (nieobsługiwany profil)	Tylko EN 16931; parsuje raport Schematron SVRL w trybie fail-closed
`ExternalValidationResult`	Obiekt wartości readonly	Znormalizowany werdykt narzędzia	—	—	`passes()`, `fails()`, `nonConformanceCount()`, `toComplianceMatrix()`
`NonConformance`	Obiekt wartości readonly	Pojedyncze ustalenie z id reguły, klauzulą, wagą, lokalizacją	—	—	`toArray()`
`ComplianceSidecarUnavailableException`	`string $toolName`, `string $endpoint`, `int $code = 0`, `?Throwable $previous = null`	Sygnał niedostępności sidecara w trybie fail-closed	—	—	Publiczne readonly `toolName` i `endpoint`
`AiReadyCertifier::certify`	`string $pdfBytes`	Ocenia trzy kryteria gotowości; stempluje pochodzenie XMP	`array{0: AiReadyCertification, 1: string}`	`InvalidArgumentException` (stemplowanie wymaga klasycznej tablicy odsyłaczy)	Drugi element jest równy wejściu, gdy poziom wynosi `not_certified`
`AiReadyCertification`	Obiekt wartości readonly	Ocena gotowości z poziomem, liczbą kryteriów, problemami, hashem źródła	—	—	Wewnętrzna etykieta gotowości, a nie certyfikacja standardowa
`XRechnungTestSuiteRunner::__construct`	`string $suitePath`, `ExternalValidator $validator`, `bool $useCuratedNegativeFallback = true`	Rozwiązuje katalog wypakowanego zestawu	—	`InvalidArgumentException` (katalog nie istnieje)	Celuje w oficjalny zestaw testów KoSIT XRechnung
`XRechnungTestSuiteRunner::run`	`bool $stopOnFirstFailure = false`	Waliduje każdą instancję zestawu przez mostek	`XRechnungTestSuiteResult`	`XRechnungTestSuiteException` (walidator niedostępny; brak plików XML)	Także `isAvailable()`, `getSuitePath()`, `discoverTestFiles()`
`XRechnungTestSuiteResult`	Obiekt wartości readonly	Zagregowany wynik zestawu	—	—	`allPassed()`, `totalCount()`, `getFailures()`, `getErrors()`, `toSummary()`
`XRechnungTestCaseResult`	Obiekt wartości readonly	Wynik pojedynczego przypadku	—	—	`passed()`, `hasError()`, `getFilename()`
`XRechnungTestSuiteException`	Konstruktory statyczne	Sygnał błędu wykonawczego zestawu	`self`	—	`validatorUnavailable()`, `noTestFilesFound(string $suitePath)`

namespace NextPDF\Enterprise\Compliance;

final class ComplianceGateway
{
    /** @param list<ExternalValidator> $validators */
    public function __construct(
        array $validators,
        private readonly LoggerInterface $logger,
        private readonly bool $optional = false,
    );

    /** @param array<string, mixed> $options */
    public function validate(
        string $pdfContent,
        ComplianceProfile $profile,
        array $options = [],
    ): ?ExternalValidationResult;

    /** @return list<ExternalValidationResult> */
    public function validateAllProfiles(string $pdfContent, string $toolName): array;

    /** @return array<string, bool> */
    public function healthCheck(): array;

    /**
     * @param list<ExternalValidationResult> $results
     * @return array<string, mixed>
     */
    public static function buildComplianceMatrix(array $results, string $commitSha): array;
}

interface ExternalValidator
{
    public function getToolName(): string;

    public function isAvailable(): bool;

    /** @param array<string, mixed> $options */
    public function validate(
        string $pdfContent,
        ComplianceProfile $profile,
        array $options = [],
    ): ExternalValidationResult;
}

enum ComplianceProfile: string
{
    case PdfA1b = 'pdfa-1b';
    // PdfA2b, PdfA3b, PdfA4, PdfA4f, PdfUa1, PdfUa2, Pdf20Arlington,
    // PadesBasic, PadesTimestamp, PadesLongTerm, PadesArchive,
    // Zugferd24, FacturX108, En16931

    public function standardReference(): string;

    public function toolName(): string;
}

final class AiReadyCertifier
{
    /** @return array{0: AiReadyCertification, 1: string} Tuple of [certification, stamped PDF bytes] */
    public function certify(string $pdfBytes): array;
}

Kontrakt zachowania

ComplianceGateway::validate() rozwiązuje zarejestrowany ExternalValidator, którego getToolName() odpowiada wartości ComplianceProfile::toolName(), sprawdza isAvailable(), deleguje wywołanie i zwraca znormalizowany ExternalValidationResult. Reguły obserwowalne z zewnątrz:

Domyślne zachowanie fail-closed. Gdy rozwiązany sidecar jest niedostępny, a tryb opcjonalny jest wyłączony, wywołanie zgłasza ComplianceSidecarUnavailableException. Dokument nie zostaje sprawdzony; nigdy nie jest traktowany jako zaakceptowany.
Tryb opcjonalny. Skonstruowanie bramy z optional: true (operatorzy podpinają to ze zmiennej środowiskowej NEXTPDF_COMPLIANCE_OPTIONAL) obniża niedostępny sidecar do zapisanego w dzienniku ostrzeżenia i zwrócenia null. Wywołujący muszą traktować null jako „niesprawdzony”. Tryb opcjonalny obejmuje wyłącznie wstępną sondę dostępności; błąd transportu w trakcie samego wywołania walidacji zgłasza ComplianceSidecarUnavailableException w obu trybach.
Nieznany profil. Profil bez zarejestrowanego walidatora zgłasza InvalidArgumentException; nigdy nie przechodzi po cichu.
Semantyka zaliczenia. ExternalValidationResult::passes() wymaga, aby conformant było prawdą oraz zero niezgodności. Każdy wynik niesie profil, nazwę i wersję narzędzia, liczbę asercji, ustalenia, SHA-256 zwalidowanych bajtów, znacznik czasu UTC oraz czas trwania wywołania.
Macierz jest zapisem, a nie stwierdzeniem. buildComplianceMatrix() to statyczny reduktor wytwarzający strukturę z wersjonowanym schematem, wersjami narzędzi i commit SHA dla zachowania śledzenia. Rejestruje dane wyjściowe narzędzia; niczego nie stwierdza.
Przepływ danych. Pełny strumień bajtów pliku PDF jest przesyłany do skonfigurowanego sidecara przez klienta PSR-18. Każda walidacja jest zapisywana przez PSR-3 wraz z profilem, narzędziem, zaliczeniem/niezaliczeniem, liczbą asercji i czasem trwania.

Rozwiązywanie profilu na narzędzie, zgodnie ze zwracaną wartością ComplianceProfile::standardReference() i ::toolName():

Przypadki profilu	Odniesienie do standardu	Narzędzie
`pdfa-1b`, `pdfa-2b`, `pdfa-3b`, `pdfa-4`, `pdfa-4f`	ISO 19005-1/-2/-3/-4 (Level B; Level F dla 4f)	veraPDF
`pdfua-1`, `pdfua-2`	ISO 14289-1:2014, ISO 14289-2:2024	veraPDF
`pdf20-arlington`	ISO 32000-2:2020 (model Arlington)	veraPDF
`pades-b-b`, `pades-b-t`, `pades-b-lt`, `pades-b-lta`	ETSI EN 319 142-1 B-B po B-LTA	EU DSS
`zugferd-2.4`, `factur-x-1.08`, `en-16931`	ZUGFeRD 2.4 / Factur-X 1.08 / EN 16931-1:2017	Mustang/KoSIT

AiReadyCertifier::certify() ocenia trzy kryteria: obecność podpisu strukturalnego, kondycję LTV oraz brak szyfrowania. Trzy zaliczone kryteria dają poziom certified; jedno lub dwa dają partial; zero daje not_certified. Przy certified lub partial dokleja aktualizację przyrostową niosącą strumień pochodzenia XMP oraz nadpisanie Catalog; oryginalne bajty nigdy nie są modyfikowane. Poziom „certified” to wewnętrzna dla NextPDF etykieta gotowości, a nie certyfikacja standardowa.

VeraPdfValidator parsuje wyłącznie odpowiedzi sidecara w formacie JSON (bez XML; z konstrukcji wolne od XXE). KoSitValidator parsuje raport XML SVRL demona z odrzuconymi deklaracjami DOCTYPE i wyłączonym dostępem sieciowym, a raport, którego nie da się sparsować, traktuje jako niepowodzenie wywołania.

Przypadki brzegowe i tryby awarii

Przekroczenie limitu czasu sidecara lub błąd transportu ujawnia się jako ComplianceSidecarUnavailableException z mostka; obowiązuje domyślne zachowanie fail-closed.
Odpowiedź sidecara inna niż 200 wytwarza wynik z niepowodzeniem oraz ustaleniem specyficznym dla narzędzia (na przykład VERAPDF-HTTP-ERROR); nigdy nie jest pozytywnym wynikiem zgodności.
Zniekształcone ciało JSON lub XML sidecara jest niepowodzeniem walidacji wywołania, a nie pozytywnym wynikiem zgodności.
Wyniki EU DSS bez podpisów kończą się niepowodzeniem z DSS-NO-SIGNATURES. Wskazanie inne niż TOTAL_PASSED kończy się niepowodzeniem z DSS-SIG-INVALID. Poziom podpisu poniżej oczekiwanej wartości bazowej kończy się niepowodzeniem z DSS-LEVEL-MISMATCH.
DssValidator publikuje swój budżet limitu czasu na żądanie w każdym żądaniu poprzez nagłówek X-NextPDF-Timeout-Seconds; klient PSR-18 integratora musi go honorować, aby zablokowany sidecar nie mógł nieograniczenie zatrzymać wątku wywołującego.
ZugferdExternalValidator opcjonalnie kieruje wywołania sidecara przez wstrzyknięty wyłącznik obwodu; otwarty wyłącznik mapuje się na ComplianceSidecarUnavailableException (fail-fast, wciąż fail-closed). Domyślnie jest to wyłącznik no-op.
KoSitValidator::isAvailable() akceptuje HTTP 200 i 405 z sondy kondycji demona; demon odpowiada na GET kodem 405, będąc w dobrej kondycji.
Stemplowanie AiReadyCertifier kończy się fail-closed z InvalidArgumentException, gdy oryginalny dokument nie posiada klasycznej tablicy odsyłaczy (na przykład strumieni odsyłaczy).
XRechnungTestSuiteRunner::run() odmawia uruchomienia, gdy walidator jest niedostępny lub zestaw nie zawiera plików XML; przy włączonym useCuratedNegativeFallback podstawia wyselekcjonowany negatywny korpus, gdy zestaw nie dostarcza żadnych nieprawidłowych instancji.

Zachowanie w trybie FIPS

Ten moduł nie wykonuje podpisywania ani powiernictwa kluczy. Polityka algorytmów trybu FIPS jest zarządzana przez moduły Security i Signature. Zgodność podpisu jest delegowana do EU DSS, które dokonuje własnego ustalenia.

Zgodność ze standardami

Brama deleguje werdykt o zgodności do zewnętrznego narzędzia; projekt odzwierciedla wyznaczoną przez same standardy granicę, zgodnie z którą zgodność jest ustalana względem wymagań, a nie deklarowana przez producenta.

Zachowanie	Odniesienie
Obowiązek procesora przestrzegającego zgodności; zgodność ustalana względem standardu	ISO 19005-4:2020 §5.2
Wymagania pliku PDF/A-4 a samodeklaracja producenta	ISO 19005-4:2020 §6.6.4
Zgodność z PDF/UA-2 jest właściwością pliku	ISO 14289-2:2024 §6
Bazowe poziomy podpisu PAdES	ETSI EN 319 142-1 §5.4.3

Werdykt wytwarza zewnętrzne narzędzie. NextPDF nie posiada żadnej certyfikacji i żadnej nie przyznaje; obsługa profilu nie oznacza zgodności z nim. Wyniki walidacji są technicznymi zapisami kontroli struktury do celów referencyjnych, a nie poradą prawną; skonsultuj się ze swoim zespołem ds. zgodności, aby ocenić wystarczalność regulacyjną.

Uwagi wdrożeniowe

Operator hostuje i obsługuje sidecary, przypina ich wersje, ogranicza ich zasięg sieciowy, waliduje ich TLS i kontroluje środowisko, które włącza tryb opcjonalny. Punkty końcowe sidecarów stanowią granicę zaufania; mechanizmy kontroli rezydencji i przechowywania dokumentów, wyników i dzienników są obowiązkiem operatora.
Dane wyjściowe buildComplianceMatrix() są zaprojektowane pod śledzenie w CI: przypnij commit SHA i archiwizuj macierz obok artefaktów budowania.
Runner XRechnung oczekuje oficjalnego zestawu testów wypakowanego do lokalnego katalogu; komunikat jego konstruktora wskazuje publiczne źródło pobrania.
Wewnętrzne szczegóły mechanizmów pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tablice mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Zobacz także

Przegląd możliwości Compliance
Validation — pełna dokumentacja referencyjna
Evidence — szczegółowa referencja
Pro Compliance — e-faktura w obrębie procesu (odrębna powierzchnia)
Core Conformance