Mòduls

Tria el mòdul al qual pertany el teu canvi i sàpigues a quins mòduls pot cridar.

Abans de començar

• Llegeix Arquitectura per al mapa de carpetes i les regles.
• Cada mòdul té el mateix nom a app/backend/internal/<module>/, i a app/frontend/src/lib/<module>/ i app/tests/<module>/ quan té pantalles o proves al navegador.

Troba el mòdul correcte

Mòdul	Fa
requests	Demanar, aprovacions, regles de sol·licituds, llistes externes, informes
movies	Títols de pel·lícules, edicions, col·leccions, cerca i organització
shows	Sèries, temporades, episodis, cerca i organització
music	Artistes, àlbums, cançons, cerca i organització
sources	Fonts, el pont de Jackett i Prowlarr, cerca de Llançaments
downloads	Gestors de baixades, la cua, fitxers vistos, mapes de rutes, etiquetes, opcions de còpia
subtitles	Idiomes de subtítols, llocs, coincidència i desat
discover	Explorar, Popular, Cercar, Persones, Calendari, pàgines de títols
suggest	Triar i ordenar files i prestatges (només backend)
mediafiles	Registres del catàleg, regles d’elecció, noms, paquets de dades, detalls dels fitxers multimèdia
importer	Importació de fitxers: descomprimir, etiquetes, coincidència (només backend)
library	Carpetes de la Biblioteca, adopció i canvi de nom (només backend)
metadata	El client de dades externes, consultes de música, escales de classificació, tràilers
mediaservers	Dir a Plex, Jellyfin i Emby que tornin a mirar
accounts	Usuaris, inici de sessió, inici de sessió únic, inici de sessió de l’app d’IA, límits per a nens, opcions de visionat
alerts	Canals d’avisos i quan parlen
migrate	Portar dades des de les apps anteriors
arrapi	L’API a l’estil de Sonarr i Radarr
ai	Connexions d’apps d’IA (retingudes)
backups	Fer, conservar i restaurar còpies de seguretat
health	Comprovacions de salut, el doctor, el paquet de suport
updates	La comprovació d’actualitzacions i la llista d’actualitzacions signada
setup	L’assistent del primer inici

Ordre de capes

Un mòdul només importa una capa inferior. Ningú importa discover. tools/structurecheck/allow.go és la font de veritat.

Capa	Mòduls
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

Si el teu mòdul necessita alguna cosa d’una capa superior, no la importis. Fes que el mòdul superior passi dades simples cap avall, o defineix una interfície petita a l’inferior que omple wiring.go.

Afegeix una ruta o un mòdul

Ruta nova

Registra-la al routes.go del mòdul amb el seu permís. openapi.json surt de les rutes, i una prova falla si no coincideixen. Els camins i els noms de camps ja publicats es queden. Afegeix camps, mai no els canviïs de nom. Després reescriu Rutes de l’API amb go run ./app/backend/tools/apidoc.

Mòdul nou

Primer encaixa el teu canvi en els 23 que hi ha, i obre una incidència abans d’afegir-ne un. Un mòdul nou necessita la seva carpeta de backend (i lib/<module>/ i app/tests/<module>/ si té pantalles), un lloc a l’ordre de capes a tools/structurecheck i una línia a wiring.go.

Si no funciona

Símptoma. Falla TestModuleEdges. Causa. Un mòdul n’importa un de la mateixa capa o d’una de superior. Solució. Passa dades simples cap avall des del mòdul superior, o afegeix una interfície petita connectada a wiring.go.

Símptoma. Falla TestSQLOnlyInStore o TestTableOwnership. Causa. L’SQL és fora d’un fitxer store*.go, o toca la taula d’un altre mòdul. Solució. Mou la consulta al store del propietari i crida el servei del propietari amb l’ID.

Per a experts

Més regles

• Un mòdul només importa el paquet arrel d’un altre mòdul.
• Les funcions del store reben un database.Querier. Llegeix les files d’un altre mòdul a través del seu servei amb l’ID, i passa les llistes llargues d’ID com una sola matriu JSON amb json_each(?).
• settings, schedules, secrets, jobs i events són del core. Cada grup de paràmetres té un mòdul propietari. Per canviar el grup d’un altre mòdul, crida el seu propietari.
• Cada crida a l’exterior passa per core/outbound.
• Els paquets del core van en files, de dalt a baix: parts, webserver i startup, logs, jobs i model, outbound i secrets, i després database, files i releasename. Un paquet del core només importa de la seva pròpia fila o d’una d’inferior.
• Noms: els fitxers de Go van en minúscules amb guions baixos, les parts de Svelte en PascalCase, i els fitxers de TypeScript, documents, proves i desplegament en kebab-case. Els fitxers de Python usen guions baixos per poder-se importar. Les carpetes d’app/ van en minúscules, d’una sola paraula.
• Canvia el nom del codi lliurement, però tot el que es desa o s’envia conserva el seu nom: taules i columnes, claus de paràmetres, camps JSON, noms de tasques i noms d’interruptors.
• Els comentaris no porten números del full de ruta, dates, noms ni guions llargs.

Propietaris dels registres

Propietari	Registres
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 els camps de fila compartits

Les comprovacions

Les comprovacions són a app/backend/tools/structurecheck. La majoria necessiten -tags structure.

Comprovació	Garanteix
TestTopLayout	Carpetes de dalt del repositori
TestModuleSet, TestCoreSet, TestPackageMap	Carpetes permeses a internal/ i internal/core/
TestModuleEdges	Ordre de capes
TestModuleImportsRootOnly	Només importacions del paquet arrel
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Importacions del core, ordre de files i noms
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	On va l’SQL i qui és propietari de cada taula
TestGoFileNames, TestNoBannedPackageNames	Noms de fitxers i paquets
TestFileSizeCap, TestCorePackageSize	Mida dels fitxers i dels paquets del core
TestCommentHygiene	Les regles dels comentaris de dalt
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Un moviment no canvia cap ruta, migració, nom de capçalera HTTP ni clau JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Les adreces de pàgines antigues no tornen al codi, a les proves ni als documents
TestNoDependencyBotConfig	Cap fitxer de bot de dependències a .github

Relacionat

• Arquitectura
• Proves
• Rutes de l’API