เอกสารอ้างอิงทางเทคนิค Pain001: CLI, Python API และ REST

เอกสารอ้างอิงนี้อธิบายอินเทอร์เฟซบรรทัดคำสั่ง Python API ไมโครเซอร์วิส REST และไปป์ไลน์การตรวจสอบความถูกต้องของ pain001 v0.0.57 ทุกแฟล็ก ทุก endpoint และทุกพฤติกรรมที่ระบุไว้ที่นี่นำมาจากโค้ดที่เผยแพร่จริง ไม่ใช่จากความคาดหวัง

Pain001 รองรับนิยามข้อความ ISO 20022 จำนวน 11 รายการ ได้แก่ pain.001.001.03 ถึง pain.001.001.12 (Customer Credit Transfer Initiation จำนวนสิบเวอร์ชัน) และ pain.008.001.02 (Customer Direct Debit Initiation)

1. อินเทอร์เฟซบรรทัดคำสั่ง#

ไฟล์ปฏิบัติการ pain001 จัดกลุ่มความสามารถไว้เป็นคำสั่งย่อย หากเรียกใช้ด้วยแฟล็กสำหรับการสร้างไฟล์เพียงอย่างเดียว ระบบจะเรียก generate โดยปริยาย ระบบอัตโนมัติที่มีอยู่เดิมจึงทำงานได้ต่อไป

คำสั่งย่อย	วัตถุประสงค์
`generate`	แปลงไฟล์ข้อมูลเป็น XML ตามมาตรฐาน ISO 20022 ที่ผ่านการตรวจสอบกับสกีมา (คำสั่งเริ่มต้น)
`validate`	ตรวจสอบความถูกต้องของข้อมูลนำเข้าโดยไม่เขียนไฟล์ XML
`versions [--json]`	แสดงรายการนิยามข้อความที่รองรับทั้ง 11 รายการ
`inspect [--json]`	แสดงฟิลด์ที่จำเป็นและฟิลด์ทางเลือกของข้อความแต่ละประเภท
`init [-o DIR]`	สร้างเทมเพลต CSV ตั้งต้นสำหรับข้อความแต่ละประเภท
`serve [--host] [--port] [--reload]`	เริ่มไมโครเซอร์วิส REST ที่พัฒนาด้วย FastAPI (ต้องติดตั้งส่วนเสริม `api`)
`mcp`	เริ่มเซิร์ฟเวอร์ Model Context Protocol ที่มาพร้อมในตัว (5 เครื่องมือ ส่วนเซิร์ฟเวอร์ฉบับเต็ม 17 เครื่องมือเผยแพร่ในชื่อ `pain001-mcp`)
`plugins list / show / disable`	ตรวจสอบและจัดการปลั๊กอินประเภท loader, validator, scheme และ writer ที่ค้นพบ

ตัวเลือกของ `generate`

แฟล็ก	คำอธิบาย
`-t, --xml-message-type`	นิยามข้อความ เช่น `pain.001.001.09`
`-d, --data`	ข้อมูลนำเข้า: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet` หรือไฟล์ที่เข้ารหัสด้วย PGP `.gpg` / `.asc`
`-o, --output-dir`	ไดเรกทอรีที่จัดเก็บไฟล์ XML ที่สร้างขึ้น
`-m, --template` / `-s, --schema`	แทนที่เทมเพลต Jinja2 หรือสกีมา XSD ที่มาพร้อมในตัว
`-c, --config`	โหลดค่าเริ่มต้นจากโปรไฟล์การตั้งค่า (`--profile`, `--show-config`)
`--dry-run` (ชื่อเรียกอื่น `--validate-only`)	ตรวจสอบข้อมูลนำเข้ากับ JSON Schema, XSD และกฎเกณฑ์ของสกีม โดยไม่เขียนไฟล์ผลลัพธ์
`--scheme`	บังคับใช้กฎเกณฑ์ของสกีม: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` หรือ `xborder-ct`
`--explain --scheme-format {text,json}`	รายงานกฎของสกีมแต่ละข้อที่ผ่านหรือไม่ผ่าน ในรูปแบบที่มนุษย์หรือเครื่องอ่านได้
`--streaming` / `--chunk-size`	การประมวลผลเป็นก้อนโดยจำกัดการใช้หน่วยความจำสำหรับชุดข้อมูลขนาดใหญ่ (ค่าเริ่มต้น 1,000 รายการต่อก้อน แต่ละก้อนจะกลายเป็นไฟล์ XML ของตนเอง พร้อมคำนวณ `NbOfTxs` และ `CtrlSum` ขึ้นใหม่)
`--emit-metrics`	ส่งออกเมตริกการทำงานในรูปแบบที่เครื่องอ่านได้สำหรับไปป์ไลน์การสังเกตการณ์ระบบ

