Pain001
جرّب العرض ›

مرجع

Pain001: المرجع التقني — CLI وواجهة Python وREST

كل خيار ونقطة نهاية وسلوك في pain001 v0.0.56 — مأخوذ من الشيفرة المُصدرة، لا من الطموح.

4 دقيقة قراءة آخر مراجعة

يوثّق هذا المرجع واجهة سطر الأوامر وواجهة Python البرمجية وخدمة REST المصغّرة ومسار التحقق في pain001 v0.0.57. كل خيار ونقطة نهاية وسلوك مذكور هنا مأخوذ من الشيفرة المُصدرة، لا من الطموح.

يدعم Pain001 11 تعريفًا لرسائل ISO 20022: من pain.001.001.03 إلى pain.001.001.12 (بدء تحويل ائتماني للعميل، عشرة إصدارات) وpain.008.001.02 (بدء خصم مباشر للعميل).

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 فحص وإدارة إضافات المحمّلات والمدقّقات والأنظمة والكتّاب المكتشفة.

خيارات 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 البرمجية#

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

يمر كل مستند مولَّد بثلاث طبقات قبل كتابته:

  1. التحقق من الإدخال — يُفحص كل سجل وفق JSON Schema الخاص بنوع الرسالة، مع تطبيع الأسماء البديلة للحقول وفحوص صياغة IBAN/BIC.
  2. كتاب قواعد النظام (اختياري) — قواعد SEPA SCT أو SEPA Instant أو SEPA SDD Core أو SEPA B2B أو التحويل الائتماني عبر الحدود.
  3. التحقق وفق XSD — يُتحقق من ملف XML المولَّد وفق مخطط ISO 20022 الرسمي عبر xmlschema قبل كتابة بايت واحد على القرص.

تُعالَج المبالغ النقدية كـ decimal.Decimal أثناء توليد XML والتحقق وفق النظام — وليس أبدًا كأعداد 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

جميع نقاط النهاية مركّبة تحت /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. بنية الإضافات#

المنظومة قابلة للتوسعة عبر أربع مجموعات نقاط دخول: 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، وتغطية 100% لسلاسل التوثيق، وفحص أمني (Bandit وpip-audit). وتُولَّد قائمة SBOM بصيغة CycloneDX لكل بناء إصدار.

تابع مع دليل التثبيت أو خادم MCP لوكلاء الذكاء الاصطناعي أو مسرد المدفوعات.