Pain001: مرجع فنی — CLI، رابط Python و REST

این مرجع، رابط خط فرمان، رابط برنامه‌نویسی 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`، یا `.gpg` / `.asc` رمزنگاری‌شده با PGP.
`-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",
)

هر سند تولیدشده پیش از نوشته‌شدن از سه لایه عبور می‌کند:

اعتبارسنجی ورودی — هر رکورد در برابر JSON Schema مربوط به آن نوع پیام بررسی می‌شود، همراه با یکسان‌سازی نام‌های مستعار فیلدها و بررسی نحوی IBAN/BIC.
آیین‌نامه طرح (اختیاری) — قواعد SEPA SCT، SEPA Instant، SEPA SDD Core، SEPA B2B یا انتقال اعتباری برون‌مرزی.
اعتبارسنجی XSD — XML رندرشده پیش از آنکه حتی یک بایت روی دیسک نوشته شود، از طریق xmlschema در برابر طرحواره رسمی ISO 20022 اعتبارسنجی می‌شود.

مبالغ پولی در سراسر تولید 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

همه نقاط انتهایی زیر /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 — فاصله‌ها حذف و حروف یکدست می‌شوند و سپس بررسی صورت می‌گیرد (باقی‌مانده بر 97 مطابق ISO 13616 برای IBAN، ساختار ISO 9362 برای BIC).
تاریخ‌ها — تجزیه YYYY-MM-DD مطابق ISO 8601 برای تاریخ‌های اجرا.
مبالغ — از مسیر 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 برای عامل‌های هوش مصنوعی یا واژه‌نامه پرداخت‌ها ادامه دهید.