Solução de problemas na área de trabalho

Identifique o tempo de execução antes de alterá-lo

Uma sessão de desktop tem limites de falha separados: o Vite fornece ativos de frontend durante o desenvolvimento; o processo Tauri Rust possui integração nativa; o sidecar Bun atende solicitações de aplicativos e persistência; o webview SolidJS se conecta a essa API. Uma janela em branco, um tempo limite de inicialização, uma resposta 401 e uma lista de projetos vazia podem ter causas diferentes.

Registre o comando de inicialização e se o endpoint veio das variáveis Tauri ou Vite. Não exclua um banco de dados nem reinstale dependências apenas porque um tempo de execução diferente mostra dados diferentes.

Entenda o tempo de inicialização

O shell Rust gera um token de inicialização, resolve dados de aplicativos e diretórios de migração e gera o sidecar de destino. A criança liga 127.0.0.1 em uma porta efêmera. Ele espera até que seu público /api/health responde e, em seguida, grava um evento pronto para JSON com essa porta. A visualização da web invoca get_sidecar_endpoint e cria seu tempo de execução de API gerenciado.

Repetir reinicia as tentativas de conexão do webview; não reabastece um orçamento esgotado de supervisão da Rust. Corrija a causa da inicialização e reinicie o aplicativo quando o supervisor atingir o estado de falha do terminal. Uma porta anterior à reinicialização secundária pode estar obsoleta.

Verifique as portas e a integridade separadamente

Vite usa localhost:1420 com seleção estrita de porta, correspondendo ao URL de desenvolvimento configurado do Tauri. Ele falha em vez de se mover silenciosamente para outra porta. A porta sidecar não está relacionada e muda entre os lançamentos. A porta HTTPS complementar é um terceiro listener, padrão 8443, e o Studio usa loopback 4396.

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token

curl --max-time 5 --fail-with-body "$CADCAM_URL/api/health"
curl --max-time 5 --fail-with-body "$CADCAM_URL/health"   -H "Authorization: Bearer $CADCAM_TOKEN"
curl --max-time 5 --fail-with-body "$CADCAM_URL/version"   -H "Authorization: Bearer $CADCAM_TOKEN"

A rota de saúde pública retorna status e carimbo de data/hora. As rotas do sistema autenticadas expõem a prontidão e a versão do aplicativo. Um processo íntegro não prova que todos os provedores, consultas de banco de dados ou caixas de diálogo nativas funcionam. Compare o API de saúde e API do sistema ao selecionar sondas.

Se a porta 1420 estiver ocupada, identifique e pare deliberadamente o servidor de desenvolvimento existente. Se uma porta de API lembrada recusar conexões, leia o evento ready atual ou resolva novamente o endpoint Tauri em vez de adivinhar as portas vizinhas.

Reproduzir com um sidecar isolado

Um processo de origem é útil para separar problemas do pacote nativo do comportamento do servidor. Execute isto a partir da raiz do repositório em um terminal interativo; ele cria um novo diretório de dados e usa explicitamente a pasta de migração gerada.

CADCAM_DIAGNOSTIC_DIR=$(mktemp -d /tmp/cadcamfun-desktop-guide.XXXXXX)
CADCAMFUN_TOKEN=local-development-token CADCAMFUN_DATA_DIR="$CADCAM_DIAGNOSTIC_DIR/data" CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" CADCAMFUN_AI_OFFLINE=true bun --no-env-file apps/sidecar/src/main.ts

Copie a porta anunciada nas variáveis de teste em um segundo terminal. O modo AI offline evita depender de um modelo remoto configurado para diagnósticos básicos de inicialização; ele não executa um modelo local alternativo. O servidor observa stdin EOF, um evento de desligamento explícito e interrupções normais de tempo de execução.

Um processo de origem usa arquivos atuais. Um processo nativo usa o executável compilado já preparado em src-tauri/binaries. Se apenas a execução compilada falhar, reconstrua por meio bun run build:sidecar e inspecionar recursos de agrupamento/migração. A edição do TypeScript não substitui um executável já em execução.

Resolva o caminho real do banco de dados

Esses arquivos não são aliases. Combine o caminho do processo selecionado antes de investigar desenhos ausentes. Os equipamentos do navegador nunca abrem esses arquivos SQLite. O sidecar aplica migrações somente quando sua configuração fornece uma pasta de migração; omiti-lo não descobre automaticamente a pasta da árvore de origem.

A camada de banco de dados habilita WAL e chaves estrangeiras. Antes de uma atualização de banco de dados existente, ele grava um backup automático de pré-migração e retém cinco backups correspondentes. Ele não cria esse backup a cada salvamento, inicialização inalterada, primeira criação ou teste na memória. Preservar um backup consistente através do procedimento de banco de dados/recuperação; copiar apenas o arquivo principal de um banco de dados WAL em execução pode omitir o conteúdo confirmado do WAL.

