โมดูล

เลือกโมดูลที่การแก้ของคุณควรอยู่ และรู้ว่าโมดูลนั้นเรียกโมดูลไหนได้บ้าง

ก่อนเริ่ม

• อ่านสถาปัตยกรรมเพื่อดูแผนผังโฟลเดอร์และกฎ
• แต่ละโมดูลใช้ชื่อเดียวกันใน 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	ระเบียนแคตตาล็อก กฎการเลือก การตั้งชื่อ Data pack รายละเอียดสื่อ
importer	การนำเข้าไฟล์: แตกไฟล์ แท็ก การจับคู่ (แบ็กเอนด์เท่านั้น)
library	โฟลเดอร์คลัง การรับเข้าดูแล และการเปลี่ยนชื่อ (แบ็กเอนด์เท่านั้น)
metadata	ตัวเชื่อมข้อมูลภายนอก การค้นหาเพลง ระดับเรตติ้ง ตัวอย่างภาพยนตร์
mediaservers	สั่ง Plex, Jellyfin และ Emby ให้สแกนใหม่
accounts	ผู้ใช้ การล็อกอิน single sign-on การล็อกอินของแอป AI โควตาสำหรับเด็ก ตัวเลือกการรับชม
alerts	ช่องทางการแจ้งเตือนและเวลาที่แจ้ง
migrate	การนำข้อมูลมาจากแอปรุ่นเดิม
arrapi	API แบบ Sonarr และ Radarr
ai	การเชื่อมต่อแอป AI (ยังไม่เปิดให้ใช้)
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

ถ้าโมดูลของคุณต้องการบางอย่างจากชั้นที่สูงกว่า อย่านำเข้าตรง ๆ ให้โมดูลชั้นบนส่งข้อมูลธรรมดาลงมา หรือกำหนด interface เล็ก ๆ ในโมดูลชั้นล่างให้ 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 ล้มเหลว สาเหตุ. โมดูลนำเข้าโมดูลที่อยู่ชั้นเดียวกันหรือสูงกว่า วิธีแก้. ให้โมดูลชั้นบนส่งข้อมูลธรรมดาลงมา หรือเพิ่ม interface เล็ก ๆ ที่เชื่อมใน wiring.go

อาการ. TestSQLOnlyInStore หรือ TestTableOwnership ล้มเหลว สาเหตุ. มี SQL อยู่นอกไฟล์ store*.go หรือไปแตะตารางของโมดูลอื่น วิธีแก้. ย้าย query ไปไว้ใน store ของเจ้าของ แล้วเรียก service ของเจ้าของด้วย ID

สำหรับผู้เชี่ยวชาญ

กฎเพิ่มเติม

• โมดูลนำเข้าได้เฉพาะ package รากของโมดูลอื่น
• ฟังก์ชันของ store รับ database.Querier อ่านแถวของโมดูลอื่นผ่าน service ของมันด้วย ID และส่งรายการ ID ยาว ๆ เป็น JSON array เดียวด้วย json_each(?)
• settings, schedules, secrets, jobs และ events เป็นของ core กลุ่มการตั้งค่าแต่ละกลุ่มมีโมดูลเจ้าของหนึ่งตัว หากต้องการแก้กลุ่มของโมดูลอื่น ให้เรียกเจ้าของ
• ทุกการเรียกออกไปภายนอกต้องผ่าน core/outbound
• Package ของ core เรียงเป็นแถว จากบนลงล่าง: parts, webserver และ startup, logs, jobs และ model, outbound และ secrets แล้วจึง database, files และ releasename Package ของ core นำเข้าได้เฉพาะแถวเดียวกันหรือต่ำกว่า
• การตั้งชื่อ: ไฟล์ Go ใช้ตัวพิมพ์เล็กและขีดล่าง ส่วนของ Svelte ใช้ PascalCase ส่วน TypeScript เอกสาร เทสต์ และไฟล์ deploy ใช้ kebab-case ไฟล์ Python ใช้ขีดล่างเพื่อให้ import ได้ โฟลเดอร์ใน app/ เป็นตัวพิมพ์เล็กและคำเดียว
• เปลี่ยนชื่อในโค้ดได้อิสระ แต่สิ่งที่ถูกเก็บหรือส่งออกไปต้องคงชื่อเดิม: ตารางและคอลัมน์ คีย์ของการตั้งค่า ฟิลด์ JSON ชื่อ job และชื่อสวิตช์
• คอมเมนต์ห้ามมีเลขโรดแมป วันที่ ชื่อคน หรือ em dash

เจ้าของระเบียน

เจ้าของ	ระเบียน
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	ขนาดไฟล์และขนาด package ของ core
TestCommentHygiene	กฎของคอมเมนต์ข้างต้น
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	การย้ายโค้ดต้องไม่เปลี่ยนเส้นทาง migration ชื่อ HTTP header หรือคีย์ JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	ที่อยู่หน้าเก่าต้องไม่กลับมาในโค้ด เทสต์ และเอกสาร
TestNoDependencyBotConfig	ไม่มีไฟล์ของบอตจัดการ dependency ใน .github

หน้าที่เกี่ยวข้อง

• สถาปัตยกรรม
• การทดสอบ
• เส้นทาง API