canvas-web · implementation
实现逻辑
canvas-web 是独立的 Next.js 子站（端口 3004），与 story-web 同款架构：登录、数据库、KIE 调用全部归口主站 book-mall。本页解释画布编辑器、节点运行模型、跨站协议与可观测能力。
1. 架构与端口
canvas-web（:3004）：纯前端 + 浏览器代理/api/book-mall/*tool-web（:3001）：「AI 海报画布」侧栏组（首页 / 创意画室 / 画作 / 实现逻辑）book-mall（:3000）：单一 Postgres、NextAuth 会话、KIE 客户端、OSS 上传- 后台轮询：
book-mall的canvas:poll-loop，由根pnpm dev:all默认拉起
2. 画布编辑器（@xyflow/react）
- React Flow v12 渲染节点，onlyRenderVisibleElements 在节点 > 500 时自动启用
- 状态：
zustand+zundo（撤销/重做），自动每 1.5s debounce 持久化 - 外部拖图：根
onDrop拦截image/*，落点用screenToFlowPosition转画布坐标，立刻渲染 blob URL 占位，后台并发上传 OSS 替换 - 6 类节点：
image/text/product-params/ai-text/image-gen/output，统一NodeShell提供输入/输出端口与状态角标
3. 节点执行 / 任务
- 前端拓扑排序（
topoSort），逐节点调用POST /api/canvas/projects/:id/nodes/:nodeId/run - book-mall 的
canvas-task-service计算inputHash（去重缓存）、提交 KIE，写CanvasGenerationTask - 前端运行队列单画布并发 ≤ 5；后端
assertCanvasInflightCap二次校验 - 5s 轮询
GET /api/canvas/projects/:id/tasks同步状态；KIE 完成后persistKieResultToOss把图存为永久 OSS URL - 错误兜底：节点角标显示
failCode+failMessage
4. 关键 API（/api/canvas/*）
| 路径 | 说明 |
|---|---|
GET /viewer-session | 当前用户（与 NextAuth 会话同源） |
GET /engine-models | 可用模型；DB 为空时 fallback 内置三套 |
GET / POST /projects | 列出 / 新建画布 |
GET / PATCH / DELETE /projects/:id | 读取 / 自动保存 / 软删除（OSS 清理入队） |
POST /projects/:id/nodes/:nodeId/run | 提交单节点 AI 任务 |
GET /projects/:id/tasks | 批量节点状态（前端 5s 轮询） |
POST /uploads | 外部拖图直传 OSS |
GET / POST /templates | 列模板 / 保存为我的模板 |
GET /works | 所有 SUCCEEDED 图像任务，画作库视图 |
POST /kie/poll · /cleanup · /callback/:kind | 异步轮询 / OSS 清理 / KIE webhook |
5. 跨域 / 环境变量
CANVAS_WEB_ORIGINS：白名单，允许浏览器从 canvas-web 直接调 book-mallCANVAS_CORS_IN_APP：1 时由 book-mall 主动写 CORS 头CANVAS_AI_USER_INFLIGHT_MAX/CANVAS_PROJECT_INFLIGHT_MAX：并发上限NEXT_PUBLIC_CANVAS_WEB_ORIGIN：tool-web「创意画室」外链回 canvas-web 用
6. 可观测 / Dev 入口
GET /dev（book-mall）：服务/进程总览，含 canvas / canvas-poll 卡片GET /dev/canvas/tasks：CanvasGenerationTask 看板（与 story 同款）pnpm --filter book-mall canvas:poll-once：手动跑一次轮询 / OSS 清理
7. 后续迭代
- AiText 节点接入 LLM（KIE 文本路由），目前为 prompt 透传
- 多图融合预设、三视图模板的运行时占位填充（自动从 ProductParams 注入参数）
- Output 节点附加 PNG 导出 / 海报排版叠加
- 项目级缩略图自动从最近一次 SUCCEEDED 图像生成