项目与画布

项目（Project）是组织工作的顶层容器，每个项目包含一个画布（Canvas）和多个对话。

概念层次

项目 (Project)
 ├─ 画布 (Canvas) — 一对一，节点+边的可视化编辑器
 ├─ 对话 (Conversation) — 一对多，与AI的聊天
 └─ 节点组 (NodeGroup) — 可复用的节点集合

项目端点

方法	路径	说明
GET	/api/v1/projects	项目列表
POST	/api/v1/projects	创建项目
GET	/api/v1/projects/{id}	项目详情（含画布和对话列表）
PATCH	/api/v1/projects/{id}	更新项目
DELETE	/api/v1/projects/{id}	删除项目
WebSocket	/api/v1/projects/{id}/ws?token=xxx	项目实时协作

画布端点

方法	路径	说明
GET	/api/v1/canvas	画布列表
POST	/api/v1/canvas	创建画布
GET	/api/v1/canvas/{id}	画布详情
PATCH	/api/v1/canvas/{id}	更新画布
DELETE	/api/v1/canvas/{id}	删除画布
GET	/api/v1/canvas/{id}/nodes	获取画布节点
POST	/api/v1/canvas/{id}/nodes	批量创建节点
GET	/api/v1/canvas/{id}/edges	获取画布边
POST	/api/v1/canvas/{id}/edges	批量创建边
WebSocket	/api/v1/canvas/{id}/ws?token=xxx	画布实时编辑

节点组端点

方法	路径	说明
GET	/api/v1/node-groups	节点组列表
POST	/api/v1/node-groups	创建节点组
GET	/api/v1/node-groups/{id}	节点组详情
PATCH	/api/v1/node-groups/{id}	更新节点组
DELETE	/api/v1/node-groups/{id}	删除节点组

画布节点类型

类型	说明
text	文本节点
image	图片节点
video	视频节点
code	代码节点
markdown	Markdown 节点
file	文件节点
group	打组节点

节点响应示例

{
  "id": "f1a2b3c4-...",
  "type": "text",
  "x": 100.0,
  "y": 200.0,
  "width": 200.0,
  "height": 100.0,
  "rotation": 0.0,
  "data": {
    "label": "需求分析",
    "text": "功能需求描述..."
  },
  "canvas_id": "e0d1c2b3-...",
  "created_by_id": "550e8400-..."
}

项目 WebSocket

项目 WebSocket 是融合端点，同时承载画布操作和对话通信。消息通过 domain 字段区分：

{
  "domain": "canvas",
  "action": "create",
  "payload": [...]
}

{
  "domain": "conversation",
  "type": "request_completion",
  "payload": {...},
  "conversation_id": "d4e5f6a7-..."
}

详见 项目 WebSocket。

测试要点

测试建议

1. 项目-画布一对一：创建项目时自动创建画布，删除项目时级联删除
2. 节点坐标：x、y、width、height、rotation 应接受合理范围的浮点数
3. 批量操作原子性：批量创建节点时，任一个失败应全部回滚
4. 临时 ID 映射：批量创建中使用 temp_id 时，边的 source_id/target_id 应正确映射
5. 并发编辑：通过项目 WebSocket 模拟多用户同时编辑画布
6. AI 画布操作：AI 通过工具调用创建/修改/删除画布元素，需要用户确认
7. 节点组：节点组可以跨画布复用，测试组的引用完整性