Modules

Διάλεξε το module όπου ανήκει η αλλαγή σου και μάθε ποια modules επιτρέπεται να καλέσει.

Πριν ξεκινήσεις

• Διάβασε την Αρχιτεκτονική για τον χάρτη των φακέλων και τους κανόνες.
• Κάθε module έχει το ίδιο όνομα στο app/backend/internal/<module>/, και στα app/frontend/src/lib/<module>/ και app/tests/<module>/ όταν έχει οθόνες ή δοκιμές στο πρόγραμμα περιήγησης.

Βρες το σωστό module

Module	Κάνει
requests	Αιτήματα, εγκρίσεις, κανόνες αιτημάτων, εξωτερικές λίστες, αναφορές
movies	Τίτλους ταινιών, εκδόσεις, σετ, αναζήτηση και οργάνωση
shows	Σειρές, σεζόν, επεισόδια, αναζήτηση και οργάνωση
music	Καλλιτέχνες, άλμπουμ, κομμάτια, αναζήτηση και οργάνωση
sources	Πηγές, τη γέφυρα Jackett και Prowlarr, αναζήτηση κυκλοφοριών
downloads	Προγράμματα λήψεων, την ουρά, αρχεία που έχουν ήδη φανεί, αντιστοιχίσεις διαδρομών, ετικέτες, επιλογές αντιγράφων
subtitles	Γλώσσες υποτίτλων, ιστότοπους, αντιστοίχιση και αποθήκευση
discover	Εξερεύνηση, Popular, Αναζήτηση, Άνθρωποι, Ημερολόγιο, σελίδες τίτλων
suggest	Επιλογή και ταξινόμηση γραμμών και ραφιών (μόνο backend)
mediafiles	Εγγραφές καταλόγου, κανόνες επιλογής, ονομασία, πακέτα δεδομένων, λεπτομέρειες πολυμέσων
importer	Εισαγωγή αρχείων: αποσυμπίεση, ετικέτες, αντιστοίχιση (μόνο backend)
library	Φακέλους Βιβλιοθήκης, υιοθέτηση και μετονομασία (μόνο backend)
metadata	Τον client εξωτερικών δεδομένων, αναζητήσεις μουσικής, κλίμακες βαθμολογιών, trailers
mediaservers	Λέει σε Plex, Jellyfin και Emby να κοιτάξουν ξανά
accounts	Χρήστες, σύνδεση, ενιαία σύνδεση, σύνδεση εφαρμογών AI, όρια για παιδιά, επιλογές προβολής
alerts	Κανάλια ειδοποιήσεων και πότε μιλούν
migrate	Εισαγωγή δεδομένων από παλαιότερες εφαρμογές
arrapi	Το API σε στυλ Sonarr και Radarr
ai	Συνδέσεις εφαρμογών AI (κρατημένη λειτουργία)
backups	Δημιουργία, φύλαξη και επαναφορά αντιγράφων ασφαλείας
health	Ελέγχους υγείας, τον doctor, το πακέτο υποστήριξης
updates	Τον έλεγχο ενημερώσεων και την υπογεγραμμένη λίστα ενημερώσεων
setup	Τον οδηγό πρώτης εκκίνησης

Σειρά επιπέδων

Ένα module εισάγει μόνο χαμηλότερο επίπεδο. Κανείς δεν εισάγει το discover. Η πηγή αλήθειας είναι το tools/structurecheck/allow.go.

Επίπεδο	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

Αν το module σου χρειάζεται κάτι από ψηλότερο επίπεδο, μην το εισάγεις. Βάλε το ψηλότερο module να περάσει απλά δεδομένα προς τα κάτω, ή όρισε στο χαμηλότερο ένα μικρό interface που το συμπληρώνει το wiring.go.

Πρόσθεσε μια διαδρομή ή ένα module

Νέα διαδρομή

Δήλωσέ την στο routes.go του module μαζί με το δικαίωμά της. Το openapi.json προκύπτει από τις διαδρομές, και μια δοκιμή αποτυγχάνει αν αποκλίνει. Οι διαδρομές και τα ονόματα πεδίων που έχουν κυκλοφορήσει μένουν. Πρόσθεσε πεδία, μην τα μετονομάζεις ποτέ. Μετά ξαναγράψε το Διαδρομές API με go run ./app/backend/tools/apidoc.

Νέο module

