Pro 에디션

Compliance — 심층 참조

한눈에 보기

Compliance 모듈은 NextPDF\Pro\Compliance 아래에 세 개의 독립적인 표면을 묶습니다.

언어 태그 보고 — 엄격한 PDF/UA-2 /Lang 정책 파사드와 구조화된 PSR-3 형태의 준수 이벤트 리포터.
전자송장 처리 — EN 16931 시맨틱 모델에 대조한 Factur-X 1.08 / ZUGFeRD 2.4 검증, 그리고 하이브리드 PDF/A-3 생성.
출처(Provenance) — 적대적으로 강화된 JUMBF 파서를 통해 호출자가 제공한 C2PA 매니페스트 저장소를 임베드하고 추출합니다. 주장 합성은 프리뷰 게이트 상태로 유지됩니다.

이 모듈은 검사한 것을 보고합니다. 문서를 인증하지 않으며 암호화 서명을 수행하지 않습니다.

가용성 및 라이선싱

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

기능별 라이선스 플래그는 없습니다. 이것은 Pro 에디션 기능입니다. 실험적인 C2PA 주장 빌더는 추가로 명시적인 환경 옵트인이 필요합니다(엣지 케이스 및 실패 모드 참조).

공개 API 표면

composer require nextpdf/pro:^3

