Moduli

Scegli il modulo a cui appartiene la tua modifica e scopri quali moduli può chiamare.

Prima di iniziare

• Leggi Architettura per la mappa delle cartelle e le regole.
• Ogni modulo ha lo stesso nome in app/backend/internal/<module>/, e in app/frontend/src/lib/<module>/ e app/tests/<module>/ quando ha schermate o test nel browser.

Trova il modulo giusto

Modulo	Si occupa di
requests	Richieste, approvazioni, regole delle richieste, liste esterne, segnalazioni
movies	Titoli dei film, edizioni, raccolte, ricerca e organizzazione
shows	Serie, stagioni, episodi, ricerca e organizzazione
music	Artisti, album, tracce, ricerca e organizzazione
sources	Fonti, il ponte con Jackett e Prowlarr, ricerca delle release
downloads	Downloader, la coda, file già visti, mappe dei percorsi, tag, scelte sulle copie
subtitles	Lingue dei sottotitoli, siti, abbinamento e salvataggio
discover	Esplora, Popolari, Cerca, Persone, Calendario, pagine dei titoli
suggest	Scelta e ordine di righe e scaffali (solo backend)
mediafiles	Record del catalogo, regole di scelta, assegnazione dei nomi, pacchetti di dati, dettagli multimediali
importer	Importazione dei file: decompressione, tag, abbinamento (solo backend)
library	Cartelle della Libreria, adozione e rinomina (solo backend)
metadata	Il client dei dati esterni, ricerche musicali, scale delle classificazioni, trailer
mediaservers	Dire a Plex, Jellyfin ed Emby di controllare di nuovo
accounts	Utenti, accesso, accesso singolo, accesso delle app AI, limiti per i bambini, scelte di visione
alerts	Canali di avviso e quando parlano
migrate	Portare i dati dalle app precedenti
arrapi	L’API in stile Sonarr e Radarr
ai	Connessioni delle app AI (in sospeso)
backups	Creare, conservare e ripristinare i backup
health	Controlli di salute, il doctor, il pacchetto di supporto
updates	Il controllo degli aggiornamenti e l’elenco firmato degli aggiornamenti
setup	La procedura guidata del primo avvio

Ordine dei livelli

Un modulo importa solo un livello inferiore. Nessuno importa discover. La fonte di verità è tools/structurecheck/allow.go.

Livello	Moduli
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

Se il tuo modulo ha bisogno di qualcosa da un livello superiore, non importarlo. Fai passare dati semplici dal modulo superiore, oppure definisci una piccola interfaccia in quello inferiore che wiring.go riempie.

Aggiungi una route o un modulo

Nuova route

Registrala nel routes.go del modulo con il suo permesso. openapi.json viene generato dalle route e un test fallisce se non coincidono. I percorsi e i nomi dei campi già pubblicati restano. Aggiungi campi, non rinominarli mai. Poi riscrivi Route dell’API con go run ./app/backend/tools/apidoc.

Nuovo modulo

Prima prova a far rientrare la tua modifica nei 23 esistenti. Apri un’issue prima di aggiungerne uno. Un nuovo modulo ha bisogno della sua cartella nel backend (più lib/<module>/ e app/tests/<module>/ se ha schermate), di un posto nell’ordine dei livelli in tools/structurecheck e di una riga in wiring.go.

Se non funziona

Sintomo. TestModuleEdges fallisce. Causa. Un modulo ne importa uno dello stesso livello o di un livello superiore. Soluzione. Passa dati semplici dal modulo superiore, oppure aggiungi una piccola interfaccia collegata in wiring.go.

Sintomo. TestSQLOnlyInStore o TestTableOwnership fallisce. Causa. L’SQL si trova fuori da un file store*.go, oppure tocca la tabella di un altro modulo. Soluzione. Sposta la query nello store del proprietario e chiama il servizio del proprietario tramite ID.

Per esperti

Altre regole

• Un modulo importa solo il pacchetto radice di un altro modulo.
• Le funzioni dello store prendono un database.Querier. Leggi le righe di un altro modulo tramite il suo servizio con gli ID, e passa le liste lunghe di ID come un unico array JSON con json_each(?).
• settings, schedules, secrets, jobs ed events appartengono a core. Ogni gruppo di impostazioni ha un solo modulo proprietario. Per cambiare il gruppo di un altro modulo, chiama il suo proprietario.
• Ogni chiamata verso l’esterno passa da core/outbound.
• I pacchetti core stanno su righe, dall’alto in basso: parts, webserver e startup, logs, jobs e model, outbound e secrets, poi database, files e releasename. Un pacchetto core importa solo la propria riga o una inferiore.
• Nomi: i file Go sono in minuscolo con i trattini bassi, le parti Svelte sono in PascalCase, e i file TypeScript, docs, test e deploy sono in kebab-case. I file Python usano i trattini bassi per poter essere importati. Le cartelle in app/ sono in minuscolo, di una sola parola.
• Rinomina pure il codice, ma tutto ciò che viene salvato o inviato mantiene il suo nome: tabelle e colonne, chiavi delle impostazioni, campi JSON, nomi dei processi e nomi degli interruttori.
• I commenti non contengono numeri della roadmap, date, nomi o lineette em.

Proprietari dei record

Proprietario	Record
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 e i campi di riga condivisi

I controlli

I controlli si trovano in app/backend/tools/structurecheck. La maggior parte richiede -tags structure.

Controllo	Verifica
TestTopLayout	Le cartelle principali del repository
TestModuleSet, TestCoreSet, TestPackageMap	Le cartelle ammesse in internal/ e internal/core/
TestModuleEdges	Ordine dei livelli
TestModuleImportsRootOnly	Solo import del pacchetto radice
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Import di core, ordine delle righe e nomi
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	Posizione dell’SQL e proprietari delle tabelle
TestGoFileNames, TestNoBannedPackageNames	Nomi di file e pacchetti
TestFileSizeCap, TestCorePackageSize	Dimensione dei file e dei pacchetti core
TestCommentHygiene	Le regole sui commenti qui sopra
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Uno spostamento non cambia nessuna route, migrazione, nome di header HTTP o chiave JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	I vecchi indirizzi delle pagine non tornano nel codice, nei test e nei documenti
TestNoDependencyBotConfig	Nessun file di bot per le dipendenze in .github

Correlati

• Architettura
• Test
• Route dell’API