Facturile și chitanțele au aceeași intrare. Cum să evitați amestecarea celor două structuri?

O interfață primește atât facturi, cât și chitanțe și este ușor să scrieți obiecte mari cu „toate câmpurile opționale”. Un astfel de obiect poate ține orice, dar este dificil de spus ce anume este primit. Ar fi mai clar să păstrați două contracte separate și să selectați unul dintre ele cu câmpul de tip explicit.

Facturile și chitanțele sunt adesea introduse în aceeași interfață pentru procesare, dar dacă pentru a le primi este folosit doar un obiect larg cu „toate câmpurile opționale", acesta poate găzdui orice intrare, dar nu poate spune ce fel de document este primit. Acest articol este destinat dezvoltatorilor și personalului de afaceri care trebuie să proiecteze o interfață de primire a documentelor sau să mențină regulile de validare a schemei JSON. După ce ați citit acest lucru, veți învăța cum să păstrați două contracte independente, să selectați unul cu un câmp de tip explicit și să gestionați conflictele de ramuri și tipurile necunoscute.

Exemplele din acest articol folosesc mostre sintetice pentru a demonstra metodele de procesare. Codul a fost verificat cu exemple într-un mediu izolat, dar aceasta nu este o garanție a tuturor fișierelor reale sau a performanței produsului. Înainte de a procesa documente importante, vă rugăm să păstrați originalele și să le revizuiți în funcție de limitele și elementele de acceptare din text.

Cum să tratăm cu intrarea comună a facturilor și chitanțelor? O singură propoziție concluzie

Când primiți două documente de pe același portal, este mai clar să păstrați două contracte separate și să utilizați câmpulkind necesar pentru a selecta unul dintre ele, mai degrabă decât să folosiți un obiect larg care poate conține totul.

situatia taPractici recomandatemotiv
Aceeași interfață trebuie să primească facturi și chitanțePăstrați două contracte separate, selectate cu câmpul de tip obligatoriuUn obiect mare cu toate câmpurile opționale poate conține orice, dar este dificil de explicat ceea ce se primește.
Organizați sucursale cu oneOfFiecare ramură folosește const pentru a remedia tipuloneOf necesită exact o ramură pentru a se potrivi. Câmpurile de ramură suprapuse vor duce la eșecul introducerii legale.
Tipul de intrare lipsește sau conflict de câmpReturnează un mesaj de eroare clar care arată câmpuri și surse conflictualeNumai afișarea „fără potrivire"nu poate ajuta la localizarea problemei
Clasificatorul nu poate face distincția între tipurile de documentePăstrați starea necunoscută și intrați în coada independentă pentru a fi clasificatAlegerea unei ramuri la întâmplare va produce doar „succes"fals
Verificarea structurii a trecutNu înseamnă că clasificarea este corectă și nici nu înseamnă că documentele sunt autentice.Încrederea în clasificare, verificarea structurii și autenticitatea afacerii sunt trei niveluri diferite

De ce nu poți folosi un obiect larg?

Risc de a face toate câmpurile opționale

Când o interfață acceptă atât facturi, cât și chitanțe, este ușor să scrieți obiecte mari cu „toate câmpurile opționale". Un astfel de obiect poate primi într-adevăr o varietate de intrări, dar cu costul:

  • Nu se poate spune din structură ce document este primit.
  • Elementele obligatorii și cele opționale ale celor două documente sunt amestecate între ele, iar regulile de verificare devin din ce în ce mai neclare.
  • Când apare o eroare, este dificil de explicat exact unde intrarea nu este așa cum era de așteptat.

Ar fi mai clar să păstrați două contracte separate și să selectați unul dintre ele cu un câmp de tip explicit.

oneOf nu este oricare

Suprapunerea ramurilor va duce la eșecul introducerii legale.

oneOf necesită ca intrarea să se potrivească exact cu o ramură. Dacă ambele ramuri trec în același timp, verificarea generală va eșua.

Dacă ramurile conțin doar câteva câmpuri opționale, este posibil ca acestea să se suprapună semnificativ. În acest moment, intrarea legală nu reușește să treacă verificarea.

Utilizați kind și const pentru a elimina suprapunerea

Utilizarea câmpului kind obligatoriu plus valoarea fixă a const poate stabili granițe clare între ramuri și elimina astfel de suprapuneri în avans.

Pentru mai multe detalii despre regulile de combinare, vă rugăm să consultați Reguli de combinare a schemei JSON.

Un protocol de descărcare executabil

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

Acesta este un exemplu de înregistrare simplificat și nu este un model de câmp complet al unei facturi reale. Codul demonstrează selecția ramurilor și respingerea câmpurilor redundante. Rata taxei, antetul și suma trebuie definite separat.

Dacă compania permite câmpuri suplimentare, spațiile de nume pentru aceste câmpuri ar trebui să fie explicite, mai degrabă decât să anuleze în liniște toate constrângerile.

