wordcloud/CHANGELOG.md

更新日志

2026-06-13 — 从词云生成器升级为完整创作工作流

本次更新在原有「词云生成」核心能力之上，完整新增了「模板中心」与「画布工作室」两大模块。系统从一个单纯的词云生成工具，升级为支持「选模板 → 生成词云 → 拖拽排版 → 导出成品」的一站式创作平台。

---

🆕 新增：模板中心（TemplateHome）

• 模板展示页面：新增独立的模板中心入口，可浏览、筛选、管理设计模板。
• 模板预览弹窗：点击模板缩略图弹出预览窗口，并支持在弹窗内切换多张预览图查看，而非固定单张大图。
• 异步 SVG 预览生成：模板弹窗中的预览图改为异步生成，避免阻塞主线程，提升打开速度。
• 模板 CRUD 接口：后端新增 /api/design-templates 相关接口，支持模板的上传、更新、删除。

---

🆕 新增：画布工作室（CanvasStudio）

• 独立画布编辑器：新增完整的可视化画布页面，支持多图层自由排版。
• 词云作为贴纸导入：生成的词云可一键作为贴纸插入画布，支持拖拽移动、缩放、旋转。
• 贴纸库面板：新增贴纸库，可浏览、上传、删除贴纸资源。
• 组内元素联动缩放：当调整词云大小时，同组内的底图/背景元素会按相同比例同步缩放，保持整体构图一致。
• SVG 导出自动内联后端资源：导出成品 SVG 时，自动从后端拉取贴纸、底图等资源并转为 data URL 内嵌，确保导出的文件独立可用、图片不会缺失。
• 图层导出 ZIP：支持按图层批量导出资源包。

---

🆕 新增：后端贴纸库（完全替代 localStorage）

• 贴纸文件全部迁移到后端：原先贴纸存在浏览器 localStorage，容易触发 QuotaExceededError 并导致贴纸丢失；现在统一通过 /api/assets 接口存取，文件保存在服务器。
• 资源类型体系：后端 /api/assets 支持 wordcloud / upload / shape / sticker 等类型。
• 元数据 + 文件分离：贴纸的元数据存在后端 JSON，文件存在后端磁盘，前端仅保存轻量引用。

---

🔧 问题修复

问题	原因	修复方案
词云导入画布时生成两个重复贴纸	React StrictMode 双重触发 effect，pending 状态未提交就被二次消费	增加 importingStickerRef 引用锁，防止同一词云重复导入
调整词云大小时底图不同步缩放	resize handler 只更新被拖拽的元素	记录 groupId 与组内元素初始尺寸，按比例同步缩放同组伙伴
导出的 SVG 图片错误/缺失	serializeDocument 把后端 URL 当作 SVG 文本处理	将 serializeDocument 改为异步，fetch 后端资源并内联为 data URL
贴纸/词云上传报 413	Nginx 默认 client_max_body_size 仅 1MB	前端 Nginx 配置 client_max_body_size 100M
生成任务进度连接超时断开	Nginx 默认 60 秒 read timeout	Nginx 配置 proxy_read_timeout / proxy_send_timeout 3600 秒，关闭 buffering
Docker 部署后词云任务失败	release 包漏掉 wordcloud_generate_hybrid.py	补回脚本并在 backend/Dockerfile 中显式复制

---

🐳 新增：Docker Compose 一键部署

• 新增 docker-compose.yml：编排 frontend + backend 服务，含健康检查与 5 个持久化卷。
• 新增 frontend/Dockerfile：Node 多阶段构建 → Nginx 静态服务。
• 新增 backend/Dockerfile：Python 3.10 + 编译 EfficientWordCloud C++ 扩展，healthcheck 已安装 curl。
• 新增 frontend/nginx.conf：静态资源服务、/api 反向代理、SSE 长连接优化、大文件上传支持。
• 新增 frontend/.dockerignore 与 backend/.dockerignore：避免构建时带入 node_modules、.venv、__pycache__ 等。

便捷命令

• 新增 Makefile：
  • make build / make up / make down
  • make logs / make logs-backend / make logs-frontend
  • make restart / make clean / make shell-backend

部署文档

• 新增 DOCKER.md：环境要求、快速开始、数据持久化说明、端口配置、常见问题排查。

Release 包

• 新增 release/ 目录与 release.tar.gz：仅包含源代码 + Docker 部署所需文件（已排除 node_modules、.venv、编译产物、测试输出等）。
• 包大小约 28 MB（主要为 backend/assets/fonts/STHeiti Medium.ttc 字体文件）。

---

📦 依赖

• 后端 requirements.txt 新增 fastapi>=0.136.0、uvicorn[standard]>=0.32.0、python-multipart>=0.0.27、pydantic>=2.10.0、pillow>=10.0.0、numpy>=2.0.0、matplotlib>=3.10.0、pandas>=2.0.0、openpyxl>=3.1.0。
• 前端保持 React 18 + Vite 5 技术栈，新增 xlsx 用于 Excel 解析。

---

📝 其他说明

• 数据持久化：Docker Compose 使用 5 个命名卷保存任务工作区、贴纸资源、项目文件、设计模板、上传字体，容器重建不会丢失用户数据。
• API 调用：前端统一使用相对路径 /api/*，本地开发由 Vite 代理到 localhost:8000，生产环境由 Nginx 代理到后端容器。
• 原有词云生成功能保留：TestWorkbench 作为原始生成工作台继续可用，新增强的模板中心与画布工作室与其并行。