الجامع

مكتبة المكتبات الإسلامية

🚀 تجهيز بيئة التطوير

المتطلبات الأساسية

1. ثبّت Docker حسب نظام تشغيلك من خلال هذا الرابط
2. ثبّت Mise حسب نظام تشغيلك من خلال هذا الرابط
3. ثبّت مكتبة gpg حسب نظام تشغيلك. على سبيل المثال، نفّذ هذا الأمر إذا كنت تستخدم نظام macOS:

brew install gnupg

4. ثبّت مكتبة libpq حسب نظام تشغيلك. على سبيل المثال، نفّذ هذا الأمر إذا كنت تستخدم نظام macOS:

brew install libpq

5. أضِف مكتبة libpq إلى متغير PATH حسب نظام تشغيلك باتباع التعليمات الموضّحة بعد تثبيت المكتبة. على سبيل المثال، نفّذ هذا الأمر إذا كنت تستخدم نظام macOS مع Zsh:

echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> /Users/{user}/.zshrc

إعداد المشروع

1. نفّذ الأمر التالي لنسخ مستودع المشروع إلى حاسبك:

git clone git@github.com:ieasybooks/aljam3-web-app.git

2. افتح سطر الأوامر داخل مجلد المشروع ونفّذ الأمر التالي لتثبيت الأدوات المطلوبة للتطوير من خلال Mise:

mise install

3. نفّذ الأمر التالي لتثبيت اعتماديات المشروع وتشغيل خادم التطوير المحلّي:

mise dev

4. افتح الرابط http://localhost:3000 في متصفحك للوصول إلى الصفحة الرئيسية للمشروع

الأدوات المُثبتة

ستحصل على الأدوات التالية باتباعك للخطوات المذكورة أعلاه:

• Docker
• Mise
• gnupg
• libpq
• Ruby (3.4.4)
• Rails (8.0.2)
• Node.js (24.1.0)
• Yarn (4.9.1)
• PostgreSQL (17.5)
• Meilisearch (1.15.1)

المنافذ والخدمات

يمكنك الوصول إلى الخدمات من خلال المنافذ التالية:

• PostgreSQL → 5433 (localhost:5433)
• Meilisearch → 7701 (localhost:7701)

وبمجرّد إيقاف تشغيل خادم التطوير المحلّي من خلال الضغط على Cmd+C أو Ctrl+C، ستتوقف خدمات Docker (PostgreSQL و Meilisearch) عن العمل تلقائيًا.

⚙️ تجهيز المحرر

أُعِدّ هذا المشروع ليعمل مع محرر VSCode أو ما يشبهه من المحررات مثل Cursor و Windsurf وغيرهما. بمجرّد فتح المشروع في أحد هذه المحررات سيظهر لك إشعار يسألك "هل تريد تثبيت الإضافات المُوصى بها؟"، وإذا ضغطت على زر Install ستبدأ عملية تثبيت الإضافات الموجودة في ملف .vscode/extensions.json.

الإضافات المُوصى بها:

• Ruby LSP
• Rails DB Schema
• Rails I18n
• Tailwind CSS IntelliSense
• vscode-gemfile
• GitLens — Git supercharged
• Mise VSCode
• Stimulus LSP
• Live Preview
• SQLTools
• SQLTools PostgreSQL/Cockroach Driver
• vscode-icons
• Git Blame

كما أن إعدادات جميع هذه الإضافات موجودة مسبقًا في ملف .vscode/settings.json، لذا لا داعي لإعدادها يدويًّا.

💎 المكتبات المستخدمة للغة Ruby

ملاحظة: جميع المكتبات يجب أن تكون مُحددة بإصدار مُعيّن لضمان الاستقرار والتوافق.

المصادقة والأمان

• devise
• devise-i18n
• omniauth
• omniauth-google-oauth2
• omniauth-rails_csrf_protection
• rack-attack
• rails_cloudflare_turnstile

البحث والأداء والتحسين

• goldiloader
• meilisearch-rails
• oj
• pagy
• sitemap_generator

واجهة المستخدم

• lookbook
• phlex-icons
• phlex-rails
• rails-i18n
• ruby_ui
• tailwind_merge

التطوير والاختبار

• active_record_doctor
• addressable
• annotaterb
• better_errors
• binding_of_caller
• cache_with_locale
• factory_bot_rails
• faker
• hotwire-spark
• i18n-tasks
• literal
• net-ssh
• rspec-rails
• rubocop-rake
• rubocop-rspec
• rubocop-rspec_rails
• shoulda-matchers
• simplecov-json
• simplecov
• tqdm
• webmock

الإنتاج والمراقبة

• avo
• browser
• cloudflare-rails
• get_process_mem
• memory_profiler
• mission_control-jobs
• pg_query
• pghero
• rack-mini-profiler
• rails_performance
• solid_errors
• stackprof
• strict_ivars
• sys-cpu
• sys-filesystem

بالإضافة إلى مكتبات إطار عمل Ruby on Rails الأساسية.

🟨 المكتبات المستخدمة للغة JavaScript

ملاحظة: جميع المكتبات يجب أن تكون مُحددة بإصدار مُعيّن لضمان الاستقرار والتوافق.

• @floating-ui/dom
• @rails/request.js
• @stimulus-components/clipboard
• @stimulus-components/read-more
• @tailwindcss/forms
• @tailwindcss/typography
• embla-carousel
• prettier
• tom-select
• tw-animate-css

بالإضافة إلى مكتبات إطار عمل Ruby on Rails الأساسية.

