التعليمات

خصوصية البيانات والامتثال

هل تغادر أي بيانات بنيتي التحتية؟

لا — حتى لاستخراج PDF. يعمل Bank Statement Parser كمكتبة عديمة الحالة. تتم جميع العمليات — التحليل وتنقيح PII واستخراج الأرشيف — داخل ذاكرة التشغيل المحلية. خط أنابيب PDF الهجين يستخدم Ollama للاستدلال المحلي بنماذج LLM — بدون APIs سحابية. محللات XML مُقوّاة بـ no_network=True، مما يحظر جميع الوصول الصادر على مستوى المحلل. بياناتك المالية لا تغادر بيئتك أبدًا.

كيف يعمل تنقيح PII؟

تُخفى الحقول الحساسة قبل وصولها إلى منطق تطبيقك. يحدد المحلل أسماء المدينين والدائنين وأرقام IBAN والعناوين البريدية، ويستبدلها بـ ***REDACTED*** في مخرجات وحدة التحكم ووضع البث.

• التنقيح مفعّل افتراضيًا في مخرجات CLI ووضع البث.
• صادرات الملفات (CSV وJSON وExcel) تحتفظ بالبيانات غير المنقحة للمعالجة اللاحقة.
• فعّل العرض بـ --show-pii في CLI أو redact_pii=False في API.

هل عملية الاستخراج حتمية؟

نعم للتنسيقات المنظمة — مخرجات متطابقة بالبايت في كل تشغيل. بنفس ملف الإدخال، المحللات الحتمية (CAMT، PAIN.001، CSV، OFX، QFX، MT940) تنتج نفس النتيجة كل مرة. لا عشوائية، لا استدلال نموذجي، لا أخذ عينات.

لخط أنابيب PDF الهجين، مسارات الاستخراج المعتمدة على LLM قد تنتج اختلافات طفيفة بين التشغيلات. لهذا السبب يُتحقق من كل استخراج PDF بـ القاعدة الذهبية (opening + credits − debits == closing) ويمكن مراجعة التناقضات تفاعليًا.

يفرض CI الحتمية بـ 718 اختبارًا بتغطية فرعية 100%، بما في ذلك التشويش القائم على الخصائص عبر Hypothesis.

ما معايير الامتثال التي يتبعها المشروع؟

يحتفظ المشروع بوثائق متوا��قة مع ISO 13485 مع تتبع كامل:

• سجل مخاطر كمّي مع تسجيل درجات الخطورة/الاحتمالية وتقييم المخاطر المتبقية.
• خطة التحقق والمصادقة بـ 19 خطوة مبوّبة عبر 5 مراحل.
• إجراء التحكم في التغيير مع تقييم التأثير وبروتوكولات التراجع.
• سجل SOUP يغطي جميع التبعيات مع مستويات المخاطر وتتبع نهاية العمر.
• مصفوفة التتبع تربط مدخلات التصميم بالتنفيذ والتحقق.

يتضمن كل إصدار CycloneDX SBOM ومجاميع SHA-256 وشهادة مصدر بناء GitHub.

الأداء وقابلية التوسع

ما مدى سرعة Bank Statement Parser؟

يُتحقق من حدود الأداء في CI عند كل commit:

سرعة استخراج PDF تعتمد على مسار التوجيه: حتمي (أقل من ثانية)، نص + LLM (ثوانٍ)، رؤية + LLM (ثوانٍ لكل صفحة).

كيف تُعالج الملفات الكبيرة؟

بث بذاكرة محدودة — اختُبر عند 50,000 معاملة لكل ملف. استخدم parse_streaming() لمعالجة ملفات XML تدريجيًا. كل معاملة تُنتج كقاموس؛ تُمسح العناصر بعد المعالجة لمنع نمو الذاكرة. الذاكرة لا تتناسب مع حجم الملف — اختبار 50 ألف معاملة (25+ ميغابايت) يستخدم أقل من ضعف ذاكرة اختبار 10 آلاف معاملة.

للملفات التي تتجاوز 50 ميغابايت (مثل دفعات PAIN.001 من مضيف إلى مضيف بأكثر من 100 ألف دفعة)، يبث المحلل عبر ملف مؤقت مع تجريد مساحة الاسم بالقطع — المستند الكامل لا يُحمّل في الذاكرة أبدًا.

كيف تُعالج أرشيفات ZIP بأمان؟

iter_secure_xml_entries() يتحقق من كل عضو قبل الاس��خراج:

• سقف حجم الإدخال (افتراضي 10 ميغابايت لكل إدخال)
• سقف إجمالي الحجم غير ال��ضغوط (افتراضي 50 مي��ابايت)
• حد نسبة الضغط (افتراضي 100:1) لمنع ZIP bombs
• رفض المدخلات المشفرة

