Модули

Избери модула, към който принадлежи промяната ти, и знай кои модули може да вика.

Преди да започнеш

• Прочети Архитектура за картата на папките и правилата.
• Всеки модул има едно и също име в 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	Потребители, вход, единен вход (SSO), вход за AI приложения, детски лимити, избори за гледане
alerts	Канали за известия и кога се обаждат
migrate	Пренасяне на данни от по-старите приложения
arrapi	API в стила на Sonarr и Radarr
ai	Връзки с 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 попълва.

Добави маршрут или модул

Нов маршрут

Регистрирай го в routes.go на модула заедно с правото му. openapi.json се прави от маршрутите и тест пада при разминаване. Публикуваните пътища и имена на полета остават. Добавяй полета, никога не ги преименувай. После презапиши API маршрути с go run ./app/backend/tools/apidoc.

Нов модул

Първо опитай да вместиш промяната си в 23-те и отвори проблем, преди да добавиш нов. Новият модул има нужда от папка в бекенда (плюс lib/<module>/ и app/tests/<module>/, ако има екрани), място в реда на слоевете в tools/structurecheck и ред във wiring.go.

Ако не работи

Проблем. TestModuleEdges пада. Причина. Модул импортира друг от същия или от по-висок слой. Решение. Подай обикновени данни надолу от по-горния модул или добави малък интерфейс, свързан във wiring.go.

Проблем. TestSQLOnlyInStore или TestTableOwnership пада. Причина. SQL стои извън файл store*.go или пипа таблица на друг модул. Решение. Премести заявката в хранилището на собственика и извикай услугата на собственика по ID.

За експерти

Още правила

• Модулът импортира само кореновия пакет на друг модул.
• Функциите на хранилището приемат 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 импортира само от своя ред или от по-долен.
• Имена: файловете на Go са с малки букви и долни черти, частите на Svelte са PascalCase, а файловете на TypeScript, документацията, тестовете и deploy са 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	Преместване не променя маршрут, миграция, име на HTTP хедър или ключ на JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Старите адреси на страници остават извън кода, тестовете и документацията
TestNoDependencyBotConfig	Няма файл на бот за зависимости в .github

Свързано

• Архитектура
• Тестване
• API маршрути