🧪 تشغيل حالات الاختبار

ملاحظة: نسعى في هذا المشروع إلى المحافظة على تغطية كاملة (100%) للشيفرة المصدرية بحالات اختبار دقيقة ومفيدة.

1. شغّل خادم التطوير من خلال تنفيذ الأمر mise dev أو ابدأ تشغيل خدمات Docker الخاصة بالمشروع من خلال تنفيذ الأمر mise docker:start
2. نفّذ الأمر CI=1 bundle exec rspec لتشغيل حالات الاختبار
3. ستحصل على تقرير بنسبة تغطية الشيفرة المصدرية بحالات الاختبار ويمكنك تصفّح التقرير المُفصّل الموجود في coverage/index.html
4. أوقف تشغيل خادم التطوير أو أوقف خدمات Docker إذا كنت شغّلتها من خلال تنفيذ الأمر mise docker:stop

🗃️ إضافة بيانات حقيقية إلى المشروع

يمكنك إضافة كتب حقيقية إلى المشروع من إحدى المكتبات المُعالجة رقميًا التالية:

• مكتبة المسجد النبوي
• المكتبة الوقفية
• المكتبة الشاملة الوقفية

خطوات إضافة كتاب في بيئة التطوير

1. اختر إحدى المكتبات واستعرض الكتب المتاحة
2. احصل على روابط تحميل ملفات PDF و TXT و DOCX للكتاب المطلوب من مستودع المكتبة على HuggingFace
3. نفّذ الأمر التالي مع استبدال المتغيرات بالقيم المناسبة:

rake db:import_book -- \
  --title="القول الصواب في حكم النسخ في الكتاب" \
  --author="ـ" \
  --category="علوم القرآن" \
  --pages=16 \
  --volumes=-1 \
  --library-id=1 \
  --pdf-urls="https://huggingface.co/datasets/ieasybooks-org/prophet-mosque-library/resolve/main/pdf/1%D9%80%20211.0%20%D8%B9%D9%84%D9%88%D9%85%20%D8%A7%D9%84%D9%82%D8%B1%D8%A2%D9%86/00016%D9%80%20%D8%A7%D9%84%D9%82%D9%88%D9%84%20%D8%A7%D9%84%D8%B5%D9%88%D8%A7%D8%A8%20%D9%81%D9%8A%20%D8%AD%D9%83%D9%85%20%D8%A7%D9%84%D9%86%D8%B3%D8%AE%20%D9%81%D9%8A%20%D8%A7%D9%84%D9%83%D8%AA%D8%A7%D8%A8%20---%20%D9%80.PDF/KTB.pdf" \
  --txt-urls="https://huggingface.co/datasets/ieasybooks-org/prophet-mosque-library/resolve/main/txt/1%D9%80%20211.0%20%D8%B9%D9%84%D9%88%D9%85%20%D8%A7%D9%84%D9%82%D8%B1%D8%A2%D9%86/00016%D9%80%20%D8%A7%D9%84%D9%82%D9%88%D9%84%20%D8%A7%D9%84%D8%B5%D9%88%D8%A7%D8%A8%20%D9%81%D9%8A%20%D8%AD%D9%83%D9%85%20%D8%A7%D9%84%D9%86%D8%B3%D8%AE%20%D9%81%D9%8A%20%D8%A7%D9%84%D9%83%D8%AA%D8%A7%D8%A8%20---%20%D9%80.PDF/KTB.txt" \
  --docx-urls="https://huggingface.co/datasets/ieasybooks-org/prophet-mosque-library/resolve/main/docx/1%D9%80%20211.0%20%D8%B9%D9%84%D9%88%D9%85%20%D8%A7%D9%84%D9%82%D8%B1%D8%A2%D9%86/00016%D9%80%20%D8%A7%D9%84%D9%82%D9%88%D9%84%20%D8%A7%D9%84%D8%B5%D9%88%D8%A7%D8%A8%20%D9%81%D9%8A%20%D8%AD%D9%83%D9%85%20%D8%A7%D9%84%D9%86%D8%B3%D8%AE%20%D9%81%D9%8A%20%D8%A7%D9%84%D9%83%D8%AA%D8%A7%D8%A8%20---%20%D9%80.PDF/KTB.docx"

خطوات إضافة مكتبة كاملة إلى قاعدة بيانات الجامع بعد نشره

ملاحظة: هذه الخطوات مخصصة لإضافة المكتبات الكاملة إلى الجامع بعد نشره، وليس في بيئة التطوير.

1. حمّل ملف index.tsv الخاص بالمكتبة المطلوبة من مستودعها على HuggingFace. على سبيل المثال، يمكنك تحميل ملف فهرس المكتبة الوقفية من هذا الرابط.
2. نفّذ الأمر التالي مع تعديل المتغيرات حسب المكتبة المطلوبة:

ruby script/import_books.rb \
  --index-path=path/to/index.tsv \
  --huggingface-library-id=ieasybooks-org/library-dataset-id \
  --aljam3-library-id=0 \
  --server-ip=$SERVER_IP \
  --server-username=$SERVER_USERNAME

على سبيل المثال، الأمر التالي يُضيف المكتبة الوقفية إلى الجامع

ruby script/import_books.rb \
  --index-path=/path/to/index.tsv \
  --huggingface-library-id=ieasybooks-org/waqfeya-library \
  --aljam3-library-id=2 \
  --server-ip=$SERVER_IP \
  --server-username=$SERVER_USERNAME