# API 接口规范

本文档定义前端需要后端实现的所有 API 接口。

## 基础约定

- **Base URL**: 通过环境变量 `VITE_API_BASE_URL` 配置
- **认证方式**: Bearer Token（通过 `Authorization: Bearer <token>` 请求头）
- **响应格式**: 统一 JSON 格式
- **分页参数**: `page`（从 1 开始）、`pageSize`（默认 20）

---

## 1. 产品模块

### 1.1 搜索产品列表

**POST** `/products/search`

**请求参数**:

```json
{
  "query": "秋季南瓜",           // 搜索关键词（可选）
  "filters": {                   // 筛选条件（可选）
    "series": ["Fall", "Christmas"],
    "season": ["秋季"],
    "visual": ["南瓜", "枫叶"],
    "function": ["插枝", "墙挂"],
    "material": ["Wood", "Fabric"],
    "price": ["$10-20", "$20+"],
    "year": ["2024", "2025"]
  },
  "sort": "相关度",              // 排序：相关度 | 价格从低到高 | 价格从高到低 | 最新上架
  "page": 1,
  "pageSize": 20
}
```

**响应**:

```json
{
  "items": [
    {
      "id": "1",
      "nameCn": "秋季南瓜收获插枝装饰",
      "nameEn": "Fall Harvest Pumpkin Stake Decor",
      "sku": "HL-FD-20241101",
      "price": 8.99,
      "source": "Hobby Lobby",
      "images": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg"
      ],
      "tags": {
        "series": "Fall",
        "season": "秋季",
        "visual": ["南瓜", "枫叶"],
        "function": "插枝",
        "material": "Wood"
      },
      "description": "精美的秋季南瓜插枝装饰...",
      "dimensions": "H: 18\" W: 6\"",
      "category": "Fall > Outdoor Decor > Stake"
    }
  ],
  "total": 156,
  "page": 1,
  "pageSize": 20
}
```

**说明**:
- `query` 支持模糊搜索，应匹配：nameCn、nameEn、description、sku、category、tags 各字段
- `filters` 中各数组为 OR 关系，不同 filter 之间为 AND 关系
- `visual` 字段匹配时，只要产品 tags.visual 包含任一选中值即匹配
- `price` 区间格式：`$1-5`、`$5-10`、`$10-20`、`$20+`
- `year` 从 SKU 中提取（SKU 格式：`XX-XX-YYYYMMDD`，取 YYYY）

---

### 1.2 获取产品详情

**GET** `/products/:id`

**响应**:

```json
{
  "id": "1",
  "nameCn": "秋季南瓜收获插枝装饰",
  "nameEn": "Fall Harvest Pumpkin Stake Decor",
  "sku": "HL-FD-20241101",
  "price": 8.99,
  "source": "Hobby Lobby",
  "images": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "tags": {
    "series": "Fall",
    "season": "秋季",
    "visual": ["南瓜", "枫叶"],
    "function": "插枝",
    "material": "Wood"
  },
  "description": "精美的秋季南瓜插枝装饰...",
  "dimensions": "H: 18\" W: 6\"",
  "category": "Fall > Outdoor Decor > Stake"
}
```

**404 响应**:

```json
{
  "error": "Product not found"
}
```

---

### 1.3 获取相似产品

**GET** `/products/:id/similar?limit=5`

**响应**:

```json
[
  {
    "id": "6",
    "nameCn": "户外庭院秋季南瓜灯笼",
    "nameEn": "Outdoor Pumpkin Lantern Decor",
    "sku": "WE-OL-20241156",
    "price": 29.99,
    "source": "West Elm",
    "images": ["https://example.com/image6.jpg"],
    "tags": { ... },
    "description": "...",
    "dimensions": "H: 12\" W: 8\"",
    "category": "Fall > Outdoor Decor > Lanterns"
  }
]
```

**相似度算法建议**:
- 同系列 +3 分
- 同季节 +2 分
- 同功能 +2 分
- 同材质 +1 分
- 共有视觉元素 +1/个
- 共有分类层级 +1/层

---

## 2. 导出模块

