# 数据清洗统一接口文档

> 版本：v2.0.0
> 更新日期：2025-01-01
> 基础URL：`https://server-msq.fmode.cn`
> 接口前缀：`/api/v2/`

本文档定义了一套统一的、经过数据清洗后的前端友好接口，将三个平台（Amazon SP-API、Sorftime、TikHub）的原始数据转换为统一格式，便于前端对接。

---

## 目录

- [1. 设计原则](#1-设计原则)
- [2. 通用类型定义](#2-通用类型定义)
- [3. 统一响应格式](#3-统一响应格式)
- [4. 错误码表](#4-错误码表)
- [5. 接口定义](#5-接口定义)
  - [5.1 商品管理 (Products)](#51-商品管理-products)
  - [5.2 关键词分析 (Keywords)](#52-关键词分析-keywords)
  - [5.3 类目分析 (Categories)](#53-类目分析-categories)
  - [5.4 订单管理 (Orders)](#54-订单管理-orders)
  - [5.5 Listing 管理 (Listings)](#55-listing-管理-listings)
  - [5.6 TikTok 数据 (TikTok)](#56-tiktok-数据-tiktok)
  - [5.7 监控与订阅 (Monitoring)](#57-监控与订阅-monitoring)
  - [5.8 卖家信息 (Sellers)](#58-卖家信息-sellers)
- [附录：数据来源映射总表](#附录数据来源映射总表)

---

## 1. 设计原则

| # | 原则 | 说明 |
|---|------|------|
| 1 | 统一响应格式 | 所有接口返回 `{ code: number, message: string, data: T }` |
| 2 | 字段命名统一 | 全部使用 camelCase |
| 3 | 时间格式统一 | ISO 8601 格式，如 `2025-01-01T12:00:00.000Z` |
| 4 | 金额格式统一 | `{ amount: number, currency: string }` |
| 5 | 分页格式统一 | `{ items: T[], total: number, page: number, pageSize: number, hasMore: boolean }` |
| 6 | 精简字段 | 去除平台特有的冗余字段，只保留前端需要的核心字段 |

---

## 2. 通用类型定义

```typescript
/** 统一响应包装 */
interface ApiResponse<T> {
  /** 业务状态码，0 表示成功 */
  code: number;
  /** 状态描述 */
  message: string;
  /** 响应数据 */
  data: T;
}

/** 统一分页响应 */
interface PaginatedResponse<T> {
  /** 数据列表 */
  items: T[];
  /** 总记录数 */
  total: number;
  /** 当前页码（从 1 开始） */
  page: number;
  /** 每页条数 */
  pageSize: number;
  /** 是否有更多数据 */
  hasMore: boolean;
}

/** 统一金额 */
interface Money {
  /** 金额数值 */
  amount: number;
  /** 货币代码，如 USD、CNY */
  currency: string;
}

/** 统一分页请求参数 */
interface PaginationParams {
  /** 页码，默认 1 */
  page?: number;
  /** 每页条数，默认 20 */
  pageSize?: number;
}

/** 统一时间范围请求参数 */
interface DateRangeParams {
  /** 开始日期 ISO 8601 */
  startDate: string;
  /** 结束日期 ISO 8601 */
  endDate: string;
}

/** 统一商品摘要（多处复用） */
interface ProductSummary {
  /** 统一商品 ID */
  id: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 主图 URL */
  imageUrl: string;
  /** 价格 */
  price: Money | null;
  /** 评分（1-5） */
  rating: number | null;
  /** 评论数 */
  reviewCount: number | null;
  /** 类目名称 */
  category: string;
  /** 数据来源平台 */
  platform: 'amazon' | 'sorftime';
}
```

---

## 3. 统一响应格式

### 成功响应

```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

### 错误响应

```json
{
  "code": 40001,
  "message": "缺少必填参数: keyword",
  "data": null
}
```

### 分页响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [ ... ],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

## 4. 错误码表

| 错误码 | 说明 | HTTP 状态码 |
|--------|------|------------|
| 0 | 成功 | 200 |
| 40001 | 缺少必填参数 | 400 |
| 40002 | 参数格式错误 | 400 |
| 40003 | 参数值超出范围 | 400 |
| 40101 | 未授权（缺少认证信息） | 401 |
| 40102 | 认证过期 | 401 |
| 40301 | 无权访问该资源 | 403 |
| 40401 | 资源不存在 | 404 |
| 40901 | 请求冲突（重复操作） | 409 |
| 42901 | 请求频率超限 | 429 |
| 50001 | 服务器内部错误 | 500 |
| 50002 | Amazon SP-API 调用失败 | 502 |
| 50003 | Sorftime API 调用失败 | 502 |
| 50004 | TikHub API 调用失败 | 502 |
| 50005 | 数据清洗转换异常 | 500 |
| 50301 | 上游服务不可用 | 503 |
| 50401 | 上游服务响应超时 | 504 |

---

## 5. 接口定义

### 5.1 商品管理 (Products)

---

#### `GET /api/v2/products/search` — 统一搜索商品

聚合 Amazon Catalog Items 搜索 + Sorftime ProductQuery，返回统一格式的商品列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `CatalogItemsApi.searchCatalogItems` → `GET /api/amazon/catalog/items` |
| Sorftime | `ProductApi.getProductQuery` → `POST /api/sorftime/forward` → `/api/ProductQuery` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword | string | 是 | 搜索关键词 |
| platform | string | 否 | 数据来源：`amazon` \| `sorftime`，默认全部 |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
// ApiResponse<PaginatedResponse<ProductSummary>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "B0EXAMPLE1",
        "asin": "B0EXAMPLE1",
        "title": "Wireless Bluetooth Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
        "price": { "amount": 29.99, "currency": "USD" },
        "rating": 4.5,
        "reviewCount": 1280,
        "category": "Electronics",
        "platform": "amazon"
      }
    ],
    "total": 156,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

#### `GET /api/v2/products/:id` — 商品详情

聚合 Amazon CatalogItem 详情 + Sorftime ProductRequest，返回完整商品信息。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `CatalogItemsApi.getCatalogItem` → `GET /api/amazon/catalog/items/:asin` |
| Sorftime | `ProductApi.getProductRequest` → `POST /api/sorftime/forward` → `/api/ProductRequest` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 商品 ID（ASIN） |

**响应类型：**

```typescript
interface ProductDetail {
  /** 商品 ID */
  id: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 商品描述 */
  description: string;
  /** 图片列表 */
  images: string[];
  /** 价格 */
  price: Money | null;
  /** 评分（1-5） */
  rating: number | null;
  /** 评论数 */
  reviewCount: number | null;
  /** 类目名称 */
  category: string;
  /** 品牌 */
  brand: string;
  /** BSR 销售排名 */
  salesRank: number | null;
  /** 变体列表 */
  variations: {
    asin: string;
    title: string;
    price: Money | null;
    imageUrl: string;
    attributes: Record<string, string>;
  }[];
}

// ApiResponse<ProductDetail>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "B0EXAMPLE1",
    "asin": "B0EXAMPLE1",
    "title": "Wireless Bluetooth Earbuds",
    "description": "High quality wireless earbuds with noise cancellation...",
    "images": [
      "https://images-na.ssl-images-amazon.com/images/I/img1.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/img2.jpg"
    ],
    "price": { "amount": 29.99, "currency": "USD" },
    "rating": 4.5,
    "reviewCount": 1280,
    "category": "Electronics > Headphones",
    "brand": "ExampleBrand",
    "salesRank": 156,
    "variations": [
      {
        "asin": "B0EXAMPLE2",
        "title": "Wireless Bluetooth Earbuds - Black",
        "price": { "amount": 29.99, "currency": "USD" },
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/black.jpg",
        "attributes": { "color": "Black" }
      }
    ]
  }
}
```

---

#### `GET /api/v2/products/:id/sales` — 商品销量数据

聚合 Amazon Sales OrderMetrics + Sorftime AsinSalesVolume，返回统一的销量趋势数据。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `SalesApi.getOrderMetrics` → `GET /api/amazon/sales/orderMetrics` |
| Sorftime | `ProductApi.getAsinSalesVolume` → `POST /api/sorftime/forward` → `/api/AsinSalesVolume` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 商品 ID（ASIN） |
| startDate | string | 是 | 开始日期 ISO 8601 |
| endDate | string | 是 | 结束日期 ISO 8601 |
| granularity | string | 否 | 粒度：`day` \| `week` \| `month`，默认 `day` |

**响应类型：**

```typescript
interface ProductSalesData {
  periods: {
    /** 日期 ISO 8601 */
    date: string;
    /** 销售件数 */
    unitCount: number;
    /** 订单数 */
    orderCount: number;
    /** 销售额 */
    revenue: Money;
  }[];
}

// ApiResponse<ProductSalesData>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "periods": [
      {
        "date": "2025-01-01T00:00:00.000Z",
        "unitCount": 15,
        "orderCount": 10,
        "revenue": { "amount": 449.85, "currency": "USD" }
      },
      {
        "date": "2025-01-02T00:00:00.000Z",
        "unitCount": 22,
        "orderCount": 18,
        "revenue": { "amount": 659.78, "currency": "USD" }
      }
    ]
  }
}
```

---

#### `GET /api/v2/products/:id/reviews` — 商品评论分析

聚合 Amazon CustomerFeedback + Sorftime ProductReviewsQuery，返回评论汇总与主题分析。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `CustomerFeedbackApi` → `GET /api/amazon/customerFeedback/items/:asin/reviews/topics` |
| Sorftime | `ProductApi.getProductReviewsQuery` → `POST /api/sorftime/forward` → `/api/ProductReviewsQuery` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 商品 ID（ASIN） |

**响应类型：**

```typescript
interface ProductReviewsData {
  /** 评论汇总 */
  summary: {
    /** 总评论数 */
    total: number;
    /** 平均评分 */
    avgRating: number;
    /** 评分分布（1-5 星各多少） */
    distribution: {
      1: number;
      2: number;
      3: number;
      4: number;
      5: number;
    };
  };
  /** 评论主题分析 */
  topics: {
    /** 主题名称 */
    name: string;
    /** 情感倾向：positive | negative | neutral */
    sentiment: string;
    /** 提及次数 */
    count: number;
  }[];
  /** 评论列表 */
  reviews: {
    /** 评论 ID */
    id: string;
    /** 评分 */
    rating: number;
    /** 评论标题 */
    title: string;
    /** 评论内容 */
    content: string;
    /** 评论时间 ISO 8601 */
    createTime: string;
    /** 评论者名称 */
    author: string;
    /** 是否已验证购买 */
    verified: boolean;
  }[];
}

// ApiResponse<ProductReviewsData>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "summary": {
      "total": 1280,
      "avgRating": 4.5,
      "distribution": { "1": 32, "2": 48, "3": 96, "4": 320, "5": 784 }
    },
    "topics": [
      { "name": "音质", "sentiment": "positive", "count": 456 },
      { "name": "电池续航", "sentiment": "positive", "count": 312 },
      { "name": "连接稳定性", "sentiment": "negative", "count": 89 }
    ],
    "reviews": [
      {
        "id": "R1EXAMPLE",
        "rating": 5,
        "title": "Great sound quality",
        "content": "These earbuds have amazing sound...",
        "createTime": "2025-01-10T08:30:00.000Z",
        "author": "John D.",
        "verified": true
      }
    ]
  }
}
```

---

#### `GET /api/v2/products/:id/similar` — 同类产品

基于 Sorftime SimilarProductRealtimeRequest 获取同类产品列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `ProductApi.getSimilarProductRealtimeRequest` → `POST /api/sorftime/forward` → `/api/SimilarProductRealtimeRequest` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 商品 ID（ASIN） |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
// ApiResponse<PaginatedResponse<ProductSummary>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "B0SIMILAR1",
        "asin": "B0SIMILAR1",
        "title": "Noise Cancelling Wireless Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/similar1.jpg",
        "price": { "amount": 34.99, "currency": "USD" },
        "rating": 4.3,
        "reviewCount": 890,
        "category": "Electronics",
        "platform": "sorftime"
      }
    ],
    "total": 45,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

### 5.2 关键词分析 (Keywords)

---

#### `GET /api/v2/keywords/search` — 关键词查询

基于 Sorftime KeywordQuery 查询关键词数据。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `KeywordApi.getKeywordQuery` → `POST /api/sorftime/forward` → `/api/KeywordQuery` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword | string | 是 | 搜索关键词 |
| matchMode | string | 否 | 匹配模式：`broad` \| `exact` \| `phrase`，默认 `broad` |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
interface KeywordItem {
  /** 关键词 */
  keyword: string;
  /** 月搜索量 */
  searchVolume: number;
  /** 搜索趋势：up | down | stable */
  trend: string;
  /** 竞争程度：high | medium | low */
  competition: string;
  /** 每次点击费用 */
  cpc: Money;
}

// ApiResponse<PaginatedResponse<KeywordItem>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "keyword": "wireless earbuds",
        "searchVolume": 450000,
        "trend": "up",
        "competition": "high",
        "cpc": { "amount": 1.25, "currency": "USD" }
      },
      {
        "keyword": "wireless earbuds bluetooth",
        "searchVolume": 120000,
        "trend": "stable",
        "competition": "medium",
        "cpc": { "amount": 0.85, "currency": "USD" }
      }
    ],
    "total": 256,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

#### `GET /api/v2/keywords/:keyword/products` — 关键词下的产品排名

基于 Sorftime KeywordProductRanking 获取关键词下的产品排名列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `KeywordApi.getKeywordProductRanking` → `POST /api/sorftime/forward` → `/api/KeywordProductRanking` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword (路径) | string | 是 | 关键词 |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
interface RankedProduct extends ProductSummary {
  /** 在该关键词下的排名 */
  rank: number;
}

// ApiResponse<PaginatedResponse<RankedProduct>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "B0EXAMPLE1",
        "asin": "B0EXAMPLE1",
        "title": "Wireless Bluetooth Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
        "price": { "amount": 29.99, "currency": "USD" },
        "rating": 4.5,
        "reviewCount": 1280,
        "category": "Electronics",
        "platform": "sorftime",
        "rank": 1
      }
    ],
    "total": 48,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

#### `GET /api/v2/keywords/reverse/:asin` — ASIN 反查关键词

聚合 Sorftime ASINRequestKeyword + KeywordRequest，通过 ASIN 反查关联关键词。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `KeywordApi.getASINRequestKeyword` → `POST /api/sorftime/forward` → `/api/ASINRequestKeyword` |
| Sorftime | `KeywordApi.getKeywordRequest` → `POST /api/sorftime/forward` → `/api/KeywordRequest` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| asin (路径) | string | 是 | 商品 ASIN |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
interface ReverseKeywordItem {
  /** 关键词 */
  keyword: string;
  /** 该 ASIN 在此关键词下的排名 */
  rank: number;
  /** 月搜索量 */
  searchVolume: number;
  /** 搜索趋势：up | down | stable */
  trend: string;
}

// ApiResponse<PaginatedResponse<ReverseKeywordItem>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "keyword": "wireless earbuds",
        "rank": 3,
        "searchVolume": 450000,
        "trend": "up"
      },
      {
        "keyword": "bluetooth earbuds",
        "rank": 7,
        "searchVolume": 280000,
        "trend": "stable"
      }
    ],
    "total": 89,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

#### `GET /api/v2/keywords/:keyword/trend` — 关键词趋势

基于 Sorftime KeywordSearchResultTrend 获取关键词搜索趋势数据。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `KeywordApi.getKeywordSearchResultTrend` → `POST /api/sorftime/forward` → `/api/KeywordSearchResultTrend` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword (路径) | string | 是 | 关键词 |

**响应类型：**

```typescript
interface KeywordTrendData {
  periods: {
    /** 日期 ISO 8601 */
    date: string;
    /** 搜索量 */
    searchVolume: number;
    /** 搜索结果数 */
    resultCount: number;
  }[];
}

// ApiResponse<KeywordTrendData>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "periods": [
      {
        "date": "2025-01-01T00:00:00.000Z",
        "searchVolume": 450000,
        "resultCount": 3200
      },
      {
        "date": "2025-02-01T00:00:00.000Z",
        "searchVolume": 480000,
        "resultCount": 3350
      }
    ]
  }
}
```

---

### 5.3 类目分析 (Categories)

---

#### `GET /api/v2/categories/tree` — 类目树

聚合 Amazon Catalog Categories + Sorftime CategoryTree，返回统一的类目树结构。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `CatalogItemsApi.getCatalogCategories` → `GET /api/amazon/catalog/categories` |
| Sorftime | `CategoryApi.getCategoryTree` → `POST /api/sorftime/forward` → `/api/CategoryTree` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| platform | string | 否 | 数据来源：`amazon` \| `sorftime`，默认全部 |
| domain | string | 否 | 市场域名，如 `amazon.com` |

**响应类型：**

```typescript
interface CategoryNode {
  /** 类目 ID */
  id: string;
  /** 类目名称 */
  name: string;
  /** 父类目 ID，顶级为 null */
  parentId: string | null;
  /** 子类目列表 */
  children: CategoryNode[];
  /** 类目下商品数量 */
  productCount: number | null;
}

// ApiResponse<{ items: CategoryNode[] }>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "1234",
        "name": "Electronics",
        "parentId": null,
        "children": [
          {
            "id": "5678",
            "name": "Headphones",
            "parentId": "1234",
            "children": [],
            "productCount": 15600
          }
        ],
        "productCount": 256000
      }
    ]
  }
}
```

---

#### `GET /api/v2/categories/:id/top-products` — 类目热销产品

基于 Sorftime CategoryRequest + CategoryProducts 获取类目下的热销产品。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `CategoryApi.getCategoryRequest` → `POST /api/sorftime/forward` → `/api/CategoryRequest` |
| Sorftime | `CategoryApi.getCategoryProducts` → `POST /api/sorftime/forward` → `/api/CategoryProducts` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 类目 ID |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
interface RankedProduct extends ProductSummary {
  /** 在该类目下的排名 */
  rank: number;
}

// ApiResponse<PaginatedResponse<RankedProduct>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "B0TOP001",
        "asin": "B0TOP001",
        "title": "Best Selling Wireless Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/top1.jpg",
        "price": { "amount": 24.99, "currency": "USD" },
        "rating": 4.7,
        "reviewCount": 5600,
        "category": "Headphones",
        "platform": "sorftime",
        "rank": 1
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

#### `GET /api/v2/categories/:id/keywords` — 类目关键词

基于 Sorftime CategoryRequestKeyword 获取类目下的关键词列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `KeywordApi.getCategoryRequestKeyword` → `POST /api/sorftime/forward` → `/api/CategoryRequestKeyword` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 类目 ID |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
// ApiResponse<PaginatedResponse<KeywordItem>>
// KeywordItem 定义见 5.2 关键词查询
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "keyword": "wireless earbuds",
        "searchVolume": 450000,
        "trend": "up",
        "competition": "high",
        "cpc": { "amount": 1.25, "currency": "USD" }
      }
    ],
    "total": 120,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

### 5.4 订单管理 (Orders)

> 仅 Amazon 平台

---

#### `GET /api/v2/orders` — 订单列表

基于 Amazon Orders API 获取订单列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `OrdersApi.getOrders` → `GET /api/amazon/orders` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| startDate | string | 是 | 开始日期 ISO 8601 |
| endDate | string | 是 | 结束日期 ISO 8601 |
| status | string | 否 | 订单状态：`pending` \| `shipped` \| `delivered` \| `cancelled` |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
interface OrderItem {
  /** 订单 ID */
  orderId: string;
  /** 下单时间 ISO 8601 */
  orderDate: string;
  /** 订单状态 */
  status: string;
  /** 订单总额 */
  total: Money;
  /** 商品件数 */
  itemCount: number;
  /** 买家名称 */
  buyerName: string;
  /** 销售渠道 */
  channel: string;
}

// ApiResponse<PaginatedResponse<OrderItem>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "orderId": "111-1234567-1234567",
        "orderDate": "2025-01-15T10:30:00.000Z",
        "status": "shipped",
        "total": { "amount": 59.98, "currency": "USD" },
        "itemCount": 2,
        "buyerName": "John D.",
        "channel": "Amazon.com"
      }
    ],
    "total": 350,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

#### `GET /api/v2/orders/:id` — 订单详情

基于 Amazon Orders API 获取订单详情及商品明细。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `OrdersApi.getOrder` → `GET /api/amazon/orders/:orderId` |
| Amazon | `OrdersApi.getOrderItems` → `GET /api/amazon/orders/:orderId/items` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 订单 ID |

**响应类型：**

```typescript
interface OrderDetail {
  /** 订单 ID */
  orderId: string;
  /** 下单时间 ISO 8601 */
  orderDate: string;
  /** 订单状态 */
  status: string;
  /** 订单总额 */
  total: Money;
  /** 订单商品列表 */
  items: {
    /** ASIN */
    asin: string;
    /** SKU */
    sku: string;
    /** 商品标题 */
    title: string;
    /** 数量 */
    quantity: number;
    /** 单价 */
    price: Money;
    /** 商品图片 */
    imageUrl: string;
  }[];
  /** 配送信息 */
  shipping: {
    /** 收件人 */
    name: string;
    /** 配送方式 */
    method: string;
    /** 配送状态 */
    status: string;
    /** 预计送达时间 ISO 8601 */
    estimatedDelivery: string | null;
  };
  /** 支付信息 */
  payment: {
    /** 支付方式 */
    method: string;
    /** 支付总额 */
    total: Money;
  };
}

