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 服务器或支付术语表。