Desarrollo

Requisitos

• Vaya a 1.26 o más reciente; el módulo fija la cadena de herramientas mínima.
• Node.js 24 (ver .node-version).
• pnpm 9.12.2, coincidiendo con la interfaz packageManager campo.
• jq para las pruebas sintéticas de selección de versiones del instalador.
• Docker es opcional para el desarrollo local y solo se requiere para la verificación del contenedor.

Ejecute todos los destinos Make desde la raíz del repositorio.

Comandos

make clean no elimina la base de datos ni las dependencias. Air reconstruye y reinicia automáticamente el backend cuando Go source, SQL incorporado, go.mod, o go.sum cambios. Vite actualiza el código del frontend a través de HMR sin reiniciar el backend. Usar make dev WEB_PORT=5174 cuando el puerto frontend predeterminado está ocupado.

El Makefile ejecuta Air v1.67.4 hasta go run; la primera invocación lo descarga y lo construye. No se necesita ninguna instalación global de Air y sus dependencias permanecen fuera del módulo de la aplicación. .air.toml mantiene las compilaciones temporales ignoradas bin/air/ y le da al servidor hasta diez segundos para un apagado correcto antes de reiniciar. Las compilaciones de backend de desarrollo desactivan CGO, coinciden con las compilaciones de producción y evitan discrepancias entre el objetivo de implementación y el vinculador de macOS C. Las pruebas de carrera todavía utilizan CGO.

Configuración

Proceso de copiar .env.example no lo activa. Exporte variables en su shell o proporcionelas a un solo comando:

SUBLANE_LOG_LEVEL=debug make dev
SUBLANE_ADDR=127.0.0.1:9090 ./bin/sublane

WEB_PORT cambia solo el puerto frontend. El backend escucha 127.0.0.1:8080 por defecto, y Vite lee lo mismo SUBLANE_ADDR como backend. Si una instancia Docker existente u otro proceso usa 8080, elija un puerto backend libre:

SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174

make dev comprueba la dirección del backend antes de iniciar Air o Vite y falla si está ocupada. Esto evita que un nuevo frontend se conecte silenciosamente a un backend antiguo o no relacionado mientras Air permanece ejecutándose después de un error de vinculación. Al empezar make dev-api y make dev-web por separado pasar lo mismo SUBLANE_ADDR a ambos comandos.

El proxy API debe preservar el Host (changeOrigin: false) para autenticación del mismo origen. Comience con un directorio de datos de prueba vacío para realizar la configuración y cree un administrador a través del formulario utilizando credenciales sintéticas. Nunca restablezca una instancia en funcionamiento eliminando su base de datos.

Pruebas

Las pruebas de backend cubren la validación del entorno, la inicialización nueva SQLite, la configuración/carreras/reversión únicas, el ciclo de vida de los miembros, los límites de sesión por usuario, la revocación del tiempo de desactivación, el acceso API basado en roles, las comprobaciones de origen/cuerpo, los límites de velocidad, el fallo de preparación y los límites API/de activos estáticos. Las pruebas de frontend cubren enrutamiento y menús según roles, creación de miembros/cambios de estado, validación de configuración, errores de inicio de sesión, cierre de sesión y borrado de caché de identidad cruzada, caducidad, validación de respuestas, navegación y selección persistente de tema/idioma. Utilice únicamente accesorios sintéticos y bases de datos temporales.

Ejecute pruebas enfocadas durante el desarrollo:

go test ./internal/server -run TestRoutesAndAssetBoundary -count=1
pnpm --dir web test src/App.test.tsx

La verificación del navegador debe cubrir diseños estrechos y de escritorio, navegación móvil, recarga de ruta directa, cambios de idioma, temas claros/oscuros/del sistema y un backend desconectado. Las pruebas unitarias no reemplazan estas comprobaciones.

Codex pruebas de adaptador

Las pruebas del adaptador nunca utilizan una cuenta real. Inyectan productos falsos locales a través de una costura de transporte mientras la selección del punto final de producción permanece fija. Para ejercitar una CLI Codex instalada con una configuración temporal aislada y una salida de modelo sintético:

SUBLANE_TEST_CODEX=1 go test ./internal/server -run TestCodexCLIProtocol -count=1 -v

El conjunto de pruebas normal omite esta prueba de inclusión voluntaria del cliente externo. No lea el contenido existente de un desarrollador. auth.json o llavero para pruebas. La aceptación de proveedores en vivo y de escritorio requiere una cuenta autorizada explícitamente; registre esos resultados por separado de la cobertura del protocolo.

Agregar traducciones

1. Agregar una clave en inglés web/src/locales/en.ts.
2. Agregue la misma clave en web/src/locales/zh.ts y cada diccionario local JSON adicional. Preservar las variables de interpolación y proporcionar las categorías plurales requeridas por cada idioma.
3. Usar useTranslation() y t() en componentes, incluidas las etiquetas ARIA.
4. Correr pnpm --dir web typecheck e inspeccionar traducciones más largas en el escritorio y anchos estrechos. Verifique el diseño árabe de derecha a izquierda y mantenga el código y los identificadores de izquierda a derecha.

