Desenvolvimento
Desenvolvimento
1 - Pré-requisitos
- Docker e Docker Compose instalados
- Tempo de execução Bun instalado (https://bun.sh)
- Repositório Lowcode Studio clonado
- Repositório Tauri do Motor Lowcode clonado (opcional, para funcionalidade de pré-visualização)
2 - Instalação
2.1 - Dependências de Instalação
A partir da raiz do projeto, instale todas as dependências do workspace:
2.2 - Iniciar Serviços de Infraestrutura
Lowcode Studio requer PostgreSQL e Redis. A é fornecido na raiz do projeto:docker-compose.yml
Começa assim:
- PostgreSQL 17 na porta (usuário: , senha: 5432 run2biz run2biz)
- PgBouncer na porta (pooler de conexão para PostgreSQL, modo transação) 6432
- Redis 7 na porta (senha: 6379 run2biz)
-
📌 A API se conecta via PgBouncer (porta) em vez de diretamente ao PostgreSQL (porta). O PgBouncer oferece pooling de conexões no modo de transação, essencial para cargas de trabalho multi-inquilino. 6432 5432
2.3 - Configuração do Ambiente
Configuração do servidor
Crie um arquivo no diretório após o modelo. .env/ server .env .example
Para desenvolvimento local, configure o banco de dados e URLs do Redis apontando para via PgBouncer: localhost
DATABASE_URL=postgresql://run2biz:run2biz@localhost:6432/postgres
REDIS_URL=redis://default:run2biz@localhost:6379❗ Não inclua no — o PgBouncer no modo de transação não suporta parâmetros de inicialização. O esquema de Drizzle já é qualificado com , então todas as consultas são prefixadas automaticamente. search_path DATABASE_URL pgSchema("lowcode_studio")
Migrações de banco de dados usam que reescrevem a porta de para conectar diretamente ao PostgreSQL (contornando o PgBouncer), já que precisa do parâmetro de inicialização. drizzle.config.ts 6432 5432 drizzle-kit search_path
📌 Ao rodar dentro do Docker (por exemplo, via Edge-runtime), use os nomes de host dos contêineres:
Configuração do Cliente
Crie um arquivo no diretório após o modelo. .env /client .env .example
Para desenvolvimento local, o cliente aponta diretamente para a API do servidor:
VITE_API_URL=http://localhost:8080/api
VITE_ENGINE_URL=http://localhost:1420/tauri-engineVariável | Descrição | Padrão |
|---|---|---|
VITE_API_URL | URL completa para o servidor API do Lowcode Studio | /lowcode-studio-api/api (produção) |
VITE_ENGINE_URL | URL onde a Tauri Engine é servida | /tauri-engine (produção) |
📌 Em produção, ambos e usam caminhos relativos porque a API e o motor são servidos pela mesma origem em tempo de execução de borda. No desenvolvimento local, eles devem apontar para as URLs reais dos serviços, já que não há proxy reverso.
VITE_API_URL VITE_ENGINE_URL
2.4 - Executar migrações de banco de dados
Após iniciar o PostgreSQL, execute as migrações do banco de dados:
2.5 - Iniciar Servidores de Desenvolvimento
A partir da raiz do projeto, inicie tanto o cliente quanto o servidor simultaneamente:
Começa assim:
- Servidor (Hono API): http://localhost:8080
- Cliente (Vite): http://localhost:4000
Você também pode começar individualmente:
Iniciar o motor Tauri (opcional)
Para usar o recurso de pré-visualização móvel, inicie o servidor de desenvolvimento do Tauri Engine em seu próprio repositório:
Isso serve ao motor em .http://localhost:1420/tauri-engine
Veja Integração do Motor para detalhes da configuração do Motor Tauri.
2.6. Definir o Cookie de Autenticação
A aplicação requer um token JWT válido. Defina o cookie no seu navegador para .HYPER-AUTH-TOKENlocalhost:4000
Você pode fazer isso via DevTools do navegador:
- Abra no seu navegador http://localhost:4000
- Abrir DevTools → Cookies de Aplicação → → http://localhost:4000
- Adicione um cookie com nome e um token JWT válido como valor HYPER-AUTH-TOKEN
Alternativamente, se o tempo de execução de borda estiver disponível, use o endpoint set-cookie:
2.7. Acesse ao Lowcode Studio
Quando ambos os serviços estiverem em execução, acesse o Lowcode Studio em:
3. Notas de Arquitetura
3.1. Stack de Middleware de Servidor
O middleware da API executa nesta ordem:
- prettyJSON → → trimTrailingSlashcors
- /health endpoint (não autenticado)
- /webhooks Rotas (não autenticadas)
- setTenantDb → validateToken
- Rotas de domínio (, , , /components/projects/permissions/users)
📌 O middleware CORS é colocado antes da autenticação para garantir que as solicitações de pré-voo tenham sucesso. Isso é essencial quando o cliente e o servidor rodam em origens diferentes (por exemplo, e ).OPTIONSlocalhost:4000localhost:8080
3.2. Solicitações de Origem Cruzada
No desenvolvimento local, o cliente () faz requisições diretas ao servidor (). Isso exige: localhost:4000localhost:8080
- Servidor: CORS configurado com origem dinâmica e credentials: true
- Cliente: Todas as solicitações de busca incluem enviar cookies de origem cruzada credentials: "include"
- Tauri Engine: Usa em seu cliente HTTP pelo mesmo motivo withCredentials: true
Em produção, todos os serviços estão atrás da mesma origem (tempo de execução de borda), então a origem cruzada não é um problema.
4. Implantação via tempo de execução de borda
Para implantação via Edge-runtime (configuração semelhante a produção), consulte a integração original Edge-runtime:
4.1. Configurar o Volume do Docker
No runtime do Edge, adicione o volume correspondente para o servidor Lowcode Studio: docker-compose.yml
volumes:
- ../edge-functions/lowcode-studio/server:/home/deno/functions/lowcode-studio-api/1.0.04.2. Iniciar Serviços de Execução em Borda
Navegue até o diretório raiz Edge-runtime e execute:
docker-compose up -d --build📌 Ao iniciar, o tempo de execução da borda irá automaticamente:
- Executar migrações de banco de dados
- Configure o esquema necessário para o Lowcode Studio
- Preencher dados iniciais de seed
Uma vez em execução, acesse o Lowcode Studio via Edge-runtime em:
5. Solução de problemas
5.1. Problemas de Conexão com Banco de Dados
Se você encontrar erros na conexão do banco de dados:
- Verifique se o PostgreSQL está rodando: docker compose ps
- Confirme que o parâmetro está corretamente definido em search_pathDATABASE_URL
- Verifique se o esquema existe no banco de dados lowcode_studio
- Certifique-se de estar usando (desenvolvedor local) ou o nome de host Docker (container) localhost:5432
5.2. Falhas na migração
Se as migrações falharem em executar:
- Verifique se o PostgreSQL está acessível: docker compose logs postgres
- Verificar credenciais de banco de dados em server/.env
- Certifique-se de que o formato da URL do banco de dados esteja correto
- Execute migrações manualmente: cd server && bun run db:migrate
5.3. Problemas de Conexão com o Cliente
Se o cliente não conseguir se conectar à API:
- Verifique se o servidor está rodando na porta 8080
- Verifique os pontos de entrada para VITE_API_URLclient/.envhttp://localhost:8080/api
- Verifique o console do navegador para erros CORS — certifique-se de que o middleware CORS do servidor esteja antes da autenticação
- Verifique se o cookie está configurado para o domínio correto HYPER-AUTH-TOKEN
5.4. Prévia Não Funcionando
Se a prévia móvel mostrar "Projeto não encontrado":
- Verifique se o Motor Tauri está rodando em http://localhost:1420/tauri-engine
- Pontos de verificação para VITE_ENGINE_URLclient/.env http://localhost:1420/tauri-engine
- Verifique se a Tauri Engine tem e .env VITE_API_URL=http://localhost:8080/api VITE_ENGINE_MODE=PREVIEW
- Verifique no console do navegador para erros de CORS ou autenticação
- Certifique-se de que o cliente HTTP do Tauri Engine esteja ativado withCredentials: true
