# Sorftime API 前端调用指南

## 概述

Sorftime 模块通过统一的 **转发代理** 模式工作。前端所有请求都发送到同一个端点 `/api/sorftime/forward`，由服务端代理转发到 Sorftime 官方 API。

## 基础信息

- **请求地址**: `https://partyvoc.com/api/sorftime/forward`
- **请求方法**: `POST`
- **Content-Type**: `application/json`
- **认证**: 服务端已内置 Token，前端无需传递

## 请求格式

```json
{
  "path": "/api/接口名称",
  "method": "POST",
  "query": { "domain": 1 },
  "body": { /* Sorftime 官方 API 的请求参数 */ },
  "function": "清洗函数名（可选）"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| path | string | ✅ | Sorftime 官方 API 路径，如 `/api/ProductQuery` |
| method | string | 否 | HTTP 方法，默认 `POST` |
| query | object | 否 | URL 查询参数，`domain` 放这里 |
| body | object | 否 | 请求体参数，透传给 Sorftime 官方 API |
| function | string | 否 | 服务端数据清洗函数名 |

## domain 参数说明

`domain` 放在 `query` 中，表示亚马逊站点：

| domain | 站点 |
|--------|------|
| 1 | 美国 (amazon.com) |
| 2 | 英国 (amazon.co.uk) |
| 3 | 德国 (amazon.de) |
| 4 | 法国 (amazon.fr) |
| 5 | 日本 (amazon.co.jp) |
| 6 | 加拿大 (amazon.ca) |

---

## 前端调用示例

### 1. 商品评论采集（ProductReviewsCollection）

```javascript
fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/ProductReviewsCollection",
    method: "POST",
    query: { domain: 1 },
    body: {
      ASIN: "B0GMQCC7PF",
      Mode: 1,
      Star: "1,2,3,4,5",
      OnlyPurchase: 1,
      Page: 10
    },
    function: "collectProductReviews"
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

### 2. 商品搜索（ProductQuery）

```javascript
fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/ProductQuery",
    method: "POST",
    query: { domain: 1 },
    body: {
      Page: 1,
      Query: "1",
      QueryType: "3",
      pattern: "anker"
    }
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

### 3. 获取分类树（CategoryTree）

```javascript
fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/CategoryTree",
    method: "POST",
    query: { domain: 1 },
    body: {},
    function: "cleanCategoryTree"  // 触发服务端清洗，存入 AmazonCategory 表
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

### 4. ASIN 销量查询（AsinSalesVolume）

```javascript
fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/AsinSalesVolume",
    method: "POST",
    query: { domain: 1 },
    body: {
      ASIN: "B0GMQCC7PF"
    }
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

### 5. 关键词查询（KeywordQuery）

```javascript
fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/KeywordQuery",
    method: "POST",
    query: { domain: 1 },
    body: {
      keyword: "phone case"
    }
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

### 6. ASIN 关键词排名（ASINKeywordRanking）

