Ciclo de vida do projeto

O que um projeto contém

Um projeto agrupa desenhos, componentes reutilizáveis e percursos da ferramenta salvos. Um desenho armazena um documento JSON; um componente armazena dados de projeto reutilizáveis; um percurso pode conter NC simples e metadados ou um documento CAM portátil validado. Materiais, cortadores e configurações de máquina são registros de recursos separados que os fluxos de trabalho de usinagem podem fazer referência. Um identificador de projeto não substitui nenhum desses identificadores de recursos.

Este guia segue as mesmas famílias utilizadas pelo desktop. Ele separa salvar o estado do aplicativo, baixar um arquivo, registrar uma versão do percurso da ferramenta e confirmar o histórico do projeto. Essas operações preservam informações diferentes. Comece com um projeto de desenvolvimento descartável antes de aplicar a sequência ao trabalho de produção.

Os exemplos são modelos de solicitação cujos corpos JSON correspondem aos esquemas atuais. Elas não são respostas capturadas do servidor. Para cada campo e status declarado, use o Projetos, Desenhos, Componentes, e Percursos da ferramenta Referências de API.

Selecione a API real

Execute a área de trabalho com bun run desktop:dev, ou inicie um sidecar manual isolado usando o receita de desenvolvimento local. O processo manual anuncia uma porta efêmera. A visualização do navegador sem um endpoint usa fixtures na memória; ele não pode estabelecer que um projeto sobrevive ao reiniciar o servidor.

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token
CADCAM_DEMO_DIR=$(mktemp -d /tmp/cadcamfun-project-guide.XXXXXX)

curl --fail-with-body "$CADCAM_URL/api/health"
curl --fail-with-body "$CADCAM_URL/api/projects"   -H "Authorization: Bearer $CADCAM_TOKEN"

A saúde é pública, portanto pode ser bem-sucedida enquanto uma solicitação de projeto protegido falha na autorização. Use o token fornecido para este processo. Mantenha o mesmo shell para os exemplos a seguir para que a URL, o token, o diretório temporário e os identificadores extraídos permaneçam disponíveis. Mantenha o stdin do sidecar aberto em seu terminal de lançamento.

Criar e inspecionar um projeto

curl --fail-with-body -X POST "$CADCAM_URL/api/projects"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"Bracket study","description":"Disposable guide project","organizationId":null,"isPublic":false}'   -o "$CADCAM_DEMO_DIR/project.json"

CADCAM_PROJECT_ID=$(bun --no-env-file -e   'console.write((await Bun.file(process.argv[1]).json()).id)'   "$CADCAM_DEMO_DIR/project.json")
curl --fail-with-body "$CADCAM_URL/api/projects/$CADCAM_PROJECT_ID"   -H "Authorization: Bearer $CADCAM_TOKEN"

A criação retorna HTTP 201 com uma linha do projeto. O manipulador requer um nome verdadeiro, mesmo que o esquema de transporte declare esse campo opcional. A organização fornecida deve ser aquela à qual o chamador pertence. A leitura do projeto retorna informações do proprietário/organização e contagens de desenhos/componentes; é uma forma de resposta diferente da criação.

Na área de trabalho, use /projects para navegar e /projects/:id para abrir o painel. Possui guias Desenhos, Componentes e Percursos, além de ações de edição, exclusão e controle de versão. A atualização do projeto requer o nome novamente; o proprietário ou ADMIN/GERENTE da organização pode atualizar, enquanto a exclusão é restrita ao proprietário ou ADMIN.

Crie e abra um desenho

curl --fail-with-body -X POST "$CADCAM_URL/api/projects/$CADCAM_PROJECT_ID/drawings"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"Main drawing","description":null,"data":{"elements":[],"version":"1.0"}}'   -o "$CADCAM_DEMO_DIR/drawing.json"

CADCAM_DRAWING_ID=$(bun --no-env-file -e   'console.write((await Bun.file(process.argv[1]).json()).id)'   "$CADCAM_DEMO_DIR/drawing.json")
curl --fail-with-body "$CADCAM_URL/api/drawings/$CADCAM_DRAWING_ID"   -H "Authorization: Bearer $CADCAM_TOKEN"

A mesma forma de documento vazio é usada pelo fluxo de criação de desenho do painel do projeto. Cria uma linha, não uma geometria. Abrir /cad?drawingId=<id> ou /drawings/<id> para editá-lo. Com /cad?projectId=<id>, o CAD seleciona o desenho mais recente do projeto; um desenho nomeado tem precedência.

A criação de desenhos precisa de acesso ao projeto e de um nome. A leitura/atualização de um desenho individual requer o proprietário do projeto ou um membro da organização; a exclusão adiciona uma verificação de proprietário/organização-ADMIN. JSON data não é validado como um documento de geometria desenhável completo pelo ponto final genérico. Uma gravação bem-sucedida, portanto, não prova que todos os elementos fornecidos podem ser renderizados.

