3d2014db37
- 更新 User 模型：添加 name、isFirstLogin、role 枚举、team 关联 - 创建 Department 模型：支持层级结构和部门负责人 - 创建 Team 模型：小组管理和组长关联 - 更新 Product 模型：添加 createdBy、collaborators、visibility、软删除 - 更新 ProductSKU 模型：添加 ownerId、transferHistory、软删除 - 创建 Feedback 模型：问题反馈系统 - 创建 ActivityLog 模型：操作日志记录 - 添加 6 种角色枚举：SUPER_ADMIN、ADMIN、DEPARTMENT_MANAGER、TEAM_LEADER、DESIGNER、VIEWER - 添加用户状态枚举：ACTIVE、INACTIVE、SUSPENDED - 运行数据库迁移并生成 Prisma Client - 更新文档：TODO.md、PHASE1_COMPLETE.md
154 lines
3.3 KiB
Markdown
154 lines
3.3 KiB
Markdown
# 产品上传 API 使用指南
|
||
|
||
## 概述
|
||
|
||
产品上传功能已完成，支持批量上传 3D 模型文件并自动创建产品和 SKU。
|
||
|
||
## 功能特性
|
||
|
||
✅ **已完成**：
|
||
- Apple HIG 2025 风格的上传弹窗
|
||
- 拖拽上传和点击选择文件
|
||
- 批量上传多个文件
|
||
- 实时上传进度显示
|
||
- 文件验证（格式、大小）
|
||
- 产品信息表单
|
||
- 文件上传到 MinIO
|
||
- 自动创建产品和 SKU 记录
|
||
- 上传成功后自动刷新列表
|
||
|
||
⏳ **待完成**：
|
||
- DWG 文件转换为 GLB/GLTF
|
||
- 自动生成缩略图
|
||
- 文件压缩优化
|
||
|
||
## API 端点
|
||
|
||
### 上传产品
|
||
```
|
||
POST /api/products/upload
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
**请求参数**：
|
||
- `modelNumber` (必填): 产品型号，如 "SF-001"
|
||
- `name` (必填): 产品名称，如 "现代简约沙发"
|
||
- `category` (可选): 产品分类
|
||
- `description` (可选): 产品描述
|
||
- `files` (必填): 3D 模型文件数组
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"product": {
|
||
"id": "...",
|
||
"modelNumber": "SF-001",
|
||
"name": "现代简约沙发",
|
||
"modelUrl": "http://localhost:9000/furniture-models/models/SF-001",
|
||
"thumbnailUrl": "/placeholder-thumbnail.png",
|
||
"skus": [
|
||
{
|
||
"id": "...",
|
||
"skuCode": "SF-001-01",
|
||
"modelUrl": "...",
|
||
...
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取产品列表
|
||
```
|
||
GET /api/products
|
||
```
|
||
|
||
**查询参数**：
|
||
- `search` (可选): 搜索关键词
|
||
- `category` (可选): 产品分类
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"products": [...]
|
||
}
|
||
```
|
||
|
||
## 使用流程
|
||
|
||
1. 用户点击"上传产品"按钮
|
||
2. 弹出上传弹窗
|
||
3. 填写产品信息（型号、名称、分类、描述）
|
||
4. 拖拽或选择 3D 模型文件
|
||
5. 显示上传进度
|
||
6. 点击"确认上传"
|
||
7. 文件上传到 MinIO
|
||
8. 创建产品和 SKU 记录
|
||
9. 自动刷新产品列表
|
||
|
||
## 文件要求
|
||
|
||
- **支持格式**: .dwg, .glb, .gltf
|
||
- **单文件大小**: 最大 100MB
|
||
- **批量上传**: 支持同时上传多个文件
|
||
- **自动 SKU**: 每个文件自动创建一个 SKU
|
||
|
||
## 环境配置
|
||
|
||
确保 `.env` 文件中配置了以下变量：
|
||
|
||
```env
|
||
# MinIO 配置
|
||
S3_ENDPOINT=http://localhost:9000
|
||
S3_REGION=us-east-1
|
||
S3_BUCKET=furniture-models
|
||
S3_ACCESS_KEY=minioadmin
|
||
S3_SECRET_KEY=minioadmin
|
||
|
||
# 数据库配置
|
||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/furniture3d
|
||
```
|
||
|
||
## 测试步骤
|
||
|
||
1. 启动开发服务器：
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
2. 确保 MinIO 和 PostgreSQL 正在运行
|
||
|
||
3. 访问 http://localhost:3000
|
||
|
||
4. 点击"上传产品"按钮
|
||
|
||
5. 填写产品信息并上传文件
|
||
|
||
6. 查看产品列表是否更新
|
||
|
||
## 故障排查
|
||
|
||
### 上传失败
|
||
- 检查 MinIO 是否运行：访问 http://localhost:9000
|
||
- 检查数据库连接：运行 `npm run prisma:studio`
|
||
- 查看浏览器控制台错误信息
|
||
- 查看服务器日志
|
||
|
||
### 文件格式不支持
|
||
- 当前支持 .dwg, .glb, .gltf 格式
|
||
- DWG 转换功能待实现
|
||
|
||
### 缩略图显示占位图
|
||
- 自动生成缩略图功能待实现
|
||
- 当前使用占位图 `/placeholder-thumbnail.png`
|
||
|
||
## 下一步优化
|
||
|
||
1. **DWG 转换**：集成 DWG 转 GLB/GLTF 转换服务
|
||
2. **缩略图生成**：使用 Three.js 服务端渲染生成缩略图
|
||
3. **文件压缩**：上传前自动压缩大文件
|
||
4. **进度优化**：显示真实的上传进度（当前是模拟）
|
||
5. **错误处理**：更详细的错误提示和重试机制
|