Desenvolvimento

Requisitos

• Vá 1.26 ou mais recente; o módulo fixa a cadeia de ferramentas mínima.
• Node.js 24 (ver .node-version).
• pnpm 9.12.2, correspondente à interface packageManager Campo.
• jq para os testes sintéticos de seleção de lançamento do instalador.
• Docker é opcional para o desenvolvimento local e necessário apenas para a verificação do recipiente.

Execute todos os alvos Criar a partir da raiz do repositório.

Comandos

make clean não remove a base de dados ou dependências. O ar reconstrui automaticamente e reinicia a infra- estrutura quando Go source, SQL incorporado, go.mod, ou go.sum alterações. A janela actualiza o código da interface através do HMR sem reiniciar a infra- estrutura. Use make dev WEB_PORT=5174 quando a porta de frontend padrão estiver ocupada.

O Makefile roda Air v1.67.4 através go run; a primeira invocação baixa e constrói-o. Nenhuma instalação global de ar é necessária, e suas dependências ficam fora do módulo de aplicação. .air.toml mantém as compilaçãos temporárias sob ignorado bin/air/ e dá ao servidor até dez segundos para o desligamento gracioso antes de uma reinicialização. A infraestrutura de desenvolvimento cria desativar o CGO, combinando as construções de produção e evitando erros no macOS C linker implantation-target. Os testes de corrida ainda usam o CGO.

Configuração

A Copiar .env.example não o ativa. Exportar variáveis na sua shell ou fornecê- las para um único comando:

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

WEB_PORT muda apenas a porta da interface. A infra- estrutura ouve- a 127.0.0.1:8080 por padrão, e Vite lê o mesmo SUBLANE_ADDR como infra- estrutura. Se existir um Docker instância ou outro processo usa 8080, escolha uma porta de infraestrutura gratuita:

SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174

make dev verifica o endereço da infra- estrutura antes de iniciar o Ar ou o Vite e falha se estiver ocupado. Isto impede que uma nova interface se conecte silenciosamente a uma infra- estrutura não relacionada ou antiga enquanto o Ar permanece em execução após uma falha de ligação. Ao iniciar make dev-api e make dev-web em separado, passar o mesmo SUBLANE_ADDR para ambos os comandos.

A API proxy deve preservar a máquina (changeOrigin: false) para autenticação de mesma origem. Comece com um diretório de dados de teste vazio para executar a configuração e criar um administrador através do formulário usando credenciais sintéticas. Nunca reponha uma instância de trabalho, apagando seu banco de dados.

Ensaios

Testes de infra- estrutura cobrem validação do ambiente, fresco SQLite inicialização, configuração única/corridas/rollback, ciclo de vida dos membros, limites de sessão por usuário, revogação de tempo desativada, função baseada API acesso, verificação da origem/corpo, limites de taxa, falha de prontidão, e APIOs testes frontend cobrem roteamento consciente de funções e menus, criação de membros/alterações de status, validação de configuração, erros de login, logout e limpeza de cache de identidade cruzada, expiração, validação de resposta, navegação e seleção persistente de temas/linguagem. Use apenas dispositivos sintéticos e bancos de dados temporários.

Executar testes focados durante o desenvolvimento:

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

A verificação do navegador deve abranger os layouts de área de trabalho e estreitos, navegação móvel, recarga de rota direta, alterações de linguagem, temas de luz/escuro/sistema e uma infraestrutura desconectada. Os testes de unidade não substituem essas verificações.

Codex testes de adaptadores

Os testes do adaptador nunca usam uma conta real. Injectam fluxos falsos locais através de uma costura de transporte, enquanto a selecção dos parâmetros de produção permanece fixa. Para exercer uma instalação Codex CLI com uma configuração temporária isolada e saída de modelo sintético:

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

O conjunto de testes normal ignora este teste de opt- in externo- cliente. Não leia o programador existente auth.json ou chaveiro para testes. O provedor ao vivo e a aceitação do desktop exigem uma conta explicitamente autorizada; grave esses resultados separadamente da cobertura do protocolo.

Adicionando traduções

1. Adicionar uma chave em Inglês web/src/locales/en.ts.
2. Adicionar a mesma chave web/src/locales/zh.ts e cada localidade adicional JSON dicionário. Preservar variáveis de interpolação e fornecer as categorias plurais exigidas por cada idioma.
3. Utilização useTranslation() e t() Nos componentes, incluindo as etiquetas ARIA.
4. Executar pnpm --dir web typecheck e inspeccione traduções mais longas na área de trabalho e larguras estreitas. Verifique o layout árabe da direita para a esquerda e mantenha códigos e identificadores da esquerda para a direita.

