청구서와 영수증은 동일한 입구를 공유합니다. 두 구조의 혼합을 피하는 방법은 무엇입니까?

송장과 영수증은 처리를 위해 동일한 인터페이스에 배치되는 경우가 많지만 "모든 필드 선택 사항"이 포함된 광범위한 개체만 사용하여 수신하는 경우 모든 입력을 수용할 수 있지만 어떤 종류의 문서가 수신되는지 알 수 없습니다. 이 문서는 문서 수신 인터페이스를 디자인하거나 JSON 스키마 유효성 검사 규칙을 유지해야 하는 개발자 및 비즈니스 담당자를 위한 것입니다. 이 글을 읽고 나면 두 개의 독립적인 계약을 유지하는 방법, 명시적인 유형 필드가 있는 계약을 선택하는 방법, 분기 충돌 및 알 수 없는 유형을 처리하는 방법을 배우게 됩니다.

이 문서의 예에서는 합성 샘플을 사용하여 처리 방법을 보여줍니다. 코드는 격리된 환경에서 예제로 확인되었으나, 이것이 모든 실제 파일이나 제품 성능을 보장하는 것은 아닙니다. 중요한 서류를 처리하기 전, 원본을 보관하시고, 본문에 기재된 경계 및 허용 항목에 따라 검토하시기 바랍니다.

송장, 영수증 공동입장 처리는 어떻게 하나요? 한 문장 결론

동일한 포털에서 두 개의 문서를 수신할 때 모든 것을 담을 수 있는 광범위한 개체를 사용하는 것보다 두 개의 별도 계약을 유지하고 필수 kind 필드를 사용하여 그 중 하나를 선택하는 것이 더 명확합니다.

왜 광범위한 객체를 사용할 수 없나요?

모든 필드를 선택사항으로 만드는 위험

인터페이스가 송장과 영수증을 모두 허용하면 "모든 필드 선택 사항"을 사용하여 큰 개체를 쉽게 작성할 수 있습니다. 이러한 객체는 실제로 다양한 입력을 받을 수 있지만 다음과 같은 비용이 듭니다.

• 어떤 문서가 수신되었는지 구조로는 알 수 없습니다.
• 두 서류의 필수항목과 선택항목이 혼재되어 있어 검증기준이 점점 모호해지고 있습니다.
• 오류가 발생했을 때, 어디에서 입력이 예상과 다른지 정확히 설명하기 어렵습니다.

두 개의 별도 계약을 유지하고 명시적인 유형 필드를 사용하여 그 중 하나를 선택하는 것이 더 명확합니다.

oneOf는 그냥 아무 하나가 아닙니다

분기가 겹치면 올바른 입력이 실패하게 됩니다.

oneOf에서는 입력이 정확히 하나의 분기와 일치해야 합니다. 두 분기가 동시에 통과하면 전체 검증이 실패합니다.

분기에 선택 필드가 몇 개만 포함되어 있으면 크게 겹칠 가능성이 높습니다. 현재 법적 입력이 검증을 통과하지 못했습니다.

중복을 제거하려면 kind와 const를 사용하세요.

필수 kind 필드와 const의 고정 값을 함께 사용하면 분기 간의 명확한 경계를 설정하고 이러한 중복을 미리 제거할 수 있습니다.

조합 규칙에 대한 자세한 내용은 JSON 스키마 조합 규칙를 참조하세요.

실행 가능한 오프로드 프로토콜

from jsonschema import Draft202012Validator

def branch(kind, identity):
    return {
        "type": "object", "additionalProperties": False,
        "required": ["kind", identity],
        "properties": {"kind": {"const": kind},
                       identity: {"type": "string", "minLength": 1}}
    }

schema = {"oneOf": [branch("invoice", "invoice_number"),
                    branch("receipt", "receipt_number")]}
v = Draft202012Validator(schema)
valid = lambda x: not list(v.iter_errors(x))
assert valid({"kind": "invoice", "invoice_number": "I-1"})
assert valid({"kind": "receipt", "receipt_number": "R-1"})
assert not valid({"kind": "invoice", "receipt_number": "R-1"})
assert not valid({"kind": "receipt", "receipt_number": ""})
assert not valid({"kind": "invoice", "invoice_number": "I-1",
                  "receipt_number": "R-1"})
assert not valid({"kind": "unknown"})

이는 단순화된 예시 기록이며 실제 송장의 완전한 필드 모델은 아닙니다. 코드는 중복 필드의 분기 선택 및 거부를 보여줍니다. 세율, 헤더 및 금액은 별도로 정의해야 합니다.

