Modul

Pilih modul tempat perubahan kamu berada, dan ketahui modul mana saja yang boleh dipanggilnya.

Sebelum mulai

• Baca Arsitektur untuk peta folder dan aturannya.
• Setiap modul punya nama yang sama di app/backend/internal/<module>/, dan di app/frontend/src/lib/<module>/ serta app/tests/<module>/ kalau punya layar atau tes browser.

Cari modul yang tepat

Modul	Tugasnya
requests	Meminta, persetujuan, aturan permintaan, daftar luar, laporan
movies	Judul film, edisi, set, pencarian, dan penataan
shows	Serial, musim, episode, pencarian, dan penataan
music	Artis, album, lagu, pencarian, dan penataan
sources	Sumber, jembatan Jackett dan Prowlarr, pencarian rilis
downloads	Downloader, antrean, file yang sudah terlihat, pemetaan path, tag, pilihan salinan
subtitles	Bahasa subtitle, situs, pencocokan, dan penyimpanan
discover	Jelajahi, Populer, Pencarian, Orang, Kalender, halaman judul
suggest	Memilih dan mengurutkan baris dan rak (hanya backend)
mediafiles	Record katalog, aturan pilihan, penamaan, paket data, detail media
importer	Impor file: ekstrak, tag, pencocokan (hanya backend)
library	Folder pustaka, mengambil alih, dan mengganti nama (hanya backend)
metadata	Klien data luar, pencarian musik, tangga rating, trailer
mediaservers	Memberi tahu Plex, Jellyfin, dan Emby untuk memindai ulang
accounts	Pengguna, login, single sign-on, login aplikasi AI, batas anak, pilihan tontonan
alerts	Saluran notifikasi dan kapan mereka berbunyi
migrate	Membawa data dari aplikasi lama
arrapi	API bergaya Sonarr dan Radarr
ai	Koneksi aplikasi AI (ditunda)
backups	Membuat, menyimpan, dan memulihkan backup
health	Pemeriksaan kondisi, doctor, paket dukungan
updates	Pemeriksaan update dan daftar update bertanda tangan
setup	Wizard pertama kali dijalankan

Urutan layer

Sebuah modul hanya mengimpor layer yang lebih rendah. Tidak ada yang mengimpor discover. tools/structurecheck/allow.go adalah sumber kebenarannya.

Layer	Modul
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

Kalau modul kamu butuh sesuatu dari layer yang lebih tinggi, jangan diimpor. Minta modul yang lebih tinggi mengirim data biasa ke bawah, atau definisikan interface kecil di modul yang lebih rendah yang diisi oleh wiring.go.

Tambah route atau modul

Route baru

Daftarkan di routes.go milik modul beserta izinnya. openapi.json dibuat dari route, dan sebuah tes gagal kalau ada yang menyimpang. Path dan nama field yang sudah dirilis tetap. Tambahkan field, jangan pernah ganti nama. Lalu tulis ulang Route API dengan go run ./app/backend/tools/apidoc.

Modul baru

Masukkan perubahan kamu ke 23 modul yang ada dulu, dan buka issue sebelum menambah modul. Modul baru butuh folder backend-nya (plus lib/<module>/ dan app/tests/<module>/ kalau punya layar), tempat di urutan layer di tools/structurecheck, dan satu baris di wiring.go.

Kalau tidak berhasil

Gejala. TestModuleEdges gagal. Penyebab. Sebuah modul mengimpor modul di layer yang sama atau lebih tinggi. Solusi. Kirim data biasa ke bawah dari modul yang lebih tinggi, atau tambahkan interface kecil yang dihubungkan di wiring.go.

Gejala. TestSQLOnlyInStore atau TestTableOwnership gagal. Penyebab. SQL ada di luar file store*.go, atau menyentuh tabel modul lain. Solusi. Pindahkan query ke store pemiliknya dan panggil service pemiliknya dengan ID.

Untuk yang mahir

Aturan lainnya

• Sebuah modul hanya mengimpor package root dari modul lain.
• Fungsi store menerima database.Querier. Baca baris milik modul lain lewat service-nya dengan ID, dan kirim daftar ID yang panjang sebagai satu array JSON dengan json_each(?).
• settings, schedules, secrets, jobs, dan events milik core. Setiap grup pengaturan punya satu modul pemilik. Untuk mengubah grup milik modul lain, panggil pemiliknya.
• Setiap panggilan ke luar lewat core/outbound.
• Package core tersusun dalam baris, dari atas ke bawah: parts, webserver dan startup, logs, jobs dan model, outbound dan secrets, lalu database, files, dan releasename. Sebuah package core hanya mengimpor barisnya sendiri atau yang lebih rendah.
• Penamaan: file Go huruf kecil dengan underscore, bagian Svelte PascalCase, dan file TypeScript, docs, tes, dan deploy memakai kebab-case. File Python memakai underscore supaya bisa diimpor. Folder di app/ huruf kecil, satu kata.
• Ganti nama kode dengan bebas, tetapi apa pun yang disimpan atau dikirim tetap pada namanya: tabel dan kolom, kunci pengaturan, field JSON, nama tugas, dan nama sakelar.
• Komentar tidak memuat nomor roadmap, tanggal, nama, atau em dash.

Pemilik record

Pemilik	Record
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 dan field baris bersama

Pemeriksaannya

Pemeriksaan ada di app/backend/tools/structurecheck. Sebagian besar butuh -tags structure.

Pemeriksaan	Menjaga
TestTopLayout	Folder teratas repo
TestModuleSet, TestCoreSet, TestPackageMap	Folder yang diizinkan di internal/ dan internal/core/
TestModuleEdges	Urutan layer
TestModuleImportsRootOnly	Impor hanya ke package root
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Impor core, urutan baris, dan nama
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	Penempatan SQL dan pemilik tabel
TestGoFileNames, TestNoBannedPackageNames	Nama file dan package
TestFileSizeCap, TestCorePackageSize	Ukuran file dan package core
TestCommentHygiene	Aturan komentar di atas
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Pemindahan tidak mengubah route, migrasi, nama header HTTP, atau kunci JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Alamat halaman lama tidak muncul lagi di kode, tes, dan docs
TestNoDependencyBotConfig	Tidak ada file bot dependensi di .github

Terkait

• Arsitektur
• Pengujian
• Route API