# 更新日志

## 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` 作为原始生成工作台继续可用，新增强的模板中心与画布工作室与其并行。