// ApiResponse<OrderDetail>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "orderId": "111-1234567-1234567",
    "orderDate": "2025-01-15T10:30:00.000Z",
    "status": "shipped",
    "total": { "amount": 59.98, "currency": "USD" },
    "items": [
      {
        "asin": "B0EXAMPLE1",
        "sku": "WE-BLK-001",
        "title": "Wireless Bluetooth Earbuds - Black",
        "quantity": 2,
        "price": { "amount": 29.99, "currency": "USD" },
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg"
      }
    ],
    "shipping": {
      "name": "John Doe",
      "method": "Standard Shipping",
      "status": "In Transit",
      "estimatedDelivery": "2025-01-20T00:00:00.000Z"
    },
    "payment": {
      "method": "Credit Card",
      "total": { "amount": 59.98, "currency": "USD" }
    }
  }
}
```

---

#### `GET /api/v2/orders/metrics` — 订单统计指标

基于 Amazon Sales OrderMetrics 获取订单统计数据。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `SalesApi.getOrderMetrics` → `GET /api/amazon/sales/orderMetrics` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| startDate | string | 是 | 开始日期 ISO 8601 |
| endDate | string | 是 | 结束日期 ISO 8601 |
| granularity | string | 否 | 粒度：`day` \| `week` \| `month`，默认 `day` |

**响应类型：**

```typescript
interface OrderMetricsData {
  periods: {
    /** 日期 ISO 8601 */
    date: string;
    /** 订单数 */
    orderCount: number;
    /** 销售件数 */
    unitCount: number;
    /** 销售额 */
    revenue: Money;
  }[];
}

