وثائق تطبيق OpenPGP GUI

مرحبًا بكم في الوثائق الرسمية لتطبيق OpenPGP GUI.

نظرة عامة

يوفر هذا التطبيق واجهة مستخدم عصرية وسهلة الاستخدام لإدارة مفاتيح OpenPGP، والتشفير، وفك التشفير، وتوقيع الرسائل، والتحقق منها، وإنشاء شهادات SSL. تتم جميع العمليات التشفيرية محليًا لضمان أقصى درجات الخصوصية.

الميزات

• واجهة مستخدم عصرية باستخدام ttkbootstrap (سمة Superhero)
• إنشاء وتحميل وتصدير أزواج مفاتيح OpenPGP
• تعيين اسم المفتاح والبريد الإلكتروني وكلمة المرور وعرض بصمة المفتاح
• تشفير وفك تشفير الرسائل
• توقيع الرسائل والتحقق منها (توقيعات منفصلة)
• تصدير المفتاح العام بتنسيق ASCII-armor (.asc)
• تصور بصمة المفتاح للتحقق الأمني
• إنشاء شهادات SSL مع اسم مخصص (CN)
• مسح/إعادة تعيين جميع الحقول بنقرة واحدة
• نظام تسجيل مركزي (معلومات، تحذيرات، أخطاء، استثناءات غير معالجة)
• عارض السجلات مع تصفية في الوقت الفعلي (الكل، معلومات، تحذير، خطأ)
• استخدام log_info، log_warning، log_error لمدخلات السجل المخصصة
• التقاط تتبع المكالمات وعرضه تلقائيًا في عارض السجلات
• شريط قوائم ديناميكي مع نوافذ حوار “حول”، “مساعدة”، “عرض السجلات”، “رعاة”، “الإصدار”
• تنظيم الإصدارات الدلالية ومعلومات الإصدار
• هيكل نمطي (struttura، gui، إلخ)
• قابلية التوسع والسمات بسهولة (عبر ttkbootstrap)

البدء

المتطلبات

• Python 3.9 أو أحدث
• PySide6 (مضمن في المتطلبات)
• pgpy (مضمن في المتطلبات)
• cryptography (مضمن في المتطلبات)
• pyperclip (مضمن في المتطلبات)

ملاحظة: تم نقل التطبيق من Tkinter/ttkbootstrap إلى PySide6 للحصول على واجهة مستخدم أكثر حداثة وسهولة في الصيانة.

التثبيت

1. استنسخ أو نزّل هذا المستودع.
2. (اختياري) أنشئ بيئة افتراضية:

   python -m venv venv
   venv\Scripts\activate
   

3. قم بتثبيت التبعيات:

   pip install -r requirements.txt
   

تشغيل التطبيق

شغّل من المجلد الجذاري للمشروع:

python main.py

إذا واجهتك أخطاء في الاستيراد، فتأكد من أنك تشغل من المجلد الجذاري وليس من مجلد فرعي.

دليل المستخدم

نظرة عامة على النافذة الرئيسية

• أدخل اسمك وبريدك الإلكتروني وكلمة المرور لإنشاء مفتاح.
• اختر الخوارزمية (حاليًا RSA؛ المزيد قريبًا).
• استخدم الأزرار لإنشاء أو تحميل أو تصدير المفاتيح.
• تظهر بصمة المفتاح المحمل/المنشأ للتحقق.
• استخدم مساحة النص لإدخال الرسائل للتشفير أو فك التشفير أو التوقيع أو التحقق.
• قم بتصدير مفتاحك العام للمشاركة بأمان.
• أنشئ شهادات SSL مباشرة من الواجهة.
• استخدم زر ‘مسح’ لإعادة تعيين جميع الحقول.

شريط القوائم

• ملف: تصدير المفتاح العام، خروج
• السجل: عرض السجلات (مع مرشحات: الكل، معلومات، تحذير، خطأ)
• مساعدة: مساعدة، حول، رعاة

نظام التسجيل وعرض السجلات

• يتم تسجيل جميع الإجراءات والتحذيرات والأخطاء والاستثناءات غير المعالجة تلقائيًا.
• استخدم log_info(msg)، log_warning(msg)، log_error(msg) في نصوصك البرمجية لتسجيل مدخلات مخصصة.
• يتيح لك عارض السجلات (سجل > عرض السجل) تصفية وعرض السجلات حسب المستوى.
• إذا كان ملف السجل مفقودًا، فسيتم عرض آخر تتبع مكالمات إذا كان متاحًا.

نصائح

• جميع العمليات التشفيرية تتم محليًا (بدون سحابة).
• لتحقيق أقصى درجات الأمان، استخدم كلمات مرور قوية.
• توفر نافذة السجل ملاحظات وتفاصيل الأخطاء.

استخدام متقدم

تصدير المفاتيح العامة

• استخدم زر ‘تصدير المفتاح العام’ أو عنصر القائمة لحفظ مفتاحك العام بتنسيق ASCII-armor (.asc).

التحقق من البصمة

• تحقق دائمًا من بصمة المفتاح قبل مشاركة مفتاحك العام لزيادة الأمان.

إنشاء شهادات SSL

• أدخل الاسم الشائع المطلوب (CN) في حقل الاسم.
• انقر فوق زر ‘إنشاء شهادة SSL’ لإنشاء شهادة موقعة ذاتيًا.

تمديد التطبيق

