Module

Chọn module mà thay đổi của bạn thuộc về, và biết nó được gọi những module nào.

Trước khi bắt đầu

• Đọc Kiến trúc để biết sơ đồ thư mục và các quy tắc.
• Mỗi module có cùng một tên trong app/backend/internal/<module>/, và trong app/frontend/src/lib/<module>/ và app/tests/<module>/ khi nó có màn hình hoặc bài kiểm tra trên trình duyệt.

Tìm đúng module

Module	Phụ trách
requests	Yêu cầu, duyệt, quy tắc yêu cầu, danh sách ngoài, báo cáo
movies	Các mục phim lẻ, ấn bản, bộ phim, tìm kiếm và sắp xếp
shows	Phim bộ, mùa, tập, tìm kiếm và sắp xếp
music	Nghệ sĩ, album, bài hát, tìm kiếm và sắp xếp
sources	Các Nguồn, cầu nối Jackett và Prowlarr, tìm bản phát hành
downloads	Trình tải xuống, hàng đợi, tệp đã thấy, ánh xạ đường dẫn, thẻ, lựa chọn bản
subtitles	Ngôn ngữ phụ đề, các trang, đối chiếu và lưu
discover	Khám phá, Phổ biến, Tìm kiếm, Nhân vật, Lịch, trang của mục
suggest	Chọn và sắp xếp các hàng và kệ (chỉ backend)
mediafiles	Bản ghi danh mục, quy tắc chọn, đặt tên, gói dữ liệu, chi tiết media
importer	Nhập tệp: giải nén, thẻ, đối chiếu (chỉ backend)
library	Thư mục Thư viện, tiếp nhận và đổi tên (chỉ backend)
metadata	Client dữ liệu bên ngoài, tra cứu nhạc, thang xếp hạng độ tuổi, trailer
mediaservers	Báo cho Plex, Jellyfin và Emby quét lại
accounts	Người dùng, đăng nhập, đăng nhập một lần, đăng nhập ứng dụng AI, giới hạn cho trẻ em, lựa chọn xem
alerts	Các kênh cảnh báo và khi nào chúng lên tiếng
migrate	Đưa dữ liệu sang từ các ứng dụng cũ
arrapi	API theo kiểu Sonarr và Radarr
ai	Kết nối ứng dụng AI (chưa mở)
backups	Tạo, giữ và khôi phục bản sao lưu
health	Kiểm tra tình trạng, doctor, gói hỗ trợ
updates	Kiểm tra cập nhật và danh sách cập nhật có chữ ký
setup	Trình hướng dẫn lần chạy đầu tiên

Thứ tự tầng

Một module chỉ import tầng thấp hơn. Không có gì import discover. tools/structurecheck/allow.go là nguồn chuẩn.

Tầng	Module
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

Nếu module của bạn cần thứ gì từ tầng cao hơn, đừng import nó. Hãy để module cao hơn truyền dữ liệu thuần xuống, hoặc định nghĩa một interface nhỏ ở module thấp để wiring.go điền vào.

Thêm một route hoặc một module

Route mới

Đăng ký nó trong routes.go của module cùng với quyền của nó. openapi.json được sinh ra từ các route, và một bài kiểm tra thất bại khi có lệch. Các đường dẫn và tên trường đã phát hành được giữ nguyên. Thêm trường, đừng đổi tên. Sau đó viết lại Các route API bằng go run ./app/backend/tools/apidoc.

Module mới

Hãy cố đặt thay đổi của bạn vào 23 module hiện có trước, và mở issue trước khi thêm một module. Một module mới cần thư mục backend của nó (cộng với lib/<module>/ và app/tests/<module>/ nếu nó có màn hình), một vị trí trong thứ tự tầng ở tools/structurecheck, và một dòng trong wiring.go.

Nếu không hoạt động

Triệu chứng. TestModuleEdges thất bại. Nguyên nhân. Một module import module cùng tầng hoặc tầng cao hơn. Cách khắc phục. Truyền dữ liệu thuần xuống từ module cao hơn, hoặc thêm một interface nhỏ được nối trong wiring.go.

Triệu chứng. TestSQLOnlyInStore hoặc TestTableOwnership thất bại. Nguyên nhân. SQL nằm ngoài một tệp store*.go, hoặc đụng vào bảng của module khác. Cách khắc phục. Chuyển truy vấn vào store của module sở hữu và gọi service của module đó theo ID.

Dành cho người dùng nâng cao

Thêm quy tắc

• Một module chỉ import gói gốc của module khác.
• Các hàm store nhận một database.Querier. Đọc các hàng của module khác qua service của nó theo ID, và truyền danh sách ID dài thành một mảng JSON duy nhất với json_each(?).
• settings, schedules, secrets, jobs và events thuộc về core. Mỗi nhóm cài đặt có một module sở hữu. Muốn đổi nhóm của module khác, hãy gọi module sở hữu nó.
• Mọi lệnh gọi ra ngoài đều đi qua core/outbound.
• Các gói core xếp thành hàng, từ trên xuống: parts, webserver và startup, logs, jobs và model, outbound và secrets, rồi database, files và releasename. Một gói core chỉ import hàng của chính nó hoặc hàng thấp hơn.
• Tên gọi: tệp Go viết thường có dấu gạch dưới, phần Svelte viết kiểu PascalCase, còn tệp TypeScript, tài liệu, kiểm thử và deploy viết kiểu kebab-case. Tệp Python dùng dấu gạch dưới để có thể import. Thư mục trong app/ viết thường, một từ.
• Cứ đổi tên mã thoải mái, nhưng mọi thứ được lưu hoặc gửi đi giữ nguyên tên: bảng và cột, khóa cài đặt, trường JSON, tên tác vụ và tên công tắc.
• Chú thích không ghi số trong lộ trình, ngày tháng, tên người hay dấu gạch ngang dài.

Chủ sở hữu bản ghi

Chủ sở hữu	Bản ghi
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 và các trường hàng dùng chung

Các bước kiểm tra

Các bước kiểm tra nằm trong app/backend/tools/structurecheck. Hầu hết cần -tags structure.

Kiểm tra	Bảo đảm
TestTopLayout	Các thư mục cấp cao nhất của repo
TestModuleSet, TestCoreSet, TestPackageMap	Các thư mục được phép trong internal/ và internal/core/
TestModuleEdges	Thứ tự tầng
TestModuleImportsRootOnly	Chỉ import gói gốc
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Import của core, thứ tự hàng và tên gọi
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	Vị trí đặt SQL và chủ sở hữu bảng
TestGoFileNames, TestNoBannedPackageNames	Tên tệp và tên gói
TestFileSizeCap, TestCorePackageSize	Cỡ tệp và cỡ gói core
TestCommentHygiene	Các quy tắc chú thích ở trên
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Một lần di chuyển không làm đổi route, migration, tên header HTTP hay khóa JSON nào
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Địa chỉ trang cũ không quay lại trong mã, kiểm thử và tài liệu
TestNoDependencyBotConfig	Không có tệp bot phụ thuộc trong .github

Liên quan

• Kiến trúc
• Kiểm thử
• Các route API