Pain001

సూచిక

Pain001 సాంకేతిక సూచిక: CLI, Python API, REST

pain001 v0.0.71 యొక్క ప్రతి ఫ్లాగ్, ఎండ్‌పాయింట్, ప్రవర్తన. ఆకాంక్ష నుండి కాదు, షిప్ అయిన కోడ్ నుండి తీసుకున్నవి.

5 నిమిషాల పఠనంచివరి సమీక్ష

ఈ సూచిక pain001 v0.0.71 యొక్క కమాండ్-లైన్ ఇంటర్‌ఫేస్, Python API, REST మైక్రోసర్వీస్, ధృవీకరణ పైప్‌లైన్‌లను నమోదు చేస్తుంది. ఇక్కడ పేర్కొన్న ప్రతి ఫ్లాగ్, ఎండ్‌పాయింట్, ప్రవర్తన షిప్ అయిన కోడ్ నుండి తీసుకున్నవే, ఆకాంక్ష నుండి కాదు.

Pain001 12 ISO 20022 సందేశ నిర్వచనాలకు మద్దతిస్తుంది: pain.001.001.03 నుండి pain.001.001.13 వరకు (Customer Credit Transfer Initiation, పదకొండు వెర్షన్లు) మరియు pain.008.001.02 (Customer Direct Debit Initiation).

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 లావాదేవీలు; ప్రతి చంక్ తిరిగి లెక్కించిన NbOfTxs మరియు CtrlSumతో సొంత XML ఫైల్ అవుతుంది).
--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",
)

జనరేట్ అయిన ప్రతి పత్రం రాయబడే ముందు మూడు పొరలను దాటుతుంది:

  1. ఇన్‌పుట్ ధృవీకరణ: ప్రతి రికార్డు సందేశ రకపు JSON Schemaకు వ్యతిరేకంగా తనిఖీ అవుతుంది, ఫీల్డ్-అలియాస్ సాధారణీకరణ మరియు IBAN/BIC సింటాక్స్ తనిఖీలతో సహా.
  2. స్కీమ్ రూల్‌బుక్ (ఐచ్ఛికం): SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B, లేదా క్రాస్-బోర్డర్ క్రెడిట్ ట్రాన్స్‌ఫర్ నియమాలు.
  3. 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% డాక్‌స్ట్రింగ్ కవరేజ్, మరియు సెక్యూరిటీ లింటింగ్ (Bandit, pip-audit). ప్రతి విడుదల బిల్డ్‌కు ఒక CycloneDX SBOM జనరేట్ అవుతుంది.

ఇన్‌స్టాలేషన్ గైడ్, AI ఏజెంట్ల కోసం MCP సర్వర్, లేదా చెల్లింపుల పదకోశంతో కొనసాగండి.