Desenvolvimento local

Processos de desenvolvimento

Uma sessão completa de desenvolvimento de desktop executa um shell Rust, um sidecar Bun e Vite. O shell fornece recursos nativos e supervisiona o sidecar; Vite fornece ativos de visualização da web e recarga dinâmica. bun run desktop:dev prepara os recursos binários e de migração antes de iniciar esses processos.

Para um trabalho de tela mais rápido, execute a área de trabalho dev roteiro sozinho. App.tsx seleciona a API de visualização na memória somente fora do Tauri e somente quando VITE_SIDECAR_URL está ausente. Espera-se que as falhas de visualização de coleções de API não suportadas retornem 501. Use um sidecar ao vivo para persistência, autorização, streaming de IA e serviços de servidor.

CADCAMFUN_TOKEN=local-development-token CADCAMFUN_DATA_DIR=/tmp/cadcamfun-development CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" bun --no-env-file apps/sidecar/src/main.ts

O token acima é um exemplo de um processo de desenvolvimento local isolado. Escolha seu próprio valor. Mantenha o stdin aberto: fechá-lo para o sidecar. O servidor imprime um JSON ready evento com sua porta efêmera após /api/health responde; os logs vão para stderr.

VITE_SIDECAR_URL=http://127.0.0.1:43111 VITE_SIDECAR_TOKEN=local-development-token bun run --filter @cadcamfun/desktop dev

Substitua a porta 43111 pela porta do evento pronto e use o token fornecido a esse sidecar antes de executar. Vite usa a porta 1420 com seleção estrita de porta, correspondendo ao URL de desenvolvimento Tauri. O sidecar permite origens CORS do navegador em HTTP localhost/loopback e as origens Tauri suportadas; ainda requer a autorização adequada para rotas protegidas.

Diretórios de dados e migrações

O sidecar abre <CADCAMFUN_DATA_DIR>/cadcamfun.db. Tauri escolhe seu próprio diretório de dados do aplicativo e o passa para o filho. Um processo manual usa o diretório que você fornece. Esses bancos de dados são independentes mesmo quando seus nomes de arquivo são idênticos.

O script de migração CLI lê DATABASE_URL e de outra forma usa ./data/cadcamfun.db em relação ao seu diretório de trabalho. Raiz db:migrate corre para dentro packages/db. Escolha um URL de arquivo absoluto para operações CLI deliberadas; não infira o destino a partir de um nome de arquivo relativo mostrado em um log.

DATABASE_URL=file:/tmp/cadcamfun-cli/cadcamfun.db bun run db:migrate

As alterações de esquema se originam em packages/db/src/schema.ts. Correr bun run db:generate, revise a migração gerada e aplique-a primeiro a um banco de dados isolado. O sidecar usa CADCAMFUN_MIGRATIONS_DIR quando fornecido; compilações empacotadas preparam o diretório gerado como um recurso.

A camada de banco de dados habilita WAL e chaves estrangeiras. Quando um arquivo existente precisa de migração, o caminho de atualização cria um backup ao lado dele em backups/ e mantém os últimos cinco backups automáticos correspondentes. A primeira criação, um esquema inalterado e bancos de dados na memória não criam um backup de atualização. Preserve os dados de forma independente antes de operações manuais de recuperação.

Verificações direcionadas

bun run --filter @cadcamfun/core typecheck
bun test packages/core
bun run --filter @cadcamfun/desktop typecheck
bun test apps/desktop/src/viewport
bun run --cwd packages/web check
bun run --cwd packages/web build

Selecione verificações pelo limite alterado. Mudanças de geometria pura precisam de asserções de geometria; As alterações no contrato de API precisam de verificações de clientes gerados e manipuladores afetados; mudanças de persistência precisam de testes de repositório e migração; As alterações na interação da IU precisam do componente relevante e do fluxo de tempo de execução. A raiz test roteiro inclui packages, apps, e scripts.

