البنية

اعرف أين تقع الشيفرة وما القواعد السارية قبل أن تغيّر شيئًا كبيرًا.

باختصار

HolyArrs برنامج واحد مكتوب بلغة Go وتطبيق الويب مدمج فيه. يقدّم تطبيق الويب وواجهة JSON API على المنفذ 6262، ويحفظ بياناته في ملفَّي SQLite داخل مجلد الإعدادات. ويتصل ببرامج التنزيل، والمصادر (عبر Jackett أو Prowlarr)، وخوادم الوسائط، وقنوات التنبيه، وخادم البيانات الوصفية الخاص بـ HolyArrs.

تتبّع طلبًا واحدًا. شخص يطلب فيلمًا من الاستكشاف.

1. تسجّل requests الطلب.
2. بعد الموافقة، تطلب movies الإصدارات من sources.
3. تقيّمها قواعد الاختيار في mediafiles.
4. ترسل downloads أفضلها إلى برنامج التنزيل.
5. عند انتهائه، تستورد mediafiles الملف.
6. تُبلَّغ mediaservers وalerts.

خريطة الشيفرة

app/backend/cmd/holyarrs/            main.go starts the program; wiring.go builds the modules and joins them
app/backend/internal/<module>/       one flat folder per module
app/backend/internal/core/           plumbing every module may use
app/backend/tools/                   dev-only programs
app/frontend/                        the SvelteKit web app; embed.go bundles its build
app/frontend/src/routes/<page>/      thin pages that combine module parts
app/frontend/src/lib/<module>/       each module's web code
app/frontend/src/lib/ui/             parts used by 2 or more modules, and nothing else
app/frontend/src/lib/core/           server client, app state, helpers
app/tests/                           end-to-end tests (Playwright)
deploy/                              the Dockerfile and release scripts
docs/                                guides and these pages

يقع go.mod في جذر المستودع لأن go:embed لا يصل إلى مجلد أعلى منه.

أين تجد الأشياء

تريد أن تغيّر	ابحث في
طريقة اختيار الإصدار	internal/mediafiles
عميل برنامج تنزيل	internal/downloads، واختبارات العقد في internal/downloads/conformance_test.go
قناة تنبيه	internal/alerts
تسجيل الدخول والمستخدمين ومفاتيح API	internal/accounts
معالج التشغيل الأول	internal/setup، app/frontend/src/routes/welcome
استيراد ملف مكتمل (فك الضغط، الوسوم، المطابقة)	internal/importer
مجلدات المكتبة والضمّ وإعادة التسمية	internal/library
طريقة اختيار الصفوف والرفوف وترتيبها	internal/suggest
الأقسام المفعّلة من التطبيق	internal/core/parts
عنوان صفحة	app/frontend/src/routes/
ترحيل لقاعدة البيانات (migration)	internal/core/database/migrations/
صورة Docker	deploy/Dockerfile

القواعد

الفحوص في app/backend/tools/structurecheck تُفشل البناء إذا خُرقت قاعدة منها. شغّلها بالسطر المذكور في الاختبار.

• ترتيب الطبقات. تستورد الوحدة وحدات من طبقة أدنى فقط، وحزمتها الجذرية فقط. والوحدات في الطبقة نفسها لا يستورد بعضها بعضًا أبدًا.
• النداء إلى الأعلى. إذا احتاجت وحدة أدنى إلى شيء من وحدة أعلى، تمرّر الوحدة الأعلى بيانات بسيطة إلى الأسفل، أو تعرّف الوحدة الأدنى واجهة صغيرة يملؤها wiring.go.
• SQL يبقى في بيته. ملفات store*.go الخاصة بالوحدة هي وحدها التي تحوي SQL، وعلى جداول الوحدة نفسها فقط. لقراءة صفوف وحدة أخرى، نادِ خدمتها.
• الجداول المشتركة ملك core. صِل إلى settings وschedules وsecrets وjobs وevents عبر أدوات core المساعدة.
• مخرج واحد. كل اتصال بالخارج يمر عبر core/outbound.
• الميزات المحجوبة تسجّل مفتاح تبديل لدى core/startup. ما دام مطفأً، لا يوجد مسار API لها وتخفي الصفحة الميزة.
• لا حزم للمتفرقات. لا util ولا common ولا shared ولا helpers.

ترتيب الطبقات مذكور في الوحدات.

للخبراء

داخل الوحدة

كل وحدة في الخلفية تستعمل أسماء الملفات نفسها.

الملف	يحوي
routes.go	مسارات API، ومع كل واحد الإذن الذي يحتاج إليه
service.go وملفات المواضيع	المنطق الذي تناديه الوحدات الأخرى
store.go، store_<topic>.go	كل SQL الخاص بجداول الوحدة نفسها
types.go	سجلات الوحدة

في جهة الويب، يحوي lib/<module>/ الملف index.ts (ما يجوز للوحدات الأخرى استعماله)، وأجزاء Svelte الخاصة بها واختباراتها، ويضاف api.ts وstate.svelte.ts فقط إذا كانت لها نداءات أو حالة خاصة بها.

حزم core

core هو البنية التحتية. لا يحوي قواعد المنتج ولا يستورد أي وحدة.

الحزمة	تحوي
core/database	فتح ملفَّي SQLite وترحيلهما، وأدوات الاستعلام المساعدة، وأدوات الإعدادات والأحداث المساعدة، وحقول الصفوف المشتركة، وتقليص السجل
core/files	أدوات الملفات والمجلدات المساعدة، والمساحة الحرة على القرص
core/releasename	استخراج الجودة والمجموعة وأرقام الحلقات من اسم الإصدار
core/outbound	الطريق الوحيد للاتصال بالخوادم الخارجية، مع فحص العناوين
core/secrets	مخزن المفاتيح وتدوير المفاتيح
core/logs	سجل تشغيل التطبيق وملاحظات الأعطال
core/jobs	قائمة انتظار المهام، والجداول الزمنية، والحلقات التي تعيد التشغيل بعد عطل
core/webserver	بنية الموجّه، وURL base، والضغط، والدفع المباشر
core/startup	مستخدم التشغيل، ووضع الذاكرة المنخفضة، ومفاتيح تبديل الميزات المحجوبة، وحد الذاكرة، والأقسام
core/parts	مفاتيح تبديل الأقسام التي تسألها كل وحدة قبل أن تخدم أو تعمل
core/model	الأنواع المشتركة مثل الفاعلين والمواضيع

إذا اضطر core إلى لمس بيانات وحدة، تسجّل الوحدة خطّافًا لدى core في wiring.go. هكذا يعمل تدوير المفاتيح.

البيانات

الملف	يحوي
holyarrs.db	المكتبة والطلبات والإعدادات وكل ما عداها من المهم
holyarrs-events.db	السجل وصفوف الأحداث الأخرى. يكبر ويُقلَّص دون المساس بالملف الرئيسي

الترحيلات ملفات SQL مرقّمة في core/database/migrations/main وcore/database/migrations/events. تُنفَّذ عند بدء التشغيل.

صفحات ذات صلة

• الوحدات
• المساهمة
• الاختبار