// ApiResponse<OrderMetricsData>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "periods": [
      {
        "date": "2025-01-01T00:00:00.000Z",
        "orderCount": 45,
        "unitCount": 68,
        "revenue": { "amount": 2034.55, "currency": "USD" }
      },
      {
        "date": "2025-01-02T00:00:00.000Z",
        "orderCount": 52,
        "unitCount": 79,
        "revenue": { "amount": 2367.21, "currency": "USD" }
      }
    ]
  }
}
```

---

### 5.5 Listing 管理 (Listings)

> 仅 Amazon 平台

---

#### `GET /api/v2/listings` — Listing 列表

基于 Amazon Listings Items API 获取卖家的 Listing 列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `ListingsItemsApi.searchListingsItems` → `GET /api/amazo
### 5.5 Listing 管理 (Listings)

> 仅 Amazon 平台

---

#### `GET /api/v2/listings` — Listing 列表

基于 Amazon Listings Items API 获取卖家的 Listing 列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `ListingsItemsApi.searchListingsItems` → `GET /api/amazon/listings/items/:sellerId` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sellerId | string | 是 | 卖家 ID |
| keywords | string | 否 | 搜索关键词 |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
interface ListingItem {
  /** SKU */
  sku: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 状态：active | inactive | incomplete */
  status: string;
  /** 价格 */
  price: Money | null;
  /** 主图 URL */
  imageUrl: string;
  /** 商品状况：new | used | refurbished */
  condition: string;
  /** 创建时间 ISO 8601 */
  createdAt: string;
}