Verificações de shell nativas são executadas em apps/desktop/src-tauri com cargo clippy --all-targets -- -D warnings e cargo test. Prepare primeiro o sidecar e as migrações de destino, já que o contexto de construção do Tauri inclui esses recursos. Os testes de integração do sistema operacional podem exigir um desktop e chaveiro nativos.

Configuração de tempo de execução

apps/sidecar/src/config.ts possui a camada de configuração sidecar. As entradas necessárias são CADCAMFUN_TOKEN e CADCAMFUN_DATA_DIR. CADCAMFUN_MIGRATIONS_DIR seleciona recursos de migração. O host de IA padrão é nikcli; CADCAMFUN_AI_HOST=direct seleciona chamadas diretas e CADCAMFUN_AI_OFFLINE suporta operação offline/teste.

A configuração opcional inclui o URL do aplicativo e links de autenticação de desenvolvimento, credenciais Stripe e identificadores de preço, configurações de administrador/cron e OTEL_EXPORTER_OTLP_ENDPOINT. A faturação não está disponível sem a configuração do fornecedor relevante; a exportação de telemetria está desativada sem o terminal do coletor. Forneça apenas os insumos necessários para o seu fluxo.

As variáveis de endpoint do navegador são configuração do Vite, não configuração secundária. Um emparelhamento complementar contém um token e um endereço HTTPS diferentes. Um token de ponte de ação independente tem seu próprio escopo e vida útil. Não substitua essas credenciais umas pelas outras.

Use configuração de processo explícita ou configurações de aplicativo. O comando sidecar de amostra desativa o carregamento do arquivo de ambiente do Bun. Nunca imprima tokens reais, chaves de modelo, links de emparelhamento ou material de assinatura em registros ou exemplos de documentação.

Efeito e propriedade de recursos

O repositório fixa Efeito em 4.0.0-rc.112. Uso de serviços Context.Service, as implementações são fornecidas por meio de camadas e as operações retornam efeitos digitados. Utilize o instalado effect/ai-docs/src documentação ao alterar esta API, incluindo seus módulos HTTP instáveis.

Decodifique a entrada externa nos limites. Mapeie exceções estrangeiras em erros digitados, preserve tags de erro estáveis e deixe que uma camada com escopo possua identificadores de banco de dados, trabalhadores, fluxos e recursos de servidor. O fluxo de desligamento do sidecar lida com um evento de desligamento pai, fechamento stdin e interrupção de tempo de execução; logs e protocolo stdout têm destinos diferentes.

Os principais cálculos CAD/CAM permanecem funções simples em hot paths computacionais. A validação de encapsulamento no limite não requer colocar todas as operações geométricas dentro de um Efeito. Use as convenções da unidade geométrica principal e execute conversões de exibição/exportação na aresta apropriada. Os ângulos de desenho usam radianos; alguns parâmetros de recurso e valores de eixo rotativo CAM usam graus explicitamente.

Solução de problemas de inicialização

• Porto Vite ocupado: liberar porta 1420 ou parar o servidor de desenvolvimento existente; o modo de porta estrito não escolhe outra porta silenciosamente.
• A inicialização continua tentando novamente: inspecione a saída do sidecar pronto/erro e o caminho de migração. O aplicativo resolve novamente o endpoint enquanto seu orçamento de conexão permanece.
• O servidor sai imediatamente: verifique a configuração necessária e se o processo de inicialização fechou stdin.
• Faltam projetos: confirme o diretório de dados, o endpoint da API e se o aplicativo está usando o cliente falso.
• 401 respostas: verifique se o cliente está usando o token do processo atual em vez de uma inicialização anterior.
• 501 na visualização do navegador: use um sidecar real para essa coleção de API.
• A construção do contexto nativo falha: preparar os recursos binários e de migração do sidecar para o destino correto.

Documentação e desenvolvimento complementar