Leia a saída e os logs do protocolo

Em um terminal sidecar de origem, stdout é reservado para eventos de protocolo pronto/erro e os logs do aplicativo JSON vão para stderr. No aplicativo nativo, o plug-in de registro Rust captura eventos do lado do shell, incluindo saída filho supervisionada. O shell edita linhas que podem conter suas credenciais de inicialização.

O nativo get_logs_dir o comando resolve o diretório de log do aplicativo do sistema operacional. É mais confiável do que assumir um caminho universal entre sistemas. Um diagnóstico do desenvolvedor dentro do webview pode invocá-lo por meio da interface de comando Tauri existente; a abertura do caminho nativo é restrita às pastas permitidas e recusa tipos de arquivos executáveis.

O componente reutilizável da tela de inicialização oferece suporte a um retorno de chamada opcional de Visualização de logs, mas o atual App.tsx não passa esse retorno de chamada. Não presuma que o botão Exibir logs estará visível durante uma falha na inicialização. Mantenha o terminal de inicialização de desenvolvimento disponível ou use o diretório de log nativo por meio de uma superfície de diagnóstico apropriada.

Para um relatório, inclua o modo de inicialização, dados não secretos/caminhos de migração, espera decorrida, versão atual da API, etiqueta/mensagem de erro exata e últimos eventos de inicialização relevantes. Redija tokens de inicialização/sessão/dispositivo, links de emparelhamento, chaves de modelo e material de assinatura.

Distinguir autenticação de dados vazios

O modo cliente real do navegador requer ambos VITE_SIDECAR_URL e VITE_SIDECAR_TOKEN. Uma URL sem token não ativa o substituto falso; a resolução do endpoint falha. As variáveis devem ser fornecidas antes do início do Vite. Atualizar um shell pai não reconfigura um servidor já em execução.

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

As chamadas protegidas podem usar o contexto da sessão da conta além do token do aplicativo. Os tokens de ponte complementares e independentes têm escopos mais restritos e não substituem um token de lançamento. Um 401 precisa de diagnóstico de credenciais; um 403 precisa de diagnóstico de operação/acesso; um projeto ausente ou inacessível pode ser relatado como 404.

Algumas telas, incluindo guias de recursos filhos do projeto, atualmente transformam erros de listas individuais em matrizes vazias. Uma guia em branco não é evidência suficiente de que os registros foram excluídos. Leia o correspondente projeto, desenho, ou percurso da ferramenta endpoint antes de recriar o trabalho.

Um token de inicialização válido tem 64 caracteres hexadecimais (32 bytes aleatórios) e muda a cada inicialização. Um token de formato diferente não foi emitido pelo shell da área de trabalho.

Reconheça as limitações nativas e de visualização

A API falsa lida com projetos, desenhos, materiais, ferramentas, máquinas, percursos da ferramenta de ferramentas, KV e caminhos de gerador selecionados. Coleções não suportadas retornam HTTP 501 com uma mensagem específica de visualização. Os dados do aparelho pertencem à página em execução. Uma ação de visualização bem-sucedida não pode demonstrar comportamento persistente de organização, plug-in, cobrança ou provedor ativo.

Diálogos nativos, operações de chaveiro, bandeja, atualizador e materiais macOS exigem o host Tauri e os recursos corretos. Um comando registrado ainda pode estar indisponível para o webview sob sua configuração de capacidade. Para abertura de arquivos, o shell registra associações suportadas e encaminha caminhos; isso por si só não prova que um editor específico importou o conteúdo.

Falhas gráficas são outro limite. Um tamanho de contêiner diferente de zero, entidades/camadas visíveis, seleção desbloqueada e WebGL compatível são pré-requisitos para as interações relevantes da janela de visualização. Uma malha renderizada é uma evidência de renderização, não de um salvamento bem-sucedido ou verificação CAM. Use o diagnóstico da janela de visualização para capacidade do trabalhador, tempo limite e comportamento de quatro visualizações.

Recupere problemas de preferência e exibição

O registro de preferência de webview compartilhado é cadcamfun.settings. Os padrões incluem milímetros, tema do sistema, três casas decimais, preferência GRBL, ajuste ativado, tolerância 0.01 mm e vidro ativado. Os campos armazenados são validados de forma independente; valores inválidos retornam sem causar falha no shell. O armazenamento local completo/bloqueado pode impedir a persistência.

