Faktury a účtenky sdílejí stejný vchod. Jak se vyhnout smíchání dvou struktur?

Faktury a účtenky se často vkládají do stejného rozhraní pro zpracování, ale pokud se k jejich přijímání použije pouze široký objekt s "všemi volitelnými poli", může pojmout jakýkoli vstup, ale nemůže říct, jaký druh dokumentu je přijat. Tento článek je určen vývojářům a obchodním pracovníkům, kteří potřebují navrhnout rozhraní pro příjem dokumentů nebo udržovat pravidla ověřování schématu JSON. Po přečtení tohoto článku se naučíte, jak zachovat dvě nezávislé smlouvy, vybrat jednu s polem explicitního typu a jak řešit konflikty větví a neznámé typy.

Příklady v tomto článku používají syntetické vzorky k demonstraci metod zpracování. Kód byl zkontrolován s příklady v izolovaném prostředí, ale to není zárukou všech skutečných souborů nebo výkonu produktu. Před zpracováním důležitých dokumentů si prosím uschovejte originály a zkontrolujte je podle hranic a přejímacích položek v textu.

Jak se vypořádat se společným vstupem faktur a účtenek? Závěr jednou větou

Při příjmu dvou dokumentů ze stejného portálu je jasnější ponechat si dvě samostatné smlouvy a použít požadované pole kind k výběru jedné z nich, než používat široký objekt, který pojme vše.

Proč nemůžete použít široký objekt?

Riziko, že všechna pole budou nepovinná

Když rozhraní akceptuje faktury i účtenky, je snadné psát velké objekty se „všechna pole volitelná". Takový objekt může skutečně přijímat různé vstupy, ale za cenu:

• Ze struktury nelze určit, který dokument byl přijat.
• Požadované položky a volitelné položky obou dokumentů se vzájemně mísí a ověřovací pravidla jsou stále více nejasná.
• Když dojde k chybě, je obtížné přesně vysvětlit, kde vstup není podle očekávání.

Bylo by jasnější ponechat dvě samostatné smlouvy a vybrat jednu z nich s explicitním typem pole.

oneOf není jen tak ledajaký

Překrývající se větve způsobí selhání právního vstupu.

oneOf vyžaduje, aby vstup odpovídal přesně jedné větvi. Pokud obě větve projdou současně, celkové ověření se nezdaří.

Pokud větve obsahují pouze několik volitelných polí, pravděpodobně se budou výrazně překrývat. V tuto chvíli právní vstup neprošel ověřením.

K odstranění překrývání použijte druh a stálost

Použitím požadovaného pole kind plus pevné hodnoty const lze stanovit jasné hranice mezi větvemi a předem eliminovat takové překrývání.

Další podrobnosti o pravidlech kombinací naleznete v Pravidla kombinace schématu JSON.

Spustitelný protokol pro snížení zátěže

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ý příklad záznamu a nejedná se o úplný model pole skutečné faktury. Kód demonstruje výběr větve a odmítnutí nadbytečných polí. Samostatně je třeba definovat sazbu daně, hlavičku a částku.

Pokud firma povoluje další pole, měly by být obory názvů pro tato pole explicitní, spíše než tiché zrušení všech omezení.

V chybové zprávě nezobrazujte pouze „no match".

Zobrazí se pouze „neshoda"a uživatelé ani správci neví, kde je problém. Následující tabulka uvádí několik běžných vstupních funkcí a odpovídajících metod zpětné vazby:

Neurčité typy také potřebují zásuvku

Pokud klasifikátor nedokáže rozlišit mezi fakturami a účtenkami, měl by opustit neznámý stav namísto vybírání náhodné větve, aby hádal „úspěch".

Jsou zde tři různé úrovně, na které je třeba se dívat samostatně:

• Důvěra klasifikace: Jak jistý je systém při posuzování typu dokumentu.
• Ověření struktury: Zda vstup odpovídá vybrané smlouvě.
• Obchodní autenticita: Zda je samotný dokument autentický a platný.

Absolvování strukturálního ověření nemůže prokázat, že klasifikace je správné, ani nemůže prokázat, že dokument je pravý.

Typ dokumentu musí být také zachován v procesu překladu

Stejné pole může vyžadovat použití různých výrazů v různých dokumentech. Při použití terminologie a dvojjazyčných pracovních postupů pro revize OmniDoc pomůže recenzentům poskytnutí typu dokumentu spolu s dodacím listem porozumět kontextu čísel a částek.

Nedovolte, aby široký objekt JSON tyto rozdíly smazal.

📊 Srovnání jádra

🎯 Která metoda je pro vás vhodná?

Pokud potřebujete dostávat faktury i účtenky

Udržujte dvě samostatné smlouvy a udělejte z kind povinné pole.

Pokud se pole vaší pobočky hodně překrývají

Opravte kind pomocí const v každé větvi, abyste se vyhnuli tomu, že legální vstup odpovídá více větvím současně.

Pokud váš systém umožňuje další pole

Nejprve vyjasněte jmenný prostor dalších polí a poté se rozhodněte, jak zmírnit omezení.

Pokud si váš klasifikátor není dostatečně jistý

Ponechte stav neznámý, odešlete dokument do fronty k třídění a nevybírejte násilně větev.

❓ Často kladené otázky (FAQ)

1. Proč nepoužít pouze objekt se všemi poli volitelnými?

Takový předmět může pojmout cokoli, ale je těžké říci, co přesně je přijato.

2. Proč selže jeden z právních vstupů?

oneOf vyžaduje shodu přesně jedné větve. Pokud obě větve projdou současně, celkové ověření se nezdaří. Tato situace může snadno nastat, když se větvená pole hodně překrývají.

3. Na co byste měli dát pozor, když povolujete další pole?

Jmenný prostor dalších polí by měl být explicitní, spíše než tiché zrušení všech omezení.

4. Co mám dělat, když klasifikátor nemůže určit typ dokumentu?

Ponechte neznámý stav a zadejte nezávislou frontu, která bude klasifikována. Nevybírejte náhodně větev, abyste dosáhli úspěchu.

5. Pokud ověření struktury projde, znamená to, že dokument je autentický?

nemůže. Spolehlivost klasifikace, ověření struktury a obchodní autentičnost jsou tři různé úrovně. Absolvování struktury nemůže prokázat, že dokument je autentický.

📝 Shrnutí

Při vkládání faktur a účtenek do stejné položky si ponechte dvě samostatné smlouvy a vyberte je s požadovaným polem kind tak, aby byl dobře viditelný typ zadaného dokladu. Ověření větve, chybová zpětná vazba a východy neznámého typu by měly být také navrženy společně.

Vyzkoušejte to hned: Nahrajte dokument a začněte překládat při zachování původního rozvržení