bun run --cwd packages/web start dirige o Astro sozinho. bun run --cwd packages/web dev inicia o Astro mais a API local do Studio. A verificação da documentação valida o índice de rota; a construção valida a compilação e pré-renderização do Astro.

Para iOS, bun run --cwd apps/mobile start inicia o Metro para um cliente de desenvolvimento personalizado. bun run --cwd apps/mobile ios cria/executa o aplicativo nativo; build exporta apenas JavaScript. A fixação nativa requer o módulo Swift local e não pode ser executada no Expo Go.

bun scripts/build.ts --help lista as opções do pipeline de lançamento. --only=resources reorganiza as migrações sem reconstruí-las e --dry-run imprime o plano sem escrever nada.

Referência de configuração de processo

As entradas booleanas são decodificadas pela configuração do efeito, e não pela veracidade arbitrária da string. Use valores verdadeiros/falso explícitos. Literais de host de IA desconhecidos falham na decodificação. Configuração do fornecimento antes da criação do processo; alterar uma variável de terminal pai não atualiza um sidecar já em execução.

Use o Studio em um banco de dados explícito

A API local do Studio escuta na porta de loopback 4396. Sua precedência de caminho é CADCAMFUN_DB, então DATABASE_URL com um file: prefixo removido, então raiz do repositório data/cadcamfun.db. Isso difere do caminho do diretório de trabalho CLI padrão do pacote de banco de dados. Ele abre apenas um banco de dados existente e não cria/migra um banco de dados automaticamente.

DATABASE_URL=file:/tmp/cadcamfun-studio/cadcamfun.db   bun run db:migrate

CADCAMFUN_DB=/tmp/cadcamfun-studio/cadcamfun.db   bun run --cwd packages/web dev

O primeiro comando inicializa o arquivo. O segundo inicia o Studio mais o Astro nesse caminho. Um novo esquema migrado não contém uma sessão de usuário/senha apenas porque existe; O login no Studio requer uma conta adequada. Suas solicitações autenticadas usam o cookie de sessão do Studio e retornam 401 sem uma sessão válida.

Quando o arquivo estiver ausente, a API Studio retornará 503 com o caminho selecionado. Quando o Astro é executado sem o processo complementar do Studio, o proxy /studio/api as solicitações não podem alcançar a porta 4396. As próprias páginas de documentação podem ser desenvolvidas com packages/web start sem iniciar o Studio.

Âncoras de implementação: packages/web/script/dev.ts, script/studio-server.ts, astro.config.mjs, packages/db/src/migrate.ts, e apps/sidecar/src/config.ts.

Um ciclo de desenvolvimento repetível

1. Escolha um diretório de dados secundário descartável e uma pasta de migração explícita.
2. Inicie o sidecar em um terminal interativo e registre a porta a partir de seu evento pronto.
3. Inicie o Vite em outro terminal com o URL/token correspondente ou abra o aplicativo nativo com seu sidecar supervisionado.
4. Reproduza uma ação e inspecione sua resposta e estado persistente.
5. Para alterações de back-end, reinicie o sidecar, atualize o endpoint do navegador se sua porta for alterada e repita a ação.
6. Pare o processo com sua interrupção normal ou caminho de desligamento pai para que os recursos sejam finalizados.

O sidecar drena brevemente os escopos HTTP, verifica o WAL e fecha o SQLite no desligamento normal do escopo. Eliminar um processo sem esse caminho pode interromper o trabalho em andamento. Uma edição do código-fonte não substitui o binário compilado já supervisionado pelo Tauri; reconstrua o sidecar ao testar o comportamento compilado.

Para validação de tempo de execução compilado, scripts/smoke-sidecar.ts pode executar um binário selecionado com um diretório inicial/dados isolado e IA offline. Ele mede o comportamento de prontidão/saúde/ação e exerce um trabalho de kernel. Sem --binary primeiro ele compila um executável temporário, então planeje o custo de construção; seu resultado é separado dos testes no nível de origem.

Qual processo é executado onde

Loop interno por tipo de mudança

Em 3D