Salve, duplique e exporte dados de projeto

Em um desenho armazenado já aberto, a ação de salvar do CAD atualiza esse desenho e adiciona componentes ausentes da biblioteca local ao seu projeto. A página CAD implementa seu próprio Cmd/Ctrl+S manipulador. Um documento sem destino armazenado abre o fluxo de exportação/salvamento; Salvar como projeto requer geometria ou um elemento selecionado e cria um novo projeto e desenho.

O instantâneo do desenho inclui elementos, camadas, identificador do elemento selecionado, configurações de medição e uma versão do formato. O caminho de carregamento atual restaura elementos e configurações válidas de unidades/tolerância, mapeia identificadores de camada desconhecidos para a camada ativa e limpa a seleção. Não infira a restauração completa da camada a partir dos campos presentes em uma exportação.

A sincronização de componentes do projeto corresponde a nomes cortados e que não diferenciam maiúsculas de minúsculas e adiciona nomes ausentes; ele não substitui uma definição de mesmo nome. A criação de componentes é o melhor esforço e pode falhar de forma independente. Um desenho salvo não prova que todos os componentes locais foram copiados e o fluxo de salvamento de múltiplas solicitações não é uma transação de banco de dados.

A partir de um cartão de desenho, o Duplicate carrega seus dados armazenados e cria um novo identificador. Download exporta os dados desse desenho como JSON; ele não exporta um projeto inteiro. As atualizações genéricas de desenhos aplicam valores verdadeiros de nomes/dados/miniaturas e permitem uma descrição nula explícita. Eles não expõem o parâmetro hash de comparação e troca do repositório.

Armazene um componente reutilizável

curl --fail-with-body -X POST "$CADCAM_URL/api/projects/$CADCAM_PROJECT_ID/components"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"Bracket insert","description":"Reusable empty template","data":{"name":"Bracket insert","type":"custom","elements":[]}}'   -o "$CADCAM_DEMO_DIR/component.json"

CADCAM_COMPONENT_ID=$(bun --no-env-file -e   'console.write((await Bun.file(process.argv[1]).json()).id)'   "$CADCAM_DEMO_DIR/component.json")
curl --fail-with-body -X PUT "$CADCAM_URL/api/components/$CADCAM_COMPONENT_ID"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"type":"custom","isPublic":false,"data":{"name":"Bracket insert","type":"custom","elements":[]}}'

A criação retorna HTTP 201. A operação de criação do repositório atual armazena nome, descrição, dados e associação do projeto; ele não persiste opções de tipo/público/miniatura de nível superior na criação. A atualização explícita acima define o tipo e a visibilidade de nível superior pretendidos. A atualização valida dados verdadeiros do componente, normaliza campos opcionais ausentes e rejeita um patch vazio.

Abrir /components/:id para a tela de detalhes ou navegue /components com um filtro de projeto. A visibilidade atualmente inclui proprietários de projetos, membros da organização e componentes públicos. Os manipuladores de componentes não impõem uma porta adicional somente ao proprietário para edições/exclusões de componentes visíveis; não trate a visibilidade pública como um compartilhamento protegido somente leitura.

Preparar recursos de usinagem

As telas de recursos são /materials, /tools, e /machine, com rotas detalhadas individuais. Os materiais requerem um nome e um valor de propriedades. As ferramentas exigem nome, tipo, diâmetro diferente de zero e material. A UI fornece restrições de diâmetro positivas, mas as integrações devem validar explicitamente as dimensões de engenharia, em vez de depender de verificações de veracidade.

{
  "name": "6 mm end mill",
  "type": "endmill",
  "diameter": 6,
  "material": "carbide",
  "numberOfFlutes": 3,
  "cuttingLength": 18,
  "shankDiameter": 6,
  "isPublic": false
}

Uma configuração de máquina precisa do tipo mill, lathe, printer, ou laser; dimensões positivas do volume de trabalho, velocidade máxima do fuso e taxa máxima de avanço; e dados opcionais do controlador/eixos. As configurações de quatro/cinco eixos requerem configuração rotativa compatível verificada pelo manipulador. Esses registros descrevem equipamentos; sua existência não verifica um programa gerado específico.

Usar Materiais, Ferramentas, e Máquinas para corpos exatos. Listas de materiais/ferramentas retornam matrizes; rotas de máquina usam um envelope de sucesso. Leia a resposta do endpoint selecionado em vez de assumir um formato de coleção universal.

Salve e reabra um programa CAM

Um percurso pode ser criado em um projeto com POST /api/toolpaths usando nome e projectId ou anexado a um desenho com POST /api/drawings/:id/toolpaths usando nome e dados. O painel do projeto usa a família de nível superior e abre o resultado por meio de /cam?loadToolpath=<id>. A página CAM lê o original salvo por meio da API.