รหัสสถานะการออกออกแบบมาให้ใช้กับ CI ได้: 0 สำเร็จ, 1 การตรวจสอบไม่ผ่าน, 2 ใช้คำสั่งไม่ถูกต้อง

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

เอกสารทุกฉบับที่สร้างขึ้นต้องผ่านการตรวจสามชั้นก่อนถูกเขียนลงไฟล์:

การตรวจสอบข้อมูลนำเข้า — แต่ละระเบียนจะถูกตรวจกับ JSON Schema ของข้อความประเภทนั้น พร้อมการปรับชื่อฟิลด์พ้องให้เป็นมาตรฐานและการตรวจรูปแบบ IBAN/BIC
กฎเกณฑ์ของสกีม (ทางเลือก) — กฎของ SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B หรือการโอนเงินข้ามพรมแดน
การตรวจสอบด้วย XSD — XML ที่สร้างขึ้นจะถูกตรวจกับสกีมา ISO 20022 อย่างเป็นทางการผ่าน xmlschema ก่อนที่จะเขียนข้อมูลแม้แต่ไบต์เดียวลงดิสก์

ระหว่างการสร้าง XML และการตรวจสอบตามกฎของสกีม จำนวนเงินจะถูกจัดการเป็น decimal.Decimal เสมอ — ไม่ใช่เลขทศนิยมแบบ IEEE 754 — และยอดควบคุม NbOfTxs / CtrlSum จะถูกคำนวณขึ้นใหม่จากระเบียนที่ผ่านการตรวจสอบ แทนที่จะเชื่อค่าที่มากับข้อมูลนำเข้า

นอกเหนือจากการสร้าง pain.001 ไลบรารีหลักยังมีตัวอ่านและตัวสร้างรายงานสถานะ pain.002 (เพื่อให้คุณอ่านคำตอบรับหรือปฏิเสธจากธนาคารได้) และตัวอ่านและตัวสร้างรายการเดินบัญชี camt.053 สำหรับการกระทบยอดสิ้นวัน พร้อมทั้ง VersionMapper ที่ย้ายระเบียนข้ามเวอร์ชันของข้อความ

3. ไมโครเซอร์วิส REST#

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

endpoint ทั้งหมดอยู่ภายใต้ /api/v1 (พร้อมชื่อเรียกอื่นที่ไม่ระบุเวอร์ชันคือ /api):

เมธอดและเส้นทาง	วัตถุประสงค์
`GET /api/v1/health`	การตรวจสอบว่าระบบยังทำงานอยู่
`POST /api/v1/validate`	ตรวจสอบระเบียน แล้วคืนค่าข้อผิดพลาดในระดับฟิลด์
`POST /api/v1/generate`	การสร้าง XML แบบซิงโครนัส
`POST /api/v1/generate/async`	จัดคิวชุดข้อมูลขนาดใหญ่เพื่อสร้างไฟล์เบื้องหลัง
`GET /api/v1/status/{job_id}`	ตรวจสอบสถานะงานแบบอะซิงโครนัส
`GET /api/v1/download/{job_id}`	ดาวน์โหลดไฟล์ XML ที่เสร็จสมบูรณ์
`DELETE /api/v1/jobs/{job_id}`	ล้างงานที่เสร็จสิ้นแล้ว
`GET /metrics`	เมตริกของ Prometheus

