Модулі

Обери модуль, до якого належить твоя зміна, і дізнайся, які модулі їй можна викликати.

Перш ніж почати

• Прочитай Архітектуру, де є карта тек і правила.
• Кожен модуль має однакову назву в app/backend/internal/<module>/, а також у app/frontend/src/lib/<module>/ і app/tests/<module>/, якщо в нього є екрани чи браузерні тести.

Знайди потрібний модуль

Модуль	Що робить
requests	Запити, схвалення, правила запитів, зовнішні списки, звіти
movies	Фільми, видання, набори, пошук і впорядкування
shows	Серіали, сезони, серії, пошук і впорядкування
music	Виконавці, альбоми, треки, пошук і впорядкування
sources	Джерела, міст до Jackett і Prowlarr, пошук релізів
downloads	Завантажувачі, черга, побачені файли, зіставлення шляхів, теги, вибір копій
subtitles	Мови субтитрів, сайти, зіставлення й збереження
discover	Огляд, Популярне, Пошук, Люди, Календар, сторінки тайтлів
suggest	Вибір і впорядкування рядків та полиць (лише бекенд)
mediafiles	Записи каталогу, правила вибору, іменування, пакети даних, подробиці про медіа
importer	Імпорт файлів: розпакування, теги, зіставлення (лише бекенд)
library	Теки бібліотеки, прийняття й перейменування (лише бекенд)
metadata	Клієнт зовнішніх даних, пошук музики, шкали рейтингів, трейлери
mediaservers	Сповіщення Plex, Jellyfin і Emby, щоб вони перевірили наново
accounts	Користувачі, вхід, єдиний вхід, вхід застосунків ШІ, дитячі ліміти, вибір перегляду
alerts	Канали сповіщень і те, коли вони надсилають повідомлення
migrate	Перенесення даних із попередніх застосунків
arrapi	API у стилі Sonarr і Radarr
ai	Підключення застосунків ШІ (відкладена функція)
backups	Створення, зберігання й відновлення бекапів
health	Перевірки справності, доктор, пакет для підтримки
updates	Перевірка оновлень і підписаний список оновлень
setup	Майстер першого запуску

Порядок шарів

Модуль імпортує лише нижчий шар. Ніхто не імпортує discover. Джерело істини — tools/structurecheck/allow.go.

Шар	Модулі
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

Якщо твоєму модулю щось потрібне з вищого шару, не імпортуй його. Нехай вищий модуль передасть вниз прості дані, або опиши в нижчому невеликий інтерфейс, який наповнює wiring.go.

Додай маршрут або модуль

Новий маршрут

Зареєструй його в routes.go модуля разом із дозволом. openapi.json береться з маршрутів, і тест падає, коли вони розходяться. Маршрути й назви полів, що вже вийшли, лишаються. Поля додавай, ніколи не перейменовуй. Потім перепиши Маршрути API командою go run ./app/backend/tools/apidoc.

Новий модуль

Спершу спробуй вкласти зміну в наявні 23 і відкрий issue, перш ніж додавати новий. Новому модулю потрібні тека бекенда (а також lib/<module>/ і app/tests/<module>/, якщо є екрани), місце в порядку шарів у tools/structurecheck і рядок у wiring.go.

Якщо не працює

Ознака. Падає TestModuleEdges. Причина. Модуль імпортує модуль того самого або вищого шару. Рішення. Передай прості дані вниз із вищого модуля або додай невеликий інтерфейс, який наповнює wiring.go.

Ознака. Падає TestSQLOnlyInStore або TestTableOwnership. Причина. SQL лежить поза файлом store*.go або торкається таблиці іншого модуля. Рішення. Перенеси запит у store власника й виклич сервіс власника за ID.

Для досвідчених

Інші правила

• Модуль імпортує лише кореневий пакет іншого модуля.
• Функції store приймають database.Querier. Рядки іншого модуля читай через його сервіс за ID, а довгі списки ID передавай одним масивом JSON через json_each(?).
• settings, schedules, secrets, jobs і events належать core. Кожна група параметрів має одного модуля-власника. Щоб змінити групу іншого модуля, звернися до її власника.
• Кожен зовнішній виклик іде через core/outbound.
• Пакети core стоять рядами згори донизу: parts, webserver і startup, logs, jobs і model, outbound і secrets, потім database, files і releasename. Пакет core імпортує лише зі свого ряду або нижчого.
• Назви: файли Go пишуться малими літерами з підкресленнями, частини Svelte — у PascalCase, а файли TypeScript, документації, тестів і розгортання — у kebab-case. Файли Python пишуться з підкресленнями, щоб їх можна було імпортувати. Теки в app/ — малими літерами, одне слово.
• Код перейменовуй вільно, але все, що зберігається чи надсилається, лишається під своєю назвою: таблиці й стовпці, ключі параметрів, поля JSON, назви завдань і назви перемикачів.
• У коментарях немає номерів із дорожньої карти, дат, імен і довгих тире.

Власники записів

Власник	Записи
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	Верхні теки репозиторію
TestModuleSet, TestCoreSet, TestPackageMap	Теки, дозволені в internal/ і internal/core/
TestModuleEdges	Порядок шарів
TestModuleImportsRootOnly	Імпорти лише кореневого пакета
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Імпорти core, порядок рядів і назви
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	Розміщення SQL і власники таблиць
TestGoFileNames, TestNoBannedPackageNames	Назви файлів і пакетів
TestFileSizeCap, TestCorePackageSize	Розмір файлів і пакетів core
TestCommentHygiene	Правила коментарів, наведені вище
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Перенесення не змінює жодного маршруту, міграції, назви заголовка HTTP чи ключа JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Старі адреси сторінок не повертаються в код, тести й документацію
TestNoDependencyBotConfig	У .github немає файлу бота залежностей

Пов’язане

• Архітектура
• Тестування
• Маршрути API