Faktúry a účtenky zdieľajú rovnaký vchod. Ako sa vyhnúť zmiešaniu týchto dvoch štruktúr?

Jedno rozhranie akceptuje faktúry aj potvrdenky a je ľahké písať veľké objekty so „všetky polia voliteľné“. Takýto predmet môže držať čokoľvek, ale je ťažké povedať, čo presne je prijaté. Jasnejšie by bolo ponechať dve samostatné zmluvy a vybrať jednu z nich s poľom explicitného typu.

Faktúry a potvrdenky sa často vkladajú do rovnakého rozhrania na spracovanie, ale ak sa na ich príjem použije iba široký objekt s „všetky polia voliteľné", môže sa prispôsobiť ľubovoľnému vstupu, ale nedokáže povedať, aký druh dokumentu sa prijíma. Tento článok je určený pre vývojárov a obchodný personál, ktorí potrebujú navrhnúť rozhranie na príjem dokumentov alebo udržiavať pravidlá overovania schémy JSON. Po prečítaní tohto článku sa naučíte, ako zachovať dve nezávislé zmluvy, vybrať jednu s poľom explicitného typu a ako riešiť konflikty medzi vetvami a neznáme typy.

Príklady v tomto článku používajú syntetické vzorky na demonštráciu metód spracovania. Kód bol skontrolovaný pomocou príkladov v izolovanom prostredí, ale to nie je zárukou všetkých skutočných súborov alebo výkonu produktu. Pred spracovaním dôležitých dokumentov si uschovajte originály a skontrolujte ich podľa hraníc a akceptačných položiek v texte.

Ako sa vysporiadať so spoločným vstupom faktúr a účteniek? Záver jednou vetou

Pri prijímaní dvoch dokumentov z toho istého portálu je jasnejšie ponechať si dve samostatné zmluvy a použiť požadované polekind na výber jednej z nich, namiesto použitia širokého objektu, ktorý pojme všetko.

vaša situáciaOdporúčané postupydôvod
Rovnaké rozhranie potrebuje prijímať faktúry a potvrdenkyPonechajte si dve samostatné zmluvy vybraté s požadovaným poľom druhuVeľký objekt so všetkými voliteľnými poľami môže obsahovať čokoľvek, ale je ťažké vysvetliť, čo sa prijíma.
Organizujte pobočky s oneOfKaždá vetva používa const na opravu druhuoneOf vyžaduje, aby bola priradená práve jedna vetva. Prekrývajúce sa polia vetvy spôsobia zlyhanie právneho vstupu.
Chýbajúci typ vstupu alebo konflikt poľaVráti jasnú chybovú správu zobrazujúcu konfliktné polia a zdrojeIba zobrazenie „žiadna zhoda"nemôže pomôcť nájsť problém
Klasifikátor nedokáže rozlíšiť medzi typmi dokumentovZachovajte neznámy stav a vstúpte do nezávislého frontu na klasifikáciuNáhodný výber pobočky prinesie iba falošný „úspech"
Overenie štruktúry bolo úspešnéNeznamená to, že klasifikácia je správna, ani to, že dokumenty sú autentické.Spoľahlivosť klasifikácie, overenie štruktúry a obchodná autenticita sú tri rôzne úrovne

Prečo nemôžete použiť široký objekt?

Riziko, že všetky polia budú nepovinné

Keď rozhranie akceptuje faktúry aj potvrdenky, je ľahké písať veľké objekty so „všetky polia voliteľné". Takýto objekt môže skutočne prijímať rôzne vstupy, ale za cenu:

  • Zo štruktúry nie je možné zistiť, ktorý dokument bol prijatý.
  • Požadované položky a voliteľné položky týchto dvoch dokumentov sa navzájom miešajú a pravidlá overovania sú čoraz nejasnejšie.
  • Keď sa vyskytne chyba, je ťažké presne vysvetliť, kde vstup nie je podľa očakávania.

Jasnejšie by bolo ponechať dve samostatné zmluvy a vybrať jednu z nich s explicitným typovým poľom.

oneOf nie je len tak hocijaký

Prekrývajúce sa vetvy môžu spôsobiť platné zlyhania vstupov

oneOf vyžaduje, aby vstup zodpovedal presne jednej vetve. Ak obe vetvy prejdú súčasne, celková validácia tiež zlyhá.

Ak vetva obsahuje len niekoľko voliteľných polí, pravdepodobne sa budú výrazne prekrývať. V tomto bode legitímny vstup v skutočnosti neprejde overením.

Používajte druh a konštant, aby ste odstránili prekrytie

Použitím požadovaného poľa kind plus const na stanovenie hodnôt môžete jasne vyznačiť hranice medzi vetvami a takéto prekryvy vopred eliminovať.

Pre viac informácií o pravidlách kombinácií pozri Pravidlá kombinácie schémy JSON.

Spustiteľný odklonový protokol

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"})

Toto je zjednodušený ukážkový záznam, nie kompletný terénny model skutočnej faktúry. Kód demonštruje výber vetiev a odmietanie redundantných polí; daňové sadzby, hlavičky a sumy musia byť definované samostatne.

Ak firma povolí ďalšie polia, menné priestory pre tieto polia by mali byť jasne definované, namiesto tichého odstraňovania všetkých obmedzení.