심볼	매개변수	기본 동작	반환	예외 또는 실패 조건	비고
`LangComplianceReporter::warn()` / `::error()`	`string $tag, string $reason, ?string $clauseReference = null`	PSR-3 로거를 통해 언어 태그 이벤트마다 하나의 구조화된 JSON 레코드를 방출합니다	`void`	레코드의 JSON 인코딩이 실패하면 `JsonException`	`warn` = lax 모드 거부, `error` = strict 모드 거부
`LangComplianceReporter::reportException()`	`InvalidBcp47TagException $exception, string $severity = 'error'`	예외에서 태그와 사유를 추출하고 `warn()` 또는 `error()`에 위임합니다	`void`	위와 같음	편의 경로
`LangComplianceReporter::buildRecord()`	`string $severity, string $tag, string $reason, ?string $clauseReference = null`	로깅 없이 레코드 배열을 빌드합니다	`array`	예외를 던지지 않음	파일별 JSON 요약 같은 커스텀 싱크용
`ConformancePolicy::default()`	`?LoggerInterface $logger = null`	strict UA-2 정책: 잘못된 형식이거나 등록되지 않은 `/Lang` 태그를 거부합니다	`self`	예외를 던지지 않음	v5.0 기본값은 strict입니다
`ConformancePolicy::fromCore()`	`CoreConformancePolicy $core, ?LoggerInterface $logger = null`	기존 Core 정책을 있는 그대로 감쌉니다. 어떤 축도 뒤집지 않습니다	`self`	예외를 던지지 않음	strict 자세를 위해서는 `default()`를 선호하십시오
`ConformancePolicy::withStrictUa2()`	`bool $enabled`	strict 축이 설정된 복사본을 반환합니다. 비활성화 시 PSR-3 `notice`를 방출합니다	`self`	예외를 던지지 않음	Deprecated 옵트아웃, 제거 목표 `6.0.0`
`ConformancePolicy::isStrictUa2()` / `::mode()`	—	기저 Core 정책을 읽습니다	`bool` / `ConformanceMode`	예외를 던지지 않음	—
`EInvoiceValidator::validate()`	`string $pdfPath`	전체 파이프라인: PDF/A-3 래퍼 검사, 첨부 추출, 프로필 감지, EN 16931 규칙, Schematron	`EInvoiceValidationResult`	I/O 실패, 잘못된 형식의 PDF 구조, 또는 도구 크래시 시 `EInvoiceException` 서브클래스	고정된 SPI 인터페이스. 올바른 형식의 비전자송장 PDF는 결과를 반환하며 예외를 던지지 않습니다
`EInvoiceXmlValidator::validate()`	`string $xmlPayload, ValidatorContext $context`	CII 페이로드에 대한 구조적 사전 검사와 EN 16931 심층 시맨틱 규칙 코퍼스	계약형 `ValidationResult`	잘못된 입력에 대해 예외를 던지지 않음. 거부는 findings를 담은 실패 결과로 표면화됨	구체적인 계층 간 검증기. 입력은 `XmlGuard`를 통해 게이트됨
`EInvoiceValidationResult::isValid()`	—	래퍼, 첨부 사양, 프로필, 구문이 성립하고 FATAL 위반이 없을 때만 true	`bool`	예외를 던지지 않음	위반 목록이 비어 있다는 것만으로는 유효성이 아님
`EInvoiceValidationResult::notAnEInvoice()`	—	결정적인 all-null, all-false 결과	`self`	예외를 던지지 않음	”하이브리드 송장 아님” 경우를 위한 팩토리
`EInvoiceProfile`	문자열 기반 enum	케이스 `MINIMUM`, `BASIC_WL`, `BASIC`, `EN16931`, `EXTENDED`, BT-24 URN 기반	—	—	`isEn16931Conformant()`는 `MINIMUM`과 `BASIC_WL`에 대해 false
`EInvoiceSyntax`	문자열 기반 enum	케이스 `UN_CEFACT_CII`, `UBL_INVOICE`, `UBL_CREDIT_NOTE`	—	—	CII만 `isFacturXEligible()`. UBL은 검증 전용
`BusinessRuleViolation`	`string $ruleId, BusinessRuleSeverity $severity, string $message, ?string $xpath = null, ?string $ramPath = null`	불변 위반 DTO	—	—	규칙 ID 계열 `BR-`, `BR-CO-`, `BR-CL-`, `BR-DEC-`, `BR-FXEXT-`
`BusinessRuleSeverity`	문자열 기반 enum	`FATAL`은 송장을 무효화하고 `WARNING`은 품질 우려를 표시합니다	—	—	EN 16931 Schematron 수준을 반영
`FacturXEmbedder::embed()`	시그니처 펜스 참조	PDF/A 소스에 임베디드 파일 스트림, filespec, XMP를 추가하고 xref를 재작성합니다	`void`	잘못된 형식의 XML, 읽을 수 없는 소스, 누락된 카탈로그, 객체 스트림 또는 xref 스트림 소스, 또는 출력 쓰기 실패 시 `EInvoiceException`	소스 파일은 그대로 유지됨
`FacturXEmbedderOptions::default()`	—	`/AFRelationship /Alternative`, 파일명 `factur-x.xml`, 타입 `INVOICE`, 버전 `1.0`	`self`	예외를 던지지 않음	기본값은 독일 의무를 충족하며 프랑스에서도 계속 허용됨
`FacturXEmbedderOptions::withRelationship()` / `::withFilename()`	`string`	오버라이드가 적용된 복사본을 반환합니다	`self`	허용 집합을 벗어나면 `InvalidArgumentException`	관계: `Source`, `Data`, `Alternative`. 파일명에는 `zugferd-invoice.xml`과 `xrechnung.xml` 포함
`FacturXEmbedderOptions::withDocumentType()`	`string $documentType`	XMP 문서 타입 오버라이드가 적용된 복사본을 반환합니다	`self`	예외를 던지지 않음	값은 방어적으로 열거되지 않음
`FacturXContractEmbedder::embed()`	`string $pdfBytes, string $xmlPayload, EmbedderOptions $options`	단기 임시 파일을 통한 `FacturXEmbedder`에 대한 바이트 입력·바이트 출력 어댑터	`string`	`EInvoiceException`. `XRECHNUNG` 프로필은 Enterprise 전용으로 거부됨	계층 간 `EmbedderInterface` 구현
`C2paManifestEmbedder::embed()`	`string $pdfBytes, ManifestStore $store`	저장소의 바이트 직렬화를 프로필 위치에 임베드합니다	`string`	임베드 실패 시 `C2paException`	고정된 SPI 인터페이스. 바이트 전용, I/O 없음
`C2paManifestEmbedder::extract()`	`string $pdfBytes`	강화된 JUMBF 파서를 통해 임베디드 저장소를 파싱합니다	`ManifestStore\|null`	저장소가 존재하지만 강화 한도를 위반하면 `C2paException` 서브클래스	null은 부재를 나타냄. 부재는 예외를 던지지 않음
`ManifestStore::fromBoxes()` / `::empty()`	`list<JumbfBox>` / —	불변 저장소 값 객체를 빌드합니다	`self`	예외를 던지지 않음	박스 순서는 왕복 동등성에 중요합니다
`ManifestStore::toBytes()` / `::isEmpty()` / `::size()`	—	루트 박스를 직렬화합니다. 빈 저장소는 빈 문자열로 직렬화됩니다	`string` / `bool` / `int`	예외를 던지지 않음	—
`JumbfBoxParser::parse()`	`string $bytes`	하드 캡 아래에서 루트 레벨 JUMBF 박스를 파싱합니다	`list<JumbfBox>`	`MalformedJumbfException`, `JumbfBombException`, `JumbfCycleDetectedException`, `JumbfDepthExceededException`	한도: 깊이 8, 박스당 64 MiB, 총 128 MiB, `MAX_CHILDREN_PER_SUPERBOX` 4096
`JumbfBox::superbox()` / `::leaf()`	`string $tbox, …`	검증된 박스를 빌드합니다. `toBytes()`는 파서를 통해 왕복합니다	`self`	TBox가 정확히 4바이트가 아니면 `MalformedJumbfException`	—
`C2paCapabilityStatus::current()` / `::summary()`	—	C2PA 기능 성숙도를 보고합니다. 현재 `preview-draft`	`self` / `string`	예외를 던지지 않음	기계가 확인 가능한 프리뷰 마커
`Feature::PREVIEW_C2PA_DRAFT->isEnabled()`	—	매 호출마다 프로세스 환경을 읽습니다. 리터럴 `'1'`만 활성화합니다	`bool`	예외를 던지지 않음	환경 변수 `NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT`
`ExperimentalC2paEmbedder::buildManifestStore()`	`string $sourceBytes, string $producer`	하나의 SHA-256 해시 바인딩 주장 어서션을 담은 드래프트 고정 매니페스트 저장소를 빌드합니다	`ManifestStore`	프리뷰 플래그가 꺼져 있으면 생성자가 `LogicException`을 던집니다	프리뷰. 와이어 포맷은 드래프트 스냅샷에 고정됨. 주장 서명은 방출되지 않음

