# 产品上传 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. **错误处理**：更详细的错误提示和重试机制