Moduly

Vyber modul, do kterého změna patří, a věz, které moduly smí volat.

Než začneš

• Mapu složek a pravidla najdeš v architektuře.
• Každý modul má stejný název v app/backend/internal/<module>/ a také v app/frontend/src/lib/<module>/ a app/tests/<module>/, pokud má obrazovky nebo testy v prohlížeči.

Najdi správný modul

Modul	Dělá
requests	Žádosti, schvalování, pravidla žádostí, externí seznamy, hlášení
movies	Filmové tituly, vydání, sady, hledání a třídění
shows	Seriály, řady, epizody, hledání a třídění
music	Umělce, alba, skladby, hledání a třídění
sources	Zdroje, most k Jackettu a Prowlarru, hledání release
downloads	Stahovače, frontu, viděné soubory, mapy cest, tagy, volby kopií
subtitles	Jazyky titulků, weby, přiřazení a ukládání
discover	Explore, Popular, Search, People, Calendar, stránky titulů
suggest	Výběr a řazení řádků a polic (jen backend)
mediafiles	Záznamy katalogu, pravidla výběru, pojmenování, datové balíčky, údaje o médiích
importer	Import souborů: rozbalení, tagy, přiřazení (jen backend)
library	Složky knihovny, převzetí a přejmenování (jen backend)
metadata	Klienta pro vnější data, hudební dotazy, žebříčky hodnocení, trailery
mediaservers	Pokyn pro Plex, Jellyfin a Emby, aby se podívaly znovu
accounts	Uživatele, přihlášení, single sign-on, přihlášení AI aplikací, dětské limity, volby sledování
alerts	Kanály upozornění a kdy se ozvou
migrate	Převod dat z dřívějších aplikací
arrapi	API ve stylu Sonarru a Radarru
ai	Připojení AI aplikací (odložená funkce)
backups	Vytváření, uchovávání a obnova záloh
health	Kontroly zdraví, doctor, balíček pro podporu
updates	Kontrola aktualizací a podepsaný seznam aktualizací
setup	Průvodce prvním spuštěním

Pořadí vrstev

Modul importuje jen nižší vrstvu. Nic neimportuje discover. Zdrojem pravdy je tools/structurecheck/allow.go.

Vrstva	Moduly
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

Když tvůj modul potřebuje něco z vyšší vrstvy, neimportuj ji. Nech vyšší modul předat obyčejná data dolů, nebo v nižším definuj malé rozhraní, které doplní wiring.go.

Přidej trasu nebo modul

Nová trasa

Zaregistruj ji v routes.go modulu s jejím oprávněním. openapi.json vzniká z tras a test selže, když se rozejdou. Cesty a názvy polí, které už vyšly, zůstávají. Pole přidávej, nikdy je nepřejmenovávej. Potom přepiš trasy API příkazem go run ./app/backend/tools/apidoc.

Nový modul

Nejdřív svou změnu zkus vměstnat do těch 23 a před přidáním nového otevři issue. Nový modul potřebuje svou backendovou složku (plus lib/<module>/ a app/tests/<module>/, pokud má obrazovky), místo v pořadí vrstev v tools/structurecheck a řádek ve wiring.go.

Když to nefunguje

Příznak. Selže TestModuleEdges. Příčina. Modul importuje jiný ze stejné nebo vyšší vrstvy. Řešení. Předej obyčejná data dolů z vyššího modulu, nebo přidej malé rozhraní doplněné ve wiring.go.

Příznak. Selže TestSQLOnlyInStore nebo TestTableOwnership. Příčina. SQL leží mimo soubor store*.go, nebo sahá na tabulku jiného modulu. Řešení. Přesuň dotaz do store vlastníka a zavolej službu vlastníka podle ID.

Pro pokročilé

Další pravidla

• Modul importuje jen kořenový balíček jiného modulu.
• Funkce store berou database.Querier. Řádky jiného modulu čti přes jeho službu podle ID a dlouhé seznamy ID předávej jako jedno pole JSON přes json_each(?).
• settings, schedules, secrets, jobs a events patří jádru. Každá skupina nastavení má jeden modul-vlastníka. Chceš-li změnit skupinu jiného modulu, zavolej jejího vlastníka.
• Každé volání ven jde přes core/outbound.
• Balíčky jádra leží v řadách shora dolů: parts, webserver a startup, logs, jobs a model, outbound a secrets, pak database, files a releasename. Balíček jádra importuje jen svou řadu nebo nižší.
• Názvy: soubory Go jsou malými písmeny s podtržítky, části Svelte jsou v PascalCase a soubory TypeScriptu, dokumentace, testů a nasazení jsou v kebab-case. Soubory Pythonu mají podtržítka, aby šly importovat. Složky v app/ jsou malými písmeny, jedno slovo.
• Kód přejmenovávej libovolně, ale cokoli uložené nebo odeslané si drží název: tabulky a sloupce, klíče nastavení, pole JSON, názvy úloh a názvy přepínačů.
• Komentáře neobsahují čísla z roadmapy, data, jména ani pomlčky.

Vlastníci záznamů

Vlastník	Záznamy
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 a sdílená pole řádků

Kontroly

Kontroly leží v app/backend/tools/structurecheck. Většina potřebuje -tags structure.

Kontrola	Hlídá
TestTopLayout	Složky nejvyšší úrovně repozitáře
TestModuleSet, TestCoreSet, TestPackageMap	Složky povolené v internal/ a internal/core/
TestModuleEdges	Pořadí vrstev
TestModuleImportsRootOnly	Importy jen kořenového balíčku
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Importy jádra, pořadí řad a názvy
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	Umístění SQL a vlastníky tabulek
TestGoFileNames, TestNoBannedPackageNames	Názvy souborů a balíčků
TestFileSizeCap, TestCorePackageSize	Velikost souborů a balíčků jádra
TestCommentHygiene	Pravidla pro komentáře výše
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Přesun nezmění žádnou trasu, migraci, název hlavičky HTTP ani klíč JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Staré adresy stránek zůstanou pryč z kódu, testů i dokumentace
TestNoDependencyBotConfig	V .github není soubor dependency botu

Související

• Architektura
• Testování
• Trasy API