文档

项目生命周期

创建一个项目，保存其设计数据，重新打开它，然后选择正确的历史记录类型。

项目包含什么

项目对工程图、可重用组件和保存的刀具路径进行分组。一张图纸存储一个JSON文档；组件存储可重用的设计数据；刀具路径可以保存普通 NC 和元数据或经过验证的便携式 CAM 文档。材料、刀具和机器配置是加工工作流程可以引用的单独资源记录。项目标识符不会取代任何这些资源标识符。

本指南遵循桌面使用的相同系列。它将保存应用程序状态、下载文件、记录刀具路径版本和提交项目历史记录分开。这些操作保留不同的信息。在将序列应用到生产工作之前，从一次性开发项目开始。

这些示例是其 JSON 正文与当前架构匹配的请求模板。它们不是捕获的服务器响应。对于每个字段和声明的状态，请使用项目, 图纸, 成分，和刀具路径 API 参考。

选择真实的API

运行桌面 bun run desktop:dev，或者使用以下命令启动一个独立的手动 sidecar 当地发展秘诀。手动过程会宣布一个临时端口。没有端点的浏览器预览使用内存中的设备；它无法确定项目在重新启动服务器后仍然存在。

第二个终端：替换示例端口和令牌

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"

健康状况是公开的，因此当受保护的项目请求无法授权时它可以成功。使用提供给此进程的令牌。对于以下示例保持相同的 shell，以便 URL、令牌、临时目录和提取的标识符保持可用。在启动终端中保持 sidecar 的标准输入打开。

创建并检查项目

创建一个私人项目

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"

创建返回带有项目行的 HTTP 201。即使传输模式声明该字段是可选的，处理程序也需要一个真实的名称。提供的组织必须是调用者所属的组织。读取项目返回所有者/组织信息和图纸/组件计数；这是与创造不同的响应形状。

在桌面上，使用 /projects 浏览和 /projects/:id 打开仪表板。它具有“工程图”、“组件”和“刀具路径”选项卡，以及“编辑”、“删除”和“版本控制”操作。项目更新需要重新命名；所有者或组织 ADMIN/MANAGER 可以更新，而删除仅限于所有者或 ADMIN。

创建并打开工程图

创建一个空的编辑器文档并保留其标识符

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"

项目仪表板的创建绘图流程使用相同的空文档形状。它创建一行，而不是几何图形。打开 /cad?drawingId=<id> 或 /drawings/<id> 来编辑它。和 /cad?projectId=<id>、CAD选择工程最新图纸；命名绘图优先。

绘图创建需要项目访问权限和名称。单个图纸读取/更新需要项目所有者或组织成员；删除会添加所有者/组织 ADMIN 检查。 JSON data 未通过通用端点验证为完整的可绘制几何文档。因此，成功的写入并不能证明每个提供的元素都可以渲染。

保存、复制和导出设计数据

在已打开的存储图形上，CAD 保存操作会更新该图形并将缺少的本地库组件添加到其项目中。 CAD页面实现了自己的 Cmd/Ctrl+S 处理程序。没有存储目的地的文档将打开导出/保存流程；另存为项目需要几何图形或选定的元素，并创建新项目和图形。

绘图快照包括元素、图层、所选元素标识符、测量设置和格式版本。当前加载路径恢复元素和有效单位/公差设置，将未知图层标识符映射到活动图层，并清除选择。不要从导出中存在的字段推断完整的图层恢复。

项目组件同步匹配修剪过的、不区分大小写的名称并添加缺失的名称；它不会覆盖同名定义。组件创建是尽最大努力，并且可能会独立失败。保存的图形并不能证明每个本地组件都被复制，并且多请求保存流程不是一个数据库事务。

复制从绘图卡加载其存储的数据并创建新的标识符。下载将该绘图的数据导出为 JSON；它不会导出整个项目。通用绘图更新应用真实的名称/数据/缩略图值并允许显式的空描述。它们不会公开存储库的比较和交换哈希参数。

存储可重复使用的组件

创建一个组件，然后在更新时验证其可重用数据

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":[]}}'

创建返回 HTTP 201。当前存储库创建操作存储名称、描述、数据和项目关联；它不会在创建时保留顶级类型/公共/缩略图选项。上面的显式更新设置了预期的顶级类型和可见性。更新验证真实的组件数据，标准化缺失的可选字段，并拒绝空补丁。

打开 /components/:id 查看详细信息屏幕或浏览 /components 带有项目过滤器。可见性当前包括项目所有者、组织成员和公共组件。组件处理程序不会强制为可见组件编辑/删除额外的所有者专用的门；不要将公共可见性视为受保护的只读共享。

准备加工资源

资源屏幕是 /materials, /tools，和 /machine，具有单独的详细路线。材质需要名称和属性值。工具需要名称、类型、非零直径和材料。 UI 提供正直径约束，但集成应明确验证工程尺寸，而不是依赖真实性检查。

POST /api/tools 的刀具主体示例

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