```javascript
fetch('https://partyvoc.com/api/sorftime/forward', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: "/api/ASINKeywordRanking",
    method: "POST",
    query: { domain: 1 },
    body: {
      ASIN: "B0GMQCC7PF"
    }
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

---

## 可用接口完整列表

### 分类相关

| path | 说明 | 数据清洗函数 |
|------|------|-------------|
| `/api/CategoryTree` | 获取分类树 | `cleanCategoryTree` |
| `/api/CategoryRequest` | 分类请求 | - |
| `/api/CategoryProducts` | 分类下的商品 | - |

### 商品相关

| path | 说明 | 数据清洗函数 |
|------|------|-------------|
| `/api/ProductRequest` | 商品数据请求（含产品趋势） | - |
| `/api/ProductQuery` | 商品搜索 | - |
| `/api/AsinSalesVolume` | ASIN 销量数据 | - |
| `/api/ProductVariationHistory` | 商品变体历史 | - |
| `/api/ProductReviewsCollection` | 商品评论采集 | `collectProductReviews` |
| `/api/ProductReviewsCollectionStatusQuery` | 评论采集状态查询 | - |
| `/api/ProductReviewsQuery` | 商品评论查询 | - |
| `/api/SimilarProductRealtimeRequest` | 相似商品实时请求 | - |
| `/api/SimilarProductRealtimeRequestStatusQuery` | 相似商品请求状态 | - |
| `/api/SimilarProductRealtimeRequestCollection` | 相似商品采集 | - |

### 关键词相关

| path | 说明 |
|------|------|
| `/api/KeywordQuery` | 关键词查询 |
| `/api/KeywordSearchResults` | 关键词搜索结果 |
| `/api/KeywordRequest` | 关键词请求 |
| `/api/KeywordSearchResultTrend` | 关键词搜索趋势 |
| `/api/CategoryRequestKeyword` | 分类关键词请求 |
| `/api/ASINRequestKeyword` | ASIN 关键词请求 |
| `/api/KeywordProductRanking` | 关键词商品排名 |
| `/api/ASINKeywordRanking` | ASIN 关键词排名 |
| `/api/KeywordBatchSubscription` | 关键词批量订阅 |
| `/api/KeywordTasks` | 关键词任务列表 |
| `/api/KeywordBatchTaskUpdate` | 关键词批量任务更新 |
| `/api/KeywordBatchScheduleList` | 关键词批量计划列表 |
| `/api/KeywordBatchScheduleDetail` | 关键词批量计划详情 |

### 榜单与卖家相关

| path | 说明 |
|------|------|
| `/api/BestSellerListSubscription` | 畅销榜订阅 |
| `/api/BestSellerListTask` | 畅销榜任务 |
| `/api/BestSellerListDelete` | 畅销榜删除 |
| `/api/BestSellerListDataCollect` | 畅销榜数据采集 |
| `/api/ProductSellerTasks` | 商品卖家任务 |
| `/api/ProductSellerTaskUpdate` | 卖家任务更新 |
| `/api/ProductSellerTaskScheduleList` | 卖家任务计划列表 |
| `/api/ProductSellerTaskScheduleDetail` | 卖家任务计划详情 |
| `/api/ASINSubscription` | ASIN 订阅 |
| `/api/ASINSubscriptionQuery` | ASIN 订阅查询 |
| `/api/ASINSubscriptionCollection` | ASIN 订阅采集 |

---

## ProductQuery 的 QueryType 说明

| QueryType | 说明 |
|-----------|------|
| 1 | 基于 ASIN 查询同类产品（需先调 ProductRequest） |
| 2 | 基于类目（nodeId）查询 |
| 3 | 查询品牌旗下热销产品（如 AnkerDirect） |
| 4 | 查看亚马逊各榜单热销产品 |
| 5 | 查看卖家 Collection 旗下热销产品 |
| 6 | 基于 ABA 关键词查热销产品（仅支持 ABA 关键词） |
| 7 | 基于产品标题或属性包含词查产品 |
| 8 | 限定售价范围查产品（单位为最小单位，如美国站为分） |
| 10 | 限定查询季节性产品 |
| 11 | 限定上架时间范围查产品（日期格式 yyyy-MM-dd） |
| 12 | 限定星级范围查产品 |
| 13 | 限定评论数范围查产品 |
| 14 | 限定发货方式查产品 |

---

## 数据清洗函数

### cleanCategoryTree

用于 `/api/CategoryTree`，自动将分类数据清洗后存入 Parse Server 的 `AmazonCategory` 表。

存储字段映射：

| AmazonCategory 字段 | 来源 | 说明 |
|---------------------|------|------|
| categoryId | Id | 分类 ID |
| domain | query.domain | 站点 |
| parentId | ParentId | 父分类 ID |
| nodeId | NodeId | 节点 ID |
| name | Name | 英文名称 |
| cnName | CNName | 中文名称 |
| url | URL | 分类链接 |
| dataUpdatedAt | 自动 | 更新时间 |

### collectProductReviews

用于 `/api/ProductReviewsCollection`，采集商品评论数据。

---

## 响应格式

Sorftime 官方 API 返回数据直接透传，常见响应结构：

```json
// 成功
{
  "Code": 200,
  "Message": "success",
  "Data": { /* 具体数据 */ }
}

// 积分不足
{
  "Code": 4,
  "Message": "积分余额不足"
}
```

## 注意事项

1. 所有接口统一通过 `POST /api/sorftime/forward` 转发
2. `domain` 参数放在 `query` 中，不是 `body` 中
3. `function` 字段用于触发服务端数据清洗（注意不是 `functionName`）
4. 服务端内置重试机制（3 次，间隔 1 秒），5xx 错误自动重试
5. 请求超时 30 秒
6. 当前账户积分余额不足时会返回 `{Code: 4, Message: "积分余额不足"}`