Código de contribuição

Localize a implementação

Comece com o comportamento que você está mudando. Para uma ação na área de trabalho, siga apps/desktop/src/app/routes.tsx ao seu adaptador de página e tela de recursos. Localize a solicitação em seu cliente ou auxiliar de recurso, o esquema do terminal em packages/api, o manipulador em apps/sidecar/src/httpe o serviço ou repositório abaixo dele.

Para uma alteração de geometria ou saída NC, comece em packages/core e seus testes adjacentes. Para um problema de persistência, inspecione a consulta do repositório e packages/db/src/schema.ts. Para ciclo de vida nativo, caixa de diálogo de arquivo, chaveiro ou comportamento do atualizador, inspecione apps/desktop/src-tauri/src. Isso mantém uma mudança próxima de sua responsabilidade real.

Responsabilidades do espaço de trabalho

Use o ponto de entrada público de um módulo, quando disponível. Mantenha o acesso SQLite fora da geometria central e dos clientes. As telas de recursos não devem ignorar a autorização secundária ou incorporar credenciais do servidor. As alterações transversais devem atualizar explicitamente cada limite afetado.

Alterar contratos compartilhados deliberadamente

1. Defina os esquemas de solicitação, resposta e erro digitado no pacote de contrato.
2. Implemente o manipulador e seu comportamento de serviço/repositório, incluindo verificações de propriedade.
3. Gere novamente os clientes e verifique se a saída gerada é atual.
4. Atualize consumidores de desktop, complementares, plug-ins ou clientes externos que usam a superfície alterada.
5. Documente a entrada, a saída, o comportamento de falha e os limites operacionais suportados.

bun run generate
bun run generate:check
bun run --filter @cadcamfun/api typecheck
bun run --filter @cadcamfun/sidecar typecheck

Os clientes gerados são resultados do gerador de contrato. Consertar o contrato ou gerador quando seus formatos estiverem errados; uma correção manuscrita na saída gerada será perdida na regeneração. Preserve a semântica existente do cliente ou identifique o impacto de compatibilidade de uma alteração deliberada da API.

Convenções de implementação

Escreva código, comentários e documentação em inglês. Mantenha as interfaces TypeScript exportadas explícitas e use unknown além de validação de esquema para valores não confiáveis. Uso de importações relativas de TypeScript .ts extensões. As distâncias CAD usam milímetros e os ângulos de desenho usam radianos; honrar recursos explicitamente com valor de grau e entradas rotativas CAM. Formate os números NC no limite do posto.

O código de efeito usa as APIs de serviço/camada/erro da versão fixada. Os serviços possuem dependências externas; recursos próprios das camadas com escopo definido. Evite adicionar leituras ocultas de configuração de processo dentro de um módulo de domínio. Mantenha os cálculos geométricos puros e isole as operações do sistema de arquivos, da rede e do banco de dados por trás de seus adaptadores.

Para uma alteração de esquema, modifique schema.ts, gerar uma migração e exercitar a criação e a atualização de um banco de dados existente. Para uma alteração na interface do usuário, mantenha os adaptadores de rota pequenos e coloque a lógica de interação no recurso relevante. Para trabalho nativo, mantenha a geometria e a lógica do repositório no sidecar/core em vez de movê-los para o Rust.

Verificação antes da revisão

• Execute a verificação de tipo do pacote afetado e testes significativos para o comportamento alterado.
• Para uma correção de bug, demonstre a condição de falha e seu resultado corrigido.
• Para contratos compartilhados, verifique os clientes gerados e os consumidores afetados.
• Para persistência, verifique o comportamento da migração e a integridade dos dados usando bancos de dados isolados.
• Para interações nativas ou renderizadas, exercite o tempo de execução de destino real, além dos testes lógicos.
• Atualize a documentação do usuário/desenvolvedor e explique as limitações operacionais restantes.

As verificações de raiz são bun run typecheck e bun run test. CI também tem Rust e trabalhos específicos de complementares. Relate o que foi executado e quaisquer falhas ou cobertura de tempo de execução indisponível; distinguir um fluxo de trabalho configurado de uma execução bem-sucedida.

Mantenha as alterações revisáveis

Mantenha os artefatos gerados, as atualizações de dependências, as alterações de comportamento e as alterações de documentação rastreáveis para o mesmo propósito concreto. Evite reformatar módulos não relacionados. Preserve o trabalho existente do usuário e use diretórios de dados descartáveis para experimentos.

Não inclua tokens de inicialização, links de emparelhamento de dispositivos, chaves de modelo, conteúdo de banco de dados ou credenciais de assinatura em patches ou capturas de tela. Os exemplos devem usar espaços reservados. Um dispositivo local ou provedor simulado pode validar um fluxo determinístico; documento onde o provedor real ou a integração nativa permanecem necessários.

Verificações úteis

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

Usos de embalagens nativas scripts/build.ts; usar --help ou --dry-run para inspecionar suas etapas. Os testes de unidade são separados do estágio de verificação de tipo do pipeline de construção. Consulte o guia de lançamento para assinatura, arquitetura de destino e validação do atualizador.

