Rujukan Teknikal Pain001: CLI, Python API dan REST

Rujukan ini mendokumentasikan antara muka baris perintah, Python API, perkhidmatan mikro REST dan saluran pengesahan bagi pain001 v0.0.57. Setiap flag, titik akhir dan gelagat yang disenaraikan di sini diambil daripada kod yang telah dikeluarkan, bukan daripada harapan semata-mata.

Pain001 menyokong 11 takrifan mesej ISO 20022: pain.001.001.03 hingga pain.001.001.12 (Customer Credit Transfer Initiation, sepuluh versi) dan pain.008.001.02 (Customer Direct Debit Initiation).

1. Antara Muka Baris Perintah#

Fail boleh laku pain001 mengumpulkan fungsinya ke dalam subperintah. Menjalankannya dengan flag penjanaan sahaja akan memanggil generate secara tersirat, jadi automasi sedia ada terus berfungsi.

Subperintah	Tujuan
`generate`	Menukarkan fail data kepada XML ISO 20022 yang disahkan skema (perintah lalai).
`validate`	Mengesahkan data input tanpa menulis XML.
`versions [--json]`	Menyenaraikan kesemua 11 takrifan mesej yang disokong.
`inspect [--json]`	Memaparkan medan wajib dan medan pilihan bagi sesuatu jenis mesej.
`init [-o DIR]`	Menjana rangka templat CSV permulaan bagi sesuatu jenis mesej.
`serve [--host] [--port] [--reload]`	Melancarkan perkhidmatan mikro REST FastAPI (memerlukan ekstra `api`).
`mcp`	Melancarkan pelayan Model Context Protocol terbina dalam (5 alat; pelayan penuh 17 alat dikeluarkan sebagai `pain001-mcp`).
`plugins list / show / disable`	Memeriksa dan mengurus plugin loader, validator, scheme dan writer yang ditemui.

Pilihan `generate`