비즈니스에서 추가 필드를 허용하는 경우 모든 제약 조건을 조용히 취소하는 대신 이러한 필드의 네임스페이스를 명시적으로 만들어야 합니다.

오류 메시지에 '일치 없음'만 표시하지 마세요.

"불일치"만 표시되며 사용자나 관리자 모두 문제가 어디에 있는지 알 수 없습니다. 다음 표에는 몇 가지 일반적인 입력 기능과 해당 피드백 방법이 나열되어 있습니다.

불확정 유형에도 콘센트가 필요합니다

분류자가 송장과 영수증을 구별할 수 없는 경우 "성공"을 추측하기 위해 무작위 분기를 선택하는 대신 알 수 없는 상태를 떠나야 합니다.

여기에는 별도로 살펴보아야 할 세 가지 수준이 있습니다.

• 분류 신뢰도: 문서 유형을 판단하는 시스템의 신뢰도입니다.
• 구조 검증: 입력 내용이 선택한 계약과 일치하는지 여부입니다.
• 비즈니스 진정성: 문서 자체가 진정성 있고 유효한지 여부입니다.

구조검증을 통과했다고 해서 분류가 정확하다는 것을 증명할 수 없고, 문서가 진짜라는 것을 증명할 수도 없습니다.

번역 과정에서도 문서 유형을 유지해야 합니다.

동일한 필드가 다른 문서에서는 다른 용어를 사용해야 할 수도 있습니다. OmniDoc의 용어 및 이중 언어 검토 작업 흐름을 사용할 때 배달 목록과 함께 문서 유형을 제공하면 검토자가 숫자와 금액의 맥락을 이해하는 데 도움이 됩니다.

광범위한 JSON 개체가 이러한 차이점을 지우도록 두지 마십시오.

📊 핵심 비교

🎯 어떤 방법이 당신에게 적합합니까?

청구서와 영수증을 모두 받아야 하는 경우

두 개의 별도 계약을 유지하고 kind를 필수 필드로 만드세요.

Branch 필드가 많이 겹치는 경우

동시에 여러 분기와 일치하는 합법적인 입력을 방지하려면 각 분기에서 const를 사용하여 kind를 수정하세요.

시스템에서 추가 필드를 허용하는 경우

먼저 추가 필드의 네임스페이스를 명확히 한 다음 제약 조건을 완화하는 방법을 결정합니다.

분류자의 자신감이 충분하지 않은 경우

상태를 알 수 없음으로 두고, 문서를 정렬할 대기열로 보내고, 강제로 분기를 선택하지 마십시오.

❓ 자주 묻는 질문(FAQ)

1. 모든 필드가 선택사항인 객체를 사용하면 어떨까요?

그러한 객체는 무엇이든 담을 수 있지만, 그것이 정확히 무엇인지 말하기는 어렵습니다.

2. oneOf가 법적 입력에 실패하는 이유는 무엇인가요?

oneOf에서는 정확히 하나의 분기와 일치해야 합니다. 두 분기가 동시에 통과하면 전체 검증이 실패합니다. 이러한 상황은 분기 필드가 많이 겹칠 때 쉽게 발생할 수 있습니다.

3. 추가 필드 허용 시 주의할 점은 무엇인가요?

모든 제약 조건을 자동으로 취소하기보다는 추가 필드의 네임스페이스를 명시적으로 만들어야 합니다.

4. 분류자가 문서 유형을 결정할 수 없는 경우 어떻게 해야 합니까?

알 수 없는 상태를 유지하고 분류할 독립 대기열에 들어갑니다. 성공을 위해 무작위로 지점을 선택하지 마십시오.

5. 구조검증에 성공하면 문서가 진짜라는 뜻인가요?

할 수 없습니다. 분류 신뢰도, 구조 검증 및 비즈니스 신뢰성은 세 가지 수준입니다. 구조를 전달해도 문서가 진짜라는 것을 증명할 수는 없습니다.

📝 요약

송장과 영수증을 동일한 항목에 배치하는 경우 두 개의 별도 계약을 유지하고 필수 kind 필드로 선택하여 입력한 문서 유형이 명확하게 표시되도록 합니다. 분기 확인, 오류 피드백 및 알 수 없는 유형 종료도 함께 설계해야 합니다.

지금 사용해 보세요: 원본 레이아웃을 유지하면서 번역을 시작하려면 문서를 업로드하세요.