เอกสารเชิงโต้ตอบให้บริการที่ /api/docs (Swagger UI), /api/redoc และ /api/reference (Scalar) ส่วนเอกสาร OpenAPI อยู่ที่ /openapi.json

4. การปรับข้อมูลนำเข้าให้เป็นมาตรฐาน#

ก่อนการตรวจสอบ Pain001 จะปรับข้อมูลที่ส่งออกจากระบบงานจริงให้กลายเป็นระเบียนที่ถูกต้อง:

ชื่อฟิลด์พ้อง — ชื่อคอลัมน์ที่พบบ่อยในระบบ ERP จะถูกจับคู่กับฟิลด์มาตรฐาน (ตัวอย่างเช่น amount → payment_amount)
การปรับ IBAN / BIC ให้เป็นมาตรฐาน — ตัดช่องว่างออก ปรับตัวพิมพ์ให้สม่ำเสมอ แล้วจึงตรวจสอบ (mod-97 ตาม ISO 13616 สำหรับ IBAN และโครงสร้างตาม ISO 9362 สำหรับ BIC)
วันที่ — อ่านค่าวันที่ดำเนินการตามรูปแบบ ISO 8601 YYYY-MM-DD
จำนวนเงิน — ประมวลผลผ่าน decimal.Decimal จำนวนเงินที่รูปแบบไม่ถูกต้องจะไม่ผ่านการตรวจสอบ แทนที่จะถูกปัดเศษอย่างเงียบ ๆ
ชุดอักขระ — ตัวช่วยถอดอักษรจะลดทอนเนื้อหาให้อยู่ในชุดอักขระละตินของ ISO 20022 ที่ SWIFT และ SEPA ยอมรับ

5. สถาปัตยกรรมปลั๊กอิน#

ชุดเครื่องมือนี้ขยายความสามารถได้ผ่านกลุ่ม entry point สี่กลุ่ม ได้แก่ pain001.loaders, pain001.validators, pain001.schemes และ pain001.writers โดย pain001-loader-xlsx ลงทะเบียนผ่านกลไกนี้และถูกค้นพบโดยอัตโนมัติเมื่อติดตั้ง ส่วน pain001-loader-mt101 เป็นไลบรารีอ่านข้อมูลแบบเอกเทศที่เรียกใช้ได้โดยตรง (และถูกเรียกใช้โดยเครื่องมือ convert_mt101 ของเซิร์ฟเวอร์ MCP ด้วย) นอกจากนี้ยังมีสวิตช์ปิดการทำงาน — PAIN001_DISABLE_PLUGINS=1 — ซึ่งปิดการค้นหาปลั๊กอินจากบุคคลที่สามทั้งหมดในสภาพแวดล้อมที่ควบคุมเข้มงวด

6. เกณฑ์คุณภาพ#

ไลบรารีหลักพัฒนาภายใต้เกณฑ์ที่เข้มงวดและตรวจสอบยืนยันได้ ได้แก่ ความครอบคลุมของโค้ดระดับบรรทัดและระดับสาขา 100% ที่บังคับใช้ใน CI (--cov-fail-under=100), การกำหนดชนิดข้อมูลแบบเข้มงวดด้วย mypy, ความครอบคลุมของ docstring 100% และการตรวจความปลอดภัยของโค้ด (Bandit, pip-audit) พร้อมทั้งสร้าง SBOM รูปแบบ CycloneDX สำหรับทุกบิลด์ที่เผยแพร่

อ่านต่อได้ที่ คู่มือการติดตั้ง, เซิร์ฟเวอร์ MCP สำหรับเอเจนต์ AI หรืออภิธานศัพท์การชำระเงิน