Nu afișa doar „nicio potrivire"în mesajul de eroare

Este afișată doar „nepotrivire"și nici utilizatorii, nici întreținerii nu știu unde se află problema. Următorul tabel listează câteva caracteristici comune de intrare și metodele de feedback corespunzătoare:

Caracteristici de intrareÎndoieli realeSugestii și feedback
Un fel de deficiențăNu se poate alege acordulVă rugăm să furnizați tipul de document
Câmpurile de tip și numere sunt în conflictCele două structuri sunt amestecateAfișează câmpurile conflictuale și sursele lor
Șiruri goale numerotateCheia există, dar nu are valoarePrivind înapoi la zona numerotată
Tip necunoscutAcordul actual nu acoperă acest aspectIntră în coada independentă pentru a fi clasificat

Tipurile nesigure au nevoie și ele de o ieșire

Dacă clasificatorul nu poate distinge între facturi și chitanțe, statutul necunoscut ar trebui păstrat, în loc să selecteze aleatoriu o sucursală pentru a obține un "succes".

Există trei niveluri diferite care trebuie luate în considerare separat:

  • Încredere în categorie: Cât de încrezător este sistemul în evaluarea tipurilor de documente.
  • Verificarea structurii: Introduceți dacă contractul selectat este îndeplinit.
  • Autenticitatea afacerii: Dacă documentele în sine sunt autentice și valide.

Verificarea structurală nu poate fi dovedită invers ca fiind corectă, nici nu poate dovedi că documentul este autentic.

Tipul documentului trebuie păstrat și în procesul de traducere

Același domeniu poate necesita terminologie diferită în documente diferite. Când se utilizează terminologia OmniDoc și fluxurile de lucru bilingve de revizuire, furnizarea tipurilor de documente cu liste de livrare îi ajută pe recenzori să înțeleagă contextul numărului și sumei.

Nu lăsa un obiect JSON larg să șteargă aceste diferențe.

📊 Comparație de bază

MetodăPoate fi clar definit tipul de document?Manifestări atunci când ramurile se suprapunManipularea tipurilor necunoscute
Obiecte largi cu toate câmpurile opționaleEste greu de explicat ce s-a primitNu se aplică; nu există granițe de ramificație între câmpuriUșor de înghițit de ținte largi și greu de observat
Două contracte independente + tip obligatoriuSelectează clar folosind câmpul tipFolosește const pentru a fixa valorile și a reduce suprapunereaPărăsește starea necunoscută și intră în coadă pentru a fi sortat

🎯 Care metodă ți se potrivește?

Dacă trebuie să primești atât facturile, cât și chitanțele în același timp

Păstrează două contracte separate și setează kind ca câmp obligatoriu.

Dacă câmpurile tale de ramuri se suprapun extensiv

Fixați kind cu const în fiecare ramură pentru a evita intrările legitime care să potrivească simultan mai multe ramuri.

Dacă sistemul tău permite câmpuri suplimentare

Mai întâi, clarifică spațiul de nume al câmpului suplimentar, apoi decide cum să relaxezi constrângerile.

Dacă clasificatorul tău nu e suficient de sigur

Păstrați statutul necunoscut și trimiteți documentele la coadă pentru sortare; nu selectați forțat ramuri.

❓ Întrebări frecvente (FAQ)

1. De ce să nu folosești pur și simplu un obiect unde toate câmpurile să fie opționale?

Un astfel de partener poate falsifica orice, dar este greu de spus exact ce primește.

2. De ce cauzează oneOf un eșec valid de intrare?

oneOf necesită exact potrivirea unei ramuri. Dacă ambele ramuri trec simultan, verificarea generală va eșua. Această situație este probabil să apară atunci când câmpurile de ramificație se suprapun extensiv.

3. La ce ar trebui să fii atent când permiți câmpuri suplimentare?

Spațiul de nume pentru câmpul suplimentar ar trebui să fie clar definit, în loc să se elimine liniștit toate constrângerile.

4. Ce se întâmplă dacă clasificatorul nu poate determina tipul de document?

Păstrați starea necunoscută și intrați într-o coadă independentă pentru clasificare; nu selectați aleatoriu o ramură pentru a asambla o ramură de succes.

5. Dovedește trecerea verificării structurale autenticitatea documentelor?

Nu. Încrederea în clasificare, verificarea structurală și autenticitatea afacerii sunt trei niveluri distincte; verificarea structurală nu poate dovedi autenticitatea documentelor.

📝 Rezumat

Când plasezi facturi și chitanțe în aceeași intrare, păstrează două contracte separate și selectează-le folosind câmpul necesar kind, făcând tipul documentului introdus clar vizibil. Verificarea ramurilor, feedback-ul erorilor și exporturile de tip necunoscut ar trebui, de asemenea, proiectate împreună.

Experiența acum: Încarcă documentul pentru a începe traducerea, păstrând formatul original

Actualizat 2026-11-16