diff --git a/docs/SETUP_GUIDE.md b/docs/SETUP_GUIDE.md new file mode 100644 index 0000000..ae885ae --- /dev/null +++ b/docs/SETUP_GUIDE.md @@ -0,0 +1,248 @@ +# 扑克牌设计管理系统 - 实施完成说明 + +## 实施进度 + +### ✅ 已完成功能 + +#### 后端 (Django) + +1. **项目架构** + - Django 5.x项目结构 + - REST API框架集成 + - CORS配置 + - 数据库模型设计 + +2. **核心应用模块** + - **Projects应用** + - Project模型 - 项目配置 + - Asset模型 - 素材文件管理 + - CardLayer模型 - 图层配置 + - 完整的CRUD API + - 素材上传API + - 项目详情API(包含 assets 和 layers) + + - **Templates应用** + - CardTemplate模型 - 模板配置 + - 模板列表和管理API + - 配色方案管理 + + - **Exports应用** + - Pillow图像处理 + - 中心对称生成算法 + - 单张PNG导出 + - 批量ZIP导出 + - 多分辨率支持 + +3. **管理系统** + - 数据库迁移系统 + - 初始化命令 + - 资源管理和存储 + +#### 前端 (Vue.js) + +1. **项目架构** + - Vue 3 + Vite配置 + - Vue Router路由 + - Pinia状态管理(待集成) + - Element Plus UI组件 + +2. **核心组件** + - **Home.vue** - 主页模板选择和项目管理 + - 模板系列预览 + - 项目列表 + - 创建新项目 + - 编辑已有项目 + + - **Editor.vue** - 编辑器核心 + - Fabric.js Canvas集成 + - 54张牌切换 + - 基础卡片渲染 + - 花色切换 + - 基本的图层管理 + + - **AssetUploadDialog.vue** - 素材上传对话框 + - 拖拽上传 + - 多素材类型支持 + - 步骤验证 + +3. **工具函数** + - **cardLayout.js** - 牌面布局算法 + - 数字牌花色排列模板 + - 角标位置计算 + - 花色颜色配置 + - 花色判断工具函数 + + - **symmetry.js** - 对称生成工具 + - 中心对称算法 + - 图像加载和裁剪 + - Fabric.js集成 + + - **模板配置** - 模板系列配置 + - 4种模板风格 + - 颜色方案 + - 默认素材配置 + +4. **API接口** + - 项目管理API封装 + - 模板管理API封装 + - 导出服务API封装 + - 素材上传API封装 + +### 🚧 待完善功能 + +1. **前端编辑器增强** + - 素材库界面集成 + - 图层详细管理 + - 花色图案上传和预览 + - JQK人像上传和对称化 + - 背面图案上传 + - 实时Canvas渲染数据同步 + +2. **模板数据填充** + - 创建示例SVG素材 + - 模板数据初始化 + - 用户引导流程 + +3. **测试和调试** + - API功能测试 + - 前端集成测试 + - 导出功能验证 + - 性能优化 + +## 使用流程 + +### 1. 启动后端 + +```bash +cd backend +pip install -r requirements.txt +python manage.py migrate +python manage.py runserver +``` + +**初始化数据(可选):** +```bash +python manage.py init_system +``` + +后端运行在 http://localhost:8000 + +### 2. 启动前端 + +```bash +cd frontend +npm install +npm run dev +``` + +前端运行在 http://localhost:5173 + +### 3. 使用系统 + +**创建项目:** +1. 打开 http://localhost:5173 +2. 选择模板系列(经典/现代/卡通/复古) +3. 系统自动创建新项目并跳转到编辑器 + +**编辑扑克牌:** +1. 选择不同的花色(黑桃/红桃/梅花/方块) +2. 点击底部卡片列表切换当前编辑的牌 +3. 左侧面板可管理素材和图层 +4. 顶部可编辑项目名称和导出设置 + +**导出:** +1. 导出当前牌面:点击"导出当前"按钮 +2. 导出整副牌:点击"导出全部"按钮 + +## 数据库结构 + +### Project表 +- 主键:UUID +- 字段:名称、模板ID、牌面尺寸、导出设置 +- 关联:assets, layers + +### Asset表 +- 字段:类型、key、文件路径、尺寸 +- 关联:project, layers +- 存储:文件系统中的上传文件 + +### CardLayer表 +- 字段:卡片类型、key、图层信息 +- 关联:project、file_ref + +### CardTemplate表 +- 字段:模板配置、配色方案 +- 关联:suit_symbols + +## API端点 + +完整的API列表请参考 `backend/apps/` 目录下的 View 函数。 + +主要端点: +- `/api/projects/` - 项目CRUD +- `/api/projects/{id}/assets/` - 素材管理 +- `/api/templates/` - 模板管理 +- `/api/projects/{id}/export/` - 导出 + +## 技术亮点 + +1. **前后端分离架构** - 清晰的职责划分 +2. **RESTful API设计** - 标准化接口 +3. **本地文件存储** - 素材以文件系统形式保存 +4. **多分辨率导出** - 支持打印和展示不同需求 +5. **中心对称算法** - 自动化处理JQK人像 +6. **组件化管理** - 前端模块化设计 + +## 文件清单 + +### 核心文件 +- `backend/poker_api/settings.py` - Django配置 +- `backend/apps/projects/models.py` - 数据模型 +- `frontend/src/views/Home.vue` - 主页组件 +- `frontend/src/views/Editor.vue` - 编辑器组件 + +### 依赖文件 +- `backend/requirements.txt` - Python依赖 +- `frontend/package.json` - Node依赖 + +### API文件 +- `frontend/src/api/project.js` - 项目API +- `frontend/src/api/asset.js` - 素材API +- `frontend/src/api/export.js` - 导出API +- `frontend/src/api/template.js` - 模板API + +### 工具文件 +- `frontend/src/utils/cardLayout.js` - 布局算法 +- `frontend/src/utils/symmetry.js` - 对称工具 +- `frontend/src/templates/index.js` - 模板配置 + +## 下一步开发建议 + +1. **完善编辑器功能** + - 集成素材上传组件 + - 实现Canvas数据模型同步 + - 添加图层详细控制 + +2. **测试和优化** + - 编写API测试用例 + - 前端单元测试 + - 性能优化 + +3. **增强功能** + - 撤销/重做 + - 样式批量应用 + - 项目模板保存 + - 历史版本管理 + +4. **用户体验** + - 更好的错误提示 + - 加载状态显示 + - 操作引导流程 + - 响应式设计优化 + +## 项目版本 + +- 当前版本:1.0-alpha +- 开发状态:核心功能完成,待完善UI集成 + +开发完成日期:2026-05-31 \ No newline at end of file