Módulos

Elige el módulo al que pertenece tu cambio y conoce a qué módulos puede llamar.

Antes de empezar

• Lee Arquitectura para ver el mapa de carpetas y las reglas.
• Cada módulo tiene el mismo nombre en app/backend/internal/<module>/, y en app/frontend/src/lib/<module>/ y app/tests/<module>/ cuando tiene pantallas o pruebas de navegador.

Encuentra el módulo correcto

Módulo	Qué hace
requests	Pedir títulos, aprobaciones, reglas de solicitudes, Listas externas, informes
movies	Títulos de películas, ediciones, colecciones, búsqueda y organización
shows	Series, temporadas, episodios, búsqueda y organización
music	Artistas, álbumes, pistas, búsqueda y organización
sources	Fuentes, el puente con Jackett y Prowlarr, búsqueda de lanzamientos
downloads	Gestores de descargas, la cola, archivos vistos, mapas de rutas, etiquetas, elección de copias
subtitles	Idiomas de subtítulos, sitios, coincidencias y guardado
discover	Explorar, Populares, Buscar, Personas, Calendario, páginas de títulos
suggest	Elegir y ordenar filas y estantes (solo backend)
mediafiles	Registros del catálogo, Reglas de elección, nombres, paquetes de datos, detalles de los medios
importer	Importación de archivos: descompresión, etiquetas, coincidencias (solo backend)
library	Carpetas de la Biblioteca, adoptar y renombrar (solo backend)
metadata	El cliente de datos externos, consultas de música, escalas de clasificación, tráileres
mediaservers	Decir a Plex, Jellyfin y Emby que vuelvan a mirar
accounts	Usuarios, inicio de sesión, inicio de sesión único (SSO), inicio de sesión de apps de IA, límites para niños, preferencias de visualización
alerts	Canales de avisos y cuándo hablan
migrate	Traer datos de apps anteriores
arrapi	La API al estilo de Sonarr y Radarr
ai	Conexiones con apps de IA (retenido)
backups	Crear, conservar y restaurar copias de seguridad
health	Comprobaciones de salud, el doctor, el paquete de soporte
updates	La comprobación de actualizaciones y la lista de actualizaciones firmada
setup	El asistente de primer inicio

Orden de capas

Un módulo importa solo de una capa inferior. Nada importa discover. tools/structurecheck/allow.go es la fuente de verdad.

Capa	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

Si tu módulo necesita algo de una capa superior, no la importes. Haz que el módulo superior pase datos simples hacia abajo, o define en el inferior una interfaz pequeña que wiring.go completa.

Añade una ruta o un módulo

Ruta nueva

Regístrala en el routes.go del módulo con su permiso. openapi.json sale de las rutas, y una prueba falla si se desvía. Las rutas y los nombres de campos ya publicados se quedan. Añade campos, nunca los renombres. Después vuelve a generar Rutas de la API con go run ./app/backend/tools/apidoc.

Módulo nuevo

Primero intenta encajar tu cambio en los 23, y abre un issue antes de añadir uno. Un módulo nuevo necesita su carpeta de backend (más lib/<module>/ y app/tests/<module>/ si tiene pantallas), un lugar en el orden de capas en tools/structurecheck y una línea en wiring.go.

Si no funciona

Síntoma. Falla TestModuleEdges. Causa. Un módulo importa otro de la misma capa o de una superior. Solución. Pasa datos simples hacia abajo desde el módulo superior, o añade una interfaz pequeña conectada en wiring.go.

Síntoma. Falla TestSQLOnlyInStore o TestTableOwnership. Causa. Hay SQL fuera de un archivo store*.go, o toca la tabla de otro módulo. Solución. Mueve la consulta al store del propietario y llama al servicio del propietario por ID.

Para expertos

Más reglas

• Un módulo importa solo el paquete raíz de otro módulo.
• Las funciones del store reciben un database.Querier. Lee las filas de otro módulo a través de su servicio por ID, y pasa las listas largas de ID como un solo array JSON con json_each(?).
• settings, schedules, secrets, jobs y events son de core. Cada grupo de ajustes tiene un módulo propietario. Para cambiar el grupo de otro módulo, llama a su propietario.
• Toda llamada al exterior pasa por core/outbound.
• Los paquetes de core se ordenan en filas, de arriba abajo: parts, webserver y startup, logs, jobs y model, outbound y secrets, y luego database, files y releasename. Un paquete de core importa solo de su propia fila o de una inferior.
• Nombres: los archivos Go van en minúsculas con guiones bajos, las partes de Svelte en PascalCase, y los archivos de TypeScript, documentación, pruebas y despliegue en kebab-case. Los archivos Python usan guiones bajos para poder importarse. Las carpetas de app/ van en minúsculas, con una sola palabra.
• Renombra el código con libertad, pero todo lo que se guarda o se envía conserva su nombre: tablas y columnas, claves de ajustes, campos JSON, nombres de tareas y nombres de interruptores.
• Los comentarios no llevan números de la hoja de ruta, fechas, nombres ni rayas.

Propietarios de los registros

Propietario	Registros
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 y los campos de fila compartidos

Las comprobaciones

Las comprobaciones están en app/backend/tools/structurecheck. La mayoría necesita -tags structure.

Comprobación	Vigila
TestTopLayout	Las carpetas principales del repositorio
TestModuleSet, TestCoreSet, TestPackageMap	Las carpetas permitidas en internal/ y en internal/core/
TestModuleEdges	El orden de capas
TestModuleImportsRootOnly	Solo importaciones del paquete raíz
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Las importaciones, el orden de filas y los nombres de core
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	La ubicación del SQL y los propietarios de las tablas
TestGoFileNames, TestNoBannedPackageNames	Los nombres de archivos y paquetes
TestFileSizeCap, TestCorePackageSize	El tamaño de los archivos y de los paquetes de core
TestCommentHygiene	Las reglas de comentarios de arriba
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Un traslado no cambia ninguna ruta, migración, nombre de cabecera HTTP ni clave JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Las direcciones de páginas antiguas siguen fuera del código, las pruebas y la documentación
TestNoDependencyBotConfig	Ningún archivo de bot de dependencias en .github

Relacionado

• Arquitectura
• Pruebas
• Rutas de la API