Module

Fortgeschritten

Wähle das Modul, in das deine Änderung gehört, und erfahre, welche Module es aufrufen darf.

Bevor du beginnst

Lies Architektur für die Ordnerübersicht und die Regeln.
Jedes Modul heißt in app/backend/internal/<module>/ gleich, und ebenso in app/frontend/src/lib/<module>/ und app/tests/<module>/, wenn es Ansichten oder Browsertests hat.

Das richtige Modul finden

Modul	Aufgabe
`requests`	Anfragen, Genehmigungen, Anfrageregeln, externe Listen, Meldungen
`movies`	Filmtitel, Editionen, Reihen, Suche und Ordnen
`shows`	Serien, Staffeln, Folgen, Suche und Ordnen
`music`	Künstler, Alben, Tracks, Suche und Ordnen
`sources`	Quellen, die Brücke zu Jackett und Prowlarr, Release-Suche
`downloads`	Downloader, die Warteschlange, gesehene Dateien, Pfadzuordnungen, Tags, Kopieroptionen
`subtitles`	Untertitelsprachen, Seiten, Zuordnung und Speichern
`discover`	Entdecken, Beliebt, Suche, Personen, Kalender, Titelseiten
`suggest`	Auswählen und Sortieren von Reihen und Regalen (nur Backend)
`mediafiles`	Katalogdatensätze, Auswahlregeln, Benennung, Datenpakete, Mediendetails
`importer`	Dateiimport: Entpacken, Tags, Zuordnung (nur Backend)
`library`	Bibliotheksordner, Übernehmen und Umbenennen (nur Backend)
`metadata`	Der Client für externe Daten, Musikabfragen, Bewertungsstufen, Trailer
`mediaservers`	Plex, Jellyfin und Emby sagen, dass sie neu nachsehen sollen
`accounts`	Benutzer, Anmeldung, Single Sign-on, Anmeldung für KI-Apps, Kinderlimits, Anzeigeoptionen
`alerts`	Benachrichtigungskanäle und wann sie sich melden
`migrate`	Daten aus bisherigen Apps herüberholen
`arrapi`	Die API im Stil von Sonarr und Radarr
`ai`	Verbindungen zu KI-Apps (zurückgestellt)
`backups`	Backups erstellen, aufbewahren und wiederherstellen
`health`	Zustandsprüfungen, der Doctor, das Support-Paket
`updates`	Die Update-Prüfung und die signierte Update-Liste
`setup`	Der Assistent für den ersten Start

Reihenfolge der Schichten

Ein Modul importiert nur eine tiefere Schicht. Nichts importiert discover. Maßgeblich ist tools/structurecheck/allow.go.

