كانت مساهمتي في مشروع Mushaf Al-Imad تجربة عملية مميزة؛ لم تقتصر على كتابة أسطر برمجية، بل مرّت بمراحل متكاملة: فهم بنية المشروع، التواصل مع المشرفين، تصميم حل قابل للتوسعة، الاختبار، مراجعة الكود، ثم تحسين الحل بناءً على ملاحظات المجتمع.
في هذا المقال أشارك أهم ما تعلمته، مع تركيز على الجانب التقني: كيف يمكن للذكاء الاصطناعي أن يُساعد المطور في المساهمة بفعالية، دون أن يحل محل الفهم العميق والمراجعة البشرية.
ما التحدي؟
كان الهدف تحسين طريقة تعامل التطبيق مع صور المصحف، بحيث لا يبقى مرتبطًا بنسخة واحدة من الأصول (Assets)، وإنما يصبح قادرًا على دعم أكثر من مصحف بطريقة منظمة وقابلة للتوسعة.
التحدي لم يكن مجرد إضافة مجموعة جديدة من الصور، بل تصميم بنية تسمح للتطبيق بالتعامل مع أكثر من Mushaf configuration دون إضافة شروط خاصة داخل واجهة المستخدم لكل مصحف جديد.
وهكذا تحولت الفكرة من سؤال تشغيلي:
كيف أضيف صور مصحف جديد؟
إلى سؤال معماري أعمق:
كيف نجعل إضافة مصاحف أخرى مستقبلًا أسهل دون إعادة تصميم التطبيق في كل مرة؟
فصل التطبيق عن مصدر الصور
أحد أهم المبادئ التي عملنا عليها هو فصل واجهة التطبيق عن المكان الفعلي الذي تأتي منه صور المصحف. بدل أن تعرف الواجهة تفاصيل كل مصحف، اعتمدنا على مفهوم يشبه نمط Registry:
MushafConfigRegistry
يتم فيه تسجيل إعدادات كل مصحف ومصدر الـ assets الخاص به، ثم يطلب التطبيق الإعداد المناسب من الـ Registry في وقت التشغيل.
بهذا التصميم، يمكن أن تأتي الصور من عدة مصادر:
- Assets مدمجة داخل التطبيق؛
- ملفات محلية قام المستخدم بتنزيلها واستخراجها يدويًا؛
- مزود Assets خارجي يمكن إضافته مستقبلًا.
هذا النهج يحقق عدة مزايا تقنية:
- تقليل الت coupling بين واجهة المستخدم ومنطق المصحف؛
- إمكانية إضافة مصحف جديد بتسجيل إعداداته فقط؛
- توحيد واجهة برمجية (API) واضحة لجميع المصاحف.
لماذا كان التنزيل اليدوي مهمًا؟
من النقاط المهمة التي ظهرت أثناء النقاش مع مشرف المشروع أن إدارة ملفات المصاحف نفسها ما زالت قابلة للتطوير. هناك فكرة مستقبلية لإنشاء package manager للأصول، لكنها ما زالت في مرحلة مبكرة.
لذلك كان من المهم أن يبقى التصميم الحالي قادرًا على دعم سيناريو عملي:
المستخدم ينزّل ملفات المصحف بنفسه، يفك ضغطها، ثم يسجل مسارها داخل التطبيق.
هذا الحل مناسب للمرحلة الحالية لأنه:
- لا يربط التطبيق بخدمة تنزيل محددة؛
- يبقي الباب مفتوحًا أمام package manager أكثر تطورًا في المستقبل؛
- يمنح المستخدم مرونة في إدارة الملفات بنفسه.
التحدي الأكبر: تجهيز الصور
إضافة الـ API وحدها لم تكن كافية. كان علينا أيضًا التأكد من إمكانية تجهيز ملفات المصحف بالشكل الذي يتوقعه التطبيق.
العقد الذي اعتمدناه للصور كان:
<root>/<page>/<line>.png
أي أن لكل صفحة مجلدًا خاصًا، وداخله توجد صور الأسطر.
بالنسبة للنسخة التي عملت عليها، وصلنا في عملية التوليد والتحقق إلى:
- 604 صفحات
- 9,060 صورة PNG للأسطر
- أي 15 سطرًا لكل صفحة
وهنا اكتشفت عمليًا أن معالجة صور المصحف أصعب بكثير من مجرد تقسيم صورة إلى أجزاء متساوية.
ليست كل الصفحات متشابهة
بعض الصفحات تحتوي على عناصر خاصة، مثل:
- بدايات السور؛
- عناوين السور؛
- الزخارف والعلامات التقليدية.
لذلك كان من الضروري اختبار صفحات مختلفة من المصحف، وليس فقط التأكد من أن السكربت أنتج العدد الصحيح من الملفات.
قمنا بالتحقق من عينات من:
- بداية المصحف؛
- وسط المصحف؛
- نهاية المصحف؛
- صفحات ذات تخطيط خاص.
كما ظهرت أثناء الاختبارات مشاكل في حدود بعض عمليات القص (cropping)، فتم تعديل المنطق وإعادة توليد الملفات والتحقق منها مرة أخرى.
هذه المرحلة أكدت لي قاعدة أساسية في هندسة البرمجيات:
نجاح السكربت لا يعني بالضرورة صحة النتيجة.
قد تحصل على 9,060 ملفًا دون أخطاء، لكن هذا لا يثبت وحده أن محتوى الصور صحيح.
التحقق قبل اعتبار العمل منتهيًا
بعد عملية التوليد، لم أعتمد على عدد الملفات فقط. تم إجراء عدة مستويات من التحقق:
- التأكد من وجود جميع الصفحات الـ 604؛
- التأكد من وجود 9,060 صورة؛
- التحقق من أسماء ومسارات الملفات؛
- التأكد من إمكانية قراءة ملفات PNG؛
- فحص عينات من الصفحات المختلفة؛
- التحقق من سلامة الـ bundle؛
- استخدام checksums للتحقق من سلامة الملفات.
وفي النهاية وصلنا إلى bundle كامل اجتاز عملية التحقق دون أخطاء في الاختبارات المنفذة.
مراجعة الكود أهم من كتابة الكود
من أكثر الجوانب استفادة في هذه التجربة التعامل مع مراجعات المشرفين. في المشاريع مفتوحة المصدر، لا يكفي أن تقول: «الحل يعمل عندي».
المشرف ينظر إلى أسئلة أوسع:
- هل الحل متوافق مع Architecture المشروع؟
- هل سيؤثر على المستخدمين الحاليين؟
- هل يمكن إضافة مصحف ثالث ورابع بالطريقة نفسها؟
- هل الـ API واضحة لمطور آخر لم يشارك في كتابة الكود؟
- هل توجد Documentation كافية لاستخدامها؟
إحدى الملاحظات المهمة كانت ضرورة توثيق كيفية استخدام الـ API الجديدة إذا أراد مطور إضافة مصحف آخر.
قمت لذلك بإضافة توثيق إلى README يشرح:
- طريقة تسجيل
MushafAssetProvider؛
- اختيار إعدادات المصحف؛
- استخدام الملفات المحلية.
كانت هذه الملاحظة مهمة لأنها ذكرتني بأن الـ API غير الموثقة ليست API مكتملة بالنسبة للمستخدمين الآخرين.
أين ساعدني الذكاء الاصطناعي؟
استخدمت أدوات AI coding agents خلال أجزاء من العمل للمساعدة في:
- تحليل المشروع؛
- مراجعة التغييرات؛
- البحث عن حالات edge cases؛
- كتابة وتشغيل الاختبارات؛
- تحليل ملاحظات code review؛
- التحقق من ملفات الصور؛
- مراجعة جودة الحل قبل تقديمه.
لكن أهم درس بالنسبة لي هو أن استخدام Agent لا يعني إعطاءه المشروع وانتظار النتيجة. كنت أراجع ما يقوم به، وأطلب منه إثبات النتائج بالاختبارات، وأتجنب الـ commits أو التغييرات الكبيرة قبل التأكد من توافقها مع متطلبات المشروع وملاحظات المشرفين.
الذكاء الاصطناعي هنا كان أداة هندسية مساعدة، وليس صاحب القرار النهائي.
ماذا تعلمت من هذه المساهمة؟
خرجت من التجربة بعدة دروس أعتبرها أهم من الكود نفسه:
- افهم Architecture المشروع قبل أن تبدأ في البرمجة.
- لا تفترض أن الحل المطلوب هو الحل الذي تخيلته أول مرة.
- تواصل مع الـ maintainers قبل اتخاذ قرارات معمارية كبيرة.
- اجعل التغييرات قابلة للتوسعة بدل معالجة حالة واحدة فقط.
- اختبر البيانات الناتجة نفسها، وليس الكود فقط.
- تعامل مع Code Review كجزء من عملية التطوير، وليس كمرحلة لإثبات أن كودك صحيح.
- وثّق الـ APIs التي تتوقع أن يستخدمها مطورون آخرون.
- استخدم AI agents للتحليل والتحقق، لكن احتفظ بالقرار والمراجعة النهائية للإنسان.
الخاتمة
كانت تجربتي مع Mushaf Al-Imad مثالًا عمليًا على أن المساهمة في Open Source تتجاوز كثيرًا فكرة إرسال Pull Request.
هي عملية تبدأ بفهم المشكلة، ثم الحوار مع المجتمع، وتصميم الحل، والاختبار، وتلقي الملاحظات، وإعادة التحسين.
والأجمل أن المشروع يتعلق بأداة تخدم القرآن الكريم، مما يجعل الاهتمام بالدقة، والاستدامة، وجودة التنفيذ أكثر أهمية.
ما زالت هناك أفكار يمكن تطويرها مستقبلًا، خصوصًا فيما يتعلق بإدارة وتنزيل أصول المصاحف، وربما الوصول إلى نظام package management يجعل إضافة مصاحف جديدة أكثر سهولة.
بالنسبة لي، هذه التجربة لم تكن نهاية مساهمة، بل خطوة جديدة في تعلم كيفية بناء برمجيات مفتوحة المصدر قابلة للصيانة والتوسع، بالتعاون مع المجتمع.
🔗 المساهمة على GitHub
لمن يرغب في الاطلاع على الجانب التقني ومراجعة التغييرات والنقاشات مع مشرفي المشروع، يمكن متابعة المساهمة عبر GitHub:
https://github.com/Itqan-community/mushaf-imad-flutter/pull/85
