ماژول‌ها

ماژولی را انتخاب کنید که تغییر شما به آن تعلق دارد و بدانید چه ماژول‌هایی را می‌تواند صدا بزند.

پیش از شروع

• برای نقشهٔ پوشه‌ها و قوانین، معماری را بخوانید.
• هر ماژول در 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	کاربران، ورود، single sign-on، ورود برنامهٔ هوش مصنوعی، سقف کودکان، انتخاب‌های تماشا
alerts	کانال‌های اعلان و زمان حرف زدن آن‌ها
migrate	آوردن داده از برنامه‌های قبلی
arrapi	API به سبک Sonarr و Radarr
ai	اتصال برنامه‌های هوش مصنوعی (نگه‌داشته‌شده)
backups	ساختن، نگه داشتن و بازیابی بکاپ‌ها
health	بررسی سلامت، doctor، بستهٔ پشتیبانی
updates	بررسی به‌روزرسانی و فهرست امضاشدهٔ به‌روزرسانی
setup	ویزارد اولین اجرا

ترتیب لایه‌ها

یک ماژول فقط لایهٔ پایین‌تر را import می‌کند. هیچ‌کس discover را import نمی‌کند. مرجع اصلی 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

اگر ماژول شما چیزی از لایهٔ بالاتر لازم دارد، آن را import نکنید. ماژول بالاتر داده‌های ساده را پایین بدهد، یا در ماژول پایین یک interface کوچک تعریف کنید که wiring.go آن را پر می‌کند.

یک مسیر یا یک ماژول اضافه کنید

مسیر جدید

آن را همراه با دسترسی‌اش در routes.go ماژول ثبت کنید. openapi.json از روی مسیرها ساخته می‌شود و آزمایشی در صورت ناهمخوانی رد می‌شود. مسیرها و نام فیلدهای منتشرشده می‌مانند. فیلد اضافه کنید، هرگز تغییر نام ندهید. بعد مسیرهای API را با go run ./app/backend/tools/apidoc دوباره بنویسید.

ماژول جدید

اول تغییر خود را در همان 23 ماژول جا بدهید، و پیش از اضافه کردن یکی issue باز کنید. ماژول جدید به پوشهٔ بک‌اند خودش نیاز دارد (و اگر صفحه دارد lib/<module>/ و app/tests/<module>/)، یک جا در ترتیب لایه‌ها در tools/structurecheck، و یک خط در wiring.go.

اگر کار نکرد

نشانه. TestModuleEdges رد می‌شود. علت. یک ماژول ماژولی را import کرده که هم‌لایه یا بالاتر است. راه‌حل. داده‌های ساده را از ماژول بالاتر پایین بدهید، یا یک interface کوچک اضافه کنید که در wiring.go وصل شود.

نشانه. TestSQLOnlyInStore یا TestTableOwnership رد می‌شود. علت. SQL بیرون از فایل store*.go است، یا به جدول ماژول دیگر دست می‌زند. راه‌حل. query را به store صاحب جدول ببرید و سرویس صاحب را با ID صدا بزنید.

برای حرفه‌ای‌ها

قوانین بیشتر

• یک ماژول فقط بستهٔ ریشهٔ ماژول دیگر را import می‌کند.
• تابع‌های store یک database.Querier می‌گیرند. ردیف‌های ماژول دیگر را از راه سرویس آن با ID بخوانید، و فهرست‌های بلند ID را به‌صورت یک آرایهٔ JSON با json_each(?) بدهید.
• settings، schedules، secrets، jobs و events مال core هستند. هر گروه تنظیمات یک ماژول صاحب دارد. برای تغییر گروه ماژول دیگر، صاحب آن را صدا بزنید.
• هر درخواست به بیرون از core/outbound می‌گذرد.
• بسته‌های core در ردیف‌هایی از بالا به پایین قرار دارند: parts، webserver و startup، logs، jobs و model، outbound و secrets، و بعد database، files و releasename. یک بستهٔ core فقط ردیف خودش یا پایین‌تر را import می‌کند.
• نام‌ها: فایل‌های Go حروف کوچک با زیرخط هستند، بخش‌های Svelte به‌شکل PascalCase، و فایل‌های TypeScript، مستندات، آزمایش و deploy به‌شکل kebab-case. فایل‌های Python زیرخط دارند تا بشود آن‌ها را import کرد. پوشه‌های app/ حروف کوچک و یک کلمه‌اند.
• کد را آزادانه تغییر نام بدهید، اما هر چیزی که ذخیره یا فرستاده می‌شود نامش را نگه می‌دارد: جدول‌ها و ستون‌ها، کلیدهای تنظیمات، فیلدهای JSON، نام کارها و نام کلیدها.
• کامنت‌ها شمارهٔ نقشهٔ راه، تاریخ، نام یا em dash ندارند.

صاحبان رکوردها

صاحب	رکوردها
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	فقط import بستهٔ ریشه
TestCoreImportsNoModule، TestCoreRowOrder، TestCoreNamesNoModuleTable	importهای core، ترتیب ردیف‌ها و نام‌ها
TestSQLOnlyInStore، TestTableOwnership، TestSQLAllowlistShrinks، TestSeedSQLAllowlist	جای SQL و صاحبان جدول‌ها
TestGoFileNames، TestNoBannedPackageNames	نام فایل‌ها و بسته‌ها
TestFileSizeCap، TestCorePackageSize	اندازهٔ فایل و بستهٔ core
TestCommentHygiene	قوانین کامنت بالا
TestRouteTableUnchanged، TestMigrationsUnchanged، TestHeaderAndJSONLiteralsUnchanged	جابه‌جایی هیچ مسیر، مهاجرت، نام هدر HTTP یا کلید JSON را تغییر نمی‌دهد
TestNoOldPageAddresses، TestNoOldPagesInTestsOrDocs	نشانی‌های قدیمی صفحه‌ها از کد، آزمایش‌ها و مستندات بیرون می‌مانند
TestNoDependencyBotConfig	هیچ فایل ربات وابستگی در .github نیست

صفحه‌های مرتبط

• معماری
• آزمایش
• مسیرهای API