モジュール

上級者

変更が属するモジュールを選び、そのモジュールがどのモジュールを呼び出せるかを確認します。

始める前に

アーキテクチャで、フォルダーのマップとルールを読みます。
各モジュールは app/backend/internal/<module>/ で同じ名前を使います。画面やブラウザーテストがある場合は、app/frontend/src/lib/<module>/ と app/tests/<module>/ でも同じ名前です。

正しいモジュールを探す

モジュール	担当
`requests`	リクエスト、承認、リクエストのルール、外部リスト、報告
`movies`	映画のタイトル、エディション、セット、検索、整理
`shows`	番組、シーズン、エピソード、検索、整理
`music`	アーティスト、アルバム、曲、検索、整理
`sources`	ソース、Jackett と Prowlarr のブリッジ、リリースの検索
`downloads`	ダウンローダー、キュー、確認済みファイル、パスの対応付け、タグ、コピーの選択
`subtitles`	字幕の言語、サイト、照合、保存
`discover`	Explore、Popular、Search、People、Calendar、タイトルページ
`suggest`	行と棚の選択と並び順(バックエンドのみ)
`mediafiles`	カタログのレコード、選定ルール、命名、データパック、メディアの詳細
`importer`	ファイルのインポート: 展開、タグ、照合(バックエンドのみ)
`library`	ライブラリフォルダー、管理対象への追加、名前の変更(バックエンドのみ)
`metadata`	外部データのクライアント、音楽の検索、レーティングの段階、予告編
`mediaservers`	Plex、Jellyfin、Emby に再スキャンを依頼
`accounts`	ユーザー、サインイン、シングルサインオン、AI アプリのサインイン、子ども向けの制限、視聴の設定
`alerts`	通知チャンネルと、通知を送るタイミング
`migrate`	以前のアプリからのデータの移行
`arrapi`	Sonarr と Radarr 形式の API
`ai`	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 はルートから作られ、ずれがあるとテストが失敗します。リリース済みのパスとフィールド名はそのまま残します。フィールドは追加するだけで、名前は変更しません。そのあと go run ./app/backend/tools/apidoc で API ルートを書き直します。

新しいモジュール

まずは変更を既存の 23 個に収められないか考え、追加する前に issue を作成します。新しいモジュールには、バックエンドのフォルダー(画面がある場合は lib/<module>/ と app/tests/<module>/ も)、tools/structurecheck のレイヤーの順序の中での位置、wiring.go の 1 行が必要です。

うまくいかないとき

症状。 TestModuleEdges が失敗する。 原因。 モジュールが、同じレイヤーか上のレイヤーのモジュールをインポートしています。 対処。 上のモジュールから単純なデータを下に渡すか、wiring.go でつなぐ小さなインターフェースを追加します。

症状。 TestSQLOnlyInStore または TestTableOwnership が失敗する。 原因。 SQL が store*.go ファイルの外にあるか、ほかのモジュールのテーブルに触れています。 対処。 クエリを所有者のストアに移し、所有者のサービスを ID で呼び出します。

上級者向け

そのほかのルール

モジュールがインポートできるのは、ほかのモジュールのルートパッケージだけです。
ストアの関数は database.Querier を受け取ります。ほかのモジュールの行は、そのサービスを通して ID で読みます。長い ID のリストは、json_each(?) を使って 1 つの JSON 配列として渡します。
settings、schedules、secrets、jobs、events は core のものです。設定のグループには、それぞれ所有者のモジュールが 1 つあります。ほかのモジュールのグループを変更するときは、その所有者を呼び出します。
外部への呼び出しはすべて core/outbound を通します。
core のパッケージは、上から下へ段に並びます: parts、webserver と startup、logs、jobs と model、outbound と secrets、そして database、files、releasename。core のパッケージがインポートできるのは、自分の段かそれより下だけです。
名前: Go のファイルは小文字とアンダースコア、Svelte のパーツは PascalCase、TypeScript、ドキュメント、テスト、デプロイのファイルは kebab-case です。Python のファイルは、インポートできるようにアンダースコアを使います。app/ 内のフォルダーは小文字の 1 語です。
コードの名前は自由に変更できますが、保存されるものや送信されるものは名前を変えません。テーブルと列、設定キー、JSON のフィールド、ジョブ名、スイッチ名が対象です。
コメントには、ロードマップの番号、日付、名前、em ダッシュを入れません。

レコードの所有者

所有者	レコード
`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` に依存関係ボットのファイルがないこと