### 2.1 获取导出记录

**GET** `/exports?page=1&pageSize=20`

**响应**:

```json
{
  "items": [
    {
      "id": "e1",
      "date": "2026-06-15 14:30",
      "count": 24,
      "sizeMB": 156,
      "status": "completed",
      "downloadUrl": "https://example.com/exports/e1.zip"
    }
  ],
  "total": 5,
  "page": 1,
  "pageSize": 20
}
```

**status 枚举**: `completed` | `processing` | `failed`

---

### 2.2 创建导出任务

**POST** `/exports`

**请求**:

```json
{
  "productIds": ["1", "2", "3"],
  "imgFormat": "original",
  "metaFormat": "json",
  "filename": "{SKU}_{序号}"
}
```

**响应**:

```json
{
  "taskId": "task_1719000000000"
}
```

---

### 2.3 查询导出进度

**GET** `/exports/:taskId/status`

**响应**:

```json
{
  "progress": 65,
  "failed": false,
  "error": null
}
```

**完成时**:

```json
{
  "progress": 100,
  "failed": false,
  "downloadUrl": "https://example.com/exports/task_xxx.zip",
  "sizeMB": 156
}
```

**失败时**:

```json
{
  "progress": 45,
  "failed": true,
  "error": "部分图片下载失败"
}
```

---

### 2.4 删除导出记录

**DELETE** `/exports/:id`

**响应**:

```json
{
  "success": true
}
```

---

## 3. 用户认证模块

### 3.1 登录

**POST** `/auth/login`

**请求**:

```json
{
  "username": "designer",
  "password": "xxx"
}
```

**响应**:

```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "u1",
    "name": "设计师小王",
    "role": "designer"
  }
}
```

---

### 3.2 获取当前用户

**GET** `/auth/me`

**Headers**: `Authorization: Bearer <token>`

**响应**:

```json
{
  "id": "u1",
  "name": "设计师小王",
  "role": "designer"
}
```

---

### 3.3 登出

**POST** `/auth/logout`

**Headers**: `Authorization: Bearer <token>`

**响应**:

```json
{
  "success": true
}
```

---

## 4. 收藏模块（可选，当前前端用 localStorage 实现）

如需后端持久化收藏：

### 4.1 获取收藏列表

**GET** `/favorites`

**响应**:

```json
{
  "productIds": ["1", "5", "12"]
}
```

### 4.2 添加收藏

**POST** `/favorites`

**请求**:

```json
{
  "productId": "1"
}
```

### 4.3 取消收藏

**DELETE** `/favorites/:productId`

---

## 数据类型定义

### Product

```typescript
interface Product {
  id: string;
  nameCn: string;           // 中文名称
  nameEn: string;           // 英文名称
  sku: string;              // SKU 编号
  price: number;            // 价格（美元）
  source: "Hobby Lobby" | "West Elm" | "Crate & Barrel";
  images: string[];         // 图片 URL 列表
  tags: {
    series: string;         // 系列：Americana, Christmas, Everyday, Fall
    season: string;         // 季节：春季, 夏季, 秋季, 冬季, 万圣节, 圣诞节
    visual: string[];       // 视觉元素：南瓜, 向日葵, 枫叶, 松鼠, 卡车...
    function: string;       // 功能：插枝, 串绳, 墙挂, 桌上摆件
    material: string;       // 材质：Wood, Metal, Ceramic, Fabric, Glass
  };
  description: string;      // 产品描述
  dimensions: string;       // 尺寸
  category: string;         // 分类路径，用 " > " 分隔
}
```

### ExportRecord

```typescript
interface ExportRecord {
  id: string;
  date: string;             // 格式：YYYY-MM-DD HH:mm
  count: number;            // 产品数量
  sizeMB: number;           // 文件大小（MB）
  status: "completed" | "processing" | "failed";
  downloadUrl?: string;     // 完成时的下载链接
}
```

### User

```typescript
interface User {
  id: string;
  name: string;
  role?: string;
}
```

---

## Mock 数据参考

前端 `src/data/mock.ts` 包含 22 条产品示例数据，可作为数据库初始化参考。