الأسئلة الشائعة

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

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

لا. يعمل محلل كشوف الحسابات البنكية كمكتبة عديمة الحالة. تتم جميع العمليات -- التحليل وإخفاء PII واستخراج الأرشيفات -- داخل ذاكرة التشغيل المحلية. لا استدعاءات API، ولا خدمات سحابية، ولا قياس عن بُعد. محللات XML محصّنة بإعداد no_network=True الذي يحظر جميع الاتصالات الصادرة على مستوى المحلل. بياناتك المالية لا تغادر بيئتك أبداً.

كيف يعمل إخفاء PII؟

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

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

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

نعم -- مخرجات متطابقة بايت بايت في كل تشغيل. بالنظر إلى نفس ملف الإدخال، ينتج المحلل نفس النتيجة في كل مرة. لا عشوائية، ولا استدلال نموذجي، ولا أخذ عينات استكشافي. يفرض نظام CI الحتمية عبر 467 اختباراً بتغطية فرعية 100%، بما في ذلك اختبار الضبابية القائم على الخصائص عبر Hypothesis.

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

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

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

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

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

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

تُتحقق عتبات الأداء في نظام CI مع كل عملية إيداع:

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

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

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

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

تتحقق iter_secure_xml_entries() من كل عنصر قبل الاستخراج:

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

لا يُكتَب أي ملف على القرص. تمر بايتات 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")

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

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

التنسيق	المعيار	أنواع الملفات	فئة المحلل
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

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

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

للبنوك التي تغلّف 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.

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

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

تحتفظ كل معاملة بعملتها الأصلية -- بدون تحويل ضمني. يُستخرَج حقل Currency من سمة Ccy في XML لكل معاملة. تبقى كشوف الحسابات متعددة العملات كما هي. تعيد طريقة get_account_balances() أرصدة الافتتاح والإغلاق لكل حساب مع رموز العملة الأصلية. تُترَك التسوية عبر العملات لمنطقك اللاحق، حيث تتحكم أنت في مصدر سعر الصرف.

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

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

ماذا يحدث عندما يكون سجل معاملة تالفاً؟

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

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

كيف يعمل كشف التكرارات؟

تكتشف فئة Deduplicator التكرارات المطابقة تماماً والمطابقات المشتبه بها مع درجات ثقة قابلة للتفسير:

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)}")

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

كيف أثبّت محلل كشوف الحسابات البنكية؟

pip install bankstatementparser

لدعم DataFrame الاختياري في Polars:

pip install bankstatementparser[polars]

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

Python 3.9 إلى 3.14. تُختبَر جميع الإصدارات في نظام CI عبر 467 اختباراً بتغطية فرعية 100%.

ما التبعيات؟

تحتوي المكتبة على 5 تبعيات مباشرة:

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

جميع التبعيات مقفلة بتجزئات SHA-256. يربط SBOM بتنسيق CycloneDX كل مكون تشغيلي.

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

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

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

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

python -m pytest                              # 467 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: حدود نسبة الضغط، حدود حجم العناصر، رفض العناصر المشفرة
• منع اجتياز المسارات: قائمة حظر للأنماط الخطيرة وحل الروابط الرمزية
• التحقق من المدخلات: حدود حجم الملف (افتراضي 100 ميغابايت)، التحقق من الامتداد/التنسيق
• سلسلة التوريد: تبعيات مقفلة بتجزئات SHA-256، SBOM بتنسيق CycloneDX، شهادة مصدر البناء
• التوقيع على الإيداعات: مفروض في نظام CI

كيف يُقارَن محلل كشوف الحسابات البنكية بـ pyiso20022؟

pyiso20022 هو أداة ISO 20022 شاملة تولّد فئات بيانات Python من مخططات ISO XML. يغطي نطاقاً واسعاً من أنواع رسائل ISO 20022 (PACS وPAIN وCAMT وADMI) مع التحقق من المخططات. محلل كشوف الحسابات البنكية مصمم خصيصاً لتحليل كشوف الحسابات البنكية مع دعم البث المباشر وإخفاء PII وكشف التكرارات وAPI موحّد عبر ستة تنسيقات بما فيها التنسيقات غير ISO (مثل CSV وOFX وQFX وMT940). إذا كنت تحتاج إلى تحليل كشوف الحسابات البنكية إلى DataFrames بأمان إنتاجي، استخدم محلل كشوف الحسابات البنكية. وإذا كنت تحتاج إلى التعامل مع كتالوج رسائل 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.

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