Moduły

Wybierz moduł, do którego należy twoja zmiana, i sprawdź, które moduły wolno jej wywoływać.

Zanim zaczniesz

• Przeczytaj Architekturę, żeby poznać mapę folderów i reguły.
• Każdy moduł ma tę samą nazwę w app/backend/internal/<module>/, a także w app/frontend/src/lib/<module>/ i app/tests/<module>/, jeśli ma ekrany lub testy w przeglądarce.

Znajdź właściwy moduł

Moduł	Odpowiada za
requests	Proszenie, zatwierdzanie, reguły próśb, listy zewnętrzne, zgłoszenia
movies	Tytuły filmów, edycje, zestawy, wyszukiwanie i porządkowanie
shows	Seriale, sezony, odcinki, wyszukiwanie i porządkowanie
music	Wykonawcy, albumy, utwory, wyszukiwanie i porządkowanie
sources	Źródła, most do Jacketta i Prowlarra, wyszukiwanie releaseów
downloads	downloadery, kolejka, widziane pliki, mapy ścieżek, tagi, wybór kopii
subtitles	Języki napisów, serwisy, dopasowanie i zapisywanie
discover	Explore, Popular, Search, People, Calendar, strony tytułów
suggest	Wybór i kolejność wierszy i półek (tylko backend)
mediafiles	Rekordy katalogu, reguły wyboru, nazewnictwo, paczki danych, szczegóły multimediów
importer	Import plików: rozpakowanie, tagi, dopasowanie (tylko backend)
library	Foldery biblioteki, przejmowanie i zmiana nazw (tylko backend)
metadata	Klient danych zewnętrznych, wyszukiwanie muzyki, drabinki ocen, zwiastuny
mediaservers	Informowanie Plexa, Jellyfina i Emby, żeby sprawdziły zmiany
accounts	Użytkownicy, logowanie, single sign-on, logowanie aplikacji AI, limity dla dzieci, wybory dotyczące oglądania
alerts	Kanały powiadomień i to, kiedy się odzywają
migrate	Przenoszenie danych z dotychczasowych aplikacji
arrapi	API w stylu Sonarra i Radarra
ai	Połączenia aplikacji AI (wstrzymane)
backups	Tworzenie, przechowywanie i przywracanie backupów
health	Kontrole kondycji, doctor, pakiet diagnostyczny
updates	Sprawdzanie aktualizacji i podpisana lista aktualizacji
setup	Kreator pierwszego uruchomienia

Kolejność warstw

Moduł importuje tylko niższą warstwę. Nic nie importuje discover. Źródłem prawdy jest tools/structurecheck/allow.go.

Warstwa	Moduły
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

Jeśli twój moduł potrzebuje czegoś z wyższej warstwy, nie importuj tego. Niech wyższy moduł przekaże w dół zwykłe dane albo zdefiniuj w niższym mały interfejs, który uzupełnia wiring.go.

Dodaj trasę lub moduł

Nowa trasa

Zarejestruj ją w pliku routes.go modułu razem z uprawnieniem. Plik openapi.json powstaje z tras, a test przerywa build, gdy się rozjadą. Wydane ścieżki i nazwy pól zostają. Pola dodawaj, nigdy nie zmieniaj ich nazw. Potem przepisz stronę Trasy API poleceniem go run ./app/backend/tools/apidoc.

Nowy moduł

Najpierw spróbuj zmieścić zmianę w istniejących 23 i otwórz zgłoszenie, zanim dodasz nowy. Nowy moduł potrzebuje folderu w backendzie (oraz lib/<module>/ i app/tests/<module>/, jeśli ma ekrany), miejsca w kolejności warstw w tools/structurecheck i linii w wiring.go.

Jeśli to nie działa

Objaw. TestModuleEdges kończy się błędem. Przyczyna. Moduł importuje inny z tej samej lub wyższej warstwy. Rozwiązanie. Przekaż zwykłe dane w dół z wyższego modułu albo dodaj mały interfejs podłączony w wiring.go.

Objaw. TestSQLOnlyInStore lub TestTableOwnership kończy się błędem. Przyczyna. SQL leży poza plikiem store*.go albo dotyka tabeli innego modułu. Rozwiązanie. Przenieś zapytanie do store właściciela i wywołaj serwis właściciela przez ID.

Dla zaawansowanych

Więcej reguł

• Moduł importuje tylko główny pakiet innego modułu.
• Funkcje store przyjmują database.Querier. Wiersze innego modułu czytaj przez jego serwis po ID, a długie listy ID przekazuj jako jedną tablicę JSON z json_each(?).
• settings, schedules, secrets, jobs i events należą do core. Każda grupa ustawień ma jeden moduł-właściciela. Żeby zmienić grupę innego modułu, wywołaj jej właściciela.
• Każde wywołanie na zewnątrz idzie przez core/outbound.
• Pakiety core leżą w rzędach, od góry do dołu: parts, webserver i startup, logs, jobs i model, outbound i secrets, a na końcu database, files i releasename. Pakiet core importuje tylko swój rząd lub niższy.
• Nazwy: pliki Go piszemy małymi literami z podkreśleniami, części Svelte w PascalCase, a pliki TypeScript, dokumentacji, testów i deploy w kebab-case. Pliki Pythona mają podkreślenia, żeby dało się je importować. Foldery w app/ mają małe litery i jedno słowo.
• Kod możesz swobodnie przemianowywać, ale wszystko, co jest zapisane lub wysyłane, zachowuje nazwę: tabele i kolumny, klucze ustawień, pola JSON, nazwy zadań i nazwy przełączników.
• W komentarzach nie ma numerów z planu rozwoju, dat, imion ani długich myślników.

Właściciele rekordów

Właściciel	Rekordy
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 i wspólne pola wierszy

Kontrole

Kontrole leżą w app/backend/tools/structurecheck. Większość wymaga -tags structure.

Kontrola	Pilnuje
TestTopLayout	Głównych folderów repo
TestModuleSet, TestCoreSet, TestPackageMap	Folderów dozwolonych w internal/ i internal/core/
TestModuleEdges	Kolejności warstw
TestModuleImportsRootOnly	Importów tylko głównego pakietu
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Importów core, kolejności rzędów i nazw
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	Miejsca SQL i właścicieli tabel
TestGoFileNames, TestNoBannedPackageNames	Nazw plików i pakietów
TestFileSizeCap, TestCorePackageSize	Rozmiaru plików i pakietów core
TestCommentHygiene	Reguł komentarzy z góry
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Tego, że przeniesienie nie zmienia trasy, migracji, nazwy nagłówka HTTP ani klucza JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Tego, że stare adresy stron nie wracają do kodu, testów ani dokumentacji
TestNoDependencyBotConfig	Braku pliku bota zależności w .github

Powiązane strony

• Architektura
• Testy
• Trasy API