A számláknak és a nyugtáknak ugyanaz a bejárata. Hogyan kerüljük el a két szerkezet keveredését?

Egy felület fogadja a számlákat és a nyugtákat is, és könnyű nagy objektumokat írni "minden mező nem kötelező". Egy ilyen tárgy bármit tartalmazhat, de nehéz megmondani, hogy pontosan mit kap. Egyértelműbb lenne, ha két külön szerződést tartana meg, és az egyiket az explicit típus mezővel választaná ki.

A számlák és a bizonylatok gyakran ugyanarra a felületre kerülnek feldolgozásra, de ha csak egy széles objektumot használunk, amelyben "minden mező nem kötelező", akkor az bármilyen bevitelt képes fogadni, de nem tudja megmondani, hogy milyen bizonylat érkezik. Ez a cikk azoknak a fejlesztőknek és üzleti dolgozóknak szól, akiknek dokumentumfogadó felületet kell tervezniük, vagy karban kell tartaniuk a JSON-séma érvényesítési szabályait. Ennek elolvasása után megtudhatja, hogyan tarthat meg két független szerződést, hogyan válasszon ki egyet explicit típusú mezővel, és hogyan kezelje az ágak ütközését és az ismeretlen típusokat.

A cikkben szereplő példák szintetikus mintákat használnak a feldolgozási módszerek bemutatására. A kódot példákkal ellenőrizték izolált környezetben, de ez nem garancia az összes valós fájlra vagy a termék teljesítményére. A fontos dokumentumok feldolgozása előtt kérjük, őrizze meg az eredeti példányokat és nézze át a szövegben szereplő határok és átvételi tételek szerint.

Hogyan kezeljük a számlák és nyugták közös bejutását? Egy mondatos következtetés

Ha ugyanarról a portálról két dokumentumot kap, egyértelműbb, hogy két külön szerződést tart fenn, és a szükséges kind mezőt használja az egyik kiválasztásához, nem pedig egy átfogó objektumot, amely mindent tartalmaz.

a helyzetedAjánlott gyakorlatokok
Ugyanazon a felületen kell fogadni a számlákat és a nyugtákatTartson két külön szerződést, a kötelező típus mezővel kiválasztvaEgy nagy objektum, amelynek minden mezője nem kötelező, bármit elhelyezhet, de nehéz megmagyarázni, hogy mi érkezik.
Szervezzen fiókokat a oneOf segítségévelMindegyik ág a const-ot használja a fajta javításáraA oneOf pontosan egy ágat igényel. Az átfedő fiókmezők a törvényes bevitel sikertelenségét okozzák.
Hiányzó beviteli típus vagy mezőütközésVilágos hibaüzenetet ad vissza, amely ütköző mezőket és forrásokat mutatCsak a „nincs egyezés"megjelenítése nem segít a probléma megtalálásában
Az osztályozó nem tud különbséget tenni a dokumentumtípusok közöttTartsa meg az ismeretlen állapotot, és lépjen be a besorolandó független sorbaA véletlenszerű fiókválasztás csak hamis "sikert" eredményez
A szerkezet ellenőrzése sikeresEz nem jelenti azt, hogy a minősítés helyes, és nem jelenti azt sem, hogy a dokumentumok hitelesek.Az osztályozási megbízhatóság, a szerkezetellenőrzés és az üzleti hitelesség három különböző szint

Miért nem használhat széles objektumot?

Az összes mező opcionálissá tételének kockázata

Ha egy felület elfogadja a számlákat és a nyugtákat is, akkor könnyű nagy objektumokat írni úgy, hogy „minden mező nem kötelező". Egy ilyen objektum valóban sokféle bemenetet kaphat, de a következők árán:

  • A szerkezetből nem lehet megállapítani, hogy melyik dokumentum érkezik.
  • A két dokumentum kötelező és választható tételei keverednek egymással, és az ellenőrzési szabályok egyre inkább összemosódnak.
  • Ha hiba történik, nehéz pontosan megmagyarázni, hogy a bemenet hol nem a vártnak megfelelő.

Egyértelműbb lenne, ha két külön szerződést tartana meg, és az egyiket egy explicit típusú mezővel választaná ki.

A oneOf nem akármilyen

Az ágak átfedése a jogi bevitel sikertelenségét okozza.

AoneOf megköveteli, hogy a bemenet pontosan egy ágnak feleljen meg. Ha mindkét ág egyszerre halad át, az általános ellenőrzés sikertelen lesz.

Ha az ágak csak néhány nem kötelező mezőt tartalmaznak, akkor valószínűleg jelentős átfedésben lesznek. Jelenleg a jogi bemenet nem megy át az ellenőrzésen.

Az átfedés megszüntetésére használja a kind és const

A szükséges kind mező plusz a const fix értékének használatával egyértelmű határvonalak hozhatók létre az ágak között, és előre kiküszöbölhetők az ilyen átfedések.

A kombinációs szabályokkal kapcsolatos további részletekért lásd: JSON-séma kombinációs szabályok.

Egy futtatható elterelő protokoll

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

Ez egy egyszerűsített példa dokumentum, nem egy teljes terepi modell egy valós számláról. A kód bemutatja az ágválasztást és a redundáns mezők elutasítását; az adókulcsokat, fejléceket és összegeket külön kell meghatározni.

Ha az üzlet további mezőket engedélyez, ezeknek a mezőknek a névtereket világosan kell meghatározni, nem pedig csendben eltávolítani az összes korlátozást.