// ApiResponse<PaginatedResponse<ListingItem>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "sku": "WE-BLK-001",
        "asin": "B0EXAMPLE1",
        "title": "Wireless Bluetooth Earbuds - Black",
        "status": "active",
        "price": { "amount": 29.99, "currency": "USD" },
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
        "condition": "new",
        "createdAt": "2024-06-15T08:00:00.000Z"
      }
    ],
    "total": 85,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

#### `GET /api/v2/listings/:sku` — Listing 详情

基于 Amazon Listings Items API 获取单个 Listing 的详细信息。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `ListingsItemsApi.getListingsItem` → `GET /api/amazon/listings/items/:sellerId/:sku` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sku (路径) | string | 是 | 商品 SKU |

**响应类型：**

```typescript
interface ListingDetail {
  /** SKU */
  sku: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 状态 */
  status: string;
  /** 价格 */
  price: Money | null;
  /** 主图 URL */
  imageUrl: string;
  /** 商品状况 */
  condition: string;
  /** 问题列表 */
  issues: {
    /** 问题代码 */
    code: string;
    /** 问题描述 */
    message: string;
    /** 严重程度：error | warning | info */
    severity: string;
  }[];
  /** 报价列表 */
  offers: {
    /** 报价类型 */
    offerType: string;
    /** 价格 */
    price: Money;
    /** 配送方式 */
    fulfillment: string;
  }[];
  /** 配送方式：FBA | FBM */
  fulfillment: string;
}

// ApiResponse<ListingDetail>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "sku": "WE-BLK-001",
    "asin": "B0EXAMPLE1",
    "title": "Wireless Bluetooth Earbuds - Black",
    "status": "active",
    "price": { "amount": 29.99, "currency": "USD" },
    "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
    "condition": "new",
    "issues": [],
    "offers": [
      {
        "offerType": "B2C",
        "price": { "amount": 29.99, "currency": "USD" },
        "fulfillment": "FBA"
      }
    ],
    "fulfillment": "FBA"
  }
}
```