진입점 시그니처, 그대로:

public static function default(?LoggerInterface $logger = null): self
public function withStrictUa2(bool $enabled): self
public function isStrictUa2(): bool

public function validate(string $pdfPath): EInvoiceValidationResult

public function embed(
    string $sourcePdfPath,
    string $xml,
    EInvoiceProfile $profile,
    string $outputPdfPath,
    ?FacturXEmbedderOptions $options = null,
): void

public function embed(string $pdfBytes, ManifestStore $store): string
public function extract(string $pdfBytes): ?ManifestStore

동작 계약

언어 태그 보고. LangComplianceReporter는 PDF/UA-2 언어 태그 이벤트마다 하나의 구조화된 JSON 레코드를 방출합니다. 각 레코드는 고정된 이벤트 판별자, 심각도(lax 모드 거부의 경우 warn, strict 모드 거부의 경우 error), 문제가 된 태그 원문, 기계가 읽을 수 있는 사유, 파싱된 태그 구성 요소(태그가 RFC 5646 형태 문법에 실패하면 null), ISO 14289-2 §8.4.4 조항 참조, 그리고 마이크로초 단위의 UTC 타임스탬프를 담습니다. JSON은 PSR-3 메시지 본문으로 전달되며, 다운스트림 싱크는 메시지 필드를 직접 파싱합니다. ConformancePolicy는 Core 준수 정책 위의 Premium 파사드입니다. 그 기본값은 strict UA-2 언어 처리를 적용하고 /Lang에 도달하는 잘못된 형식이거나 등록되지 않은 태그를 거부합니다. 옵트아웃 헬퍼 withStrictUa2(false)는 레거시 lax 동작으로 되돌리며, 유효 값이 실제로 변경될 때 PSR-3 notice를 기록합니다. NextPDF는 v5.0부터 그 헬퍼를 deprecated로 표시하며 제거 목표는 6.0.0입니다. 마이그레이션하려면 composer pdfua2:audit-lang-tags <pdf-or-dir>로 코퍼스에서 잘못된 형식의 /Lang 값을 감사하고, 이를 수정한 뒤, 옵트아웃 호출을 제거하십시오.