لا يُكتب أي ملف على القرص. بايتات XML تمر مباشرة إلى المحلل عبر from_bytes().

هل يمكنني تحليل ملفات متعددة بالتوازي؟

نعم. استخدم parse_files_parallel() الذي يوزع العمل عبر ProcessPoolExecutor:

from bankstatementparser import parse_files_parallel

results = parse_files_parallel([
    "statements/jan.xml",
    "statements/feb.xml",
    "statements/mar.xml",
])
for r in results:
    print(r.path, r.status, len(r.transactions), "rows")

لاستيعاب PDF المجمّع، استخدم scan_and_ingest() الذي يعالج أشجار مجلدات كاملة مع إزالة التكرار تلقائيًا.

التنسيقات المدعومة

ما تنسيقات كشف الحساب المدعومة؟

التنسيق	المعيار	أنواع الملفات	المحلل/الطريقة
CAMT.053	ISO 20022 كشف من البنك إلى العميل	.xml	CamtParser
PAIN.001	ISO 20022 بدء تحويل ائتماني	.xml	Pain001Parser
CSV	صادرات بنكية عامة	.csv	CsvStatementParser
OFX	Open Financial Exchange	.ofx	OfxParser
QFX	Quicken Financial Exchange	.qfx	QfxParser
MT940	معيار SWIFT	.mt940, .sta	Mt940Parser
PDF	كشوفات رقمية وممسوحة ضوئيًا	.pdf	smart_ingest()

كيف يعمل خط أنا��يب PDF الهجين؟

خط الأنابيب الهجين (v0.0.5+) يوجّه ملفات PDF بذكاء عبر ثلاثة مسارات استخراج:

• المسار A (حتمي): جداول PDF المنظمة تُحلل مباشرة — مجاني، الأسرع، لا يحتاج LLM.
• المسار B (نص + LLM): ملفات PDF رقمية بتخطيطات معقدة تُستخرج عبر LLM محلي (LiteLLM/Ollama).
• المسار C (رؤية + LLM): كشوفات ممسوحة ��وئيًا أو مصورة تُعالج بنماذج رؤية متعددة الوسائط.

يُتحقق من كل استخراج بالقاعدة الذهبية (opening + credits − debits == closing). يمكن مراجعة الت��اقضات تفاعليًا بـ --type review.

هل يتعامل المحلل مع اللهجات الخاصة بالبنوك لـ CAMT.053؟

��عم — مستقل عن مساحة الاسم بالتصميم. يزيل المحلل مساحات أسماء XML قبل المعالجة، ويتعامل مع أي متغير CAMT.053 (camt.053.001.02، camt.053.001.04، أو أغلفة بنكية خاصة) بدون إعداد خاص بمساحة الاسم. استعلامات XPath تستهدف بنية العنصر، لا معرفات URI لمساحة الاسم.

للبنوك التي تغلف CAMT في مظروف مخصص، استخدم from_string() أو from_bytes() لتغذية المستند الداخلي مباشرة.

هل يمكنني تعيين رؤوس أعمدة CSV مخصصة للمخطط القياسي؟

نعم — تسوية تلقائية، صفر إعداد. CsvStatementParser يتعرف على اختلافات الرؤوس الشائعة: "Date" و"Transaction Date" و"Booking Date" كلها تُعيّن إلى حقل date. "Amount" و"Value" و"Sum" تُعيّن إلى amount. أعمدة الائتمان/الخصم المنفصلة (مثل "Credit" و"Debit") تُكتشف وتُدمج في مبلغ واحد موقّع تلقائيًا.

ما تنسيق الإخراج؟

جميع المحللات تنتج DataFrames موحدة من pandas بأنواع أعمدة متسقة:

التنسيق	الأعمدة الرئيسية
CAMT	Amount, Currency, DrCr, Debtor, Creditor, Reference, ValDt, BookgDt, AccountId
PAIN.001	PmtInfId, PmtMtd, InstdAmt, Currency, CdtrNm, EndToEndId, MsgId, CreDtTm, NbOfTxs
CSV/OFX/QFX/MT940	date, description, amount (موحد)

يمكنك أيضًا التصدير إلى CSV أو JSON أو Excel أو DataFrames من Polars أو تنسيق يوميات hledger أو beancount.

ميزات PDF وLLM

ما نماذج LLM التي يدعمها خط الأنابيب الهجين؟

يستخدم خط الأنابيب LiteLLM كطبقة تجريد النماذج، مع جسر Ollama مباشر لطلبات الرؤية. النماذج الموصى بها:

• استخراج النص: أي نموذج متوافق مع LiteLLM (محلي أو بعيد).
• استخراج الرؤية: ollama/minicpm-v (موصى به) لملفات PDF الممسوح�� ضوئيًا.
• التصنيف: أي نموذج متوافق مع LiteLLM.

جميع النماذج تعمل 100% محليًا عبر Ollama — لا حاجة لمفاتيح API.

ما التحقق بالقاعدة الذهبية؟

كل استخراج PDF يُتحقق منه بالمعادلة: opening balance + credits − debits == closing balance. النتائج تُصنّف كـ:

• VERIFIED: الأرصدة تتطابق تمامًا.
• DISCREPANCY: الأرصدة لا تتطابق — يُوصى بالمراجعة.
• FAILED: لم يتم التحقق (بيانات رصيد مفقودة).

هل يمكنني تصنيف المعاملات تل��ائيًا؟

نعم. وحدة الإثراء (v0.0.6+) توفر ت��نيف معاملات مدعوم بـ LLM:

from bankstatementparser.enrichment import Categorizer

categorizer = Categorizer()
enriched = categorizer.categorize_batch(transactions)

المخطط الافتراضي يستخدم 13 فئة متوافقة مع Plaid. يمكنك تقديم مخطط فئات خاص بك.

هل يمكنني التصدير إلى hledger أو beancount؟

نعم (v0.0.8+). صدّر المعاملات إ��ى تنسيقات يوميات المحاسبة النصية مع تعيين الحسابات:

from bankstatementparser.export import to_hledger, to_beancount

journal = to_hledger(transactions, account="Assets:Bank:Checking")

سير عمل الخزانة

كيف يتعامل المحلل ��ع كشوفات متعددة العملات؟

كل معاملة تحتفظ بعملتها الأصلية — لا تحويل ضمني. حقل Currency يُستخرج من سمة XML Ccy لكل ��عاملة. الكشوفات متعددة العملات تبقى كما هي. دالة get_account_balances() تُعيد الأرصدة الافتتاحية والختامية لكل حساب برموز العملة الأصلية.

منذ v0.0.8، verify_balance_multi_currency() يجمّع المعاملات حسب العملة ويُشغّل القاعدة الذهب��ة بشكل مستقل لكل مجموعة — مفيد للحسابات التي تحتفظ بعملات متعدد��.

هل يدعم المحلل التنسيقات الصادرة والواردة؟

نعم. Pain001Parser يتعامل مع ملفات بدء التحويل الائتماني ISO 20022 PAIN.001 (المدفوعات الصادرة). CamtParser يتعامل مع ملفات كشف الحساب من البنك إلى العميل CAMT.053 (التقارير الواردة). كلاهما يدعم البث وتنقيح PII والتصدير إلى CSV وJSON وExcel وhledger وbeancount. استخدم detect_statement_format() لتحديد التنسيق تلقائيًا.

ماذا يحدث عندما يكون إدخال معاملة مشوّهًا؟

السلوك يعتمد على وضع التحليل:

• parse() (الوضع الدفعي) — المدخلات المشوّهة التي تفتقد حقولًا مطلوبة (Amount أو Currency أو CdtDbtInd) تُتخطى مع تحذير في السجل. باقي الكشف يُحلل بشكل طبيعي.
• parse_streaming() (وضع البث) — أخطاء التحليل تنتشر فورًا كاستثناءات. لا فقدان صامت للبيانات. هذا السلوك الفاشل-بسرعة مقصود لسير العمل المالي حيث كل معاملة يجب أن تُحسب.
• smart_ingest() (PDF هجين) — أخطاء الاستخراج تُلتقط في IngestResult مع حالة التحقق، مما يتيح المراجعة التفاعلية.

كيف تعمل إزالة التكرار؟

كل معاملة تُعيّن لها transaction_hash حتمي (بصمة MD5) بناءً على حقولها الرئيسية. هذا يُمكّن الاستيعاب التدريجي الآمن — إعادة معالجة نفس الملف تنتج نفس الـ hash، فتُكتشف المكررات تلقائيًا.

from bankstatementparser import CamtParser, Deduplicator

parser = CamtParser("statement.xml")
dedup = Deduplicator()
result = dedup.deduplicate(dedup.from_dataframe(parser.parse()))

print(f"Unique: {len(result.unique_transactions)}")
print(f"Exact duplicates: {len(result.exact_duplicates)}")
print(f"Suspected matches: {len(result.suspected_matches)}")

التثبيت والتوافق

كيف أثبت Bank Statement Parser؟

# Core install (deterministic parsers only)
pip install bankstatementparser

# PDF hybrid pipeline
pip install 'bankstatementparser[hybrid]'         # Text-LLM path
pip install 'bankstatementparser[hybrid-vision]'   # Vision-LLM path