---

### 5.6 TikTok 数据 (TikTok)

> 数据来源：TikHub API

---

#### `GET /api/v2/tiktok/users/:uniqueId` — 用户资料

获取 TikTok 用户的基本资料信息。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| TikHub | `TikTokUserApi` → `GET /api/tikhub/tiktok/user/info` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| uniqueId (路径) | string | 是 | TikTok 用户唯一标识 |

**响应类型：**

```typescript
interface TikTokUser {
  /** 用户 ID */
  userId: string;
  /** 用户唯一标识 */
  uniqueId: string;
  /** 昵称 */
  nickname: string;
  /** 头像 URL */
  avatar: string;
  /** 个人简介 */
  bio: string;
  /** 粉丝数 */
  followerCount: number;
  /** 关注数 */
  followingCount: number;
  /** 获赞数 */
  likeCount: number;
  /** 视频数 */
  videoCount: number;
}

// ApiResponse<TikTokUser>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": "6789012345",
    "uniqueId": "example_user",
    "nickname": "Example Creator",
    "avatar": "https://p16-sign.tiktokcdn.com/avatar/example.jpg",
    "bio": "Content creator | Tech reviews",
    "followerCount": 125000,
    "followingCount": 350,
    "likeCount": 2800000,
    "videoCount": 256
  }
}
```

---

#### `GET /api/v2/tiktok/videos/:id` — 视频详情

获取 TikTok 视频的详细信息。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| TikHub | `TikTokVideoApi` → `GET /api/tikhub/tiktok/video/info` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 视频 ID |

**响应类型：**

```typescript
interface TikTokVideo {
  /** 视频 ID */
  videoId: string;
  /** 视频描述 */
  description: string;
  /** 封面图 URL */
  coverUrl: string;
  /** 视频播放 URL */
  videoUrl: string;
  /** 视频时长（秒） */
  duration: number;
  /** 发布时间 ISO 8601 */
  createTime: string;
  /** 互动数据 */
  stats: {
    /** 播放量 */
    playCount: number;
    /** 点赞数 */
    likeCount: number;
    /** 评论数 */
    commentCount: number;
    /** 分享数 */
    shareCount: number;
  };
}

// ApiResponse<TikTokVideo>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "videoId": "7123456789012345678",
    "description": "Amazing wireless earbuds review! #tech #earbuds",
    "coverUrl": "https://p16-sign.tiktokcdn.com/cover/example.jpg",
    "videoUrl": "https://v16-webapp.tiktok.com/video/example.mp4",
    "duration": 60,
    "createTime": "2025-01-10T15:30:00.000Z",
    "stats": {
      "playCount": 1250000,
      "likeCount": 85000,
      "commentCount": 3200,
      "shareCount": 12000
    }
  }
}
```

---

#### `GET /api/v2/tiktok/videos/:id/comments` — 视频评论

获取 TikTok 视频的评论列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| TikHub | `TikTokVideoApi` → `GET /api/tikhub/tiktok/video/comments` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 视频 ID |
| cursor | string | 否 | 分页游标，首次请求不传 |
| count | number | 否 | 每次获取条数，默认 20 |

**响应类型：**

```typescript
interface TikTokComment {
  /** 评论 ID */
  commentId: string;
  /** 评论内容 */
  text: string;
  /** 评论者信息 */
  author: {
    userId: string;
    uniqueId: string;
    nickname: string;
    avatar: string;
  };
  /** 点赞数 */
  likeCount: number;
  /** 评论时间 ISO 8601 */
  createTime: string;
  /** 回复列表 */
  replies: TikTokComment[];
}

interface TikTokCommentListResponse {
  items: TikTokComment[];
  /** 是否有更多数据 */
  hasMore: boolean;
  /** 下一页游标 */
  cursor: string;
}

// ApiResponse<TikTokCommentListResponse>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "commentId": "7123456789000000001",
        "text": "Great review! Just ordered a pair.",
        "author": {
          "userId": "1234567890",
          "uniqueId": "tech_fan",
          "nickname": "Tech Fan",
          "avatar": "https://p16-sign.tiktokcdn.com/avatar/fan.jpg"
        },
        "likeCount": 256,
        "createTime": "2025-01-10T16:00:00.000Z",
        "replies": []
      }
    ],
    "hasMore": true,
    "cursor": "cursor_token_abc123"
  }
}
```

---

#### `GET /api/v2/tiktok/users/:id/followers` — 用户粉丝

获取 TikTok 用户的粉丝列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| TikHub | `TikTokUserApi` → `GET /api/tikhub/tiktok/user/followers` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 用户 ID |
| offset | number | 否 | 偏移量，默认 0 |
| count | number | 否 | 每次获取条数，默认 20 |

**响应类型：**

```typescript
interface TikTokUserListResponse {
  items: TikTokUser[];
  /** 是否有更多数据 */
  hasMore: boolean;
  /** 下一页偏移量 */
  offset: number;
}

// ApiResponse<TikTokUserListResponse>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "userId": "9876543210",
        "uniqueId": "follower_user",
        "nickname": "Follower",
        "avatar": "https://p16-sign.tiktokcdn.com/avatar/follower.jpg",
        "bio": "Love tech!",
        "followerCount": 500,
        "followingCount": 200,
        "likeCount": 10000,
        "videoCount": 15
      }
    ],
    "hasMore": true,
    "offset": 20
  }
}
```

---

#### `GET /api/v2/tiktok/users/:id/following` — 用户关注列表

获取 TikTok 用户的关注列表。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| TikHub | `TikTokUserApi` → `GET /api/tikhub/tiktok/app/v3/user-following` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 用户 ID |
| offset | number | 否 | 偏移量，默认 0 |
| count | number | 否 | 每次获取条数，默认 20 |

**响应类型：**

```typescript
// ApiResponse<TikTokUserListResponse>
// TikTokUserListResponse 定义见 users/:id/followers
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "userId": "1122334455",
        "uniqueId": "following_user",
        "nickname": "Following User",
        "avatar": "https://p16-sign.tiktokcdn.com/avatar/following.jpg",
        "bio": "Tech blogger",
        "followerCount": 80000,
        "followingCount": 150,
        "likeCount": 500000,
        "videoCount": 120
      }
    ],
    "hasMore": true,
    "offset": 20
  }
}
```