전자송장 처리. EInvoiceValidator는 하이브리드 PDF 검증을 위한 고정된 SPI 계약입니다: PDF/A-3 래퍼 검사, /AF 첨부 추출, BT-24 사양 식별자로부터의 프로필 감지, EN 16931 비즈니스 규칙 엔진, 그리고 Schematron 패스. 올바른 형식의 비 Factur-X PDF는 예외를 던지는 대신 EInvoiceValidationResult::notAnEInvoice()를 반환합니다. I/O 실패, 잘못된 형식의 PDF 구조, 또는 도구 크래시만 EInvoiceException 서브클래스를 발생시킵니다. EInvoiceXmlValidator는 구체적인 계층 간 XML 검증기입니다: Core XmlGuard를 통해 입력을 게이트하고, 구조적 사전 검사와 심층 EN 16931 시맨틱 규칙 코퍼스를 실행하며, fail-closed로 동작합니다 — 엔진 오류는 오류 finding으로 표면화되며 결코 조용한 통과가 되지 않습니다. FacturXEmbedder는 PDF/A 소스를 하이브리드 PDF/A-3로 수정합니다: 임베디드 파일 스트림, 구성 가능한 /AFRelationship을 가진 filespec, 그리고 Factur-X XMP 확장 패킷을 추가한 뒤, 고전적인 상호 참조 테이블을 재작성합니다. 카탈로그 /AF 배열과 /Names /EmbeddedFiles 이름 트리 양쪽 모두 첨부를 참조하므로, 레거시 ZUGFeRD 리더가 이를 해석할 수 있습니다.

출처(Provenance). C2paManifestEmbedder는 호출자가 제공한 C2PA 매니페스트 저장소를 PDF 바이트 문자열에 임베드하거나 추출합니다. ManifestStore는 경계를 넘는 불변 값 객체입니다. 이 이음매(seam)는 바이트 전용이며 벤더 중립적입니다: 주장을 합성하거나, URI 참조를 수집하거나, 해시 바인딩을 해석하지 않으며, 네트워크나 파일 시스템 I/O를 수행하지 않습니다. extract()는 미스 시 null을 반환하며 저장소가 없는 PDF에서는 저렴합니다. null이 아닌 모든 추출은 이미 JumbfBoxParser 강화 한도를 통과했습니다.

이 모듈은 검사한 것을 보고합니다. 문서를 인증하거나, 법적 구속력을 부여하거나, 어떤 출력이 규정을 충족한다고 보장하지 않습니다. 전자송장 검증기는 세무 당국 검증기가 아니며 국가별 확장(예: 이탈리아 SDI, 프랑스 Chorus Pro, 독일 XRechnung)을 제외합니다. EN 16931-1이 명시하듯, 송장 발행자는 관련 법규의 규칙을 충족할 책임을 계속 집니다. 표준에 대한 지원은 그 표준에 대한 적합성이 아닙니다. 규제 충분성은 규정 준수 팀에 문의하십시오.

엣지 케이스 및 실패 모드