Flag	Penerangan
`-t, --xml-message-type`	Takrifan mesej, contohnya `pain.001.001.09`.
`-d, --data`	Data input: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, atau `.gpg` / `.asc` yang disulitkan PGP.
`-o, --output-dir`	Direktori yang menerima XML yang dijana.
`-m, --template` / `-s, --schema`	Menggantikan templat Jinja2 atau skema XSD terbina dalam.
`-c, --config`	Memuatkan nilai lalai daripada profil konfigurasi (`--profile`, `--show-config`).
`--dry-run` (alias `--validate-only`)	Mengesahkan input terhadap JSON Schema, XSD dan rulebook skim tanpa menulis output.
`--scheme`	Menguatkuasakan rulebook skim: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b`, atau `xborder-ct`.
`--explain --scheme-format {text,json}`	Melaporkan setiap peraturan skim yang lulus atau gagal, dalam bentuk boleh dibaca manusia atau boleh dibaca mesin.
`--streaming` / `--chunk-size`	Pemprosesan berbahagian yang terbatas memori untuk kelompok besar (lalai 1,000 transaksi bagi setiap bahagian; setiap bahagian menjadi fail XML tersendiri dengan `NbOfTxs` dan `CtrlSum` yang dikira semula).
`--emit-metrics`	Mengeluarkan metrik larian yang boleh dibaca mesin untuk saluran kebolehcerapan.

Kod keluar mesra CI: 0 berjaya, 1 kegagalan pengesahan, 2 ralat penggunaan.

2. Python API#

from pain001.core.core import process_files

# Generate a validated pain.001.001.09 file from CSV
process_files(
    xml_message_type="pain.001.001.09",
    xml_template_file_path="template.xml",
    xsd_schema_file_path="schema.xsd",
    data_file_path="payments.csv",
    output_dir="out",
)

Setiap dokumen yang dijana melalui tiga lapisan sebelum ia ditulis:

Pengesahan input — setiap rekod diperiksa terhadap JSON Schema bagi jenis mesej berkenaan, dengan penormalan alias medan serta pemeriksaan sintaks IBAN/BIC.
Rulebook skim (pilihan) — peraturan SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B, atau pindahan kredit rentas sempadan.
Pengesahan XSD — XML yang telah dijana disahkan terhadap skema rasmi ISO 20022 melalui xmlschema sebelum satu bait pun ditulis ke cakera.

Amaun kewangan dikendalikan sebagai decimal.Decimal sepanjang penjanaan XML dan pengesahan skim — tidak pernah sebagai apungan IEEE 754 — dan jumlah kawalan NbOfTxs / CtrlSum dikira semula daripada rekod yang telah disahkan, bukannya dipercayai terus daripada input.

Selain penjanaan pain.001, pustaka terasnya turut menyertakan penghurai dan penjana laporan status pain.002 (supaya anda dapat membaca jawapan terima/tolak daripada bank) serta penghurai dan penjana penyata camt.053 untuk penyesuaian akhir hari, ditambah VersionMapper yang memindahkan rekod antara versi mesej.

3. Perkhidmatan Mikro REST#

pip install "pain001[api]"
pain001 serve --host 0.0.0.0 --port 8000

Kesemua titik akhir dilekapkan di bawah /api/v1 (dengan alias tanpa versi /api):

Kaedah & Laluan	Tujuan
`GET /api/v1/health`	Pemeriksaan keaktifan.
`POST /api/v1/validate`	Mengesahkan rekod; mengembalikan ralat pada peringkat medan.
`POST /api/v1/generate`	Penjanaan XML secara segerak.
`POST /api/v1/generate/async`	Membariskan kelompok besar untuk penjanaan di latar belakang.
`GET /api/v1/status/{job_id}`	Menyemak status kerja tak segerak.
`GET /api/v1/download/{job_id}`	Memuat turun XML yang telah siap.
`DELETE /api/v1/jobs/{job_id}`	Membersihkan kerja yang telah selesai.
`GET /metrics`	Metrik Prometheus.

Dokumentasi interaktif disajikan di /api/docs (Swagger UI), /api/redoc dan /api/reference (Scalar), dengan dokumen OpenAPI di /openapi.json.

4. Penormalan Input#

Pain001 menyesuaikan eksport data dunia sebenar menjadi rekod yang sah sebelum pengesahan:

Alias medan — nama lajur ERP yang lazim dipetakan kepada medan berkanun (contohnya amount → payment_amount).
Penormalan IBAN / BIC — ruang kosong dibuang, huruf diseragamkan, kemudian diperiksa (mod-97 ISO 13616 untuk IBAN, struktur ISO 9362 untuk BIC).
Tarikh — penghuraian ISO 8601 YYYY-MM-DD untuk tarikh pelaksanaan.
Amaun — disalurkan melalui decimal.Decimal; amaun yang cacat formatnya akan gagal pengesahan dan bukannya dibundarkan secara senyap.
Set aksara — pembantu transliterasi menurunkan kandungan kepada set aksara Latin ISO 20022 yang diterima SWIFT dan SEPA.

5. Seni Bina Plugin#

Rangkaian pakej ini boleh diperluas melalui empat kumpulan entry point: pain001.loaders, pain001.validators, pain001.schemes dan pain001.writers. pain001-loader-xlsx mendaftar melalui mekanisme ini dan ditemui secara automatik semasa pemasangan; pain001-loader-mt101 ialah pustaka penghuraian tersendiri yang digunakan secara terus (dan oleh alat convert_mt101 pada pelayan MCP). Suis mati — PAIN001_DISABLE_PLUGINS=1 — melumpuhkan penemuan plugin pihak ketiga sepenuhnya dalam persekitaran yang dikawal ketat.

6. Get Kualiti#

Pustaka terasnya dibangunkan dengan get yang ketat dan boleh disahkan: liputan baris dan cabang 100% yang dikuatkuasakan dalam CI (--cov-fail-under=100), penaipan mypy yang ketat, liputan docstring 100%, serta linting keselamatan (Bandit, pip-audit). SBOM CycloneDX dijana bagi setiap binaan keluaran.

Teruskan dengan Panduan Pemasangan, pelayan MCP untuk ejen AI, atau glosari pembayaran.