Modules

Choisissez le module concerné par votre changement, et sachez quels modules il peut appeler.

Avant de commencer

• Lisez Architecture pour la carte des dossiers et les règles.
• Chaque module porte le même nom dans app/backend/internal/<module>/, et dans app/frontend/src/lib/<module>/ et app/tests/<module>/ quand il a des écrans ou des tests dans le navigateur.

Trouver le bon module

Module	Rôle
requests	Les demandes, les approbations, les règles de demande, les listes externes, les signalements
movies	Les films, les éditions, les collections, la recherche et le rangement
shows	Les séries, les saisons, les épisodes, la recherche et le rangement
music	Les artistes, les albums, les pistes, la recherche et le rangement
sources	Les sources, le pont Jackett et Prowlarr, la recherche de releases
downloads	Les clients de téléchargement, la file, les fichiers déjà vus, les correspondances de chemins, les étiquettes, les choix de copie
subtitles	Les langues de sous-titres, les sites, la correspondance et l’enregistrement
discover	Explore, Popular, Search, People, Calendar, les pages de titre
suggest	Le choix et l’ordre des rangées et des étagères (backend seulement)
mediafiles	Les enregistrements du catalogue, les règles de sélection, le nommage, les paquets de données, les détails des médias
importer	L’import de fichiers : décompression, étiquettes, correspondance (backend seulement)
library	Les dossiers de bibliothèque, l’adoption et le renommage (backend seulement)
metadata	Le client de données externes, les recherches de musique, les échelles de classification, les bandes-annonces
mediaservers	Dire à Plex, Jellyfin et Emby de regarder à nouveau
accounts	Les utilisateurs, la connexion, l’authentification unique (SSO), la connexion des applications d’IA, les limites pour enfants, les choix d’affichage
alerts	Les canaux d’alerte et le moment où ils parlent
migrate	La reprise des données d’applications plus anciennes
arrapi	L’API de type Sonarr et Radarr
ai	Les connexions d’applications d’IA (en réserve)
backups	La création, la conservation et la restauration des sauvegardes
health	Les contrôles de santé, le diagnostic, l’archive de diagnostic
updates	La recherche de mises à jour et la liste signée des mises à jour
setup	L’assistant de premier lancement

Ordre des couches

Un module importe seulement une couche inférieure. Rien n’importe discover. tools/structurecheck/allow.go fait référence.

Couche	Modules
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 votre module a besoin de quelque chose d’une couche supérieure, ne l’importez pas. Faites passer des données simples par le module supérieur, ou définissez dans le module inférieur une petite interface que wiring.go remplit.

Ajouter une route ou un module

Nouvelle route

Enregistrez-la dans le routes.go du module, avec sa permission. openapi.json est généré à partir des routes, et un test échoue au moindre écart. Les chemins et les noms de champs déjà publiés restent. Ajoutez des champs, ne les renommez jamais. Ensuite, réécrivez Routes de l’API avec go run ./app/backend/tools/apidoc.

Nouveau module

Essayez d’abord de faire entrer votre changement dans les 23 modules, et ouvrez une issue avant d’en ajouter un. Un nouveau module a besoin de son dossier backend (plus lib/<module>/ et app/tests/<module>/ s’il a des écrans), d’une place dans l’ordre des couches dans tools/structurecheck, et d’une ligne dans wiring.go.

Si ça ne fonctionne pas

Symptôme. TestModuleEdges échoue. Cause. Un module en importe un autre de la même couche ou d’une couche supérieure. Solution. Faites passer des données simples depuis le module supérieur, ou ajoutez une petite interface câblée dans wiring.go.

Symptôme. TestSQLOnlyInStore ou TestTableOwnership échoue. Cause. Du SQL se trouve hors d’un fichier store*.go, ou touche à la table d’un autre module. Solution. Déplacez la requête dans le store du propriétaire et appelez le service du propriétaire par ID.

Pour les experts

Autres règles

• Un module importe seulement le paquet racine d’un autre module.
• Les fonctions de store prennent un database.Querier. Lisez les lignes d’un autre module par son service, par ID, et passez les longues listes d’ID sous forme d’un seul tableau JSON avec json_each(?).
• settings, schedules, secrets, jobs et events appartiennent à core. Chaque groupe de paramètres a un seul module propriétaire. Pour modifier le groupe d’un autre module, appelez son propriétaire.
• Chaque appel vers l’extérieur passe par core/outbound.
• Les paquets de core sont rangés par lignes, de haut en bas : parts, webserver et startup, logs, jobs et model, outbound et secrets, puis database, files et releasename. Un paquet de core importe seulement sa propre ligne ou une ligne plus basse.
• Noms : les fichiers Go sont en minuscules avec des tirets bas, les composants Svelte sont en PascalCase, et les fichiers TypeScript, de documentation, de tests et de déploiement sont en kebab-case. Les fichiers Python utilisent des tirets bas pour pouvoir être importés. Les dossiers dans app/ sont en minuscules, en un seul mot.
• Renommez le code librement, mais tout ce qui est stocké ou envoyé garde son nom : les tables et les colonnes, les clés de paramètres, les champs JSON, les noms de tâches et les noms d’interrupteurs.
• Les commentaires ne contiennent pas de numéros de feuille de route, de dates, de noms ni de tirets cadratins.

Propriétaires des enregistrements

Propriétaire	Enregistrements
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 et les champs de ligne partagés

Les contrôles

Les contrôles sont dans app/backend/tools/structurecheck. La plupart ont besoin de -tags structure.

Contrôle	Vérifie
TestTopLayout	Les dossiers à la racine du dépôt
TestModuleSet, TestCoreSet, TestPackageMap	Les dossiers autorisés dans internal/ et internal/core/
TestModuleEdges	L’ordre des couches
TestModuleImportsRootOnly	Les imports du paquet racine seulement
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Les imports de core, l’ordre des lignes et les noms
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	L’emplacement du SQL et les propriétaires des tables
TestGoFileNames, TestNoBannedPackageNames	Les noms de fichiers et de paquets
TestFileSizeCap, TestCorePackageSize	La taille des fichiers et des paquets de core
TestCommentHygiene	Les règles sur les commentaires ci-dessus
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Un déplacement ne change aucune route, aucune migration, aucun nom d’en-tête HTTP ni aucune clé JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Les anciennes adresses de pages restent absentes du code, des tests et de la documentation
TestNoDependencyBotConfig	Aucun fichier de bot de dépendances dans .github

Voir aussi

• Architecture
• Tests
• Routes de l’API