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 ta | Practici recomandate | motiv |
|---|---|---|
| Aceeași interfață trebuie să primească facturi și chitanțe | Păstrați două contracte separate, selectate cu câmpul de tip obligatoriu | Un 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 oneOf | Fiecare ramură folosește const pentru a remedia tipul | oneOf 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âmp | Returnează un mesaj de eroare clar care arată câmpuri și surse conflictuale | Numai afișarea „fără potrivire"nu poate ajuta la localizarea problemei |
| Clasificatorul nu poate face distincția între tipurile de documente | Păstrați starea necunoscută și intrați în coada independentă pentru a fi clasificat | Alegerea unei ramuri la întâmplare va produce doar „succes"fals |
| Verificarea structurii a trecut | Nu î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 reale | Sugestii și feedback |
|---|---|---|
| Un fel de deficiență | Nu se poate alege acordul | Vă rugăm să furnizați tipul de document |
| Câmpurile de tip și numere sunt în conflict | Cele două structuri sunt amestecate | Afișează câmpurile conflictuale și sursele lor |
| Șiruri goale numerotate | Cheia există, dar nu are valoare | Privind înapoi la zona numerotată |
| Tip necunoscut | Acordul actual nu acoperă acest aspect | Intră î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 suprapun | Manipularea tipurilor necunoscute |
|---|---|---|---|
| Obiecte largi cu toate câmpurile opționale | Este greu de explicat ce s-a primit | Nu se aplică; nu există granițe de ramificație între câmpuri | Ușor de înghițit de ținte largi și greu de observat |
| Două contracte independente + tip obligatoriu | Selectează clar folosind câmpul tip | Folosește const pentru a fixa valorile și a reduce suprapunerea | Pă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


