מודולים

בחר את המודול ששייך לו השינוי שלך, ודע לאילו מודולים מותר לו לקרוא.

לפני שמתחילים

• קרא את ארכיטקטורה בשביל מפת התיקיות והכללים.
• לכל מודול יש אותו שם ב-app/backend/internal/<module>/, וגם ב-app/frontend/src/lib/<module>/ וב-app/tests/<module>/ כשיש לו מסכים או בדיקות דפדפן.

למצוא את המודול הנכון

מודול	עושה
requests	בקשות, אישורים, כללי בקשות, רשימות חיצוניות, דיווחים
movies	כותרים של סרטים, מהדורות, סטים, חיפוש וסידור
shows	סדרות, עונות, פרקים, חיפוש וסידור
music	אמנים, אלבומים, רצועות, חיפוש וסידור
sources	מקורות, הגשר ל-Jackett ול-Prowlarr, חיפוש גרסאות הפצה
downloads	מורידים, התור, קבצים שנראו, מיפוי נתיבים, תגיות, בחירת עותקים
subtitles	שפות כתוביות, אתרים, התאמה ושמירה
discover	Explore, Popular, Search, People, Calendar, דפי כותרים
suggest	בחירה וסידור של שורות ומדפים (צד השרת בלבד)
mediafiles	רשומות קטלוג, כללי בחירה, מתן שמות, חבילות נתונים, פרטי מדיה
importer	ייבוא קבצים: פריקה, תגיות, התאמה (צד השרת בלבד)
library	תיקיות ספרייה, אימוץ ושינוי שמות (צד השרת בלבד)
metadata	הלקוח של נתונים חיצוניים, חיפושי מוזיקה, סולמות דירוג, טריילרים
mediaservers	להגיד ל-Plex, ל-Jellyfin ול-Emby לסרוק שוב
accounts	משתמשים, התחברות, כניסה יחידה, התחברות של אפליקציות AI, מגבלות לילדים, העדפות צפייה
alerts	ערוצי התראות ומתי הם מדברים
migrate	ייבוא נתונים מאפליקציות קודמות
arrapi	ה-API בסגנון Sonarr ו-Radarr
ai	חיבורי אפליקציות AI (יכולת שמורה)
backups	יצירת גיבויים, שמירתם ושחזורם
health	בדיקות תקינות, ה-doctor, חבילת התמיכה
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 ממלא.

להוסיף נתיב או מודול

נתיב חדש

רשום אותו ב-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, או נוגע בטבלה של מודול אחר. פתרון. העבר את השאילתה ל-store של הבעלים וקרא ל-service של הבעלים לפי ID.

למומחים

עוד כללים

• מודול מייבא רק את החבילה הראשית של מודול אחר.
• פונקציות store מקבלות database.Querier. קרא שורות של מודול אחר דרך ה-service שלו לפי 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 מייבאת רק מהשורה שלה או מנמוכה ממנה.
• שמות: קבצי Go באותיות קטנות עם קווים תחתונים, חלקי Svelte ב-PascalCase, וקבצי TypeScript, מסמכים, בדיקות ו-deploy ב-kebab-case. קבצי Python משתמשים בקווים תחתונים כדי שאפשר יהיה לייבא אותם. תיקיות ב-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	ייבוא של החבילה הראשית בלבד
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	ייבואים של core, סדר השורות ושמות
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	מיקום SQL ובעלים של טבלאות
TestGoFileNames, TestNoBannedPackageNames	שמות קבצים וחבילות
TestFileSizeCap, TestCorePackageSize	גודל קבצים וחבילות core
TestCommentHygiene	כללי ההערות שלמעלה
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	העברה לא משנה נתיב, מיגרציה, שם של header ב-HTTP או מפתח JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	כתובות ישנות של דפים לא חוזרות לקוד, לבדיקות ולמסמכים
TestNoDependencyBotConfig	אין קובץ של בוט תלויות ב-.github

קשור

• ארכיטקטורה
• בדיקות
• נתיבי API