# Extras
pip install 'bankstatementparser[enrichment]'      # Transaction categorisation
pip install 'bankstatementparser[api]'             # REST API microservice
pip install 'bankstatementparser[polars]'          # Polars DataFrame support

ما إصدارات Python المدعومة؟

Python 3.10 إلى 3.14. أُسقط دعم Python 3.9 في v0.0.6 (نهاية العمر 2025-10-31). جميع الإصدارات تُختبر في CI بـ 718 اختبارًا بتغطية فرعية 100%.

ما التبعيات؟

المكتبة الأساسية لها 5 ��بعيات مباشرة:

• lxml — تحليل XML مع تقوية أمنية
• pandas — DataFrames ومعالجة البيانات
• openpyxl — تصدير Excel
• pydantic — التحقق من البيانات والنماذج
• defusedxml — حماية XXE

الإضافات الاختيارية تضيف: litellm، pypdf، pdfplumber، pypdfium2، fastapi، uvicorn، polars.

جمي�� التبعيات بإصدارات مقفلة بـ SHA-256 hash. CycloneDX SBOM يُعيّن كل مكون تشغيل.

هل يعمل على macOS وLinux وWindows؟

نعم. المكتبة تعمل على macOS وLinux وWindows (عبر WSL). ليس لها تبعيات خاصة بالمنصة.

هل يوجد REST API؟

نعم (v0.0.8+). ثبّت بـ pip install 'bankstatementparser[api]' وشغّل:

bankstatementparser-api --port 8000

نقاط النهاية: POST /ingest (تحليل كشف) وGET /health (فحص الحالة).

إعادة الإنتاج والأمان

كيف يمكنني التحقق من إع��دة الإنتاج؟

python -m pytest                              # 718 tests, 100% branch coverage
python scripts/verify_locked_hashes.py        # SHA-256 hash verification
git log --show-signature -1                   # Verify commit signature

ما الحمايات الأمنية المدمجة؟

• حماية XXE: resolve_entities=False، no_network=True، load_dtd=False
• حماية ZIP Bomb: حدود نسبة الضغط، سقوف حجم الإدخال، رفض المدخلات المشفرة
• منع اجتياز المسار: قائمة حظر أنماط خطرة وحل الروابط الرمزية
• التحقق من المدخلات: حدود حجم الملف (100 ميغابايت افتراضيًا)، تحقق الامتداد/التنسيق
• سلسلة التوريد: تبعيات مقفلة بـ SHA-256 hash، CycloneDX SBOM، شهادة مصدر البناء
• Commits موقعة: مفروضة في CI
• نماذج LLM محلية: خط أنابيب PDF الهجين يستخدم Ollama — بدون استدعاءات API سحابية

كيف يقارن Bank Statement Parser بـ pyiso20022؟

pyiso20022 مجموعة أدوات ISO 20022 واسعة تُنشئ فئات بيانات Python من مخططات ISO XML. تغطي نطاقًا واسعًا من أنواع رسائل ISO 20022 (PACS، PAIN، CAMT، ADMI) مع التحقق من المخطط. Bank Statement Parser مصمم خصيصًا لتحليل كشوفات الحساب مع دعم PDF هجين والتحقق من الرصيد والإثراء وتصدير دفتر الأستاذ وواجهة موحدة عبر سبعة تنسيقات بما في ذلك تنسيقات غير ISO (CSV وOFX وQFX وMT940 وPDF). إذا كنت بحاجة لتحليل كشوفات الحساب إلى DataFrames بأمان إنتاجي، استخدم Bank Statement Parser. إذا كنت بحاجة للتعامل مع كتالوج رسائل ISO 20022 الكامل، استخدم pyiso20022.

ما المواعيد النهائية لترحيل SWIFT ISO 20022؟

نشرت SWIFT جدولًا زمنيًا مرحليًا للترحيل:

• نوفم��ر 2026: تصبح العناوين المنظمة والهجينة إلزامية. ستُرفض رسائل التعليمات المتعددة MT101. تبدأ المرحلة الأولى لإدارة الحالات.
• نوفمبر 2027: يجب أن تستطيع جميع المؤسسات المالية استقبال كشوفات CAMT.053 أصلاً. ستتوقف SWIFT عن تحويل MT إلى تنسيق ISO.
• نوفمبر 2028: إيقاف كامل لـ MT940 وMT942 وMT950 وMT900 وMT910. ستُستبدل بمكافئات CAMT.052 وCAMT.053 وCAMT.054.

يدعم Bank Statement Parser كلاً من تنسيق MT940 القديم وتنسيقات CAMT.053/PAIN.001 الحديثة، مما يجعله مثاليًا للفترة الانتقالية.