O modal de salvamento CAM oferece projeto existente, novo projeto ou atualização do programa salvo. A exportação do código G baixa o texto. Downloads de exportação portáteis .cam.json com format: cadcamfun-cam, configurações, programa, material, contexto do desenho e evidências correspondentes, quando disponíveis. O salvamento da aplicação persiste nesse documento no registro do percurso.

Os documentos portáteis são validados e comparados com o seu NC. A edição do código pode remover evidências obsoletas ou exigir nova análise. Novos artefatos do kernel são verificados novamente em relação às solicitações de origem capturadas; reivindicações de verificação arbitrárias fornecidas pelo cliente não são aceitas como prova. As restrições do Proprietário/ADMINISTRADOR/GERENTE também se aplicam ao salvamento de programas portáteis em um projeto.

Quando o salvamento de um novo projeto é parcialmente bem-sucedido, o modal mantém o destino criado para nova tentativa. Inspecione esse identificador antes de reiniciar o fluxo e criar outro projeto. Ver Percursos da ferramenta e documentos de programa salvos.

Escolha o histórico que você precisa

A atualização através do modo de salvamento CAM registra primeiro o programa anterior. O salvamento manual na tela de detalhes do percurso registra o estado atualizado como uma versão. A restauração de versão registra o estado atual antes de substituí-lo, portanto, uma restauração pode ser revertida por meio de outra operação de versão. São fluxos distintos; um PUT genérico não é automaticamente um commit do projeto.

Abrir /toolpaths/:id para detalhes, código G, versões e comentários. Abrir /projects/:id/history para histórico do projeto; botões por item filtram por caminhos como drawings/<id>.json. O aPI de histórico de percurso aceita versionId para restauração.

As alterações no histórico também são publicadas como eventos ao vivo (commit, pr.*, workflow.started/workflow.finished, ai.session). Um novo assinante recebe primeiro até 20 eventos correspondentes recentes.

Verifique a persistência e resolva falhas

1. Leia o projeto, desenho e componente criado por meio de seus pontos finais identificadores.
2. Abra as rotas da área de trabalho correspondentes e confirme o conteúdo real do design/programa.
3. Reinicie o mesmo diretório de dados secundários, atualize o URL efêmero e repita as leituras.
4. Baixe uma exportação separadamente e inspecione seus campos; uma linha do banco de dados não prova que um arquivo foi exportado.

Um 400 geralmente indica campos comerciais obrigatórios ausentes ou dados de documentos inválidos; um 403 indica uma operação recusada; um 404 pode significar dados ausentes ou inacessíveis. O painel do projeto atualmente transforma falhas individuais na lista de recursos em matrizes vazias, portanto, uma guia vazia por si só não é evidência suficiente de exclusão. Inspecione o resultado direto da API antes de criar duplicatas.

As âncoras de implementação são projects.ts e groups/{drawings,components,toolpaths}.ts no pacote API; os manipuladores/repositórios sidecar correspondentes; projectSnapshot.ts, CadPage.tsx, SaveCamModal.tsx, e ToolpathDetailScreen.tsx. Use um projeto isolado para testes de exclusão e preserve o trabalho do usuário antes da restauração.

Receita: todo o ciclo de vida com curl

A=(--header "Authorization: Bearer $CADCAMFUN_TOKEN" --header "Content-Type: application/json")
U="$CADCAMFUN_URL"

project=$(curl -sS "${A[@]}" -d '{"name":"Bracket"}' "$U/api/projects" | jq -r .id)
drawing=$(curl -sS "${A[@]}" -d '{"name":"Plate","data":{}}' "$U/api/projects/$project/drawings" | jq -r .id)

curl -sS "${A[@]}" "$U/api/projects/$project/drawings" | jq 'length'

curl -sS "${A[@]}" -X PUT -d '{"name":"Plate v2"}' "$U/api/drawings/$drawing"

curl -sS "${A[@]}" -d '{"name":"Program","gcode":"G21\nM30","data":{}}' \
  "$U/api/drawings/$drawing/toolpaths" | jq .id

curl -sS "${A[@]}" -d '{"message":"First version"}' "$U/api/projects/$project/vcs/commit"
curl -sS "${A[@]}" "$U/api/projects/$project/vcs/log" | jq

Executado em um sidecar novo, o commit responde com o novo objeto de commit e o log o lista:

{"oid":"44d2d03d23b27fbbc4b388e32e15dfb0f39fff87","parents":[],"message":"First version\n","author":{"name":"Local user","email":"local@cadcamfun.local","time":1792037121}}

Sem cabeçalho de sessão, o autor é o perfil local da instalação. A receita usa jq. Percurso de forma livre data é aceito como está; um portátil cadcamfun-cam o documento é validado rigorosamente, conforme descrito no guia de fabricação nativo.

Em 3D