• يمكنك إضافة دعم للمزيد من الخوارزميات (مثل ECC، Ed25519) من خلال توسيع منطق إنشاء المفاتيح في main_window.py.
• تستخدم واجهة المستخدم ttkbootstrap لسهولة تخصيص السمات.

التسجيل والتصحيح

• يتم حفظ جميع الإجراءات والتحذيرات والأخطاء والاستثناءات غير المعالجة في traceback.log.
• استخدم log_info، log_warning، log_error لمدخلات السجل المخصصة في الكود الخاص بك.
• يدعم عارض السجلات التصفية حسب: الكل، معلومات، تحذير، خطأ.
• يتم تسجيل الاستثناءات غير المعالجة وعرضها تلقائيًا في عارض السجلات (مع تتبع المكالمات).

استكشاف الأخطاء وإصلاحها

• إذا واجهت أخطاء في الاستيراد، فتأكد من أنك تشغل من المجلد الجذاري للمشروع.
• في حالة وجود مشاكل في التبعيات، تحقق من requirements.txt أو أعد تثبيت الحزم المطلوبة.

دليل المطور

مرحبًا بك أيها المطور! يوفر هذا الدليل الأساسيات للمساهمة في تطوير وتوسيع تطبيق OpenPGP GUI.

هيكل المشروع

• main.py — نقطة الدخول، تشغيل النافذة الرئيسية.
• gui/ — جميع مكونات واجهة المستخدم (النافذة الرئيسية، الأدوات، النوافذ المنبثقة).
• struttura/ — المنطق الأساسي، النوافذ المنبثقة، الأدوات المساعدة، إدارة الإصدارات، المساعدة/حول، إلخ.
• docs/ — الوثائق.
• requirements.txt — تبعيات Python.

التقنيات الرئيسية

• Python 3.x
• Tkinter — إطار عمل واجهة المستخدم (مع ttkbootstrap للسمات)
• pgpy — تشفير OpenPGP
• cryptography — إنشاء شهادات SSL
• Pillow — (اختياري) للأيقونات

كيفية المساهمة

1. انسخ المستودع وقم بعمل Fork.
2. أنشئ بيئة افتراضية وقم بتثبيت التبعيات.
3. اتبع معايير PEP8 وحافظ على نمطية الكود.
4. قم بتوثيق الميزات الجديدة وتحديث CHANGELOG.md.
5. أضف الاختبارات أو قم بتحديثها إن أمكن.
6. افتح طلب سحب مع وصف واضح.

إضافة ميزات

• لإضافة خوارزميات جديدة (مثل ECC، Ed25519)، قم بتوسيع منطق إنشاء المفاتيح في main_window.py.
• لمكونات واجهة المستخدم الجديدة، أضف الأدوات في gui/ وافصل المنطق عن واجهة المستخدم.
• استخدم أنماط ttkbootstrap لمظهر متناسق.

الاختبار

• أضف اختبارات للميزات الجديدة وإصلاحات الأخطاء.
• الاختبار اليدوي: شغل python main.py واختبر جميع وظائف واجهة المستخدم.
• (اختياري) دمج مع CI/CD للاختبار الآلي.

أسلوب الكود

• اتبع معايير PEP8.
• استخدم توثيق السلسلة النصية للوظائف/الفئات العامة.
• افصل واجهة المستخدم عن المنطق قدر الإمكان.

التسجيل والتصحيح

• استخدم log_info(msg)، log_warning(msg)، log_error(msg) في أي مكان في الكود لإنشاء سجلات مخصصة.
• يتم حفظ جميع السجلات في traceback.log وعرضها في عارض السجلات.
• يدعم عارض السجلات التصفية حسب: الكل، معلومات، تحذير، خطأ.
• يتم تسجيل الاستثناءات غير المعالجة وعرضها تلقائيًا في عارض السجلات (مع تتبع المكالمات).

الدعم والأسئلة

• افتح قضايا على GitHub للإبلاغ عن الأخطاء أو طلب ميزات جديدة.
• انظر README.md لمعلومات الاتصال والمساهمة.

مواضيع متقدمة

مرجع API

يتميز التطبيق بهيكل نمطي: المنطق الأساسي في struttura/، وواجهة المستخدم في gui/.

الفئات والوظائف الرئيسية:

• MainWindow (gui/main_window.py): منطق واجهة المستخدم الرئيسية ومعالجة الأحداث.
• gen_key، export_pubkey، clear_fields، إلخ: طرق للعمليات التشفيرية.
• Help، About، LogViewer، إلخ: نوافذ منبثقة وأدوات في struttura/.
• get_version() (struttura/version.py): إرجاع سلسلة الإصدار الحالي.

لمزيد من المعلومات، اقرأ توثيق السلسلة النصية في الكود وانظر docs/user_guide.md لتدفق الاستخدام.

أمثلة التمديد

إضافة خوارزمية مفاتيح جديدة

1. في gui/main_window.py، حدد القائمة المنسدلة لاختيار الخوارزمية.
2. أضف خوارزميتك الجديدة (مثل ECC، Ed25519) إلى قائمة الخيارات.
3. في منطق إنشاء المفاتيح، قم بتنفيذ معالجة الخوارزمية الجديدة باستخدام pgpy.
4. اختبر بدقة وقم بتحديث الوثائق.

إضافة أداة مخصصة

1. أنشئ أداتك في gui/widgets.py أو ملف جديد.