Προσάρμοσε πρώτα την αλλαγή σου στα 23 υπάρχοντα, και άνοιξε ένα issue πριν προσθέσεις νέο. Ένα νέο module χρειάζεται τον δικό του φάκελο στο backend (και lib/<module>/ και app/tests/<module>/ αν έχει οθόνες), μια θέση στη σειρά των επιπέδων στο tools/structurecheck, και μια γραμμή στο wiring.go.

Αν δεν δουλεύει

Σύμπτωμα. Αποτυγχάνει το TestModuleEdges. Αιτία. Ένα module εισάγει άλλο του ίδιου ή ψηλότερου επιπέδου. Λύση. Πέρασε απλά δεδομένα προς τα κάτω από το ψηλότερο module, ή πρόσθεσε ένα μικρό interface που συνδέεται στο wiring.go.

Σύμπτωμα. Αποτυγχάνει το TestSQLOnlyInStore ή το TestTableOwnership. Αιτία. Η SQL βρίσκεται έξω από ένα αρχείο store*.go, ή αγγίζει πίνακα άλλου module. Λύση. Μετέφερε το query στο store του ιδιοκτήτη και κάλεσε το service του ιδιοκτήτη με ID.

Για έμπειρους

Περισσότεροι κανόνες

• Ένα module εισάγει μόνο το βασικό package ενός άλλου module.
• Οι συναρτήσεις του store παίρνουν ένα database.Querier. Διάβασε γραμμές άλλου module μέσω του service του με ID, και πέρασε μεγάλες λίστες ID ως ένα JSON array με json_each(?).
• Τα settings, schedules, secrets, jobs και events ανήκουν στο core. Κάθε ομάδα ρυθμίσεων έχει ένα module-ιδιοκτήτη. Για να αλλάξεις την ομάδα άλλου module, κάλεσε τον ιδιοκτήτη της.
• Κάθε εξωτερική κλήση περνά από το core/outbound.
• Τα πακέτα του core κάθονται σε σειρές, από πάνω προς τα κάτω: parts, webserver και startup, logs, jobs και model, outbound και secrets, μετά database, files και releasename. Ένα πακέτο του core εισάγει μόνο από τη δική του σειρά ή χαμηλότερη.
• Ονόματα: τα αρχεία Go είναι με μικρά γράμματα και κάτω παύλες, τα κομμάτια Svelte σε PascalCase, και τα αρχεία TypeScript, docs, δοκιμών και deploy σε kebab-case. Τα αρχεία Python έχουν κάτω παύλες για να μπορούν να εισαχθούν. Οι φάκελοι στο app/ έχουν μικρά γράμματα, μία λέξη.
• Μετονόμαζε τον κώδικα ελεύθερα, αλλά ό,τι αποθηκεύεται ή στέλνεται κρατά το όνομά του: πίνακες και στήλες, κλειδιά ρυθμίσεων, πεδία JSON, ονόματα εργασιών και ονόματα διακοπτών.
• Τα σχόλια δεν έχουν αριθμούς του roadmap, ημερομηνίες, ονόματα ή em dashes.

Ιδιοκτήτες εγγραφών

Ιδιοκτήτης	Εγγραφές
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 και τα κοινά πεδία γραμμών

Οι έλεγχοι

Οι έλεγχοι βρίσκονται στο app/backend/tools/structurecheck. Οι περισσότεροι θέλουν -tags structure.

Έλεγχος	Εγγυάται
TestTopLayout	Τους φακέλους ανώτατου επιπέδου του repo
TestModuleSet, TestCoreSet, TestPackageMap	Τους φακέλους που επιτρέπονται στα internal/ και internal/core/
TestModuleEdges	Τη σειρά των επιπέδων
TestModuleImportsRootOnly	Imports μόνο του βασικού package
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Imports του core, σειρά γραμμών και ονόματα
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	Τη θέση της SQL και τους ιδιοκτήτες πινάκων
TestGoFileNames, TestNoBannedPackageNames	Ονόματα αρχείων και πακέτων
TestFileSizeCap, TestCorePackageSize	Μέγεθος αρχείων και πακέτων του core
TestCommentHygiene	Τους κανόνες σχολίων παραπάνω
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Ότι μια μετακίνηση δεν αλλάζει καμία διαδρομή, migration, όνομα HTTP header ή κλειδί JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Ότι οι παλιές διευθύνσεις σελίδων δεν επιστρέφουν σε κώδικα, δοκιμές και docs
TestNoDependencyBotConfig	Ότι δεν υπάρχει αρχείο dependency bot στο .github

Σχετικά

• Αρχιτεκτονική
• Δοκιμές
• Διαδρομές API