Модули

Для опытных

Выберите модуль, к которому относится ваше изменение, и узнайте, какие модули он может вызывать.

Перед началом

Прочитайте Архитектуру: там карта папок и правила.
У каждого модуля одно и то же имя в 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`	Пользователи, вход, единый вход (SSO), вход для ИИ-приложений, детские ограничения, настройки просмотра
`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` нет файла бота зависимостей

См. также

HolyArrs бесплатен. Если он сэкономил вам время, поставьте звезду на GitHub, станьте спонсором или угостите меня кофе.