Les factures et les reçus partagent la même entrée. Comment éviter de mélanger les deux structures ?

Les factures et les reçus sont souvent placés dans la même interface pour le traitement, mais si seul un objet large avec « tous les champs facultatifs » est utilisé pour les recevoir, il peut accueillir n'importe quelle entrée, mais il ne peut pas dire quel type de document est reçu. Cet article est destiné aux développeurs et au personnel commercial qui ont besoin de concevoir une interface de réception de documents ou de maintenir des règles de validation de schéma JSON. Après avoir lu ceci, vous apprendrez à conserver deux contrats indépendants, à en sélectionner un avec un champ de type explicite et à gérer les conflits de branches et les types inconnus.

Les exemples de cet article utilisent des échantillons synthétiques pour démontrer les méthodes de traitement. Le code a été vérifié avec des exemples dans un environnement isolé, mais cela ne constitue pas une garantie de tous les fichiers réels ou des performances du produit. Avant de traiter des documents importants, veuillez conserver les originaux et les examiner en fonction des limites et des éléments d'acceptation du texte.

Comment gérer la saisie partagée des factures et des reçus ? Conclusion en une phrase

Lors de la réception de deux documents du même portail, il est plus clair de conserver deux contrats distincts et d'utiliser le champ kind requis pour en sélectionner un, plutôt que d'utiliser un objet large pouvant tout contenir.

Pourquoi ne pouvez-vous pas utiliser un objet large ?

Risque de rendre tous les champs facultatifs

Lorsqu'une interface accepte à la fois les factures et les reçus, il est facile d'écrire de gros objets avec « tous les champs facultatifs ». Un tel objet peut en effet recevoir une variété d’intrants, mais au prix de :

• Il est impossible de savoir depuis la structure quel document est reçu.
• Les éléments obligatoires et facultatifs des deux documents se mélangent et les règles de vérification deviennent de plus en plus floues.
• Lorsqu'une erreur se produit, il est difficile d'expliquer exactement où la saisie n'est pas celle attendue.

Il serait plus clair de conserver deux contrats distincts et d'en sélectionner un avec un champ de type explicite.

oneOf n'est pas n'importe lequel

Les branches qui se chevauchent entraîneront l'échec de la saisie légale.

oneOf nécessite que l'entrée corresponde exactement à une branche. Si les deux branches réussissent en même temps, la vérification globale échouera.

Si les branches ne contiennent que quelques champs facultatifs, elles risquent de se chevaucher de manière significative. À l’heure actuelle, les données légales ne réussissent pas la vérification.

Utilisez kind et const pour éliminer les chevauchements

L'utilisation du champ kind requis plus la valeur fixe de const peut établir des limites claires entre les branches et éliminer à l'avance ces chevauchements.

Pour plus de détails sur les règles de combinaison, veuillez vous référer à Règles de combinaison de schéma JSON.

Un protocole de déchargement exécutable

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

Il s'agit d'un exemple d'enregistrement simplifié et non d'un modèle de terrain complet d'une facture réelle. Le code démontre la sélection de branche et le rejet des champs redondants. Le taux de taxe, l'en-tête et le montant doivent être définis séparément.

Si l'entreprise autorise des champs supplémentaires, les espaces de noms de ces champs doivent être rendus explicites plutôt que d'annuler discrètement toutes les contraintes.

Ne vous contentez pas d'afficher « aucune correspondance » dans le message d'erreur

Seule « incompatibilité » est affichée, et ni les utilisateurs ni les responsables ne savent où se situe le problème. Le tableau suivant répertorie plusieurs fonctionnalités d'entrée courantes et les méthodes de retour correspondantes :

Les types indéterminés ont également besoin d'un débouché

Si le classificateur ne peut pas faire la distinction entre les factures et les reçus, il doit quitter l'état inconnu au lieu de choisir une branche au hasard pour deviner le « succès ».

Il y a ici trois niveaux différents qui doivent être examinés séparément :

• Confiance de classification : dans quelle mesure le système est-il confiant dans l'évaluation du type de document.
• Vérification de la structure : indique si l'entrée est conforme au contrat sélectionné.
• Authenticité commerciale : indique si le document lui-même est authentique et valide.

La réussite de la vérification structurelle ne peut pas prouver que la classification est correcte, ni que le document est authentique.

Le type de document doit également être conservé dans le processus de traduction

Le même champ peut devoir utiliser des termes différents dans différents documents. Lorsque vous utilisez la terminologie de OmniDoc et les flux de travail de révision bilingues, fournir le type de document ainsi que la liste de livraison aide les réviseurs à comprendre le contexte des chiffres et des montants.

Ne laissez pas un objet JSON large effacer ces différences.

📊 Comparaison de base

🎯 Quelle méthode vous convient ?

Si vous devez recevoir à la fois des factures et des reçus

Conservez deux contrats distincts et faites de kind un champ obligatoire.

Si les champs de vos branches se chevauchent beaucoup

Corrigez kind avec const dans chaque branche pour éviter que les entrées légales ne correspondent à plusieurs branches en même temps.

Si votre système autorise des champs supplémentaires

Clarifiez d’abord l’espace de noms des champs supplémentaires, puis décidez comment assouplir les contraintes.

Si votre classificateur n'est pas suffisamment confiant

Laissez le statut inconnu, envoyez le document dans la file d'attente pour être trié et ne sélectionnez pas de force une branche.

❓ Questions fréquemment posées (FAQ)

1. Pourquoi ne pas simplement utiliser un objet avec tous les champs facultatifs ?

Un tel objet peut contenir n'importe quoi, mais il est difficile de dire exactement ce qu'il reçoit.

2. Pourquoi oneOf échoue-t-il à la saisie légale ?

oneOf nécessite de faire correspondre exactement une branche. Si les deux branches réussissent en même temps, la vérification globale échouera. Cette situation peut facilement se produire lorsque les champs de branches se chevauchent beaucoup.

3. À quoi devez-vous faire attention lorsque vous autorisez des champs supplémentaires ?

L'espace de noms des champs supplémentaires doit être rendu explicite plutôt que d'annuler silencieusement toutes les contraintes.

4. Que dois-je faire si le classificateur ne parvient pas à déterminer le type de document ?

Conservez l'état inconnu et entrez dans une file d'attente indépendante pour être classé. Ne sélectionnez pas une branche au hasard pour réussir.

5. Si la vérification de la structure réussit, cela signifie-t-il que le document est authentique ?

ne peut pas. La confiance en matière de classification, la vérification de la structure et l'authenticité commerciale sont trois niveaux différents. Passer la structure ne peut pas prouver que le document est authentique.

📝Résumé

Lorsque vous placez des factures et des reçus dans la même entrée, conservez deux contrats distincts et sélectionnez-les avec le champ kind requis afin que le type de document saisi soit clairement visible. La vérification des branches, le retour d'erreur et les sorties de type inconnu doivent également être conçus ensemble.

Essayez-le maintenant : téléchargez le document pour lancer la traduction, en conservant la mise en page d'origine.