올바른 형식의 비 Factur-X PDF는 “전자송장 아님” 결과를 반환합니다. 예외를 던지지 않습니다.
비어 있는 비즈니스 규칙 위반 목록 그 자체가 문서가 유효함을 의미하지는 않습니다. 래퍼 및 첨부 검사도 적용됩니다.
FacturXEmbedder는 압축된 객체 스트림(/Type /ObjStm)이나 상호 참조 스트림(/Type /XRef, 하이브리드 /XRefStm)을 사용하는 소스에서 fail-closed로 동작합니다. 그러한 소스는 먼저 고전적인 상호 참조 테이블로 다시 저장하십시오.
XML 페이로드는 Core XmlGuard를 통해 게이트됩니다: DOCTYPE 또는 엔티티 선언, 초과 크기 입력, 유효하지 않은 UTF-8은 임베드 경로에서는 EInvoiceException으로, 검증기 경로에서는 실패 결과로 거부됩니다.
FacturXContractEmbedder는 XRECHNUNG 프로필을 조용히 다운그레이드하는 대신 명시적으로 거부합니다. XRechnung 생성은 Enterprise 기능입니다.
C2paManifestEmbedder::extract()는 부재(null)와 변형(위반된 불변식을 명명하는 C2paException 서브클래스: 잘못된 형식의 구조, 크기 또는 개수 폭탄, 오프셋 순환, 중첩 깊이)를 구별합니다.
ExperimentalC2paEmbedder 생성은 프리뷰 환경 플래그가 '1'이 아니면 LogicException을 던집니다. 그 와이어 포맷은 C2PA 드래프트 스냅샷에 고정되어 있으며 예고 없이 변경될 수 있습니다. 주장 서명을 방출하지 않습니다. 이 기능은 C2PA PDF 프로필이 확정될 때까지 프리뷰로 유지됩니다.
strict UA-2 lax 옵트아웃은 deprecated입니다. strict 기본값으로 마이그레이션하십시오(동작 계약 참조).
이 모듈은 암호화 서명을 수행하지 않습니다. C2PA 주장 서명과 키 보관은 범위 밖입니다. FIPS 모드 서명 동작은 Security 모듈을 참조하십시오.

적합성

동작	참조	상태
자연어 선언(`/Lang`)	ISO 14289-2:2024 §8.4.4	검사 / 보고됨
핵심 송장 시맨틱 모델	EN 16931-1:2026	검사됨 (발행자가 책임을 계속 짐)
연관 파일 / 임베디드 파일 스트림	ISO 32000-2:2020 §14.13.2	생성됨 (`/AF`, `/EF`, `/Params`)
첨부 관계 및 컨테이너 규칙	Factur-X 1.08 §3.1, §6.2	생성 / 검사됨 (기본값 `/AFRelationship /Alternative`)
C2PA 매니페스트 저장소 / JUMBF	C2PA 2.1 §11.1	임베드 / 추출 지원. 주장 합성은 프리뷰

이는 모듈이 기반으로 삼은 사양과 검사하거나 생성하는 내용을 기록합니다. 인증이나 규제 충분성에 대한 진술이 아닙니다. NextPDF는 이 표준들에 대한 인증을 보유하고 있지 않습니다.

개발 노트

리포터의 레코드 형태는 안정적인 계약입니다. 다운스트림 알림 규칙은 고정된 이벤트 판별자에 고정될 수 있습니다.
strict UA-2를 비활성화하면 유효 값이 변경될 때만 텔레메트리에 보이는 deprecation notice를 방출합니다. 현재 값을 다시 단언하는 것은 조용합니다.
Factur-X 임베더는 소스 바이트를 원문 그대로 보존하고 새 객체를 추가합니다. PDF/A-3 적합성을 보존하는 것을 목표로 하지만 재검증하지는 않습니다. 확실한 증명을 위해서는 출력을 외부 PDF/A 검증기를 통해 파이프하십시오.
C2PA 이음매는 다섯 개의 불변식을 고정합니다: 서드파티 임포트 없음, 바이트 전용 계약, I/O 없음, 미스 시 null 추출, 그리고 안정 계층에서의 주장 합성 없음.
JumbfBoxParser 한도는 공개 상수입니다. 한계를 다시 유도하는 대신 이 상수에 맞춰 수용할 입력의 크기를 정하십시오.

발행 경계

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