Enterprise 에디션

Compliance — 심층 참조

한눈에 보기

Compliance 모듈은 완성된 PDF를 외부 검증 사이드카로 라우팅하고 하나의 정규화된 결과를 반환합니다. ComplianceGateway는 ComplianceProfile로부터 담당 사이드카를 해석하고, 실패-차단 가용성 정책을 시행하며, 모든 도구 판정을 ExternalValidationResult로 감쌉니다. veraPDF(PDF/A, PDF/UA, PDF 2.0 Arlington), EU DSS(PAdES 레벨), 통합 Mustang/KoSIT 사이드카(ZUGFeRD, Factur-X, EN 16931), 그리고 독립형 KoSIT 데몬을 위한 브리지가 제공됩니다. 이 모듈은 AiReadyCertifier 준비도 스탬핑과 공식 KoSIT XRechnung 테스트 스위트용 러너도 제공합니다.

가용성 및 라이선싱

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에 포함되며 Enterprise 등급 라이선스 엔벨로프로 활성화됩니다. 해당 사용 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

Compliance/Evidence 표면은 enterprise.compliance.evidence 기능으로 라이선스됩니다. 사용 권한이 누락되거나 만료되면 기능이 거부되며, 동작을 조용히 격하하지 않습니다.

등급	Compliance 표면
Core	인프로세스 바이트 스트림 및 문법 검사. 외부 사이드카 위임 없음.
Pro	인프로세스 EN 16931 / Factur-X / ZUGFeRD 검증. 외부 사이드카 없음.
Enterprise	통합 결과와 실패-차단 정책을 갖춘 외부 검증기 게이트웨이(이 모듈).

Pro 인프로세스 전자송장 검증기와 Enterprise 외부 ZUGFeRD 사이드카는 별개의 표면입니다. 외부 검증기 게이트웨이는 nextpdf/enterprise 패키지에만 포함됩니다.

공개 API 표면

composer require nextpdf/enterprise:^3