Schicht	Module
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`

Braucht dein Modul etwas aus einer höheren Schicht, dann importiere sie nicht. Lass das höhere Modul einfache Daten nach unten reichen, oder lege im tieferen ein kleines Interface fest, das wiring.go füllt.

Eine Route oder ein Modul hinzufügen

Neue Route

Melde sie in der routes.go des Moduls mit ihrer Berechtigung an. openapi.json entsteht aus den Routen, und ein Test schlägt bei Abweichungen fehl. Veröffentlichte Pfade und Feldnamen bleiben. Füge Felder hinzu, benenne sie nie um. Schreibe danach API-Routen mit go run ./app/backend/tools/apidoc neu.

Neues Modul

Versuche zuerst, deine Änderung in den 23 unterzubringen, und öffne ein Issue, bevor du eines hinzufügst. Ein neues Modul braucht seinen Backend-Ordner (dazu lib/<module>/ und app/tests/<module>/, wenn es Ansichten hat), einen Platz in der Reihenfolge der Schichten in tools/structurecheck und eine Zeile in wiring.go.

Wenn es nicht funktioniert

Symptom. TestModuleEdges schlägt fehl. Ursache. Ein Modul importiert eines aus derselben oder einer höheren Schicht. Lösung. Reiche einfache Daten aus dem höheren Modul nach unten, oder füge ein kleines Interface hinzu, das in wiring.go verdrahtet wird.

Symptom. TestSQLOnlyInStore oder TestTableOwnership schlägt fehl. Ursache. SQL steht außerhalb einer store*.go-Datei oder greift auf die Tabelle eines anderen Moduls zu. Lösung. Verschiebe die Abfrage in den Store des Eigentümers und rufe dessen Service per ID auf.

Für Fortgeschrittene

Weitere Regeln

Ein Modul importiert von einem anderen Modul nur das Wurzelpaket.
Store-Funktionen nehmen einen database.Querier entgegen. Lies die Zeilen eines anderen Moduls über dessen Service per ID, und übergib lange ID-Listen als ein JSON-Array mit json_each(?).
settings, schedules, secrets, jobs und events gehören core. Jede Einstellungsgruppe hat genau ein Modul als Eigentümer. Um die Gruppe eines anderen Moduls zu ändern, rufst du ihren Eigentümer auf.
Jeder Aufruf nach außen läuft über core/outbound.
Core-Pakete liegen in Reihen, von oben nach unten: parts, webserver und startup, logs, jobs und model, outbound und secrets, dann database, files und releasename. Ein Core-Paket importiert nur aus seiner eigenen Reihe oder tiefer.
Namen: Go-Dateien sind kleingeschrieben mit Unterstrichen, Svelte-Bausteine stehen in PascalCase, und TypeScript-, Doku-, Test- und Deploy-Dateien in kebab-case. Python-Dateien verwenden Unterstriche, damit sie importiert werden können. Ordner in app/ sind kleingeschrieben und bestehen aus einem Wort.
Benenne Code frei um, aber alles, was gespeichert oder gesendet wird, behält seinen Namen: Tabellen und Spalten, Einstellungsschlüssel, JSON-Felder, Aufgabennamen und Schalternamen.
Kommentare enthalten keine Roadmap-Nummern, Daten, Namen oder Geviertstriche.

Eigentümer der Datensätze

Eigentümer	Datensätze
`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 und die gemeinsamen Zeilenfelder

Die Prüfungen

Die Prüfungen liegen in app/backend/tools/structurecheck. Die meisten brauchen -tags structure.

Prüfung	Sichert
`TestTopLayout`	Die obersten Ordner des Repos
`TestModuleSet`, `TestCoreSet`, `TestPackageMap`	Ordner, die in `internal/` und `internal/core/` erlaubt sind
`TestModuleEdges`	Reihenfolge der Schichten
`TestModuleImportsRootOnly`	Nur Importe des Wurzelpakets
`TestCoreImportsNoModule`, `TestCoreRowOrder`, `TestCoreNamesNoModuleTable`	Importe, Reihenfolge der Reihen und Namen in core
`TestSQLOnlyInStore`, `TestTableOwnership`, `TestSQLAllowlistShrinks`, `TestSeedSQLAllowlist`	Wo SQL steht und wem Tabellen gehören
`TestGoFileNames`, `TestNoBannedPackageNames`	Datei- und Paketnamen
`TestFileSizeCap`, `TestCorePackageSize`	Größe von Dateien und Core-Paketen
`TestCommentHygiene`	Die Kommentarregeln oben
`TestRouteTableUnchanged`, `TestMigrationsUnchanged`, `TestHeaderAndJSONLiteralsUnchanged`	Ein Verschieben ändert keine Route, keine Migration, keinen HTTP-Header-Namen und keinen JSON-Schlüssel
`TestNoOldPageAddresses`, `TestNoOldPagesInTestsOrDocs`	Alte Seitenadressen bleiben aus Code, Tests und Doku verschwunden
`TestNoDependencyBotConfig`	Keine Datei für einen Abhängigkeits-Bot in `.github`