الوحدات

اختر الوحدة التي ينتمي إليها تغييرك، واعرف أي الوحدات يجوز لها أن تناديها.

قبل أن تبدأ

• اقرأ البنية لتعرف خريطة المجلدات والقواعد.
• لكل وحدة الاسم نفسه في app/backend/internal/<module>/، وفي app/frontend/src/lib/<module>/ وapp/tests/<module>/ إذا كانت لها شاشات أو اختبارات متصفح.

اعثر على الوحدة الصحيحة

الوحدة	عملها
requests	الطلب، والموافقات، وقواعد الطلبات، والقوائم الخارجية، والبلاغات
movies	أعمال الأفلام، وصيغ الأفلام، والمجموعات، والبحث والتنظيم
shows	المسلسلات، والمواسم، والحلقات، والبحث والتنظيم
music	الفنانون، والألبومات، والمقاطع، والبحث والتنظيم
sources	المصادر، وجسر Jackett و Prowlarr، والبحث عن الإصدارات
downloads	برامج التنزيل، وقائمة الانتظار، والملفات التي سبقت رؤيتها، وتعيينات المسارات، والوسوم، وخيارات النسخ
subtitles	لغات الترجمات، ومواقعها، ومطابقتها وحفظها
discover	الاستكشاف، والرائج، والبحث، والأشخاص، والتقويم، وصفحات الأعمال
suggest	اختيار الصفوف والرفوف وترتيبها (الخلفية فقط)
mediafiles	سجلات الفهرس، وقواعد الاختيار، والتسمية، وحزم البيانات، وتفاصيل الوسائط
importer	استيراد الملفات: فك الضغط، والوسوم، والمطابقة (الخلفية فقط)
library	مجلدات المكتبة، والضمّ وإعادة التسمية (الخلفية فقط)
metadata	عميل البيانات الخارجية، واستعلامات الموسيقى، وسلالم التصنيف العمري، والإعلانات التشويقية
mediaservers	إبلاغ Plex و Jellyfin و Emby بأن تفحص من جديد
accounts	المستخدمون، وتسجيل الدخول، وتسجيل الدخول الموحّد، وتسجيل دخول تطبيقات الذكاء الاصطناعي، وقيود الأطفال، وخيارات العرض
alerts	قنوات التنبيه ومتى تتكلم
migrate	جلب البيانات من التطبيقات الأقدم
arrapi	واجهة API على نمط Sonarr و Radarr
ai	اتصالات تطبيقات الذكاء الاصطناعي (محجوبة)
backups	إنشاء النسخ الاحتياطية وحفظها واستعادتها
health	فحوص السلامة، وأداة التشخيص، وحزمة الدعم
updates	فحص التحديثات وقائمة التحديثات الموقّعة
setup	معالج التشغيل الأول

ترتيب الطبقات

تستورد الوحدة من طبقة أدنى فقط. لا شيء يستورد discover. الملف tools/structurecheck/allow.go هو المرجع الحاسم.

الطبقة	الوحدات
0	core
1	metadata, suggest
2	accounts
3	mediafiles
4	importer
5	library
6	sources
7	downloads
8	subtitles, mediaservers, alerts
9	movies, shows
10	requests, health
11	music, arrapi, migrate, ai, backups, updates, setup
13	discover

إذا احتاجت وحدتك إلى شيء من طبقة أعلى، فلا تستوردها. اجعل الوحدة الأعلى تمرّر بيانات بسيطة إلى الأسفل، أو عرّف في الوحدة الأدنى واجهة صغيرة يملؤها wiring.go.

أضف مسار API أو وحدة

مسار API جديد

سجّله في routes.go الخاص بالوحدة مع إذنه. يُولَّد openapi.json من المسارات، ويفشل اختبار عند أي انحراف. المسارات المنشورة وأسماء الحقول تبقى. أضف حقولًا، ولا تُعد تسميتها أبدًا. ثم أعد كتابة مسارات API بالأمر go run ./app/backend/tools/apidoc.

وحدة جديدة

