模組

進階

選出你的變更所屬的模組，並了解它可以呼叫哪些模組。

開始之前

先讀架構，了解資料夾地圖和規則。
每個模組在 app/backend/internal/<module>/ 裡都用同一個名稱；有畫面或瀏覽器測試的話，在 app/frontend/src/lib/<module>/ 和 app/tests/<module>/ 裡也是。

找出正確的模組

模組	負責
`requests`	請求、核准、請求規則、外部清單、回報
`movies`	電影作品、版本、套組、搜尋與整理
`shows`	影集、季、集、搜尋與整理
`music`	藝人、專輯、曲目、搜尋與整理
`sources`	來源、Jackett 與 Prowlarr 橋接、發行版搜尋
`downloads`	下載器、佇列、已看過的檔案、路徑對應、tag、檔案選擇
`subtitles`	字幕語言、網站、比對與儲存
`discover`	探索、熱門、搜尋、人物、行事曆、作品頁面
`suggest`	挑選資料列與貨架並排序（僅後端）
`mediafiles`	目錄記錄、挑選規則、命名、資料包、媒體詳細資料
`importer`	檔案匯入：解壓縮、tag、比對（僅後端）
`library`	媒體庫資料夾、納入與重新命名（僅後端）
`metadata`	外部資料用戶端、音樂查詢、分級對照表、預告片
`mediaservers`	通知 Plex、Jellyfin 和 Emby 重新掃描
`accounts`	使用者、登入、Single Sign-on、AI App 登入、兒童額度、觀看選項
`alerts`	通知管道與它們何時發出通知
`migrate`	從舊的 App 帶資料過來
`arrapi`	Sonarr 和 Radarr 風格的 API
`ai`	AI App 連線（暫緩）
`backups`	建立、保存與還原 backup
`health`	健康檢查、doctor、支援封包
`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 裡的一行。

如果沒有成功

症狀。 TestModuleEdges 失敗。 原因。 有模組匯入了同一層或更高層級的模組。 解決方式。 由較高的模組把單純的資料往下傳，或加上一個在 wiring.go 裡接好的小介面。

症狀。 TestSQLOnlyInStore 或 TestTableOwnership 失敗。 原因。 SQL 放在 store*.go 檔案以外的地方，或是碰了別的模組的資料表。 解決方式。 把查詢移進擁有者的 store，並用 ID 呼叫擁有者的 service。

給進階使用者

更多規則

模組只匯入另一個模組的根 package。
Store 函式接收 database.Querier。透過別的模組的 service 用 ID 讀取它的資料列，長長的 ID 清單用 json_each(?) 以一個 JSON 陣列傳入。
settings、schedules、secrets、jobs 和 events 屬於 core。每個設定群組只有一個擁有者模組。要變更別的模組的群組，就呼叫它的擁有者。
所有對外的呼叫都經過 core/outbound。
Core packages 由上而下分成幾列：parts；webserver 和 startup；logs、jobs 和 model；outbound 和 secrets；最後是 database、files 和 releasename。一個 core package 只能匯入自己那一列或更低的列。
命名：Go 檔案用小寫加底線，Svelte 元件用 PascalCase，TypeScript、文件、測試和 deploy 檔案用 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`	repo 最上層的資料夾
`TestModuleSet`、`TestCoreSet`、`TestPackageMap`	`internal/` 和 `internal/core/` 裡允許的資料夾
`TestModuleEdges`	層級順序
`TestModuleImportsRootOnly`	只能匯入根 package
`TestCoreImportsNoModule`、`TestCoreRowOrder`、`TestCoreNamesNoModuleTable`	Core 的匯入、列順序與命名
`TestSQLOnlyInStore`、`TestTableOwnership`、`TestSQLAllowlistShrinks`、`TestSeedSQLAllowlist`	SQL 的位置與資料表擁有者
`TestGoFileNames`、`TestNoBannedPackageNames`	檔案與 package 名稱
`TestFileSizeCap`、`TestCorePackageSize`	檔案與 core package 的大小
`TestCommentHygiene`	上面的註解規則
`TestRouteTableUnchanged`、`TestMigrationsUnchanged`、`TestHeaderAndJSONLiteralsUnchanged`	搬移程式碼不會改變任何路由、migration、HTTP header 名稱或 JSON 鍵
`TestNoOldPageAddresses`、`TestNoOldPagesInTestsOrDocs`	舊的頁面位址不會再出現在程式碼、測試和文件中
`TestNoDependencyBotConfig`	`.github` 裡沒有 dependency bot 的檔案

模組