Módulos

Escolhe o módulo a que a tua alteração pertence e fica a saber que módulos pode chamar.

Antes de começares

• Lê a Arquitetura para veres o mapa de pastas e as regras.
• Cada módulo tem o mesmo nome em app/backend/internal/<module>/, e em app/frontend/src/lib/<module>/ e app/tests/<module>/ quando tem ecrãs ou testes no navegador.

Descobre o módulo certo

Módulo	Faz
requests	Pedir, aprovações, regras de pedidos, listas externas, relatórios
movies	Títulos de filmes, edições, coleções, pesquisa e organização
shows	Séries, temporadas, episódios, pesquisa e organização
music	Artistas, álbuns, faixas, pesquisa e organização
sources	Fontes, a ponte para o Jackett e o Prowlarr, pesquisa de lançamentos
downloads	Gestores de transferências, a fila, ficheiros já vistos, mapeamentos de caminhos, etiquetas, escolhas de cópias
subtitles	Idiomas das legendas, sites, correspondência e gravação
discover	Explorar, Populares, Pesquisar, Pessoas, Calendário, páginas de títulos
suggest	Escolher e ordenar linhas e prateleiras (só backend)
mediafiles	Registos do catálogo, regras de escolha, nomes, pacotes de dados, detalhes dos ficheiros multimédia
importer	Importação de ficheiros: descomprimir, etiquetas, correspondência (só backend)
library	Pastas da Biblioteca, adoção e mudança de nomes (só backend)
metadata	O cliente de dados externos, pesquisas de música, escalas de classificação, trailers
mediaservers	Dizer ao Plex, Jellyfin e Emby para olharem outra vez
accounts	Utilizadores, início de sessão, início de sessão único, início de sessão de apps de IA, limites para crianças, escolhas de visualização
alerts	Canais de avisos e quando falam
migrate	Trazer dados das apps anteriores
arrapi	A API ao estilo do Sonarr e do Radarr
ai	Ligações de apps de IA (retido)
backups	Fazer, guardar e restaurar cópias de segurança
health	Verificações de saúde, o doctor, o pacote de suporte
updates	A verificação de atualizações e a lista de atualizações assinada
setup	O assistente da primeira execução

Ordem das camadas

Um módulo só importa uma camada inferior. Nada importa discover. O ficheiro tools/structurecheck/allow.go é a fonte de verdade.

Camada	Módulos
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

Se o teu módulo precisa de algo de uma camada superior, não o importes. Faz com que o módulo superior passe dados simples para baixo, ou define uma interface pequena no inferior que o wiring.go preenche.

Acrescenta uma rota ou um módulo

Rota nova

Regista-a no routes.go do módulo com a sua permissão. O openapi.json sai das rotas, e um teste falha se houver divergência. Os caminhos e nomes de campos já publicados ficam. Acrescenta campos, nunca os renomeies. Depois reescreve as Rotas da API com go run ./app/backend/tools/apidoc.

Módulo novo

Primeiro tenta encaixar a tua alteração nos 23 que existem e abre um issue antes de acrescentares um. Um módulo novo precisa da sua pasta de backend (mais lib/<module>/ e app/tests/<module>/ se tiver ecrãs), de um lugar na ordem das camadas em tools/structurecheck e de uma linha no wiring.go.

Se não funcionar

Sintoma. TestModuleEdges falha. Causa. Um módulo importa outro da mesma camada ou de uma superior. Solução. Passa dados simples para baixo a partir do módulo superior, ou acrescenta uma interface pequena ligada no wiring.go.

Sintoma. TestSQLOnlyInStore ou TestTableOwnership falha. Causa. Há SQL fora de um ficheiro store*.go, ou toca numa tabela de outro módulo. Solução. Move a consulta para o armazém do dono e chama o serviço do dono por ID.

Para especialistas

Mais regras

• Um módulo só importa o pacote de raiz de outro módulo.
• As funções do armazém recebem um database.Querier. Lê as linhas de outro módulo através do serviço dele, por ID, e passa listas longas de IDs como um único array JSON com json_each(?).
• settings, schedules, secrets, jobs e events pertencem ao core. Cada grupo de definições tem um módulo dono. Para mudar o grupo de outro módulo, chama o dono.
• Todas as chamadas para fora passam por core/outbound.
• Os pacotes do core estão em linhas, de cima para baixo: parts, webserver e startup, logs, jobs e model, outbound e secrets, e depois database, files e releasename. Um pacote do core só importa da sua linha ou de uma inferior.
• Nomes: os ficheiros Go são em minúsculas com sublinhados, as partes Svelte em PascalCase, e os ficheiros TypeScript, de documentação, de testes e de deploy em kebab-case. Os ficheiros Python usam sublinhados para poderem ser importados. As pastas em app/ são em minúsculas, com uma só palavra.
• Podes renomear código à vontade, mas tudo o que é guardado ou enviado mantém o nome: tabelas e colunas, chaves de definições, campos JSON, nomes de tarefas e nomes de interruptores.
• Os comentários não levam números de roadmap, datas, nomes nem travessões longos.

Donos dos registos

Dono	Registos
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 e os campos de linha partilhados

As verificações

As verificações estão em app/backend/tools/structurecheck. A maioria precisa de -tags structure.

Verificação	Garante
TestTopLayout	As pastas de topo do repositório
TestModuleSet, TestCoreSet, TestPackageMap	As pastas permitidas em internal/ e internal/core/
TestModuleEdges	A ordem das camadas
TestModuleImportsRootOnly	Importações só do pacote de raiz
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Importações do core, ordem das linhas e nomes
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	Onde fica o SQL e os donos das tabelas
TestGoFileNames, TestNoBannedPackageNames	Nomes de ficheiros e de pacotes
TestFileSizeCap, TestCorePackageSize	Tamanho dos ficheiros e dos pacotes do core
TestCommentHygiene	As regras de comentários acima
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Uma mudança de sítio não altera nenhuma rota, migração, nome de cabeçalho HTTP nem chave JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Os endereços de páginas antigas não voltam ao código, aos testes nem à documentação
TestNoDependencyBotConfig	Nenhum ficheiro de bot de dependências em .github

Relacionado

• Arquitetura
• Testes
• Rotas da API