심볼	매개변수	기본 동작	반환	예외 또는 실패	비고
`ComplianceGateway::__construct`	`list<ExternalValidator> $validators`, `LoggerInterface $logger`, `bool $optional = false`	검증기를 도구 이름으로 색인	—	—	선택 모드는 가용성 확인을 경고 전용으로 격하함
`ComplianceGateway::validate`	`string $pdfContent`, `ComplianceProfile $profile`, `array $options = []`	`ComplianceProfile::toolName()`으로 검증기를 해석하고, 가용성을 확인하며, 위임	`?ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException`(도구에 등록된 검증기 없음)	사이드카가 다운된 선택 모드에서만 `null` 반환
`ComplianceGateway::validateAllProfiles`	`string $pdfContent`, `string $toolName`	도구에 매핑된 모든 프로필을 검증	`list<ExternalValidationResult>`	`validate()`와 동일	`null`(선택 모드) 결과는 건너뜀
`ComplianceGateway::healthCheck`	—	등록된 모든 사이드카 상태 엔드포인트를 프로브	`array<string, bool>`	—	도달 가능성을 보고. 문서는 검증하지 않음
`ComplianceGateway::buildComplianceMatrix` (정적)	`list<ExternalValidationResult> $results`, `string $commitSha`	결과를 스키마 버전 매트릭스로 축약	`array<string, mixed>`	—	스키마 버전 `1.0`. 도구 출력을 기록할 뿐 아무것도 단언하지 않음
`ComplianceProfile` (enum)	15개의 string 기반 케이스	각 프로필을 표준 레이블과 도구에 매핑	—	—	`standardReference(): string`, `toolName(): string`
`ExternalValidator` (인터페이스)	—	PSR-18 위의 사이드카 브리지 계약	—	전송 실패 시 `validate()`가 `ComplianceSidecarUnavailableException`을 던짐	`getToolName()`, `isAvailable()`, `validate()`
`VeraPdfValidator::validate`	인터페이스 시그니처	veraPDF REST 사이드카로 멀티파트 POST. JSON 보고서 파싱	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException`(지원되지 않는 프로필)	PDF/A, PDF/UA, Arlington. JSON만 파싱하고 XML은 결코 파싱하지 않음
`DssValidator::validate`	인터페이스 시그니처	EU DSS REST 사이드카로 Base64 JSON POST	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException`(지원되지 않는 프로필)	PAdES B-B부터 B-LTA까지. 생성자는 1초 미만의 시간 초과를 거부함
`ZugferdExternalValidator::validate`	인터페이스 시그니처	통합 Mustang/KoSIT 사이드카로 멀티파트 POST	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`(열린 회로 차단기에서도); `InvalidArgumentException`(지원되지 않는 프로필)	ZUGFeRD 2.4, Factur-X 1.08, EN 16931. 선택적으로 주입되는 회로 차단기
`KoSitValidator::validate`	인터페이스 시그니처	독립형 KoSIT 데몬으로 원시 XML POST	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException`(지원되지 않는 프로필)	EN 16931 전용. Schematron SVRL 보고서를 실패-차단으로 파싱
`ExternalValidationResult`	읽기 전용 값 객체	정규화된 도구 판정	—	—	`passes()`, `fails()`, `nonConformanceCount()`, `toComplianceMatrix()`
`NonConformance`	읽기 전용 값 객체	규칙 id, 조항, 심각도, 위치를 담은 단일 발견 항목	—	—	`toArray()`
`ComplianceSidecarUnavailableException`	`string $toolName`, `string $endpoint`, `int $code = 0`, `?Throwable $previous = null`	실패-차단 사이드카 불가용 신호	—	—	공개 읽기 전용 `toolName` 및 `endpoint`
`AiReadyCertifier::certify`	`string $pdfBytes`	세 가지 준비도 기준을 평가. XMP 프로비넌스를 스탬핑	`array{0: AiReadyCertification, 1: string}`	`InvalidArgumentException`(스탬핑은 고전적 교차 참조 테이블을 요구함)	레벨이 `not_certified`일 때 두 번째 요소는 입력과 동일함
`AiReadyCertification`	읽기 전용 값 객체	레벨, 기준 개수, 이슈, 소스 해시를 담은 준비도 평가	—	—	표준 인증이 아닌 내부 준비도 레이블
`XRechnungTestSuiteRunner::__construct`	`string $suitePath`, `ExternalValidator $validator`, `bool $useCuratedNegativeFallback = true`	추출된 스위트 디렉터리를 해석	—	`InvalidArgumentException`(디렉터리가 존재하지 않음)	공식 KoSIT XRechnung 테스트 스위트를 대상으로 함
`XRechnungTestSuiteRunner::run`	`bool $stopOnFirstFailure = false`	브리지를 통해 각 스위트 인스턴스를 검증	`XRechnungTestSuiteResult`	`XRechnungTestSuiteException`(검증기 불가용. XML 파일 없음)	`isAvailable()`, `getSuitePath()`, `discoverTestFiles()`도 있음
`XRechnungTestSuiteResult`	읽기 전용 값 객체	집계된 스위트 결과	—	—	`allPassed()`, `totalCount()`, `getFailures()`, `getErrors()`, `toSummary()`
`XRechnungTestCaseResult`	읽기 전용 값 객체	케이스별 결과	—	—	`passed()`, `hasError()`, `getFilename()`
`XRechnungTestSuiteException`	정적 생성자	스위트 런타임 실패 신호	`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;
}

동작 계약

ComplianceGateway::validate()는 getToolName()이 ComplianceProfile::toolName()과 일치하는 등록된 ExternalValidator를 해석하고, isAvailable()을 확인하며, 위임한 뒤 정규화된 ExternalValidationResult를 반환합니다. 외부에서 관찰 가능한 규칙은 다음과 같습니다.

실패-차단 기본값. 해석된 사이드카를 사용할 수 없고 선택 모드가 꺼져 있으면, 호출은 ComplianceSidecarUnavailableException을 발생시킵니다. 문서는 검사되지 않으며, 통과한 것으로 취급되는 일이 결코 없습니다.
선택 모드. 게이트웨이를 optional: true로 생성하면(운영자는 NEXTPDF_COMPLIANCE_OPTIONAL 환경 변수에서 이를 연결) 사용할 수 없는 사이드카가 기록된 경고와 null 반환으로 격하됩니다. 호출자는 null을 “검사되지 않음”으로 취급해야 합니다. 선택 모드는 사전 가용성 프로브만 적용됩니다. 검증 호출 자체 중의 전송 실패는 두 모드 모두에서 ComplianceSidecarUnavailableException을 발생시킵니다.
알 수 없는 프로필. 등록된 검증기가 없는 프로필은 InvalidArgumentException을 발생시키며, 결코 조용히 통과하지 않습니다.
통과 의미론. ExternalValidationResult::passes()는 conformant가 true이고 동시에 비적합이 0건일 것을 요구합니다. 모든 결과는 프로필, 도구 이름과 버전, 단언 개수, 발견 항목, 검증된 바이트의 SHA-256, UTC 타임스탬프, 그리고 호출 소요 시간을 담습니다.
매트릭스는 기록이지 단언이 아님. buildComplianceMatrix()는 추적성을 위해 도구 버전과 커밋 SHA를 담은 스키마 버전 구조를 생성하는 정적 리듀서입니다. 도구 출력을 기록할 뿐 아무것도 단언하지 않습니다.
데이터 흐름. 전체 PDF 바이트 스트림은 PSR-18 클라이언트를 통해 구성된 사이드카로 전송됩니다. 각 검증은 프로필, 도구, 통과/실패, 단언 개수, 소요 시간과 함께 PSR-3으로 기록됩니다.

ComplianceProfile::standardReference() 및 ::toolName()이 반환하는 프로필-도구 라우팅:

프로필 케이스	표준 참조	도구
`pdfa-1b`, `pdfa-2b`, `pdfa-3b`, `pdfa-4`, `pdfa-4f`	ISO 19005-1/-2/-3/-4 (Level B; 4f의 경우 Level F)	veraPDF
`pdfua-1`, `pdfua-2`	ISO 14289-1:2014, ISO 14289-2:2024	veraPDF
`pdf20-arlington`	ISO 32000-2:2020 (Arlington 모델)	veraPDF
`pades-b-b`, `pades-b-t`, `pades-b-lt`, `pades-b-lta`	ETSI EN 319 142-1 B-B부터 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()는 세 가지 기준을 평가합니다: 구조적 서명 존재, LTV 상태, 암호화 부재. 세 기준을 통과하면 레벨 certified가, 한두 개 통과하면 partial이, 0개 통과하면 not_certified가 됩니다. certified 또는 partial에서는 XMP 프로비넌스 스트림과 Catalog 재정의를 담은 증분 업데이트를 추가합니다. 원본 바이트는 결코 변경되지 않습니다. “certified” 레벨은 표준 인증이 아니라 NextPDF 내부 준비도 레이블입니다.

VeraPdfValidator는 JSON 사이드카 응답만 파싱합니다(XML 없음. 구성상 XXE에 안전함). KoSitValidator는 DOCTYPE 선언을 거부하고 네트워크 접근을 비활성화한 채 데몬의 XML SVRL 보고서를 파싱하며, 파싱할 수 없는 보고서는 호출의 실패로 취급합니다.

엣지 케이스 및 실패 모드

사이드카 시간 초과 또는 전송 오류는 브리지에서 ComplianceSidecarUnavailableException으로 드러나며, 실패-차단 기본값이 적용됩니다.
비 200 사이드카 응답은 도구별 발견 항목(예: VERAPDF-HTTP-ERROR)을 담은 실패 결과를 생성하며, 결코 적합성 통과가 아닙니다.
잘못된 형식의 사이드카 JSON 또는 XML 본문은 적합성 통과가 아니라 호출의 검증 실패입니다.
서명이 없는 EU DSS 결과는 DSS-NO-SIGNATURES로 실패합니다. TOTAL_PASSED 이외의 표시는 DSS-SIG-INVALID로 실패합니다. 기대 기준선보다 낮은 서명 레벨은 DSS-LEVEL-MISMATCH로 실패합니다.
DssValidator는 요청별 시간 초과 예산을 X-NextPDF-Timeout-Seconds 헤더를 통해 모든 요청에 게시합니다. 통합자의 PSR-18 클라이언트가 이를 준수해야 정체된 사이드카가 호출 스레드를 무한정 막을 수 없습니다.
ZugferdExternalValidator는 선택적으로 주입된 회로 차단기를 통해 사이드카 호출을 라우팅합니다. 열린 차단기는 ComplianceSidecarUnavailableException으로 매핑됩니다(빠른 실패. 여전히 실패-차단). 기본값은 무동작 차단기입니다.
KoSitValidator::isAvailable()는 데몬 상태 프로브에서 HTTP 200과 405를 허용합니다. 데몬은 정상일 때 GET에 405로 응답합니다.
AiReadyCertifier 스탬핑은 원본 문서에 고전적 교차 참조 테이블이 없을 때(예: 교차 참조 스트림) InvalidArgumentException으로 실패-차단됩니다.
XRechnungTestSuiteRunner::run()은 검증기를 사용할 수 없거나 스위트에 XML 파일이 없을 때 실행을 거부합니다. useCuratedNegativeFallback가 활성화되면 스위트에 무효 인스턴스가 없을 때 큐레이션된 네거티브 코퍼스로 대체합니다.

FIPS 모드 동작

이 모듈은 서명이나 키 보관을 수행하지 않습니다. FIPS 모드 알고리즘 정책은 Security 및 Signature 모듈이 관장합니다. 서명 적합성은 EU DSS에 위임되며, EU DSS가 자체 판정을 내립니다.

적합성

게이트웨이는 적합성 판정을 외부 도구에 위임합니다. 이 설계는 적합성이 생산자에 의해 단언되는 것이 아니라 요구 사항에 대조하여 결정된다는 표준 자체의 경계를 반영합니다.

동작	참조
적합 처리기 의무. 적합성은 표준에 대조하여 결정됨	ISO 19005-4:2020 §5.2
PDF/A-4 파일 요구 사항 대 생산자 자가 단언	ISO 19005-4:2020 §6.6.4
PDF/UA-2 적합성은 파일의 속성임	ISO 14289-2:2024 §6
PAdES 기준 서명 레벨	ETSI EN 319 142-1 §5.4.3

외부 도구가 판정을 생성합니다. NextPDF는 어떠한 인증도 보유하지 않으며 부여하지도 않습니다. 프로필 지원은 그 프로필에 대한 적합성이 아닙니다. 검증 결과는 참고용 기술적 구조 검사 기록이지 법률 자문이 아닙니다. 규제 충분성 판단은 규정 준수 팀에 문의하십시오.

개발 노트

운영자가 사이드카를 호스팅 및 운영하고, 버전을 핀하고, 네트워크 도달 범위를 제한하고, TLS를 검증하며, 선택 모드를 활성화하는 환경을 제어합니다. 사이드카 엔드포인트는 신뢰 경계입니다. 문서, 결과, 로그에 대한 레지던시 및 보존 제어는 운영자의 책임입니다.
buildComplianceMatrix() 출력은 CI 추적성을 위해 설계되었습니다: 커밋 SHA를 핀하고 매트릭스를 빌드 아티팩트 옆에 보관하십시오.
XRechnung 러너는 로컬 디렉터리에 추출된 공식 테스트 스위트를 기대합니다. 생성자 메시지가 공개 다운로드 소스를 명시합니다.
내부 메커니즘 세부 사항은 소스 저장소의 내부 문서에 남아 있으며 이 매뉴얼의 범위 밖입니다.

공개 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 테이블, 런북 파일명, 티켓 접두사는 범위 밖입니다.