---

#### `GET /api/v2/tiktok/shop/products/:id` — TikTok 商品详情

获取 TikTok 小店商品的详细信息。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| TikHub | `TikTokShopApi` → `GET /api/tikhub/tiktok/shop/product-detail` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | TikTok 商品 ID |

**响应类型：**

```typescript
interface TikTokShopProduct {
  /** 商品 ID */
  productId: string;
  /** 商品标题 */
  title: string;
  /** 商品描述 */
  description: string;
  /** 商品图片列表 */
  images: string[];
  /** 价格 */
  price: Money;
  /** 原价 */
  originalPrice: Money | null;
  /** 销量 */
  soldCount: number;
  /** 评分（1-5） */
  rating: number | null;
  /** 评论数 */
  reviewCount: number;
  /** 店铺名称 */
  shopName: string;
  /** 店铺 ID */
  shopId: string;
  /** 商品分类 */
  category: string;
  /** 商品状态：active | inactive */
  status: string;
}

// ApiResponse<TikTokShopProduct>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "productId": "1729384756012345",
    "title": "Wireless Earbuds Pro Max",
    "description": "Premium wireless earbuds with ANC...",
    "images": [
      "https://p16-oec-ttp.tiktokcdn.com/product/img1.jpg",
      "https://p16-oec-ttp.tiktokcdn.com/product/img2.jpg"
    ],
    "price": { "amount": 19.99, "currency": "USD" },
    "originalPrice": { "amount": 39.99, "currency": "USD" },
    "soldCount": 15600,
    "rating": 4.6,
    "reviewCount": 2340,
    "shopName": "TechStore Official",
    "shopId": "7654321098765",
    "category": "Electronics > Audio",
    "status": "active"
  }
}
```

---

#### `GET /api/v2/tiktok/ads/:id` — 广告详情

获取 TikTok 广告的详细信息。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| TikHub | `TikTokAdsApi` → `GET /api/tikhub/tiktok/ads/ads-detail` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id (路径) | string | 是 | 广告 ID |

**响应类型：**

```typescript
interface TikTokAdDetail {
  /** 广告 ID */
  adId: string;
  /** 广告标题 */
  title: string;
  /** 广告描述 */
  description: string;
  /** 广告素材 URL */
  mediaUrl: string;
  /** 广告封面 URL */
  coverUrl: string;
  /** 落地页 URL */
  landingPageUrl: string;
  /** 广告主名称 */
  advertiserName: string;
  /** 广告主 ID */
  advertiserId: string;
  /** 投放时长（天） */
  durationDays: number;
  /** 首次投放时间 ISO 8601 */
  firstSeenAt: string;
  /** 最近投放时间 ISO 8601 */
  lastSeenAt: string;
  /** 互动数据 */
  stats: {
    /** 点赞数 */
    likeCount: number;
    /** 评论数 */
    commentCount: number;
    /** 分享数 */
    shareCount: number;
  };
}

// ApiResponse<TikTokAdDetail>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "adId": "ad_7890123456",
    "title": "Wireless Earbuds - 50% OFF",
    "description": "Limited time offer on premium earbuds!",
    "mediaUrl": "https://v16-webapp.tiktok.com/ad/example.mp4",
    "coverUrl": "https://p16-sign.tiktokcdn.com/ad/cover.jpg",
    "landingPageUrl": "https://shop.tiktok.com/product/12345",
    "advertiserName": "TechStore Official",
    "advertiserId": "adv_1234567890",
    "durationDays": 14,
    "firstSeenAt": "2025-01-01T00:00:00.000Z",
    "lastSeenAt": "2025-01-14T23:59:59.000Z",
    "stats": {
      "likeCount": 12500,
      "commentCount": 890,
      "shareCount": 3400
    }
  }
}
```

---

### 5.7 监控与订阅 (Monitoring)

> 数据来源：Sorftime API

---

#### `POST /api/v2/monitoring/bestseller/subscribe` — BS榜单订阅

创建 Best Seller 榜单监控订阅任务。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `MonitorApi.subscribeBestseller` → `POST /api/sorftime/forward` → `/api/BestsellerSubscribe` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| categoryId | string | 是 | 类目 ID |
| domain | string | 是 | 市场域名，如 `amazon.com` |
| frequency | string | 否 | 监控频率：`daily` \| `weekly`，默认 `daily` |

**响应类型：**

```typescript
interface SubscribeResult {
  /** 任务 ID */
  taskId: string;
  /** 订阅状态：active | pending */
  status: string;
  /** 创建时间 ISO 8601 */
  createdAt: string;
}

// ApiResponse<SubscribeResult>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "bs_task_20250101_001",
    "status": "active",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}
```

---

#### `GET /api/v2/monitoring/bestseller/tasks` — BS榜单任务列表

获取当前所有 Best Seller 榜单监控任务。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `MonitorApi.getBestsellerTasks` → `POST /api/sorftime/forward` → `/api/BestsellerTasks` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
interface BestsellerTask {
  /** 任务 ID */
  taskId: string;
  /** 类目 ID */
  categoryId: string;
  /** 类目名称 */
  categoryName: string;
  /** 市场域名 */
  domain: string;
  /** 监控频率 */
  frequency: string;
  /** 任务状态：active | paused | expired */
  status: string;
  /** 创建时间 ISO 8601 */
  createdAt: string;
  /** 最近更新时间 ISO 8601 */
  lastUpdatedAt: string | null;
}

// ApiResponse<PaginatedResponse<BestsellerTask>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "taskId": "bs_task_20250101_001",
        "categoryId": "1234",
        "categoryName": "Electronics > Headphones",
        "domain": "amazon.com",
        "frequency": "daily",
        "status": "active",
        "createdAt": "2025-01-01T00:00:00.000Z",
        "lastUpdatedAt": "2025-01-15T06:00:00.000Z"
      }
    ],
    "total": 5,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}