Ne csak "mismatch" hibaüzeneteket jelenítsd meg

Csak a "eltérés" jelenik meg, és sem a felhasználók, sem a karbantartó személyzet nem tudja, hol van a probléma. Az alábbi táblázat több gyakori bemeneti funkciót és azok megfelelő visszacsatolási módszereit sorol:

Bemeneti jellemzőkValódi kétségekJavaslatok visszajelzésre
valamilyen hiányosságNem választhatom ki a megállapodástKérjük, adja meg a dokumentum típusát
Típus- és számmezők ütköznekA két szerkezet kevertEllentmondó mezők és azok forrásai megjelenítése
Számozott üres stringekA kulcs létezik, de nincs értékeVisszatekintve a számozott területre
Ismeretlen típusA jelenlegi megállapodás nem fedi eztLépj be a független sorba a besoroláshoz

Bizonytalan típusoknak is szükségük van kijáratra

Ha a klasifikátor nem tudja megkülönböztetni a számlákat és a nyugtákat, az ismeretlen státuszt meg kell tartani, nem véletlenszerűen választani egy fiókot a "siker" érdekében.

Három különböző szintet kell külön megvizsgálni:

  • Kategória-bizalom: Mennyire magabiztos a rendszer a dokumentumtípusok megítélésében.
  • Struktúra ellenőrzés: Írd be, hogy a kiválasztott szerződés teljesül-e.
  • Üzleti hitelesség: Maguk a dokumentumok hitelesek-e és érvényesek-e.

A szerkezeti ellenőrzés nem bizonyítható visszafordítva, és nem bizonyíthatja, hogy a dokumentum hiteles.

A dokumentumtípust a fordítási folyamatban is meg kell tartani

Ugyanaz a terület eltérő terminológiát követelhet különböző dokumentumokban. A OmniDoc terminológiát és kétnyelvű átvizsgálási munkafolyamatokat használva a dokumentumtípusok szállítási listákkal való biztosítása segít a lektoroknak megérteni a szám és mennyiség kontextusát.

Ne hagyd, hogy egy tágabb JSON objektum eltörölje ezeket a különbségeket.

📊 Alap összehasonlítás

MódszerVilágosan meg lehet határozni a dokumentum típusát?Megnyilvánulások, amikor az ágak átfednekIsmeretlen típusok kezelése
Széles objektumok, minden mező opcionálisNehéz megmagyarázni, mit kaptakNem alkalmazható; nincsenek ághatárok a mezők közöttKönnyen elnyelték a széles célpontok által, és nehezen észrevehető
Két független szerződés + kötelező típusEgyértelműen válassz a típusmező használatávalHasználj const-t az értékek javítására, hogy csökkentsd az átfedéstHagyd az ismeretlen státuszt, és lépj be a sorba a rendezésre

🎯 Melyik módszer illik hozzád?

Ha egyszerre kell megkapnod a számlákat és a nyugtákat

Tartsanak két külön szerződést, és állítsd be a kind-t kötelező mezőként.

Ha az ági mezőid nagyban átfedik egymást

Javítsd meg kind-t const-vel minden ágban, hogy elkerüld a jogos bemeneti egyezést több ág egyidejűleg.

Ha a rendszered további mezőket enged

Először tisztázzuk az extra field névterét, majd döntsük el, hogyan lazítsuk a korlátokat.

Ha a osztályozó nem elég biztos

Tartsd meg az ismeretlen státuszt, és küldd a dokumentumokat a sorba rendezhetővé; ne válassz erőszakkal az ágazakat.

❓ Gyakran Ismételt Kérdések (GYIK)

1. Miért ne használnál egy olyan objektumot, ahol minden mező opcionális?

Egy ilyen partner bármit hamisíthat, mégis nehéz pontosan megmondani, mit kap.

2. Miért okoz OneOf érvényes belépési hibát?

A oneOf pontosan megköveteli az ág megegyezését. Ha mindkét ág egyszerre megy át, az összesített ellenőrzés sikertelenül megbukik. Ez a helyzet valószínűleg akkor fordul elő, ha az ágmezők nagymértékben átfednek.

3. Mire kell figyelni, amikor további mezőket engedélyeztek?

Az extra mező névterét világosan kell meghatározni, nem pedig csendben eltávolítani az összes korlátozást.

4. Mi van, ha a klasifikátor nem tudja meghatározni a dokumentumtípust?

Tartsd meg az ismeretlen státuszt, és lépj be egy független sorba a besoroláshoz; ne válassz véletlenszerűen egy sikeres ág összeállításához.

5. A szerkezeti ellenőrzés átmenése bizonyítja a dokumentumok hitelességét?

Nem. A besorolási megbízhatóság, a szerkezeti ellenőrzés és az üzleti hitelesség három különböző szint; a szerkezeti ellenőrzés nem bizonyíthatja a dokumentumok hitelességét.

📝 Összefoglaló

Amikor a számlákat és nyugtákat ugyanabban a bejegyzésben helyezzük el, tartsd meg két külön szerződést, és válaszd ki őket a szükséges kind mező segítségével, így a bejegyzett dokumentum típusa jól láthatóvá válik. Az ági ellenőrzést, hibavisszacsatolást és ismeretlen típusú exportokat is együtt kell tervezni.

Tapasztalat most: Töltsd fel a dokumentumodat, hogy elkezdhesd a fordítást, megőrizve az eredeti formázást

Frissítve: 2026-11-16