Exemplo: alteração da validação do projeto

Suponha que uma regra de criação/atualização de projeto seja alterada. O esquema de solicitação é packages/api/src/projects.ts, o adaptador HTTP é apps/sidecar/src/http/projects.ts, e a persistência é implementada por ProjectRepo. O esquema atualmente faz name opcional, enquanto os manipuladores exigem isso para criação e atualização. Inspecione ambos os níveis antes de prometer que uma solicitação válida para o esquema será bem-sucedida.

1. Defina os casos de entrada pretendidos: nome ausente, tipo inválido, texto vazio, organização acessível e organização inacessível.
2. Decida qual condição é um erro de decodificação e qual é uma validação de negócios. Preserve o formato de status/erro documentado do endpoint.
3. Adicione asserções no limite de manipulador/serviço relevante e verifique se os chamadores não autorizados ou não-membros não podem ignorar a regra.
4. Se o esquema público for alterado, gere novamente as famílias de clientes e os consumidores de verificação de tipo.
5. Exercite o formulário de desktop e documente quaisquer requisitos de solicitação alterados.

Atualmente, a criação retorna uma linha de projeto vazia com HTTP 201. Listar/obter linhas enriquecidas com relação de retorno. Não impor um envelope genérico de sucesso a esta família sem atualizar o seu contrato e os seus consumidores. Outras famílias de endpoints usam envelopes diferentes intencionalmente.

O ponto de entrada do gerador é packages/api/scripts/generate-clients.ts. Suas saídas vivem sob src/client/generated e src/sdk/generated. As alterações na superfície do contrato pertencem ao contrato de origem; a saída gerada deve ser reproduzível.

Escolha uma regressão na profundidade certa

Uma regressão geométrica deve afirmar a geometria, não apenas repetir o cálculo que está sendo alterado. Os testes de colisão existentes fornecem padrões úteis: uma sobreposição estacionária é uma colisão no tempo zero; uma varredura rotacional intermediária pode colidir mesmo quando um ponto final está livre; um limite insuficiente não foi resolvido; e uma autorização certificada é comparada com uma referência independente densa.

bun test packages/core/src/cam/kernel/collision.test.ts
bun run --filter @cadcamfun/core typecheck
bun test packages/core

Escolha o limite análogo para outro trabalho. Uma migração de banco de dados precisa de casos novos/de atualização e comportamento de falha de backup. Um analisador de fluxo precisa de quadros divididos e cancelamento. Uma alteração salva da IU precisa de seleção de destino, falha de solicitação, nova tentativa e reabertura do estado salvo. Um comando nativo precisa de validação e comportamento de ciclo de vida, além de uma verificação de tipo de frontend.

Mantenha as verificações proporcionais à mudança. As edições de conteúdo precisam de verificação de navegação/modelo; eles não exigem a invenção de novos testes de domínio. Um teste restrito aprovado suporta apenas seu comportamento declarado, portanto inclua o pacote ou as verificações de integração exigidas pela superfície pública alterada.

Contribuir com documentação

O site está em packages/web. Uso de páginas de documentação DocsLayout, um índice, identificadores de seção e componentes de código/texto explicativo/link relacionado compartilhados. Preserve as convenções da página e o design visual existente enquanto melhora o conteúdo.

1. Leia a implementação, o manifesto e a configuração de cada comportamento documentado.
2. Use um comando ou formato de solicitação compatível e indique o diretório de trabalho, as credenciais, o caminho de dados e os pré-requisitos nativos necessários.
3. Descreva o resultado e seus modos de falha. Rotule os exemplos como exemplos; chame uma resposta capturada somente quando ela foi realmente capturada.
4. Atualize os metadados de navegação e recuperação ao adicionar ou renomear uma rota e corrija todos os links locais para o local antigo.
5. Execute verificações de índice e construção do Astro e, em seguida, inspecione a página renderizada e suas âncoras.

bun run --cwd packages/web check
bun run --cwd packages/web typecheck
bun run --cwd packages/web build

As declarações sobre CI configurado devem indicar o que o fluxo de trabalho faz. As declarações sobre publicação bem-sucedida ou aceitação em tempo de execução precisam da execução/artefato específico como evidência. A documentação deve distinguir o comportamento implementado, os padrões e os limites, sem transformar notas de planejamento interno em instruções do produto.

Lista de verificação de solicitação pull

• bun run typecheck passa pela raiz.
• bun run test passes; o novo comportamento tem um teste próximo ao código.
• As alterações de contrato são regeneradas: bun run generate:check e bun run --filter @cadcamfun/web check estão limpos.
• As alterações de esquema incluem a pasta de migração gerada e nunca são edições de uma migração aplicada.
• Mudanças de Rust passam cargo clippy e cargo test (CI executa ambos).
• O comportamento visível ao usuário é refletido na página de documentos que o descreve.

O CI executa os mesmos comandos em cada push, portanto, uma execução local verde é o melhor preditor de uma solicitação pull verde.

Em 3D