Nezobrazujte len chybové hlásenia "nezhoda"

Zobrazuje sa iba "nezhoda" a ani používatelia, ani údržbári nevedia, kde je problém. Tabuľka nižšie uvádza niekoľko bežných vstupných prvkov a ich zodpovedajúce metódy spätnej väzby:

Vstupné funkcieSkutočné pochybnostiNavrhnite spätnú väzbu
druh nedostatkuNemôžem si vybrať dohoduProsím, uveďte typ dokumentu
Konflikt typových a číselných políTieto dve štruktúry sú zmiešanéZobraziť konfliktné polia a ich zdroje
Očíslované prázdne reťazceKľúč existuje, ale nemá žiadnu hodnotuPohľad späť na očíslovanú oblasť
Neznámy typSúčasná dohoda to nepokrývaZadajte nezávislú frontu na klasifikáciu

Neisté typy tiež potrebujú únik

Ak klasifikátor nedokáže rozlíšiť medzi faktúrami a účtenkami, neznámy stav by sa mal ponechať namiesto náhodného výberu vetvy na dosiahnutie "úspechu".

Tu sú tri rôzne úrovne, ktoré je potrebné posudzovať samostatne:

  • Dôvera v kategóriu: Ako sebavedomý je systém pri hodnotení typov dokumentov.
  • Overenie štruktúry: Zadať, či je vybraná zmluva splnená.
  • Obchodná autenticita: Či sú samotné dokumenty pravé a platné.

Štrukturálne overenie nemožno spätne dokázať, že je správne, ani nemôže dokázať, že dokument je pravý.

Typ dokumentu by mal byť zachovaný aj v procese prekladu

Tá istá oblasť môže vyžadovať odlišnú terminológiu v rôznych dokumentoch. Pri používaní terminológie OmniDoc a bilingválnych hodnotiacich pracovných postupov pomáha poskytovanie typov dokumentov zoznamov dodaní recenzentom pochopiť kontext počtu a množstva.

Nedovoľte, aby široký objekt JSON vymazal tieto rozdiely.

📊 Porovnanie jadra

MetódaDá sa presne definovať typ dokumentu?Prejavy, keď sa vetvy prekrývajúManipulácia s neznámymi typmi
Široké objekty, pričom všetky polia sú voliteľnéŤažko sa vysvetľuje, čo bolo prijatéNepoužiteľné; medzi poľami neexistujú hranice vetievĽahko prehltnuté širokými terčmi a ťažko si ich všimnúť
Dve nezávislé zmluvy + povinný druhJasne vyberte pomocou poľa typuPouži const na fixáciu hodnôt a zníženie prekryvuNechajte neznámy stav a vstúpte do fronty na zoradenie

🎯 Ktorá metóda ti vyhovuje?

Ak potrebujete dostať faktúry aj účtenky naraz

Držte si dve samostatné zmluvy a nastavte kind ako povinné pole.

Ak sa vaše vetvové polia výrazne prekrývajú

Opravte kind s const v každej vetve, aby sa predišlo legitímnemu zhodovaniu viacerých vetiev súčasne.

Ak váš systém umožňuje ďalšie polia

Najprv objasniť menný priestor ďalšieho poľa a potom rozhodnúť, ako obmedzenia uvoľniť.

Ak tvoj klasifikátor nie je dostatočne istý

Nechajte neznámy stav a posielajte dokumenty do fronty na triedenie; nenásilne vyberajte vetvy.

❓ Často kladené otázky (FAQ)

1. Prečo jednoducho nepoužiť objekt, kde sú všetky polia voliteľné?

Takýto partner dokáže predstierať čokoľvek, no je ťažké presne povedať, čo dostáva.

2. Prečo oneOf spôsobuje platné zlyhanie vstupu?

oneOf vyžaduje presné zladenie vetvy. Ak obe vetvy prejdú súčasne, celková kontrola zlyhá. Táto situácia je pravdepodobná, keď sa vetvy výrazne prekrývajú.

3. Na čo by ste si mali dať pozor, keď povolujete ďalšie polia?

Menný priestor pre dodatočné pole by mal byť jasne definovaný, namiesto tichého odstraňovania všetkých obmedzení.

4. Čo ak klasifikátor nedokáže určiť typ dokumentu?

Zachovávajte neznámy stav a vstupujte do nezávislej fronty na klasifikáciu; nevyberajte náhodne vetvu na zostavenie úspešnej vetvy.

5. Dokazuje prechod štrukturálnym overením pravosť dokumentov?

Nie. Istota v klasifikácii, štrukturálna verifikácia a obchodná autenticita sú tri odlišné úrovne; štrukturálna verifikácia nemôže dokázať pravosť dokumentov.

📝 Zhrnutie

Pri vkladaní faktúr a dokladov do jedného záznamu uchovávajte dve samostatné zmluvy a vyberte ich pomocou požadovaného poľa kind, aby bol typ zadaného dokumentu jasne viditeľný. Overovanie vetiev, chybová spätná väzba a exporty neznámych typov by mali byť tiež navrhnuté spoločne.

Skúsenosti teraz: Nahrajte svoj dokument a začnite s prekladom, pričom zachovávate pôvodné formátovanie

Aktualizované 2026-11-16