Os idiomas suportados são inglês, chinês simplificado, chinês tradicional, japonês, coreano, espanhol, francês, alemão, português, russo e árabe. content/docs/ e traduções em content/<locale>/, com slugs correspondentes, navegação localizada, pesquisa e Markdown exportações. Novas traduções são assistidas por máquina e precisam de revisão nativo-falante.

As preferências de UI são locais para o navegador. Elas não são configurações de equipe e não são escritas para SQLite.

HTTP rotas e consultas na base de dados

HTTP rotas usar chi com padrão net/http manipuladores. Recursos registrar seus próprios Get, Head, Post, Patch manipuladores no interior Route grupos. Adicione rotas de gerenciamento ao roteador protegido pelo administrador em internal/server/server.go. A autenticação pública e as rotas da chave pessoal são exceções explícitas. A autenticação do portador de sessão, papel e gateway são executadas através do roteador-nível Use, protegendo erros de método e caminhos desconhecidos, bem como endpoints correspondentes. With Para validação e estrangulamento de origem. Não reintroduzir os interruptores de despacho de caminho ou método nos manipuladores.

Cada sub- roteador instala JSON NotFound e MethodNotAllowed manipuladores. O manipulador 405 deriva Allow das rotas registadas pela chi através Match, sem executar manipuladores de aplicativos. Verificações de saúde, status do sistema e ativos estáticos explicitamente registrar HEAD; outras APIs manter seus métodos declarados. O SPA é registrado apenas para GET/HEAD na raiz e não pode lidar com reservado API Recuar.

Gravar as consultas SQL com o nome internal/storage/queries/, agrupados por domínio. sqlc.yaml utiliza a inicialização consolidada SQL como seu esquema e gera internal/storage/db/Corre. make generate depois de alterar as consultas, o esquema ou configuração do gerador. Commit SQL e gerado Ir em conjunto; nunca editar arquivos gerados manualmente. WithTx(tx), e converter linhas para tipos de resposta pública.

O Makefile pinos sqlc para v1.31.1 e executa-o através go run; a primeira invocação baixa e constrói a ferramenta. Vá pode baixar uma cadeia de ferramentas compatível para o gerador. Nenhuma instalação global sqlc, serviço de nuvem, ou conexão de banco de dados é necessária para geração. As dependências do gerador ficam fora do gráfico de dependência do módulo da aplicação. Os arquivos gerados são versionados, então as construções e contêineres de produção comuns Go não precisam de sqlc. make check, incluindo IC, corridas make generate-check rejeitar o código gerado sem reescrevê-lo.

Mudar o esquema de pré- libertação

Preserve os ficheiros existentes em internal/storage/migrations/, incluindo 001_schema.sql. Acrescente migrações incrementais ordenadas e atualize consultas em internal/storage/queries/. O arranque aplica migrações em falta a bases compatíveis; rejeita a estrutura inicial incompatível com 001_settings.sql. Execute make generate, make generate-check e os testes de armazenamento relevantes. sqlc valida a estrutura, mas não migra a base em execução.

Resolução de Problemas

• Retorno do root da infraestrutura frontend_not_built: usar o Vite na porta 5173 para o desenvolvimento, ou executar make build e iniciar bin/sublane.
• A interface mostra uma falha de ligação: confirmar que o processo Go está em execução e que o proxy de Vite aponta para o endereço configurado.
• Porta já em uso: WEB_PORT Controlos Vite; SUBLANE_ADDR controla a infra- estrutura e o seu 'proxy' Vite. Escolha um endereço de infra- estrutura gratuito, por exemplo SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174. Não termine processos não relacionados.
• Ir baixa uma cadeia de ferramentas: isto é esperado quando o Go instalado é mais antigo do que go.mod requer.
• Docker compilação não pode se conectar: iniciar a sua Docker motor, em seguida, executar docker compose -f docker.compose.yaml config --quiet e docker compose -f docker.compose.yaml -f docker.compose.build.yaml build.
• A língua ou o tema permanecem alterados: as preferências são armazenadas deliberadamente no armazenamento local do navegador. Mude- as em Preferências para restaurar os padrões.

Manutenção

Manter go.sum e web/pnpm-lock.yaml sob controle de versão. Execute atualizações de dependência como alterações separadas e preserve avisos de licença de terceiros. Não copie uma árvore Shadcn Admin sobre componentes locais sem rever alterações de localização, nomeação e acessibilidade.

Controlos de embalagem e de libertação

Ver implantação para ensaios de fumo de contentores e operações de lançamento Para o oleoduto com a etiqueta. make test Inclui os testes integrados dos metadados de libertação de Node e os testes de publicação de repositório temporário; make lint verifica a sintaxe do script de lançamento/fumo. O CI constrói e testa os recipientes em ambas as arquiteturas nativas do Linux, então o fluxo de trabalho de lançamento publica essas imagens exatas testadas e extrai seus binários. Nenhuma credencial de registro é usada em verificações pull-request.