حاول أولًا أن تضع تغييرك في إحدى الوحدات الـ23، وافتح بلاغًا (issue) قبل أن تضيف واحدة. تحتاج الوحدة الجديدة إلى مجلدها في الخلفية (ومعه lib/<module>/ وapp/tests/<module>/ إذا كانت لها شاشات)، وإلى مكان في ترتيب الطبقات في tools/structurecheck، وإلى سطر في wiring.go.

إذا لم ينجح الأمر

العَرَض. يفشل TestModuleEdges. السبب. وحدة تستورد وحدة من الطبقة نفسها أو من طبقة أعلى. الحل. مرّر بيانات بسيطة إلى الأسفل من الوحدة الأعلى، أو أضف واجهة صغيرة تُوصَل في wiring.go.

العَرَض. يفشل TestSQLOnlyInStore أو TestTableOwnership. السبب. يوجد SQL خارج ملف store*.go، أو يمسّ جدول وحدة أخرى. الحل. انقل الاستعلام إلى مخزن الوحدة المالكة ونادِ خدمتها بالمعرّف.

للخبراء

قواعد أخرى

• تستورد الوحدة الحزمة الجذرية فقط من أي وحدة أخرى.
• دوال المخزن تأخذ database.Querier. اقرأ صفوف وحدة أخرى عبر خدمتها بالمعرّف، ومرّر قوائم المعرّفات الطويلة كمصفوفة JSON واحدة مع json_each(?).
• settings وschedules وsecrets وjobs وevents ملك core. لكل مجموعة إعدادات وحدة مالكة واحدة. لتغيير مجموعة تخص وحدة أخرى، نادِ مالكتها.
• كل اتصال بالخارج يمر عبر core/outbound.
• حزم core مرتبة في صفوف من الأعلى إلى الأسفل: parts، ثم webserver وstartup، ثم logs، ثم jobs وmodel، ثم outbound وsecrets، ثم database وfiles وreleasename. تستورد حزمة core من صفها أو مما دونه فقط.
• الأسماء: ملفات Go بأحرف صغيرة مع شرطات سفلية، وأجزاء Svelte بصيغة PascalCase، وملفات TypeScript والمستندات والاختبارات والنشر بصيغة kebab-case. ملفات Python تستعمل الشرطات السفلية ليمكن استيرادها. المجلدات في app/ بأحرف صغيرة ومن كلمة واحدة.
• أعد تسمية الشيفرة بحرية، لكن كل ما يُخزَّن أو يُرسَل يحتفظ باسمه: الجداول والأعمدة، ومفاتيح الإعدادات، وحقول JSON، وأسماء المهام، وأسماء مفاتيح التبديل.
• التعليقات لا تحمل أرقامًا من خارطة الطريق ولا تواريخ ولا أسماء ولا شرطات طويلة.

مالكو السجلات

المالك	السجلات
mediafiles	Title, Item, Version, Slot, Part, File, LibraryFolder, Quality, PickRules
downloads	Download, Downloader, SeenFile, PathMap
sources	Source, Release
requests	Ask, Report
accounts	User
core/jobs	Job, Schedule, JobError
core/database	Event وحقول الصفوف المشتركة

الفحوص

توجد الفحوص في app/backend/tools/structurecheck. معظمها يحتاج إلى -tags structure.

الفحص	يضبط
TestTopLayout	مجلدات المستودع العليا
TestModuleSet, TestCoreSet, TestPackageMap	المجلدات المسموح بها في internal/ وinternal/core/
TestModuleEdges	ترتيب الطبقات
TestModuleImportsRootOnly	استيراد الحزمة الجذرية فقط
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	استيرادات core وترتيب صفوفه وأسماؤه
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	موضع SQL ومالكو الجداول
TestGoFileNames, TestNoBannedPackageNames	أسماء الملفات والحزم
TestFileSizeCap, TestCorePackageSize	حجم الملفات وحجم حزم core
TestCommentHygiene	قواعد التعليقات المذكورة أعلاه
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	النقل لا يغيّر أي مسار API ولا ترحيل ولا اسم ترويسة HTTP ولا مفتاح JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	عناوين الصفحات القديمة تبقى غائبة عن الشيفرة والاختبارات والمستندات
TestNoDependencyBotConfig	لا ملف لبوت الاعتماديات في .github

صفحات ذات صلة

• البنية
• الاختبار
• مسارات API