机器配置需要类型 mill, lathe, printer，或者 laser;正工作体积尺寸、最大主轴转速和最大进给率；和可选的控制器/轴数据。四/五轴配置需要由处理程序检查兼容的旋转配置。这些记录描述了设备；它们的存在并不验证特定生成的程序。

使用材料, 工具，和机器对于精确的身体。材料/工具列表返回数组；机器路线使用成功信封。读取所选端点的响应，而不是假设一种通用集合形状。

保存并重新打开 CAM 程序

可以在项目下创建刀具路径 POST /api/toolpaths 使用名称和项目 ID，或附加到绘图 POST /api/drawings/:id/toolpaths 使用名称和数据。项目仪表板使用顶级系列并通过以下方式打开结果 /cam?loadToolpath=<id>。 CAM页面通过API读取保存的原稿。

CAM 保存模式提供现有项目、新项目或已保存程序的更新。 G 代码导出下载文本。便携式导出下载 .cam.json 和 format: cadcamfun-cam、设置、程序、库存、绘图上下文以及可用的匹配证据。应用程序保存将该文档保留在刀具路径记录中。

便携式文档经过验证并与其 NC 相匹配。编辑代码可以删除陈旧的证据或需要重新分析。根据捕获的源请求重新检查新的内核工件；客户提供的任意验证声明不被接受作为证据。所有者/管理员/管理员限制也适用于将可移植程序保存到项目中。

当新项目保存部分成功时，模式会保留其创建的目标以供重试。在重新启动流程并创建另一个项目之前检查该标识符。看刀具路径和保存的程序文件.

选择您需要的历史记录

机制	果酱	使用
编辑器撤消/重做	本地交互/会话快照	撤消当前的编辑操作。
刀具路径版本	一个程序的记录数据、NC、作者和更改消息	查看或恢复程序修订版。
项目历史	提交的项目快照和更改的实体文件	比较、分支、审查或恢复项目状态。
下载的 JSON/NC	特定导出内容	保留或转移外部工件。

通过CAM保存模式更新先记录以前的程序。刀具路径详细信息屏幕上的手动保存将更新的状态记录为版本。版本恢复会在替换之前记录当前状态，因此可以通过另一个版本操作来反转恢复。这些是不同的流程；通用 PUT 不会自动成为项目提交。

打开 /toolpaths/:id 了解详细信息、G 代码、版本和注释。打开 /projects/:id/history 项目历史记录；每个项目的按钮按路径过滤，例如 drawings/<id>.json。这刀具路径历史 API 接受 versionId 用于恢复。

历史变化也以现场事件的形式发布（commit, pr.*, workflow.started/workflow.finished, ai.session）。新订阅者首先接收最多 20 个最近的匹配事件。

验证持久性并解决故障

通过标识符端点读取创建的项目、绘图和组件。
打开相应的桌面路径，确认实际的设计/程序内容。
重新启动同一 sidecar 数据目录，更新临时 URL，然后重复读取。
单独下载导出并检查其字段；数据库行并不能证明文件已导出。

400 通常表示缺少必需的业务字段或无效的文档数据； 403 表示拒绝的操作； 404 可能意味着数据不存在或无法访问。项目仪表板当前将单个资源列表故障转换为空数组，因此仅空选项卡不足以证明删除。创建重复项之前检查直接 API 结果。

实施锚点是 projects.ts 和 groups/{drawings,components,toolpaths}.ts 在API包中；相应的 sidecar 处理程序/存储库； projectSnapshot.ts, CadPage.tsx, SaveCamModal.tsx，和 ToolpathDetailScreen.tsx。使用独立的项目进行删除测试并在恢复之前保留用户工作。

配方：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

步	手术	身体领域
创建项目	`POST /api/projects`	`name` （处理程序要求）， `description`, `organizationId`, `isPublic`
创建绘图	`POST /api/projects/{id}/drawings`	`name`, `description`, `data`, `thumbnail`
更新图纸	`PUT /api/drawings/{id}`	相同字段，部分
创建刀具路径	`POST /api/drawings/{id}/toolpaths`	`name`, `data`, `gcode`, `type`, `operationType`, `materialId`, `toolId`, `machineConfigId`, …
犯罪	`POST /api/projects/{id}/vcs/commit`	`message` （必需的）， `authorKind`, `files`
分支	`POST /api/projects/{id}/vcs/branches`	`name` （必需的）， `from`
恢复	`POST /api/projects/{id}/vcs/restore`	`rev` （必需的）， `paths`

针对新的 sidecar 运行，提交使用新的提交对象进行响应，日志列出它：

vcs/提交响应

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

如果没有会话标头，作者就是安装的本地配置文件。食谱使用 jq。自由形状刀具路径 data 按原样接受；便携式的 cadcamfun-cam 文件经过严格验证，如本地制造指南中所述。

在 3D

项目的悬念是什么拖动进行轨道旋转·滚动进行缩放·右键拖动进行平移

来自 Drizzle 迁移的具有 Project 外键的表及其自己的子项。