Pain001 技術參考：CLI、Python API 與 REST

本參考文件說明 pain001 v0.0.71 的命令列介面、Python API、REST 微服務與驗證管線。此處列出的每個旗標、端點與行為皆取自實際釋出的程式碼，而非願景。

Pain001 支援 12 種 ISO 20022 電文定義：pain.001.001.03 至 pain.001.001.13（客戶貸記轉帳發動，共十一個版本）以及 pain.008.001.02（客戶直接扣款發動）。

1. 命令列介面#

pain001 執行檔將功能劃分為多個子命令。僅帶產生旗標執行時會隱含呼叫 generate，因此既有的自動化流程可照常運作。

子命令	用途
`generate`	將資料檔轉換為經結構描述驗證的 ISO 20022 XML（預設命令）。
`validate`	僅驗證輸入資料，不寫出 XML。
`versions [--json]`	列出全部 13 種支援的電文定義。
`inspect <type> [--json]`	顯示某電文類型的必填與選填欄位。
`init <type> [-o DIR]`	為電文類型建立入門 CSV 範本。
`serve [--host] [--port] [--reload]`	啟動 FastAPI REST 微服務（需安裝 `api` 額外相依）。
`mcp`	啟動內建的 Model Context Protocol 伺服器（5 個工具；完整的 22 工具伺服器以 `pain001-mcp` 形式發行）。
`plugins list / show / disable`	檢視並管理已探索到的載入器、驗證器、方案與寫出器外掛。

`generate` 選項

旗標	說明
`-t, --xml-message-type <TYPE>`	電文定義，例如 `pain.001.001.09`。
`-d, --data <FILE>`	輸入資料：`.csv`、`.json`、`.jsonl`、`.db` / `.sqlite`、`.parquet`，或經 PGP 加密的 `.gpg` / `.asc`。
`-o, --output-dir <DIR>`	存放產生 XML 的目錄。
`-m, --template <FILE>` / `-s, --schema <FILE>`	覆寫內建的 Jinja2 範本或 XSD 結構描述。
`-c, --config <FILE>`	從組態設定檔載入預設值（`--profile`、`--show-config`）。
`--dry-run`（別名 `--validate-only`）	依 JSON Schema、XSD 與方案規則手冊驗證輸入，但不寫出任何輸出。
`--scheme <NAME>`	強制套用方案規則手冊：`sepa-sct`、`sepa-inst`、`sepa-sdd`、`sepa-b2b` 或 `xborder-ct`。
`--explain --scheme-format {text,json}`	回報每條通過或未通過的方案規則，可輸出人類可讀或機器可讀格式。
`--streaming` / `--chunk-size <N>`	針對大批次的記憶體受控分塊處理（預設每塊 1,000 筆交易；每個分塊各自產生一個 XML 檔案，並重新計算 `NbOfTxs` 與 `CtrlSum`）。
`--emit-metrics`	輸出機器可讀的執行指標，供可觀測性管線使用。

結束代碼對 CI 友善：0 表示成功、1 表示驗證失敗、2 表示用法錯誤。

In the next release

These features are in development for the next pain001 release. They are not in pain001 0.0.71, the version this reference documents, and their names may change before they ship.

旗標	說明
`--envelop-bah`	Wrap generated payment XML into an ISO 20022 Business Application Header (`head.001.001.03`) and `BizData` (`head.003.001.01`) envelope.
`--bah-sender <BIC/ID>`	Sender financial institution BIC or organisation identifier for BAH `<Fr>`.
`--bah-receiver <BIC/ID>`	Receiver financial institution BIC or organisation identifier for BAH `<To>`.
`--bah-msg-id <ID>`	Business Message Identifier for BAH `<BizMsgIdr>` (defaults to generated UUID).
`--xml-sign-key <FILE>`	PEM RSA private key for W3C XML Digital Signature (XML-DSig RSA-SHA256).
`--xml-sign-cert <FILE>`	Optional PEM X.509 certificate to embed in XML-DSig `<ds:KeyInfo>`.
`--xml-sign-passphrase-env <VAR>`	Environment variable holding passphrase to decrypt the RSA private key.

The Python API gains the matching process_files parameters: envelop_bah, xml_sign_key and xml_sign_cert.

Input normalisation gains formula injection shielding: cells starting with a formula trigger (=, +, -, @, tab, carriage return or line feed) are escaped with a leading single quote, preventing CSV injection (CWE-1236) when a file is opened in a spreadsheet.

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 在寫入磁碟前，先透過 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 正規化：去除空白、統一大小寫後再行檢查（IBAN 採 ISO 13616 mod-97 檢核，BIC 採 ISO 9362 結構檢查）。
日期：依 ISO 8601 YYYY-MM-DD 解析執行日期。
金額：一律經由 decimal.Decimal 處理；格式錯誤的金額會直接驗證失敗，而不是被默默捨入。
字元集：轉寫輔助工具會將內容化約為 SWIFT 與 SEPA 接受的 ISO 20022 拉丁字元集。

5. 外掛架構#

本套件可經由四個進入點群組擴充：pain001.loaders、pain001.validators、pain001.schemes 與 pain001.writers。pain001-loader-xlsx 透過此機制註冊，安裝後即自動被探索到；pain001-loader-mt101 則是可直接取用的獨立解析函式庫（MCP 伺服器的 convert_mt101 工具也使用它）。緊急停用開關 PAIN001_DISABLE_PLUGINS=1 可在高度管控環境中完全停用第三方外掛探索。

6. 品質關卡#

核心函式庫依循嚴格且可驗證的關卡開發：CI 強制 100% 行與分支涵蓋率（--cov-fail-under=100）、嚴格 mypy 型別檢查、100% docstring 涵蓋率，以及安全掃描（Bandit、pip-audit）。每個發行版建置都會產生 CycloneDX SBOM。

接著可閱讀安裝指南、給 AI 代理使用的 MCP 伺服器，或支付詞彙表。