API 接口规范

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

基础约定

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

1. 产品模块

1.1 搜索产品列表

POST /products/search

请求参数:

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

响应:

{
  "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

响应:

{
  "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 响应:

{
  "error": "Product not found"
}

1.3 获取相似产品

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

响应:

[
  {
    "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

响应:

{
  "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

请求:

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

响应:

{
  "taskId": "task_1719000000000"
}

2.3 查询导出进度

GET /exports/:taskId/status

响应:

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

完成时:

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

失败时:

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

2.4 删除导出记录

DELETE /exports/:id

响应:

{
  "success": true
}

3. 用户认证模块

3.1 登录

POST /auth/login

请求:

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

响应:

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

3.2 获取当前用户

GET /auth/me

Headers: Authorization: Bearer <token>

响应:

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

3.3 登出

POST /auth/logout

Headers: Authorization: Bearer <token>

响应:

{
  "success": true
}

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

如需后端持久化收藏：

4.1 获取收藏列表

GET /favorites

响应:

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

4.2 添加收藏

POST /favorites

请求:

{
  "productId": "1"
}

4.3 取消收藏

DELETE /favorites/:productId

数据类型定义

Product

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

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

User

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

Mock 数据参考

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

API_SPEC.md 7.1 KB Histórico Raw