모듈

변경이 속할 모듈을 고르고, 그 모듈이 어떤 모듈을 호출해도 되는지 확인하세요.

시작하기 전에

• 폴더 지도와 규칙은 아키텍처에서 읽으세요.
• 각 모듈은 app/backend/internal/<module>/에서 같은 이름을 쓰고, 화면이나 브라우저 테스트가 있으면 app/frontend/src/lib/<module>/과 app/tests/<module>/에서도 같은 이름을 씁니다.

맞는 모듈 찾기

모듈	하는 일
requests	요청하기, 승인, 요청 규칙, 외부 목록, 신고
movies	영화 작품, 에디션, 세트, 검색과 정리
shows	시리즈, 시즌, 에피소드, 검색과 정리
music	아티스트, 앨범, 트랙, 검색과 정리
sources	소스, Jackett과 Prowlarr 브리지, 릴리스 검색
downloads	다운로더, 대기열, 확인된 파일, 경로 매핑, 태그, 사본 선택
subtitles	자막 언어, 사이트, 매칭과 저장
discover	둘러보기, 인기, 검색, 인물, 캘린더, 작품 페이지
suggest	행과 선반 고르기와 정렬(백엔드 전용)
mediafiles	카탈로그 레코드, 선택 규칙, 이름 짓기, 데이터 팩, 미디어 세부 정보
importer	파일 가져오기: 압축 풀기, 태그, 매칭(백엔드 전용)
library	라이브러리 폴더, 편입과 이름 바꾸기(백엔드 전용)
metadata	외부 데이터 클라이언트, 음악 조회, 등급 체계, 예고편
mediaservers	Plex, Jellyfin, Emby에 다시 살펴보라고 알리기
accounts	사용자, 로그인, 통합 로그인(SSO), 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개 안에 맞춰 보고, 모듈을 추가하기 전에 이슈를 여세요. 새 모듈에는 백엔드 폴더(화면이 있으면 lib/<module>/과 app/tests/<module>/도), tools/structurecheck의 계층 순서 안의 자리, wiring.go의 한 줄이 필요합니다.

문제가 생기면

증상. TestModuleEdges가 실패합니다. 원인. 모듈이 같은 계층이나 더 높은 계층의 모듈을 가져옵니다. 해결. 높은 모듈에서 단순 데이터를 아래로 넘기거나, wiring.go에서 연결되는 작은 인터페이스를 추가하세요.

증상. TestSQLOnlyInStore 또는 TestTableOwnership이 실패합니다. 원인. SQL이 store*.go 파일 밖에 있거나 다른 모듈의 테이블을 건드립니다. 해결. 쿼리를 소유 모듈의 스토어로 옮기고, 소유 모듈의 서비스를 ID로 호출하세요.

전문가용

추가 규칙

• 모듈은 다른 모듈의 루트 패키지만 가져옵니다.
• 스토어 함수는 database.Querier를 받습니다. 다른 모듈의 행은 그 모듈의 서비스를 통해 ID로 읽고, 긴 ID 목록은 json_each(?)를 써서 JSON 배열 하나로 넘기세요.
• settings, schedules, secrets, jobs, events는 core 소유입니다. 설정 그룹마다 소유 모듈이 하나씩 있습니다. 다른 모듈의 그룹을 바꾸려면 그 소유 모듈을 호출하세요.
• 외부 호출은 모두 core/outbound를 거칩니다.
• core 패키지는 위에서 아래로 줄을 이룹니다: parts, webserver와 startup, logs, jobs와 model, outbound와 secrets, 그다음 database, files, releasename. core 패키지는 자신의 줄이나 그 아래 줄만 가져옵니다.
• 이름: Go 파일은 소문자에 밑줄, Svelte 부품은 PascalCase, TypeScript와 문서, 테스트, 배포 파일은 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	저장소 최상위 폴더
TestModuleSet, TestCoreSet, TestPackageMap	internal/과 internal/core/에 허용되는 폴더
TestModuleEdges	계층 순서
TestModuleImportsRootOnly	루트 패키지만 가져오기
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	core의 import, 줄 순서, 이름
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	SQL 위치와 테이블 소유자
TestGoFileNames, TestNoBannedPackageNames	파일 이름과 패키지 이름
TestFileSizeCap, TestCorePackageSize	파일 크기와 core 패키지 크기
TestCommentHygiene	위의 주석 규칙
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	코드를 옮겨도 경로, 마이그레이션, HTTP 헤더 이름, JSON 키가 바뀌지 않음
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	예전 페이지 주소가 코드, 테스트, 문서에 다시 나타나지 않음
TestNoDependencyBotConfig	.github에 의존성 봇 파일이 없음

관련 문서

• 아키텍처
• 테스트
• API 라우트