```

---

#### `GET /api/v2/monitoring/bestseller/:taskId/data` — BS榜单数据

获取指定 Best Seller 监控任务的榜单数据。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `MonitorApi.getBestsellerData` → `POST /api/sorftime/forward` → `/api/BestsellerData` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| taskId (路径) | string | 是 | 任务 ID |
| date | string | 否 | 查询日期 ISO 8601，默认最新 |
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
interface BestsellerDataItem {
  /** 排名 */
  rank: number;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 主图 URL */
  imageUrl: string;
  /** 价格 */
  price: Money | null;
  /** 评分 */
  rating: number | null;
  /** 评论数 */
  reviewCount: number | null;
  /** 排名变化：正数上升，负数下降，0 不变 */
  rankChange: number;
  /** 是否新上榜 */
  isNew: boolean;
}

// ApiResponse<PaginatedResponse<BestsellerDataItem>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "rank": 1,
        "asin": "B0TOP001",
        "title": "Best Selling Wireless Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/top1.jpg",
        "price": { "amount": 24.99, "currency": "USD" },
        "rating": 4.7,
        "reviewCount": 5600,
        "rankChange": 0,
        "isNew": false
      },
      {
        "rank": 2,
        "asin": "B0TOP002",
        "title": "Premium Noise Cancelling Headphones",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/top2.jpg",
        "price": { "amount": 49.99, "currency": "USD" },
        "rating": 4.5,
        "reviewCount": 3200,
        "rankChange": 2,
        "isNew": false
      }
    ],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}
```

---

#### `POST /api/v2/monitoring/asin/subscribe` — ASIN订阅

创建 ASIN 监控订阅，跟踪指定商品的价格、排名等变化。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `MonitorApi.subscribeAsin` → `POST /api/sorftime/forward` → `/api/AsinSubscribe` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| asin | string | 是 | 商品 ASIN |
| domain | string | 是 | 市场域名，如 `amazon.com` |
| frequency | string | 否 | 监控频率：`daily` \| `weekly`，默认 `daily` |

**响应类型：**

```typescript
// ApiResponse<SubscribeResult>
// SubscribeResult 定义见 bestseller/subscribe
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "taskId": "asin_task_20250101_001",
    "status": "active",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}
```

---

#### `GET /api/v2/monitoring/asin/list` — ASIN订阅列表

获取当前所有 ASIN 监控订阅。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `MonitorApi.getAsinSubscriptions` → `POST /api/sorftime/forward` → `/api/AsinSubscriptions` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | number | 否 | 页码，默认 1 |
| pageSize | number | 否 | 每页条数，默认 20 |

**响应类型：**

```typescript
interface AsinSubscriptionItem {
  /** 任务 ID */
  taskId: string;
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 主图 URL */
  imageUrl: string;
  /** 市场域名 */
  domain: string;
  /** 监控频率 */
  frequency: string;
  /** 当前价格 */
  currentPrice: Money | null;
  /** 任务状态：active | paused | expired */
  status: string;
  /** 创建时间 ISO 8601 */
  createdAt: string;
  /** 最近更新时间 ISO 8601 */
  lastUpdatedAt: string | null;
}

// ApiResponse<PaginatedResponse<AsinSubscriptionItem>>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "taskId": "asin_task_20250101_001",
        "asin": "B0EXAMPLE1",
        "title": "Wireless Bluetooth Earbuds",
        "imageUrl": "https://images-na.ssl-images-amazon.com/images/I/example.jpg",
        "domain": "amazon.com",
        "frequency": "daily",
        "currentPrice": { "amount": 29.99, "currency": "USD" },
        "status": "active",
        "createdAt": "2025-01-01T00:00:00.000Z",
        "lastUpdatedAt": "2025-01-15T06:00:00.000Z"
      }
    ],
    "total": 12,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}
```

---

#### `GET /api/v2/monitoring/asin/data` — ASIN订阅数据

获取 ASIN 监控的历史数据（价格、排名变化等）。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Sorftime | `MonitorApi.getAsinMonitorData` → `POST /api/sorftime/forward` → `/api/AsinMonitorData` |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| asin | string | 是 | 商品 ASIN |
| startDate | string | 否 | 开始日期 ISO 8601 |
| endDate | string | 否 | 结束日期 ISO 8601 |

**响应类型：**

```typescript
interface AsinMonitorDataPoint {
  /** 日期 ISO 8601 */
  date: string;
  /** 价格 */
  price: Money | null;
  /** BSR 排名 */
  salesRank: number | null;
  /** 评分 */
  rating: number | null;
  /** 评论数 */
  reviewCount: number | null;
}

interface AsinMonitorData {
  /** ASIN */
  asin: string;
  /** 商品标题 */
  title: string;
  /** 数据点列表 */
  dataPoints: AsinMonitorDataPoint[];
}

// ApiResponse<AsinMonitorData>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "asin": "B0EXAMPLE1",
    "title": "Wireless Bluetooth Earbuds",
    "dataPoints": [
      {
        "date": "2025-01-01T00:00:00.000Z",
        "price": { "amount": 29.99, "currency": "USD" },
        "salesRank": 156,
        "rating": 4.5,
        "reviewCount": 1250
      },
      {
        "date": "2025-01-02T00:00:00.000Z",
        "price": { "amount": 27.99, "currency": "USD" },
        "salesRank": 142,
        "rating": 4.5,
        "reviewCount": 1265
      }
    ]
  }
}
```

---

### 5.8 卖家信息 (Sellers)

> 仅 Amazon 平台

---

#### `GET /api/v2/sellers/account` — 卖家账户信息

获取当前卖家的账户基本信息。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `SellersApi.getMarketplaceParticipations` → `GET /api/amazon/sellers/marketplaceParticipations` |

**请求参数：**

无

**响应类型：**

```typescript
interface SellerAccount {
  /** 卖家 ID */
  sellerId: string;
  /** 卖家名称 */
  name: string;
  /** 账户状态：active | inactive */
  status: string;
  /** 注册市场列表 */
  marketplaces: {
    /** 市场 ID */
    marketplaceId: string;
    /** 市场名称 */
    name: string;
    /** 国家代码 */
    countryCode: string;
    /** 默认货币 */
    defaultCurrency: string;
    /** 是否参与 */
    isParticipating: boolean;
  }[];
}

// ApiResponse<SellerAccount>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "sellerId": "A1EXAMPLE123",
    "name": "ExampleStore",
    "status": "active",
    "marketplaces": [
      {
        "marketplaceId": "ATVPDKIKX0DER",
        "name": "Amazon.com",
        "countryCode": "US",
        "defaultCurrency": "USD",
        "isParticipating": true
      },
      {
        "marketplaceId": "A1F83G8C2ARO7P",
        "name": "Amazon.co.uk",
        "countryCode": "GB",
        "defaultCurrency": "GBP",
        "isParticipating": true
      }
    ]
  }
}
```

---

#### `GET /api/v2/sellers/marketplaces` — 卖家市场列表

获取卖家已注册的市场列表及参与状态。

**数据来源：**

| 平台 | 原始接口 |
|------|---------|
| Amazon | `SellersApi.getMarketplaceParticipations` → `GET /api/amazon/sellers/marketplaceParticipations` |

**请求参数：**