A alteração das unidades de exibição não redimensiona a geometria CAD armazenada. A tolerância do documento é propagada através do auxiliar compartilhado de configurações de CAD/gerador/verificação. Alguns valores de recurso/rotativos usam explicitamente graus; ângulos de desenho usam radianos. Verifique o contrato de campo antes de diagnosticar uma incompatibilidade numérica como geometria corrompida.

O comportamento do Glass depende do suporte Tauri/macOS. A implementação usa Liquid Glass quando compatível, vibração em macOS mais antigos por meio do plug-in e um substituto opaco quando indisponível ou desativado. As alterações de tema/material não alteram a geometria, a propriedade do projeto ou as evidências de usinagem.

Prefira as configurações relevantes ou o controle de recursos em vez de limpar todo o armazenamento de visualização da web. Esse armazenamento também pode conter transferências de sessão/editor. Uma redefinição de preferência visual não é um procedimento de reparo de banco de dados.

Separe a recuperação da UI das evidências de usinagem

Um projeto carregado, um salvamento HTTP bem-sucedido, um percurso animado e um NC gerado são observações diferentes. Antes de confiar em um resultado de usinagem salvo, inspecione o NC exato, o desenho/estoque de origem, os conjuntos de ferramentas, o envelope da máquina, o poste selecionado e a liberação/problemas de verificação para esse resultado.

O código de instantâneo CAM preserva a evidência do kernel somente quando o texto NC atual e seu hash correspondem. O programa portátil escreve, valida a consistência do documento e pode reavaliar as solicitações capturadas do kernel. Editar NC ou alterar estoque pode invalidar evidências anteriores. A reabertura do NC simples pode analisar um programa sem restaurar a mesma prova de fabricação.

Após uma falha ou interrupção do salvamento, primeiro inspecione a linha salva e suas versões. O modo de salvamento CAM registra o programa anterior antes de uma atualização, enquanto o salvamento manual de detalhes do percurso registra a revisão atualizada. O histórico do projeto está separado novamente. Usar a comparação histórica para escolher um caminho de recuperação.

Não converta uma verificação não resolvida em uma operação aceita porque a IU foi recuperada. Execute novamente a verificação apropriada em relação aos recursos reais e NC; uma investigação de integridade do aplicativo não tem autoridade sobre a segurança da máquina.

Faça a triagem de uma falha de cada vez

1. Grave o modo de inicialização, versões do processo, portas e diretório de dados real.
2. Sonde a saúde e, em seguida, uma leitura protegida. Conectividade separada da autorização.
3. Inspecione erros estruturados de inicialização/migração antes de redefinir ou excluir qualquer coisa.
4. Reproduza em um processo de origem isolado quando houver suspeita de um problema compilado/nativo.
5. Corrija a causa identificada, reinicie o processo apropriado e atualize as variáveis de endpoint obsoletas.
6. Reabra o documento/programa salvo e inspecione o estado persistente, as versões, as exportações e a verificação atual.

As âncoras de implementação são app/App.tsx, app/sidecar.ts, src-tauri/src/{sidecar,commands,lib}.rs, o sidecar main.ts/config.ts/shutdown.tse o ciclo de vida do banco de dados. Desenvolvimento local detalhes de configuração de suprimentos; emparelhamento de companheiro lida com seu limite de rede separado.

Lista de verificação de inicialização

1. O binário sidecar está presente para esta plataforma (src-tauri/binaries/sidecar-<target triple>)? desktop:dev constrói; tauri:dev pode usar um esboço.
2. As migrações são realizadas em src-tauri/resources/migrations? bun run build:sidecar ou bun scripts/build.ts --only=resources os reestabelece.
3. O sidecar imprimiu ready dentro de 60 segundos? Procure um error linha em logs stdout e JSON em stderr no diretório de log (get_logs_dir).
4. Ele reiniciou? Apenas é permitido um reinício automático; uma segunda falha deixa o status em failed.
5. Faz GET /api/health responder na porta relatada? Se isso acontecer, mas as rotas protegidas retornarem 401, o token pertence a um lançamento diferente.
6. O diretório de dados é gravável e o arquivo do banco de dados não é mantido aberto por outro processo com migrações incompatíveis?

Lendo os registros

Os logs secundários são linhas JSON no stderr, mantidas separadas do handshake stdout. Linhas que podem conter credenciais são substituídas por [redacted: line may contain credentials] antes de serem gravados, portanto, é esperada uma linha editada em um log, e não corrupção. Se o próprio handshake carregasse tal linha, o erro de inicialização relatado seria o marcador de redação; leia as linhas stderr circundantes para obter contexto.

O diretório de log é específico da plataforma. Obtenha-o do get_logs_dir comando em vez de adivinhar um caminho, e abra-o com open_path, que aceita o diretório de log do aplicativo.

Mensagens de erro e o que elas significam

Em 3D