Faktur dan kwitansi berbagi pintu masuk yang sama. Bagaimana cara menghindari pencampuran kedua struktur tersebut?

Faktur dan tanda terima sering kali dimasukkan ke dalam antarmuka yang sama untuk diproses, namun jika hanya objek luas dengan "semua bidang opsional" yang digunakan untuk menerimanya, ia dapat menampung masukan apa pun, namun tidak dapat mengetahui jenis dokumen apa yang diterima. Artikel ini ditujukan bagi pengembang dan personel bisnis yang perlu merancang antarmuka penerimaan dokumen atau memelihara aturan validasi Skema JSON. Setelah membaca ini, Anda akan mempelajari cara menyimpan dua kontrak independen, memilih satu dengan bidang tipe eksplisit, dan menangani konflik cabang dan tipe yang tidak diketahui.

Contoh dalam artikel ini menggunakan sampel sintetis untuk menunjukkan metode pemrosesan. Kode telah diperiksa dengan contoh di lingkungan yang terisolasi, namun ini bukan jaminan semua file nyata atau kinerja produk. Sebelum memproses dokumen penting, harap simpan dokumen asli dan tinjau sesuai dengan batasan dan item penerimaan dalam teks.

Bagaimana cara menangani pintu masuk faktur dan kwitansi bersama? Kesimpulan satu kalimat

Saat menerima dua dokumen dari portal yang sama, lebih jelas untuk menyimpan dua kontrak terpisah dan menggunakan bidang kind yang diperlukan untuk memilih salah satunya, daripada menggunakan objek luas yang dapat menampung semuanya.

Kenapa tidak bisa menggunakan objek yang luas?

Risiko menjadikan semua bidang opsional

Saat antarmuka menerima faktur dan tanda terima, mudah untuk menulis objek besar dengan "semua bidang opsional". Objek seperti itu memang dapat menerima berbagai masukan, namun dengan biaya:

• Tidak mungkin mengetahui dari struktur dokumen mana yang diterima.
• Item wajib dan item opsional dari kedua dokumen tercampur satu sama lain, dan aturan verifikasi menjadi semakin kabur.
• Ketika terjadi error, sulit untuk menjelaskan secara pasti dimana inputnya tidak sesuai harapan.

Akan lebih jelas jika menyimpan dua kontrak terpisah dan memilih salah satunya dengan bidang tipe eksplisit.

oneOf bukan sembarang orang

Cabang yang tumpang tindih akan menyebabkan kegagalan input hukum.

oneOf mengharuskan input cocok dengan satu cabang. Jika kedua cabang lolos pada saat yang sama, verifikasi keseluruhan akan gagal.

Jika cabang hanya berisi beberapa bidang opsional, kemungkinan besar bidang tersebut akan tumpang tindih. Saat ini, masukan hukum gagal lolos verifikasi.

Gunakan jenis dan konst untuk menghilangkan tumpang tindih

Dengan menggunakan bidang kind yang diperlukan ditambah const untuk menetapkan nilai, Anda dapat menetapkan batas yang jelas antara cabang dan menghilangkan tumpang tindih tersebut sebelumnya.

Untuk detail lebih lanjut tentang aturan kombinasi, lihat Aturan kombinasi Skema JSON.

Protokol pengalihan eksekusi

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

Ini adalah contoh catatan yang disederhanakan, bukan model lapangan lengkap dari faktur nyata. Kode ini menunjukkan pemilihan cabang dan penolakan kolom yang berlebihan; tarif pajak, header, dan jumlah perlu didefinisikan secara terpisah.

Jika bisnis mengizinkan bidang tambahan, namespace untuk bidang-bidang tersebut harus didefinisikan dengan jelas daripada diam-diam menghapus semua kendala.

Jangan hanya menampilkan pesan kesalahan "tidak cocok"

Hanya "ketidakcocokan" yang ditampilkan, dan baik pengguna maupun staf pemeliharaan tidak dapat mengetahui di mana letak masalahnya. Tabel di bawah ini mencantumkan beberapa fitur input umum dan metode umpan balik yang sesuai:

Tipe yang tidak pasti juga butuh jalan keluar

Jika pengklasifikasi tidak dapat membedakan antara faktur dan struk, status tidak diketahui sebaiknya dipertahankan, bukan secara acak memilih cabang untuk membuat "sukses."

Ada tiga tingkat berbeda di sini yang perlu dipertimbangkan secara terpisah:

• Category Confidence: Seberapa percaya diri sistem dalam menilai tipe dokumen.
• Verifikasi Struktur: Masukkan apakah kontrak yang dipilih telah dipenuhi.
• Keaslian Bisnis: Apakah dokumen itu sendiri asli dan valid.

Verifikasi struktural tidak dapat dibuktikan secara balik kebenaran, juga tidak dapat membuktikan dokumen itu asli.

Jenis dokumen juga harus dipertahankan dalam proses terjemahan

Bidang yang sama mungkin memerlukan terminologi yang berbeda dalam dokumen yang berbeda. Saat menggunakan terminologi OmniDoc dan alur kerja tinjauan dwibahasa, menyediakan daftar pengiriman kepada tipe dokumen membantu peninjau memahami konteks jumlah dan jumlahnya.

Jangan biarkan objek JSON yang luas menghapus perbedaan ini.

📊 Perbandingan Inti

🎯 Metode mana yang cocok untukmu?

Jika Anda perlu menerima faktur dan struk sekaligus

Simpan dua kontrak terpisah dan tetapkan kind sebagai bidang wajib.

Jika field cabang Anda tumpang tindih secara luas

Perbaiki kind dengan const di setiap cabang untuk menghindari pencocokan input yang sah dengan beberapa cabang secara bersamaan.

Jika sistem Anda mengizinkan bidang tambahan

Pertama, perjelas namespace dari bidang tambahan, lalu putuskan bagaimana melonggarkan batasan.

Jika pengklasifikasi Anda belum cukup yakin

Pertahankan status tidak diketahui dan kirim dokumen ke antrean untuk diurutkan; jangan pilih cabang secara paksa.

❓ Pertanyaan yang Sering Diajukan (FAQ)

1. Kenapa tidak menggunakan objek di mana semua field bersifat opsional?

Pasangan seperti itu bisa memalsukan apa saja, namun sulit untuk mengetahui apa yang sebenarnya mereka terima.

2. Mengapa oneOf menyebabkan kegagalan entri yang valid?

oneOf membutuhkan pencocokan cabang secara tepat. Jika kedua cabang lulus secara bersamaan, pemeriksaan keseluruhan akan gagal. Situasi ini kemungkinan terjadi ketika bidang cabang saling tumpang tindih secara luas.

3. Apa yang harus Anda perhatikan saat mengizinkan field tambahan?

Namespace untuk bidang tambahan harus didefinisikan dengan jelas, bukan secara diam-diam menghapus semua batasan.

4. Bagaimana jika pengklasifikasi tidak dapat menentukan jenis dokumen?

Pertahankan status tidak diketahui dan masukkan antrian independen untuk diklasifikasikan; jangan memilih cabang secara acak untuk merakit cabang yang berhasil.

5. Apakah lolos verifikasi struktural membuktikan keaslian dokumen?

Tidak. Kepercayaan klasifikasi, verifikasi struktural, dan keaslian bisnis adalah tiga tingkat yang berbeda; verifikasi struktural tidak dapat membuktikan keaslian dokumen.

📝 Ringkasan

Saat menempatkan faktur dan struk dalam entri yang sama, simpan dua kontrak terpisah dan pilih menggunakan kolom kind yang diperlukan, sehingga jenis dokumen yang dimasukkan terlihat jelas. Verifikasi cabang, umpan balik kesalahan, dan ekspor tipe tidak dikenal juga harus dirancang bersama.

Rasakan sekarang: Unggah dokumen Anda untuk mulai menerjemahkan, mempertahankan format asli