Los idiomas admitidos son inglés, chino simplificado, chino tradicional, japonés, coreano, español, francés, alemán, portugués, ruso y árabe. Los diccionarios de aplicaciones adicionales se cargan a pedido. El sitio web mantiene temas en inglés en content/docs/ y traducciones en content/<locale>/, con slugs coincidentes, navegación localizada, búsqueda y exportaciones de Markdown. Las nuevas traducciones son asistidas por máquinas y necesitan revisión por parte de un hablante nativo.

Las preferencias de la interfaz de usuario son locales para el navegador. No son configuraciones de equipo y no están escritas en SQLite.

HTTP rutas y consultas a bases de datos

HTTP las rutas usan chi con estándar net/http manejadores. Los recursos registran los suyos. Get, Head, Post, y Patch manejadores dentro Route grupos. Agregue rutas de administración al enrutador protegido por el administrador en internal/server/server.go. La autenticación pública y las rutas de clave personal son excepciones explícitas. La autenticación de sesión, rol y portador de puerta de enlace se ejecuta a nivel de enrutador Use, protegiendo errores de métodos y rutas desconocidas, así como puntos finales coincidentes. Uso público de inicio de sesión/configuración With para validación y limitación de origen. No reintroduzca cambios de envío de métodos o rutas en los controladores.

Cada subrurutador instala JSON NotFound y MethodNotAllowed manejadores. El controlador 405 deriva Allow de las rutas registradas de chi a través Match, sin ejecutar controladores de aplicaciones. Los controles de salud, el estado del sistema y los activos estáticos registran explícitamente HEAD; otras API conservan sus métodos declarados. El SPA está registrado solo para GET/HEAD en la raíz y no puede manejar reservas reservadas API.

Escriba consultas SQL con nombre en internal/storage/queries/, agrupados por dominio. sqlc.yaml utiliza el SQL de inicialización consolidado como esquema y genera internal/storage/db/. Correr make generate después de cambiar las consultas, el esquema o la configuración del generador. Confirmar SQL y generar Go juntos; Nunca edite los archivos generados manualmente. Los servicios de dominio poseen validación y transacciones, vinculan consultas con WithTx(tx)y convertir filas en tipos de respuestas públicas.

El Makefile fija sqlc a v1.31.1 y lo ejecuta go run; la primera invocación descarga y construye la herramienta. Go puede descargar una cadena de herramientas compatible para el generador. No se necesita instalación global de sqlc, servicio en la nube ni conexión a base de datos para la generación. Las dependencias del generador permanecen fuera del gráfico de dependencia del módulo de la aplicación. Los archivos generados tienen versiones, por lo que las compilaciones y contenedores de producción de Go normales no necesitan sqlc. make check, incluido CI, se ejecuta make generate-check para rechazar el código generado obsoleto sin reescribirlo.

Cambiar el esquema de versión preliminar

Conserva los archivos existentes de internal/storage/migrations/, incluido 001_schema.sql. Añade migraciones incrementales ordenadas y actualiza las consultas de internal/storage/queries/. El inicio aplica las migraciones pendientes a bases compatibles; rechaza la estructura temprana incompatible identificada por 001_settings.sql. Ejecuta make generate, make generate-check y las pruebas de almacenamiento pertinentes. sqlc valida la estructura, pero no migra la base en ejecución.

Solución de problemas

• Devoluciones de raíz de backend frontend_not_built: use Vite en el puerto 5173 para desarrollo o ejecute make build y empezar bin/sublane.
• El frontend muestra un error de conexión: Confirme que el proceso Go se esté ejecutando y que el proxy de Vite apunte a la dirección configurada.
• Puerto ya en uso: WEB_PORT controla Vite; SUBLANE_ADDR controla el backend y su proxy Vite. Elija una dirección de backend gratuita, por ejemplo SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174. No finalice procesos no relacionados.
• Vaya a descargar una cadena de herramientas: Esto se espera cuando el Go instalado es anterior a go.mod requiere.
• Docker la compilación no puede conectarse: enciende tu motor Docker, luego ejecuta docker compose -f docker.compose.yaml config --quiet y docker compose -f docker.compose.yaml -f docker.compose.build.yaml build.
• El idioma o el tema permanecen cambiados: Las preferencias se almacenan deliberadamente en el almacenamiento local del navegador. Cámbielos en Preferencias para restaurar los valores predeterminados.

Mantenimiento

Mantener go.sum y web/pnpm-lock.yaml bajo control de versiones. Ejecute actualizaciones de dependencias como cambios separados y conserve los avisos de licencias de terceros. No copie un árbol de Shadcn Admin más nuevo sobre componentes locales sin revisar los cambios de localización, nombres y accesibilidad.

Controles de embalaje y liberación.

Ver despliegue para pruebas de humo de contenedores y operaciones de liberación para la canalización activada por etiquetas. make test incluye las pruebas integradas de metadatos de lanzamiento de Node y las pruebas de publicación de repositorio temporal; make lint comprueba la sintaxis del script de liberación/humo. CI crea y prueba contenedores en ambas arquitecturas nativas de Linux, luego el flujo de trabajo de lanzamiento publica esas imágenes exactamente probadas y extrae sus archivos binarios. No se utilizan credenciales de registro en las comprobaciones de solicitudes de extracción.