无

**响应类型：**

```typescript
interface MarketplaceItem {
  /** 市场 ID */
  marketplaceId: string;
  /** 市场名称 */
  name: string;
  /** 国家代码 */
  countryCode: string;
  /** 默认语言 */
  defaultLanguage: string;
  /** 默认货币 */
  defaultCurrency: string;
  /** 域名 */
  domain: string;
  /** 是否参与 */
  isParticipating: boolean;
}

// ApiResponse<{ items: MarketplaceItem[] }>
```

**响应示例：**

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "marketplaceId": "ATVPDKIKX0DER",
        "name": "Amazon.com",
        "countryCode": "US",
        "defaultLanguage": "en_US",
        "defaultCurrency": "USD",
        "domain": "amazon.com",
        "isParticipating": true
      },
      {
        "marketplaceId": "A1F83G8C2ARO7P",
        "name": "Amazon.co.uk",
        "countryCode": "GB",
        "defaultLanguage": "en_GB",
        "defaultCurrency": "GBP",
        "domain": "amazon.co.uk",
        "isParticipating": true
      }
    ]
  }
}
```

---

## 附录：数据来源映射总表

以下表格列出所有 `/api/v2/` 统一接口与原始平台接口的完整映射关系。

### 5.1 商品管理 (Products)

| 统一接口 | 方法 | 原始平台 | 原始接口 |
|---------|------|---------|---------|
| `/api/v2/products/search` | GET | Amazon | `GET /api/amazon/catalog/items` |
| `/api/v2/products/search` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/ProductQuery` |
| `/api/v2/products/:id` | GET | Amazon | `GET /api/amazon/catalog/items/:asin` |
| `/api/v2/products/:id` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/ProductRequest` |
| `/api/v2/products/:id/sales` | GET | Amazon | `GET /api/amazon/sales/orderMetrics` |
| `/api/v2/products/:id/sales` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/AsinSalesVolume` |
| `/api/v2/products/:id/reviews` | GET | Amazon | `GET /api/amazon/customerFeedback/items/:asin/reviews/topics` |
| `/api/v2/products/:id/reviews` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/ProductReviewsQuery` |
| `/api/v2/products/:id/similar` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/SimilarProductRealtimeRequest` |

### 5.2 关键词分析 (Keywords)

| 统一接口 | 方法 | 原始平台 | 原始接口 |
|---------|------|---------|---------|
| `/api/v2/keywords/search` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/KeywordQuery` |
| `/api/v2/keywords/:keyword/products` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/KeywordProductRanking` |
| `/api/v2/keywords/reverse/:asin` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/ASINRequestKeyword` |
| `/api/v2/keywords/reverse/:asin` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/KeywordRequest` |
| `/api/v2/keywords/:keyword/trend` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/KeywordSearchResultTrend` |

### 5.3 类目分析 (Categories)

| 统一接口 | 方法 | 原始平台 | 原始接口 |
|---------|------|---------|---------|
| `/api/v2/categories/tree` | GET | Amazon | `GET /api/amazon/catalog/categories` |
| `/api/v2/categories/tree` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/CategoryTree` |
| `/api/v2/categories/:id/top-products` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/CategoryRequest` |
| `/api/v2/categories/:id/top-products` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/CategoryProducts` |
| `/api/v2/categories/:id/keywords` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/CategoryRequestKeyword` |

### 5.4 订单管理 (Orders)

| 统一接口 | 方法 | 原始平台 | 原始接口 |
|---------|------|---------|---------|
| `/api/v2/orders` | GET | Amazon | `GET /api/amazon/orders` |
| `/api/v2/orders/:id` | GET | Amazon | `GET /api/amazon/orders/:orderId` |
| `/api/v2/orders/:id` | GET | Amazon | `GET /api/amazon/orders/:orderId/items` |
| `/api/v2/orders/metrics` | GET | Amazon | `GET /api/amazon/sales/orderMetrics` |

### 5.5 Listing 管理 (Listings)

| 统一接口 | 方法 | 原始平台 | 原始接口 |
|---------|------|---------|---------|
| `/api/v2/listings` | GET | Amazon | `GET /api/amazon/listings/items/:sellerId` |
| `/api/v2/listings/:sku` | GET | Amazon | `GET /api/amazon/listings/items/:sellerId/:sku` |

### 5.6 TikTok 数据 (TikTok)

| 统一接口 | 方法 | 原始平台 | 原始接口 |
|---------|------|---------|---------|
| `/api/v2/tiktok/users/:uniqueId` | GET | TikHub | `GET /api/tikhub/tiktok/user/info` |
| `/api/v2/tiktok/videos/:id` | GET | TikHub | `GET /api/tikhub/tiktok/video/info` |
| `/api/v2/tiktok/videos/:id/comments` | GET | TikHub | `GET /api/tikhub/tiktok/video/comments` |
| `/api/v2/tiktok/users/:id/followers` | GET | TikHub | `GET /api/tikhub/tiktok/user/followers` |
| `/api/v2/tiktok/users/:id/following` | GET | TikHub | `GET /api/tikhub/tiktok/app/v3/user-following` |
| `/api/v2/tiktok/shop/products/:id` | GET | TikHub | `GET /api/tikhub/tiktok/shop/product-detail` |
| `/api/v2/tiktok/ads/:id` | GET | TikHub | `GET /api/tikhub/tiktok/ads/ads-detail` |

### 5.7 监控与订阅 (Monitoring)

| 统一接口 | 方法 | 原始平台 | 原始接口 |
|---------|------|---------|---------|
| `/api/v2/monitoring/bestseller/subscribe` | POST | Sorftime | `POST /api/sorftime/forward` → `/api/BestsellerSubscribe` |
| `/api/v2/monitoring/bestseller/tasks` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/BestsellerTasks` |
| `/api/v2/monitoring/bestseller/:taskId/data` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/BestsellerData` |
| `/api/v2/monitoring/asin/subscribe` | POST | Sorftime | `POST /api/sorftime/forward` → `/api/AsinSubscribe` |
| `/api/v2/monitoring/asin/list` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/AsinSubscriptions` |
| `/api/v2/monitoring/asin/data` | GET | Sorftime | `POST /api/sorftime/forward` → `/api/AsinMonitorData` |

### 5.8 卖家信息 (Sellers)

| 统一接口 | 方法 | 原始平台 | 原始接口 |
|---------|------|---------|---------|
| `/api/v2/sellers/account` | GET | Amazon | `GET /api/amazon/sellers/marketplaceParticipations` |
| `/api/v2/sellers/marketplaces` | GET | Amazon | `GET /api/amazon/sellers/marketplaceParticipations` |