同步前端调用文档

docs/api/front/api-examples.md

@@ -0,0 +1,853 @@
+# 前端 API 调用示例文档
+
+## 目录
+
+- [1. 概述](#1-概述)
+- [2. 通用说明](#2-通用说明)
+  - [2.1 基础 URL](#21-基础-url)
+  - [2.2 认证方式](#22-认证方式)
+  - [2.3 响应格式](#23-响应格式)
+  - [2.4 通用请求工具封装](#24-通用请求工具封装)
+  - [2.5 错误处理](#25-错误处理)
+- [3. Amazon SP-API](#3-amazon-sp-api)
+  - [3.1 测试接口](#31-测试接口)
+  - [3.2 客户反馈 (Customer Feedback)](#32-客户反馈-customer-feedback)
+  - [3.3 订单 (Orders) ⭐](#33-订单-orders-)
+  - [3.4 销售 (Sales) ⭐](#34-销售-sales-)
+  - [3.5 商品列表 (Listings) ⭐](#35-商品列表-listings-)
+  - [3.6 外部履约 (External Fulfillment)](#36-外部履约-external-fulfillment)
+  - [3.7 目录 (Catalog Items) ⭐](#37-目录-catalog-items-)
+  - [3.8 卖家 (Sellers)](#38-卖家-sellers)
+  - [3.9 通用转发 (Forward)](#39-通用转发-forward)
+- [4. Sorftime API](#4-sorftime-api)
+  - [4.1 测试与健康检查](#41-测试与健康检查)
+  - [4.2 通用转发 (Forward) ⭐](#42-通用转发-forward-)
+- [5. TikHub API](#5-tikhub-api)
+  - [5.1 健康检查](#51-健康检查)
+  - [5.2 通用转发 (Forward)](#52-通用转发-forward)
+  - [5.3 用户相关接口 ⭐](#53-用户相关接口-)
+  - [5.4 视频相关接口 ⭐](#54-视频相关接口-)
+  - [5.5 数据分析接口](#55-数据分析接口)
+  - [5.6 电商接口](#56-电商接口)
+  - [5.7 广告接口](#57-广告接口)
+- [6. 附录：常见错误码](#6-附录常见错误码)
+
+---
+
+## 1. 概述
+
+本项目后端提供三个平台的 API 代理服务，统一挂载在 `/api/` 路径下：
+
+| 平台 | 路径前缀 | 说明 |
+|------|----------|------|
+| Amazon SP-API | `/api/amazon/` | 亚马逊卖家平台 API，涵盖订单、商品、销售、目录等模块 |
+| Sorftime API | `/api/sorftime/` | Sorftime 数据分析平台，提供类目、产品、关键词、监控等功能 |
+| TikHub API | `/api/tikhub/` | TikTok 数据平台，提供用户、视频、电商、广告等数据查询 |
+
+> ⭐ 标记表示常用接口，建议优先了解。
+
+---
+
+## 2. 通用说明
+
+### 2.1 基础 URL
+
+```
+https://server-msq.fmode.cn
+```
+
+> 本地开发环境可使用 `http://localhost:10003`，生产环境统一使用 HTTPS 域名。
+
+### 2.2 认证方式
+
+| 平台 | 认证 Header | 必填 | 说明 |
+|------|-------------|------|------|
+| Amazon SP-API | `shop-objectId` | ✅ | Parse 数据库中 Shop 对象的 ObjectId，后端通过它查询店铺的 SP-API 凭证 |
+| Sorftime API | 无需额外认证 | — | 后端已内置 API Token |
+| TikHub API | 无需额外认证 | — | 后端已内置 API Key |
+
+### 2.3 响应格式
+
+所有接口统一返回 JSON 格式，通用结构如下：
+
+```typescript
+interface ApiResponse<T = any> {
+  success: boolean;   // 是否成功
+  data: T;            // 业务数据
+  timestamp: string;  // 时间戳
+}
+```
+
+### 2.4 通用请求工具封装
+
+建议在项目中封装统一的请求工具，以下为 axios 封装示例：
+
+```typescript
+import axios, { AxiosInstance } from 'axios';
+
+const BASE_URL = 'https://server-msq.fmode.cn';
+
+// Amazon 请求实例
+export const amazonClient: AxiosInstance = axios.create({
+  baseURL: `${BASE_URL}/api/amazon`,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+// 设置店铺 ObjectId（Parse 数据库中 Shop 对象的 ObjectId）
+export function setShopObjectId(shopObjectId: string): void {
+  amazonClient.defaults.headers.common['shop-objectId'] = shopObjectId;
+}
+
+// Sorftime 请求实例（后端已内置 Token，无需前端传入）
+export const sorftimeClient: AxiosInstance = axios.create({
+  baseURL: `${BASE_URL}/api/sorftime`,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+// TikHub 请求实例（后端已内置 API Key，无需前端传入）
+export const tikhubClient: AxiosInstance = axios.create({
+  baseURL: `${BASE_URL}/api/tikhub`,
+  headers: { 'Content-Type': 'application/json' },
+});
+```
+
+### 2.5 错误处理
+
+#### axios 错误处理示例（拦截器）
+
+```typescript
+amazonClient.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response) {
+      const status = error.response.status;
+      switch (status) {
+        case 400: console.error('请求参数错误'); break;
+        case 401: console.error('认证失败，请检查 shop-objectId'); break;
+        case 403: console.error('权限不足'); break;
+        case 429: console.error('请求过于频繁，请稍后重试'); break;
+        case 500: console.error('服务器内部错误'); break;
+      }
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+---
+
+## 3. Amazon SP-API
+
+> 所有 Amazon 接口均需在请求头中携带 `shop-objectId`（Parse 数据库中 Shop 对象的 ObjectId）。
+> 测试接口 `/test` 除外，无需认证。
+
+### 3.1 测试接口
+
+#### `GET /api/amazon/test`
+
+```typescript
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/amazon/test');
+const data = await res.json();
+
+// axios
+const { data } = await amazonClient.get('/test');
+```
+
+**响应示例：**
+```json
+{
+  "success": true,
+  "data": { "message": "SP-API 路由测试成功" },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+### 3.2 客户反馈 (Customer Feedback)
+
+#### `GET /api/amazon/customerFeedback/items/:asin/reviews/topics` — 商品评论主题
+
+```typescript
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/amazon/customerFeedback/items/B0EXAMPLE1/reviews/topics', {
+  headers: { 'shop-objectId': 'your-shop-object-id' }
+});
+
+// axios
+const { data } = await amazonClient.get('/customerFeedback/items/B0EXAMPLE1/reviews/topics');
+```
+
+#### `GET /api/amazon/customerFeedback/items/:asin/browseNode` — 商品浏览节点
+
+```typescript
+const { data } = await amazonClient.get('/customerFeedback/items/B0EXAMPLE1/browseNode');
+```
+
+#### `GET /api/amazon/customerFeedback/browseNodes/:browseNodeId/reviews/topics` — 浏览节点评论主题
+
+```typescript
+const { data } = await amazonClient.get('/customerFeedback/browseNodes/12345/reviews/topics');
+```
+
+#### `GET /api/amazon/customerFeedback/items/:asin/reviews/trends` — 商品评论趋势
+
+```typescript
+const { data } = await amazonClient.get('/customerFeedback/items/B0EXAMPLE1/reviews/trends');
+```
+
+#### `GET /api/amazon/customerFeedback/browseNodes/:browseNodeId/reviews/trends` — 浏览节点评论趋势
+
+```typescript
+const { data } = await amazonClient.get('/customerFeedback/browseNodes/12345/reviews/trends');
+```
+
+#### `GET /api/amazon/customerFeedback/browseNodes/:browseNodeId/returns/topics` — 浏览节点退货主题
+
+```typescript
+const { data } = await amazonClient.get('/customerFeedback/browseNodes/12345/returns/topics');
+```
+
+#### `GET /api/amazon/customerFeedback/browseNodes/:browseNodeId/returns/trends` — 浏览节点退货趋势
+
+```typescript
+const { data } = await amazonClient.get('/customerFeedback/browseNodes/12345/returns/trends');
+```
+
+---
+
+### 3.3 订单 (Orders) ⭐
+
+#### `GET /api/amazon/orders` — 获取订单列表
+
+```typescript
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/amazon/orders?MarketplaceIds=ATVPDKIKX0DER&CreatedAfter=2025-01-01T00:00:00Z', {
+  headers: { 'shop-objectId': 'your-shop-object-id' }
+});
+
+// axios
+const { data } = await amazonClient.get('/orders', {
+  params: {
+    MarketplaceIds: 'ATVPDKIKX0DER',
+    CreatedAfter: '2025-01-01T00:00:00Z',
+    CreatedBefore: '2025-01-31T23:59:59Z',
+    OrderStatuses: 'Shipped'
+  }
+});
+```
+
+#### `GET /api/amazon/orders/:orderId` — 获取订单详情
+
+```typescript
+const { data } = await amazonClient.get('/orders/111-1234567-1234567');
+```
+
+#### `GET /api/amazon/orders/:orderId/items` — 获取订单商品明细
+
+```typescript
+const { data } = await amazonClient.get('/orders/111-1234567-1234567/items', {
+  params: { NextToken: 'optional-pagination-token' }
+});
+```
+
+---
+
+### 3.4 销售 (Sales) ⭐
+
+#### `GET /api/amazon/sales/orderMetrics` — 获取销售指标
+
+```typescript
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/amazon/sales/orderMetrics?marketplaceIds=ATVPDKIKX0DER&interval=2025-01-01T00:00:00Z--2025-01-31T23:59:59Z&granularity=Day', {
+  headers: { 'shop-objectId': 'your-shop-object-id' }
+});
+
+// axios
+const { data } = await amazonClient.get('/sales/orderMetrics', {
+  params: {
+    marketplaceIds: 'ATVPDKIKX0DER',
+    interval: '2025-01-01T00:00:00Z--2025-01-31T23:59:59Z',
+    granularity: 'Day'
+  }
+});
+```
+
+---
+
+### 3.5 商品列表 (Listings) ⭐
+
+#### `GET /api/amazon/listings/items/:sellerId` — 搜索卖家 Listing 列表
+
+```typescript
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/amazon/listings/items/A1EXAMPLE?marketplaceIds=ATVPDKIKX0DER', {
+  headers: { 'shop-objectId': 'your-shop-object-id' }
+});
+
+// axios
+const { data } = await amazonClient.get('/listings/items/A1EXAMPLE', {
+  params: {
+    marketplaceIds: 'ATVPDKIKX0DER',
+    pageSize: 20
+  }
+});
+```
+
+#### `GET /api/amazon/listings/items/:sellerId/:sku` — 获取单个 Listing 详情
+
+```typescript
+const { data } = await amazonClient.get('/listings/items/A1EXAMPLE/WH-BT-001', {
+  params: { marketplaceIds: 'ATVPDKIKX0DER' }
+});
+```
+
+#### `PUT /api/amazon/listings/items/:sellerId/:sku` — 更新 Listing
+
+```typescript
+const { data } = await amazonClient.put('/listings/items/A1EXAMPLE/WH-BT-001', {
+  productType: 'HEADPHONES',
+  attributes: {
+    item_name: [{ value: 'Updated Product Title' }]
+  }
+}, {
+  params: { marketplaceIds: 'ATVPDKIKX0DER' }
+});
+```
+
+#### `DELETE /api/amazon/listings/items/:sellerId/:sku` — 删除 Listing
+
+```typescript
+const { data } = await amazonClient.delete('/listings/items/A1EXAMPLE/WH-BT-001', {
+  params: { marketplaceIds: 'ATVPDKIKX0DER' }
+});
+```
+
+---
+
+### 3.6 外部履约 (External Fulfillment)
+
+#### `GET /api/amazon/externalFulfillment/returns` — 获取退货列表
+
+```typescript
+const { data } = await amazonClient.get('/externalFulfillment/returns', {
+  params: {
+    MarketplaceId: 'ATVPDKIKX0DER',
+    Status: 'Open'
+  }
+});
+```
+
+#### `GET /api/amazon/externalFulfillment/returns/:returnId` — 获取退货详情
+
+```typescript
+const { data } = await amazonClient.get('/externalFulfillment/returns/RET-12345');
+```
+
+---
+
+### 3.7 目录 (Catalog Items) ⭐
+
+#### `GET /api/amazon/catalog/categories` — 获取目录分类
+
+```typescript
+const { data } = await amazonClient.get('/catalog/categories', {
+  params: {
+    MarketplaceId: 'ATVPDKIKX0DER',
+    ASIN: 'B0EXAMPLE1'
+  }
+});
+```
+
+#### `GET /api/amazon/catalog/items` — 搜索目录商品
+
+```typescript
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/amazon/catalog/items?keywords=wireless+earbuds&marketplaceIds=ATVPDKIKX0DER', {
+  headers: { 'shop-objectId': 'your-shop-object-id' }
+});
+
+// axios
+const { data } = await amazonClient.get('/catalog/items', {
+  params: {
+    keywords: 'wireless earbuds',
+    marketplaceIds: 'ATVPDKIKX0DER',
+    includedData: 'summaries,images,salesRanks'
+  }
+});
+```
+
+#### `GET /api/amazon/catalog/items/:asin` — 获取商品详情
+
+```typescript
+const { data } = await amazonClient.get('/catalog/items/B0EXAMPLE1', {
+  params: {
+    marketplaceIds: 'ATVPDKIKX0DER',
+    includedData: 'summaries,images,salesRanks,dimensions,relationships'
+  }
+});
+```
+
+---
+
+### 3.8 卖家 (Sellers)
+
+#### `GET /api/amazon/sellers/account` — 获取卖家账户信息
+
+```typescript
+const { data } = await amazonClient.get('/sellers/account');
+```
+
+#### `GET /api/amazon/sellers/marketplaceParticipations` — 获取市场参与信息
+
+```typescript
+const { data } = await amazonClient.get('/sellers/marketplaceParticipations');
+```
+
+---
+
+### 3.9 通用转发 (Forward)
+
+通用转发接口可以调用任意亚马逊 SP-API 端点，适用于上述封装接口未覆盖的场景。支持 `functionId` 参数触发 Parse 云函数对返回数据做后处理。
+
+#### `POST /api/amazon/forward`
+
+**请求参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| path | string | ✅ | SP-API 路径，如 `/orders/v0/orders` |
+| method | string | 否 | HTTP 方法，默认 `GET` |
+| query | object | 否 | 查询参数 |
+| body | object | 否 | 请求体 |
+| functionName | string | 否 | 自定义转换函数名 |
+| functionId | string | 否 | Parse 云函数 ID，提供后会执行云函数处理返回数据 |
+
+```typescript
+// 基本用法 — 获取订单
+const { data } = await amazonClient.post('/forward', {
+  path: '/orders/v0/orders',
+  method: 'GET',
+  query: {
+    MarketplaceIds: 'ATVPDKIKX0DER',
+    CreatedAfter: '2025-01-01T00:00:00Z'
+  }
+});
+
+// 带云函数后处理 — 获取订单并执行云函数清洗数据
+const { data: processed } = await amazonClient.post('/forward', {
+  path: '/orders/v0/orders',
+  method: 'GET',
+  query: { MarketplaceIds: 'ATVPDKIKX0DER' },
+  functionId: 'RFDDkJ2usG'
+});
+// 响应包含 { apiResult: {...}, cloudFunctionResult: {...} }
+```
+
+**Angular HttpClient 调用示例：**
+
+```typescript
+// Angular 中的典型调用方式
+this.http.post('https://server-msq.fmode.cn/api/amazon/forward', {
+  path: '/orders/v0/orders/${orderId}',
+  functionId: 'RFDDkJ2usG'
+}, {
+  headers: { 'shop-objectId': this.shopId }
+}).subscribe(res => {
+  console.log(res);
+});
+```
+
+**带 functionId 的响应示例：**
+```json
+{
+  "success": true,
+  "data": {
+    "apiResult": { "...亚马逊原始返回..." },
+    "cloudFunctionResult": { "...云函数处理后的数据..." }
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+## 4. Sorftime API
+
+> Sorftime 的 API Token 已在后端配置，前端无需传入认证信息。
+> 所有 Sorftime 数据查询通过 `/api/sorftime/forward` 转发接口完成。
+
+### 4.1 测试与健康检查
+
+#### `GET /api/sorftime/test` — 测试接口
+
+```typescript
+const res = await fetch('https://server-msq.fmode.cn/api/sorftime/test');
+const data = await res.json();
+// { "message": "Sorftime API Router Loaded Successfully v0.0.1" }
+```
+
+#### `GET /api/sorftime/health` — 健康检查
+
+```typescript
+const res = await fetch('https://server-msq.fmode.cn/api/sorftime/health');
+const data = await res.json();
+// { "service": "sorftime", "timestamp": "2025-01-01T12:00:00.000Z" }
+```
+
+---
+
+### 4.2 通用转发 (Forward) ⭐
+
+Sorftime 所有数据查询均通过 forward 接口转发。支持 `functionId` 参数触发 Parse 云函数做后处理。
+
+#### `POST /api/sorftime/forward`
+
+**请求参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| path | string | ✅ | Sorftime API 路径，如 `/api/CategoryTree` |
+| method | string | 否 | HTTP 方法，默认 `POST` |
+| query | object | 否 | 查询参数 |
+| body | object | 否 | 请求体 |
+| function | string | 否 | 自定义转换函数名 |
+| functionId | string | 否 | Parse 云函数 ID |
+
+#### 示例：查询类目树
+
+```typescript
+// axios
+const { data } = await sorftimeClient.post('/forward', {
+  path: '/api/CategoryTree',
+  body: { domain: 'amazon.com' }
+});
+
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/sorftime/forward', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    path: '/api/CategoryTree',
+    body: { domain: 'amazon.com' }
+  })
+});
+```
+
+#### 示例：查询产品数据
+
+```typescript
+const { data } = await sorftimeClient.post('/forward', {
+  path: '/api/ProductQuery',
+  body: {
+    domain: 'amazon.com',
+    keyword: 'wireless earbuds',
+    page: 1,
+    pageSize: 20
+  }
+});
+```
+
+#### 示例：查询产品详情
+
+```typescript
+const { data } = await sorftimeClient.post('/forward', {
+  path: '/api/ProductRequest',
+  body: {
+    domain: 'amazon.com',
+    asin: 'B0EXAMPLE1'
+  }
+});
+```
+
+#### 示例：关键词查询
+
+```typescript
+const { data } = await sorftimeClient.post('/forward', {
+  path: '/api/KeywordQuery',
+  body: {
+    domain: 'amazon.com',
+    keyword: 'wireless earbuds'
+  }
+});
+```
+
+#### 示例：ASIN 反查关键词
+
+```typescript
+const { data } = await sorftimeClient.post('/forward', {
+  path: '/api/ASINRequestKeyword',
+  body: {
+    domain: 'amazon.com',
+    asin: 'B0EXAMPLE1'
+  }
+});
+```
+
+#### 示例：监控数据查询
+
+```typescript
+const { data } = await sorftimeClient.post('/forward', {
+  path: '/api/MonitorQuery',
+  body: {
+    domain: 'amazon.com',
+    asin: 'B0EXAMPLE1'
+  }
+});
+```
+
+#### 示例：带云函数后处理
+
+```typescript
+const { data } = await sorftimeClient.post('/forward', {
+  path: '/api/ProductQuery',
+  body: { domain: 'amazon.com', keyword: 'earbuds' },
+  functionId: 'cloudFuncId123'
+});
+```
+
+**Angular HttpClient 调用示例：**
+
+```typescript
+this.http.post('https://server-msq.fmode.cn/api/sorftime/forward', {
+  path: '/api/ProductQuery',
+  body: { domain: 'amazon.com', keyword: 'earbuds' }
+}).subscribe(res => {
+  console.log(res);
+});
+```
+
+---
+
+## 5. TikHub API
+
+> TikHub 的 API Key 已在后端配置，前端无需传入认证信息。
+
+### 5.1 健康检查
+
+#### `GET /api/tikhub/health`
+
+```typescript
+const res = await fetch('https://server-msq.fmode.cn/api/tikhub/health');
+const data = await res.json();
+// { "service": "tikhub", "timestamp": "2025-01-01T12:00:00.000Z" }
+```
+
+---
+
+### 5.2 通用转发 (Forward)
+
+通用转发接口可以调用任意 TikHub API 端点。支持 `functionId` 参数触发 Parse 云函数做后处理。
+
+#### `POST /api/tikhub/forward`
+
+**请求参数：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| path | string | ✅ | TikHub API 路径，如 `/api/v1/tiktok/web/fetch_user_profile` |
+| method | string | 否 | HTTP 方法，默认 `GET` |
+| query | object | 否 | 查询参数 |
+| body | object | 否 | 请求体 |
+| headers | object | 否 | 额外请求头 |
+| functionId | string | 否 | Parse 云函数 ID |
+
+```typescript
+// axios
+const { data } = await tikhubClient.post('/forward', {
+  path: '/api/v1/tiktok/web/fetch_user_profile',
+  method: 'GET',
+  query: { unique_id: 'example_user' }
+});
+
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/tikhub/forward', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    path: '/api/v1/tiktok/web/fetch_user_profile',
+    method: 'GET',
+    query: { unique_id: 'example_user' }
+  })
+});
+```
+
+---
+
+### 5.3 用户相关接口 ⭐
+
+#### `GET /api/tikhub/tiktok/web/user-profile` — 获取用户资料
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| unique_id | string | ✅ | TikTok 用户名 |
+
+```typescript
+// axios
+const { data } = await tikhubClient.get('/tiktok/web/user-profile', {
+  params: { unique_id: 'example_user' }
+});
+
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/tikhub/tiktok/web/user-profile?unique_id=example_user');
+```
+
+#### `GET /api/tikhub/tiktok/web/sec-user-id` — 通过链接获取 sec_user_id
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| url | string | ✅ | TikTok 用户主页链接 |
+
+```typescript
+const { data } = await tikhubClient.get('/tiktok/web/sec-user-id', {
+  params: { url: 'https://www.tiktok.com/@example_user' }
+});
+```
+
+#### `GET /api/tikhub/tiktok/app/v3/user-followers` — 获取用户粉丝列表
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| user_id | string | ✅ | 用户 ID |
+| offset | number | 否 | 偏移量 |
+| count | number | 否 | 每页数量 |
+
+```typescript
+const { data } = await tikhubClient.get('/tiktok/app/v3/user-followers', {
+  params: { user_id: '6789012345', offset: 0, count: 20 }
+});
+```
+
+#### `GET /api/tikhub/tiktok/app/v3/user-following` — 获取用户关注列表
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| user_id | string | ✅ | 用户 ID |
+| offset | number | 否 | 偏移量 |
+| count | number | 否 | 每页数量 |
+
+```typescript
+const { data } = await tikhubClient.get('/tiktok/app/v3/user-following', {
+  params: { user_id: '6789012345', offset: 0, count: 20 }
+});
+```
+
+---
+
+### 5.4 视频相关接口 ⭐
+
+#### `GET /api/tikhub/tiktok/app/v3/video` — 获取单个视频详情
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| aweme_id | string | ✅ | 视频 ID |
+
+```typescript
+// axios
+const { data } = await tikhubClient.get('/tiktok/app/v3/video', {
+  params: { aweme_id: '7123456789012345678' }
+});
+
+// fetch
+const res = await fetch('https://server-msq.fmode.cn/api/tikhub/tiktok/app/v3/video?aweme_id=7123456789012345678');
+```
+
+#### `GET /api/tikhub/tiktok/app/v3/user-repost-videos` — 获取用户转发视频
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| user_id | string | ✅ | 用户 ID |
+| offset | number | 否 | 偏移量 |
+| count | number | 否 | 每页数量 |
+
+```typescript
+const { data } = await tikhubClient.get('/tiktok/app/v3/user-repost-videos', {
+  params: { user_id: '6789012345', offset: 0, count: 20 }
+});
+```
+
+#### `GET /api/tikhub/tiktok/app/v3/video-comments` — 获取视频评论
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| aweme_id | string | ✅ | 视频 ID |
+| cursor | number | 否 | 分页游标 |
+| count | number | 否 | 每页数量 |
+
+```typescript
+const { data } = await tikhubClient.get('/tiktok/app/v3/video-comments', {
+  params: { aweme_id: '7123456789012345678', cursor: 0, count: 20 }
+});
+```
+
+---
+
+### 5.5 数据分析接口
+
+#### `GET /api/tikhub/tiktok/analytics/video-metrics` — 视频数据指标
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| video_id | string | ✅ | 视频 ID |
+
+```typescript
+const { data } = await tikhubClient.get('/tiktok/analytics/video-metrics', {
+  params: { video_id: '7123456789012345678' }
+});
+```
+
+#### `POST /api/tikhub/tiktok/creator/account-insights` — 创作者账户洞察
+
+```typescript
+const { data } = await tikhubClient.post('/tiktok/creator/account-insights', {
+  // 请求体参数根据 TikHub API 文档填写
+  start_date: '2025-01-01',
+  end_date: '2025-01-31'
+});
+```
+
+---
+
+### 5.6 电商接口
+
+#### `GET /api/tikhub/tiktok/shop/product-detail` — TikTok 商品详情
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| product_id | string | ✅ | 商品 ID |
+
+```typescript
+const { data } = await tikhubClient.get('/tiktok/shop/product-detail', {
+  params: { product_id: '1234567890' }
+});
+```
+
+---
+
+### 5.7 广告接口
+
+#### `GET /api/tikhub/tiktok/ads/ads-detail` — 广告详情
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| ad_id | string | ✅ | 广告 ID |
+
+```typescript
+const { data } = await tikhubClient.get('/tiktok/ads/ads-detail', {
+  params: { ad_id: 'AD12345' }
+});
+```
+
+---
+
+## 6. 附录：常见错误码
+
+| HTTP 状态码 | 说明 | 处理建议 |
+|------------|------|----------|
+| 400 | 请求参数错误 | 检查必填参数是否缺失、参数格式是否正确 |
+| 401 | 认证失败 | Amazon 接口：检查 `shop-objectId` 是否正确；其他平台：联系后端检查 Token 配置 |
+| 403 | 权限不足 | 检查店铺是否有对应 API 权限 |
+| 404 | 资源不存在 | 检查请求路径和参数 ID 是否正确 |
+| 429 | 请求频率超限 | 降低请求频率，建议添加请求节流/防抖 |
+| 500 | 服务器内部错误 | 联系后端排查，可能是上游 API 异常 |
+| 502 | 上游服务错误 | 第三方平台 API 返回异常，稍后重试 |
+| 503 | 服务不可用 | 服务维护中，稍后重试 |

docs/api/front/data-api.md

@@ -0,0 +1,2573 @@
+# 数据清洗统一接口文档
+
+> 版本：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` |

docs/api/front/data-cleaning-api.md

@@ -0,0 +1,3500 @@
+# 数据清洗统一接口设计文档
+
+> 版本：v1.0.0  
+> 更新日期：2025-01-01  
+> 基础URL：`https://server-msq.fmode.cn`  
+> 接口前缀：`/api/clean/`
+
+---
+
+## 目录
+
+- [1. 概述](#1-概述)
+- [2. 设计原则](#2-设计原则)
+- [3. 统一响应格式](#3-统一响应格式)
+- [4. 统一分页格式](#4-统一分页格式)
+- [5. 错误码定义](#5-错误码定义)
+- [6. 接口详细定义](#6-接口详细定义)
+  - [6.1 产品相关（跨平台）](#61-产品相关跨平台)
+  - [6.2 订单相关（Amazon）](#62-订单相关amazon)
+  - [6.3 商品管理（Amazon Listings）](#63-商品管理amazon-listings)
+  - [6.4 类目相关（Sorftime）](#64-类目相关sorftime)
+  - [6.5 关键词相关（Sorftime）](#65-关键词相关sorftime)
+  - [6.6 监控相关（Sorftime）](#66-监控相关sorftime)
+  - [6.7 TikTok 社交媒体（TikHub）](#67-tiktok-社交媒体tikhub)
+  - [6.8 卖家信息（Amazon）](#68-卖家信息amazon)
+  - [6.9 退货相关（Amazon）](#69-退货相关amazon)
+- [7. 前端调用示例](#7-前端调用示例)
+- [附录：数据来源映射总表](#附录数据来源映射总表)
+
+---
+
+## 1. 概述
+
+本项目对接三个平台的 API：
+
+| 平台 | 模块路径 | 原始接口前缀 | 说明 |
+|------|---------|-------------|------|
+| Amazon SP-API | `modules/fmode-amazon-sp-api` | `/api/amazon/` | 订单、商品、目录、销售、卖家、退货等 |
+| Sorftime | `modules/fmode-sorftime-api` | `/api/sorftime/` | 产品分析、类目、关键词、监控等 |
+| TikHub | `modules/fmode-tikhub-api` | `/api/tikhub/` | TikTok 用户、视频、商品、广告等 |
+
+各平台返回的数据格式不统一，字段命名风格各异（PascalCase / snake_case / camelCase 混用），前端对接困难。本文档设计一套数据清洗后的统一接口，挂载在 `/api/clean/` 下，便于前端直接使用。
+
+---
+
+## 2. 设计原则
+
+1. **统一响应格式**：所有接口返回 `{ code, message, data, timestamp }` 结构
+2. **跨平台数据标准化**：相同概念的数据（产品、订单、关键词）使用统一字段命名
+3. **分页统一**：列表接口统一使用 `{ items, total, page, pageSize, hasMore }` 结构
+4. **前端友好**：字段命名统一使用 `camelCase`，时间统一为 ISO 8601 格式
+5. **数据来源透明**：每条数据携带 `_source` 字段标识来源平台
+6. **向下兼容**：清洗层不修改原始 API 逻辑，仅做格式转换和聚合
+
+---
+
+## 3. 统一响应格式
+
+```typescript
+/** 统一响应包装 */
+interface ApiResponse<T> {
+  /** 业务状态码，0 表示成功 */
+  code: number;
+  /** 状态描述 */
+  message: string;
+  /** 响应数据 */
+  data: T;
+  /** 响应时间戳 ISO 8601 */
+  timestamp: string;
+}
+```
+
+成功响应示例：
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": { "..." : "..." },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+错误响应示例：
+```json
+{
+  "code": 40001,
+  "message": "缺少必填参数: keyword",
+  "data": null,
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+## 4. 统一分页格式
+
+```typescript
+/** 统一分页响应 */
+interface PaginatedResponse<T> {
+  /** 数据列表 */
+  items: T[];
+  /** 总记录数 */
+  total: number;
+  /** 当前页码（从 1 开始） */
+  page: number;
+  /** 每页条数 */
+  pageSize: number;
+  /** 是否有更多数据 */
+  hasMore: boolean;
+}
+
+/** 统一分页请求参数 */
+interface PaginationParams {
+  /** 页码，默认 1 */
+  page?: number;
+  /** 每页条数，默认 20 */
+  pageSize?: number;
+}
+```
+
+---
+
+## 5. 错误码定义
+
+| 错误码 | 说明 | 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 |
+
+---
+
+## 6. 接口详细定义
+
+### 6.1 产品相关（跨平台）
+
+#### 6.1.1 `GET /api/clean/products/search` — 统一产品搜索
+
+聚合 Amazon Catalog Items 搜索 + Sorftime ProductQuery，返回统一格式的产品列表。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `CatalogItemsApi.searchCatalogItems` | `GET /api/amazon/catalog/items` |
+| Sorftime | `ProductApi.getProductQuery` | `POST /api/sorftime/forward` -> `/api/ProductQuery` |
+
+**请求参数：**
+
+```typescript
+interface ProductSearchParams extends PaginationParams {
+  /** 搜索关键词 */
+  keyword?: string;
+  /** ASIN 列表（逗号分隔） */
+  asins?: string;
+  /** 品牌名称 */
+  brand?: string;
+  /** 类目 ID */
+  categoryId?: string;
+  /** 数据来源：amazon | sorftime | all（默认 all） */
+  source?: 'amazon' | 'sorftime' | 'all';
+  /** 市场域名，如 amazon.com（Sorftime 需要） */
+  domain?: string;
+  /** Amazon MarketplaceId */
+  marketplaceId?: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanProduct {
+  /** 统一产品 ID（ASIN） */
+  id: string;
+  /** 产品标题 */
+  title: string;
+  /** 品牌 */
+  brand: string;
+  /** 主图 URL */
+  imageUrl: string;
+  /** 价格 */
+  price: number | null;
+  /** 货币代码 */
+  currency: string;
+  /** 评分（1-5） */
+  rating: number | null;
+  /** 评论数 */
+  reviewCount: number | null;
+  /** 类目名称 */
+  category: string;
+  /** BSR 排名 */
+  bsrRank: number | null;
+  /** 数据来源平台 */
+  _source: 'amazon' | 'sorftime';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanProduct>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 | Sorftime 原始字段 |
+|-----------|----------------|------------------|
+| `id` | `asin` | `ASIN` |
+| `title` | `summaries[0].itemName` | `Title` |
+| `brand` | `summaries[0].brand` | `Brand` |
+| `imageUrl` | `images[0].images[0].link` | `ImageUrl` |
+| `price` | `summaries[0].price.amount` | `Price` |
+| `currency` | `summaries[0].price.currencyCode` | 根据 `domain` 推断 |
+| `rating` | — | `Rating` |
+| `reviewCount` | — | `Reviews` |
+| `category` | `salesRanks[0].displayGroupRanks[0].title` | `CategoryName` |
+| `bsrRank` | `salesRanks[0].displayGroupRanks[0].rank` | `BSR` |
+| `_source` | `'amazon'` | `'sorftime'` |
+
+---
+
+#### 6.1.2 `GET /api/clean/products/:id` — 统一产品详情
+
+聚合 Amazon CatalogItem 详情 + Sorftime ProductRequest，返回完整产品信息。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `CatalogItemsApi.getCatalogItem` | `GET /api/amazon/catalog/items/:asin` |
+| Sorftime | `ProductApi.getProductRequest` | `POST /api/sorftime/forward` -> `/api/ProductRequest` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = ASIN
+interface ProductDetailParams {
+  source?: 'amazon' | 'sorftime' | 'all';
+  domain?: string;
+  marketplaceId?: string;
+  /** 是否包含趋势数据（Sorftime，默认 false） */
+  includeTrend?: boolean;
+  trendStartDate?: string;
+  trendEndDate?: string;
+}
+
+```
+
+**响应数据：**
+
+```typescript
+interface CleanProductDetail extends CleanProduct {
+  /** 产品描述 */
+  description: string;
+  /** 商品特征/卖点列表 */
+  features: string[];
+  /** 尺寸信息 */
+  dimensions: {
+    length: number | null;
+    width: number | null;
+    height: number | null;
+    weight: number | null;
+    unit: string;
+    weightUnit: string;
+  } | null;
+  /** 变体列表 */
+  variants: Array<{
+    asin: string;
+    title: string;
+    attributes: Record<string, string>;
+  }>;
+  /** 上架时间 */
+  listedAt: string | null;
+  /** 月销量估算（Sorftime） */
+  estimatedMonthlySales: number | null;
+  /** 月收入估算（Sorftime） */
+  estimatedMonthlyRevenue: number | null;
+  /** 卖家数量 */
+  sellerCount: number | null;
+  /** FBA 费用估算 */
+  fbaFee: number | null;
+  /** 趋势数据（需 includeTrend=true） */
+  trend: Array<{
+    date: string;
+    price: number | null;
+    bsrRank: number | null;
+    rating: number | null;
+    reviewCount: number | null;
+    sales: number | null;
+  }> | null;
+  /** 数据来源详情 */
+  _sources: Array<{
+    platform: 'amazon' | 'sorftime';
+    fetchedAt: string;
+  }>;
+}
+
+// 响应: ApiResponse<CleanProductDetail>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 | Sorftime 原始字段 |
+|-----------|----------------|------------------|
+| `description` | `summaries[0].itemDescription` | `Description` |
+| `features` | `summaries[0].bulletPoints` | `Features` |
+| `dimensions.length` | `dimensions[0].item.length.value` | — |
+| `dimensions.width` | `dimensions[0].item.width.value` | — |
+| `dimensions.height` | `dimensions[0].item.height.value` | — |
+| `dimensions.weight` | `dimensions[0].item.weight.value` | — |
+| `variants` | `relationships[0].variationTheme` | — |
+| `listedAt` | — | `DateFirstAvailable` |
+| `estimatedMonthlySales` | — | `MonthlySales` |
+| `estimatedMonthlyRevenue` | — | `MonthlyRevenue` |
+| `sellerCount` | — | `SellerNum` |
+| `fbaFee` | — | `FBAFee` |
+| `trend` | — | `TrendData[]` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "B0EXAMPLE1",
+    "title": "Wireless Bluetooth Headphones",
+    "brand": "ExampleBrand",
+    "imageUrl": "https://m.media-amazon.com/images/I/example.jpg",
+    "price": 29.99,
+    "currency": "USD",
+    "rating": 4.5,
+    "reviewCount": 12580,
+    "category": "Electronics",
+    "bsrRank": 1523,
+    "description": "High quality wireless headphones with noise cancellation...",
+    "features": [
+      "Active Noise Cancellation",
+      "40-hour battery life",
+      "Bluetooth 5.3"
+    ],
+    "dimensions": {
+      "length": 18.5,
+      "width": 15.2,
+      "height": 7.8,
+      "weight": 250,
+      "unit": "cm",
+      "weightUnit": "g"
+    },
+    "variants": [
+      { "asin": "B0EXAMPLE2", "title": "Black", "attributes": { "color": "Black" } },
+      { "asin": "B0EXAMPLE3", "title": "White", "attributes": { "color": "White" } }
+    ],
+    "listedAt": "2024-03-15T00:00:00.000Z",
+    "estimatedMonthlySales": 8500,
+    "estimatedMonthlyRevenue": 254915,
+    "sellerCount": 3,
+    "fbaFee": 5.42,
+    "trend": null,
+    "_source": "sorftime",
+    "_sources": [
+      { "platform": "amazon", "fetchedAt": "2025-01-01T12:00:00.000Z" },
+      { "platform": "sorftime", "fetchedAt": "2025-01-01T12:00:01.000Z" }
+    ]
+  },
+  "timestamp": "2025-01-01T12:00:01.500Z"
+}
+```
+
+---
+
+#### 6.1.3 `GET /api/clean/products/:id/sales` — 产品销量数据
+
+聚合 Amazon Sales 数据 + Sorftime AsinSalesVolume，返回产品销量统计。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `SalesApi.getOrderMetrics` | `GET /api/amazon/sales/orderMetrics` |
+| Sorftime | `ProductApi.getAsinSalesVolume` | `POST /api/sorftime/forward` -> `/api/AsinSalesVolume` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = ASIN
+interface ProductSalesParams {
+  source?: 'amazon' | 'sorftime' | 'all';
+  domain?: string;
+  marketplaceId?: string;
+  /** 时间粒度 */
+  granularity?: 'day' | 'week' | 'month';
+  /** 开始日期 ISO 8601 */
+  startDate: string;
+  /** 结束日期 ISO 8601 */
+  endDate: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanProductSales {
+  /** ASIN */
+  asin: string;
+  /** 统计周期 */
+  period: {
+    startDate: string;
+    endDate: string;
+    granularity: 'day' | 'week' | 'month';
+  };
+  /** 汇总数据 */
+  summary: {
+    totalUnits: number;
+    totalRevenue: number;
+    currency: string;
+    averageDailyUnits: number;
+    averagePrice: number;
+  };
+  /** 时间序列数据 */
+  timeline: Array<{
+    date: string;
+    units: number;
+    revenue: number;
+    price: number | null;
+    bsrRank: number | null;
+  }>;
+  _source: 'amazon' | 'sorftime';
+}
+
+// 响应: ApiResponse<CleanProductSales>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 | Sorftime 原始字段 |
+|-----------|----------------|------------------|
+| `summary.totalUnits` | `orderMetrics[].unitCount` (求和) | `TotalSales` |
+| `summary.totalRevenue` | `orderMetrics[].totalSales.amount` (求和) | `TotalRevenue` |
+| `summary.currency` | `orderMetrics[].totalSales.currencyCode` | 根据 `domain` 推断 |
+| `timeline[].date` | `orderMetrics[].interval` (解析) | `SalesData[].Date` |
+| `timeline[].units` | `orderMetrics[].unitCount` | `SalesData[].Sales` |
+| `timeline[].revenue` | `orderMetrics[].totalSales.amount` | `SalesData[].Revenue` |
+| `timeline[].bsrRank` | — | `SalesData[].BSR` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "asin": "B0EXAMPLE1",
+    "period": {
+      "startDate": "2025-01-01",
+      "endDate": "2025-01-31",
+      "granularity": "day"
+    },
+    "summary": {
+      "totalUnits": 8500,
+      "totalRevenue": 254915.00,
+      "currency": "USD",
+      "averageDailyUnits": 274,
+      "averagePrice": 29.99
+    },
+    "timeline": [
+      { "date": "2025-01-01", "units": 280, "revenue": 8397.20, "price": 29.99, "bsrRank": 1520 },
+      { "date": "2025-01-02", "units": 265, "revenue": 7947.35, "price": 29.99, "bsrRank": 1535 }
+    ],
+    "_source": "sorftime"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.1.4 `GET /api/clean/products/:id/reviews` — 产品评论分析
+
+聚合 Amazon CustomerFeedback + Sorftime ProductReviewsQuery，返回产品评论统计与列表。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `SellersApi.getCustomerFeedback` | `GET /api/amazon/sellers/feedback` |
+| Sorftime | `ProductApi.getProductReviewsQuery` | `POST /api/sorftime/forward` -> `/api/ProductReviewsQuery` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = ASIN
+interface ProductReviewsParams extends PaginationParams {
+  source?: 'amazon' | 'sorftime' | 'all';
+  domain?: string;
+  marketplaceId?: string;
+  /** 评分筛选 1-5 */
+  rating?: number;
+  /** 排序方式 */
+  sortBy?: 'date' | 'rating' | 'helpful';
+  /** 排序方向 */
+  sortOrder?: 'asc' | 'desc';
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanReviewSummary {
+  /** ASIN */
+  asin: string;
+  /** 评分分布 */
+  ratingDistribution: {
+    '1': number;
+    '2': number;
+    '3': number;
+    '4': number;
+    '5': number;
+  };
+  /** 平均评分 */
+  averageRating: number;
+  /** 总评论数 */
+  totalReviews: number;
+}
+
+interface CleanReview {
+  /** 评论 ID */
+  id: string;
+  /** 评论标题 */
+  title: string;
+  /** 评论内容 */
+  content: string;
+  /** 评分 1-5 */
+  rating: number;
+  /** 评论者名称 */
+  reviewer: string;
+  /** 评论日期 */
+  date: string;
+  /** 是否已验证购买 */
+  verifiedPurchase: boolean;
+  /** 有帮助数 */
+  helpfulCount: number;
+  /** 数据来源 */
+  _source: 'amazon' | 'sorftime';
+}
+
+// 响应: ApiResponse<{ summary: CleanReviewSummary; reviews: PaginatedResponse<CleanReview> }>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 | Sorftime 原始字段 |
+|-----------|----------------|------------------|
+| `id` | `feedbackId` | `ReviewId` |
+| `title` | `title` | `Title` |
+| `content` | `comments` | `Content` |
+| `rating` | `rating` | `Rating` |
+| `reviewer` | `buyerName` | `Reviewer` |
+| `date` | `feedbackDate` | `Date` |
+| `verifiedPurchase` | `verified` | `VerifiedPurchase` |
+| `helpfulCount` | — | `HelpfulVotes` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "summary": {
+      "asin": "B0EXAMPLE1",
+      "ratingDistribution": { "1": 120, "2": 85, "3": 310, "4": 3200, "5": 8865 },
+      "averageRating": 4.5,
+      "totalReviews": 12580
+    },
+    "reviews": {
+      "items": [
+        {
+          "id": "R1EXAMPLE",
+          "title": "Great headphones!",
+          "content": "Amazing sound quality and comfortable to wear...",
+          "rating": 5,
+          "reviewer": "John D.",
+          "date": "2025-01-10T00:00:00.000Z",
+          "verifiedPurchase": true,
+          "helpfulCount": 42,
+          "_source": "sorftime"
+        }
+      ],
+      "total": 12580,
+      "page": 1,
+      "pageSize": 20,
+      "hasMore": true
+    }
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.1.5 `GET /api/clean/products/:id/similar` — 同类产品
+
+获取 Sorftime 同类产品实时数据。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `ProductApi.getSimilarProductRealtime` | `POST /api/sorftime/forward` -> `/api/SimilarProductRealtimeRequest` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = ASIN
+interface SimilarProductsParams extends PaginationParams {
+  domain: string;
+  /** 排序字段 */
+  sortBy?: 'price' | 'rating' | 'sales' | 'bsr';
+  sortOrder?: 'asc' | 'desc';
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanSimilarProduct {
+  /** ASIN */
+  id: string;
+  /** 产品标题 */
+  title: string;
+  /** 品牌 */
+  brand: string;
+  /** 主图 URL */
+  imageUrl: string;
+  /** 价格 */
+  price: number | null;
+  /** 货币代码 */
+  currency: string;
+  /** 评分 */
+  rating: number | null;
+  /** 评论数 */
+  reviewCount: number | null;
+  /** BSR 排名 */
+  bsrRank: number | null;
+  /** 月销量估算 */
+  estimatedMonthlySales: number | null;
+  /** 与原产品的相似度评分 */
+  similarityScore: number | null;
+  _source: 'sorftime';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanSimilarProduct>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Sorftime 原始字段 |
+|-----------|------------------|
+| `id` | `ASIN` |
+| `title` | `Title` |
+| `brand` | `Brand` |
+| `imageUrl` | `ImageUrl` |
+| `price` | `Price` |
+| `rating` | `Rating` |
+| `reviewCount` | `Reviews` |
+| `bsrRank` | `BSR` |
+| `estimatedMonthlySales` | `MonthlySales` |
+| `similarityScore` | `SimilarityScore` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "id": "B0SIMILAR1",
+        "title": "Noise Cancelling Wireless Earbuds",
+        "brand": "CompetitorBrand",
+        "imageUrl": "https://m.media-amazon.com/images/I/similar1.jpg",
+        "price": 34.99,
+        "currency": "USD",
+        "rating": 4.3,
+        "reviewCount": 8920,
+        "bsrRank": 2105,
+        "estimatedMonthlySales": 6200,
+        "similarityScore": 0.92,
+        "_source": "sorftime"
+      }
+    ],
+    "total": 25,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+### 6.2 订单相关（Amazon）
+
+#### 6.2.1 `GET /api/clean/orders` — 订单列表
+
+获取 Amazon 订单列表，统一格式输出。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `OrdersApi.getOrders` | `GET /api/amazon/orders` |
+
+**请求参数：**
+
+```typescript
+interface OrderListParams extends PaginationParams {
+  /** 市场 ID */
+  marketplaceId: string;
+  /** 订单状态筛选 */
+  status?: 'pending' | 'unshipped' | 'shipped' | 'canceled' | 'unfulfillable';
+  /** 创建时间起始 ISO 8601 */
+  createdAfter?: string;
+  /** 创建时间截止 ISO 8601 */
+  createdBefore?: string;
+  /** 配送方式 */
+  fulfillmentChannel?: 'AFN' | 'MFN';
+  /** 排序方式 */
+  sortBy?: 'createdAt' | 'updatedAt' | 'totalAmount';
+  sortOrder?: 'asc' | 'desc';
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanOrder {
+  /** 订单 ID */
+  id: string;
+  /** 订单状态 */
+  status: string;
+  /** 订单总金额 */
+  totalAmount: number;
+  /** 货币代码 */
+  currency: string;
+  /** 商品数量 */
+  itemCount: number;
+  /** 配送方式 AFN=FBA, MFN=自发货 */
+  fulfillmentChannel: 'AFN' | 'MFN';
+  /** 购买日期 */
+  createdAt: string;
+  /** 最后更新时间 */
+  updatedAt: string;
+  /** 发货地址（脱敏） */
+  shippingAddress: {
+    city: string;
+    state: string;
+    country: string;
+    postalCode: string;
+  } | null;
+  /** 市场 ID */
+  marketplaceId: string;
+  _source: 'amazon';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanOrder>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 |
+|-----------|----------------|
+| `id` | `AmazonOrderId` |
+| `status` | `OrderStatus` |
+| `totalAmount` | `OrderTotal.Amount` |
+| `currency` | `OrderTotal.CurrencyCode` |
+| `itemCount` | `NumberOfItemsShipped + NumberOfItemsUnshipped` |
+| `fulfillmentChannel` | `FulfillmentChannel` |
+| `createdAt` | `PurchaseDate` |
+| `updatedAt` | `LastUpdateDate` |
+| `shippingAddress.city` | `ShippingAddress.City` |
+| `shippingAddress.state` | `ShippingAddress.StateOrRegion` |
+| `shippingAddress.country` | `ShippingAddress.CountryCode` |
+| `shippingAddress.postalCode` | `ShippingAddress.PostalCode` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "id": "111-1234567-1234567",
+        "status": "shipped",
+        "totalAmount": 59.98,
+        "currency": "USD",
+        "itemCount": 2,
+        "fulfillmentChannel": "AFN",
+        "createdAt": "2025-01-15T08:30:00.000Z",
+        "updatedAt": "2025-01-16T14:20:00.000Z",
+        "shippingAddress": {
+          "city": "Seattle",
+          "state": "WA",
+          "country": "US",
+          "postalCode": "98101"
+        },
+        "marketplaceId": "ATVPDKIKX0DER",
+        "_source": "amazon"
+      }
+    ],
+    "total": 156,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.2.2 `GET /api/clean/orders/:id` — 订单详情
+
+获取单个订单的完整信息，包含订单项明细。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `OrdersApi.getOrder` | `GET /api/amazon/orders/:orderId` |
+| Amazon | `OrdersApi.getOrderItems` | `GET /api/amazon/orders/:orderId/items` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = Amazon 订单号
+interface OrderDetailParams {
+  marketplaceId?: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanOrderDetail extends CleanOrder {
+  /** 订单项列表 */
+  items: Array<{
+    /** 订单项 ID */
+    id: string;
+    /** ASIN */
+    asin: string;
+    /** SKU */
+    sku: string;
+    /** 商品标题 */
+    title: string;
+    /** 数量 */
+    quantity: number;
+    /** 单价 */
+    unitPrice: number;
+    /** 小计 */
+    subtotal: number;
+    /** 货币代码 */
+    currency: string;
+    /** 商品图片 */
+    imageUrl: string | null;
+  }>;
+  /** 买家信息（脱敏） */
+  buyer: {
+    name: string | null;
+    email: string | null;
+  } | null;
+  /** 配送信息 */
+  shipping: {
+    service: string | null;
+    trackingNumber: string | null;
+    estimatedDelivery: string | null;
+    shippedAt: string | null;
+    deliveredAt: string | null;
+  } | null;
+  /** 支付信息 */
+  payment: {
+    method: string | null;
+    subtotal: number;
+    shippingFee: number;
+    tax: number;
+    discount: number;
+    total: number;
+    currency: string;
+  };
+}
+
+// 响应: ApiResponse<CleanOrderDetail>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 |
+|-----------|----------------|
+| `items[].id` | `OrderItemId` |
+| `items[].asin` | `ASIN` |
+| `items[].sku` | `SellerSKU` |
+| `items[].title` | `Title` |
+| `items[].quantity` | `QuantityOrdered` |
+| `items[].unitPrice` | `ItemPrice.Amount / QuantityOrdered` |
+| `items[].subtotal` | `ItemPrice.Amount` |
+| `buyer.name` | `BuyerInfo.BuyerName` |
+| `buyer.email` | `BuyerInfo.BuyerEmail` |
+| `shipping.service` | `ShipmentServiceLevelCategory` |
+| `payment.subtotal` | `OrderTotal.Amount - ShippingPrice - Tax` |
+| `payment.shippingFee` | `ShippingPrice.Amount` |
+| `payment.tax` | `TaxCollection.Amount` |
+| `payment.total` | `OrderTotal.Amount` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "111-1234567-1234567",
+    "status": "shipped",
+    "totalAmount": 59.98,
+    "currency": "USD",
+    "itemCount": 2,
+    "fulfillmentChannel": "AFN",
+    "createdAt": "2025-01-15T08:30:00.000Z",
+    "updatedAt": "2025-01-16T14:20:00.000Z",
+    "shippingAddress": {
+      "city": "Seattle",
+      "state": "WA",
+      "country": "US",
+      "postalCode": "98101"
+    },
+    "marketplaceId": "ATVPDKIKX0DER",
+    "items": [
+      {
+        "id": "ITEM001",
+        "asin": "B0EXAMPLE1",
+        "sku": "WH-BT-001",
+        "title": "Wireless Bluetooth Headphones",
+        "quantity": 2,
+        "unitPrice": 29.99,
+        "subtotal": 59.98,
+        "currency": "USD",
+        "imageUrl": "https://m.media-amazon.com/images/I/example.jpg"
+      }
+    ],
+    "buyer": {
+      "name": "J*** D***",
+      "email": null
+    },
+    "shipping": {
+      "service": "Expedited",
+      "trackingNumber": "TBA123456789",
+      "estimatedDelivery": "2025-01-18T00:00:00.000Z",
+      "shippedAt": "2025-01-16T10:00:00.000Z",
+      "deliveredAt": null
+    },
+    "payment": {
+      "method": "Other",
+      "subtotal": 59.98,
+      "shippingFee": 0,
+      "tax": 5.40,
+      "discount": 0,
+      "total": 65.38,
+      "currency": "USD"
+    },
+    "_source": "amazon"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.2.3 `GET /api/clean/orders/metrics` — 订单统计
+
+获取 Amazon 销售订单指标汇总。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `SalesApi.getOrderMetrics` | `GET /api/amazon/sales/orderMetrics` |
+
+**请求参数：**
+
+```typescript
+interface OrderMetricsParams {
+  marketplaceId: string;
+  /** 时间粒度 */
+  granularity: 'day' | 'week' | 'month' | 'year';
+  /** 开始日期 ISO 8601 */
+  startDate: string;
+  /** 结束日期 ISO 8601 */
+  endDate: string;
+  /** 按 ASIN 筛选 */
+  asin?: string;
+  /** 按 SKU 筛选 */
+  sku?: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanOrderMetrics {
+  /** 统计周期 */
+  period: {
+    startDate: string;
+    endDate: string;
+    granularity: string;
+  };
+  /** 汇总 */
+  summary: {
+    totalOrders: number;
+    totalUnits: number;
+    totalRevenue: number;
+    averageOrderValue: number;
+    currency: string;
+  };
+  /** 时间序列 */
+  timeline: Array<{
+    date: string;
+    orders: number;
+    units: number;
+    revenue: number;
+    averageOrderValue: number;
+  }>;
+  _source: 'amazon';
+}
+
+// 响应: ApiResponse<CleanOrderMetrics>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 |
+|-----------|----------------|
+| `summary.totalOrders` | `orderMetrics[].orderCount` (求和) |
+| `summary.totalUnits` | `orderMetrics[].unitCount` (求和) |
+| `summary.totalRevenue` | `orderMetrics[].totalSales.amount` (求和) |
+| `summary.averageOrderValue` | `totalRevenue / totalOrders` |
+| `summary.currency` | `orderMetrics[0].totalSales.currencyCode` |
+| `timeline[].date` | `orderMetrics[].interval` (解析) |
+| `timeline[].orders` | `orderMetrics[].orderCount` |
+| `timeline[].units` | `orderMetrics[].unitCount` |
+| `timeline[].revenue` | `orderMetrics[].totalSales.amount` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "period": {
+      "startDate": "2025-01-01",
+      "endDate": "2025-01-31",
+      "granularity": "week"
+    },
+    "summary": {
+      "totalOrders": 420,
+      "totalUnits": 680,
+      "totalRevenue": 20386.20,
+      "averageOrderValue": 48.54,
+      "currency": "USD"
+    },
+    "timeline": [
+      { "date": "2025-01-01", "orders": 95, "units": 150, "revenue": 4497.00, "averageOrderValue": 47.34 },
+      { "date": "2025-01-08", "orders": 110, "units": 180, "revenue": 5398.20, "averageOrderValue": 49.07 },
+      { "date": "2025-01-15", "orders": 105, "units": 170, "revenue": 5098.30, "averageOrderValue": 48.56 },
+      { "date": "2025-01-22", "orders": 110, "units": 180, "revenue": 5392.70, "averageOrderValue": 49.02 }
+    ],
+    "_source": "amazon"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+### 6.3 商品管理（Amazon Listings）
+
+#### 6.3.1 `GET /api/clean/listings` — Listing 列表
+
+获取卖家的 Amazon Listing 列表。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `ListingsApi.getListingsItems` | `GET /api/amazon/listings` |
+
+**请求参数：**
+
+```typescript
+interface ListingListParams extends PaginationParams {
+  marketplaceId: string;
+  /** 按状态筛选 */
+  status?: 'active' | 'inactive' | 'incomplete';
+  /** 搜索关键词（标题/SKU/ASIN） */
+  keyword?: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanListing {
+  /** SKU */
+  sku: string;
+  /** ASIN */
+  asin: string;
+  /** 商品标题 */
+  title: string;
+  /** 主图 URL */
+  imageUrl: string | null;
+  /** 价格 */
+  price: number | null;
+  /** 货币代码 */
+  currency: string;
+  /** 状态 */
+  status: 'active' | 'inactive' | 'incomplete';
+  /** FBA 库存数量 */
+  fbaQuantity: number;
+  /** 自发货库存数量 */
+  fbmQuantity: number;
+  /** 创建时间 */
+  createdAt: string;
+  /** 最后更新时间 */
+  updatedAt: string;
+  /** 市场 ID */
+  marketplaceId: string;
+  _source: 'amazon';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanListing>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 |
+|-----------|----------------|
+| `sku` | `sku` |
+| `asin` | `summaries[0].asin` |
+| `title` | `summaries[0].itemName` |
+| `imageUrl` | `summaries[0].mainImage.link` |
+| `price` | `attributes.purchasable_offer[0].our_price[0].schedule[0].value_with_tax` |
+| `status` | `summaries[0].status[0]` |
+| `fbaQuantity` | `fulfillmentAvailability[0].quantity` (AFN) |
+| `fbmQuantity` | `fulfillmentAvailability[0].quantity` (MFN) |
+| `createdAt` | `summaries[0].createdDate` |
+| `updatedAt` | `summaries[0].lastUpdatedDate` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "sku": "WH-BT-001",
+        "asin": "B0EXAMPLE1",
+        "title": "Wireless Bluetooth Headphones",
+        "imageUrl": "https://m.media-amazon.com/images/I/example.jpg",
+        "price": 29.99,
+        "currency": "USD",
+        "status": "active",
+        "fbaQuantity": 580,
+        "fbmQuantity": 0,
+        "createdAt": "2024-03-15T00:00:00.000Z",
+        "updatedAt": "2025-01-10T08:00:00.000Z",
+        "marketplaceId": "ATVPDKIKX0DER",
+        "_source": "amazon"
+      }
+    ],
+    "total": 45,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.3.2 `GET /api/clean/listings/:sku` — Listing 详情
+
+获取单个 Listing 的完整信息。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `ListingsApi.getListingsItem` | `GET /api/amazon/listings/:sku` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: sku = 卖家 SKU
+interface ListingDetailParams {
+  marketplaceId: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanListingDetail extends CleanListing {
+  /** 商品描述 */
+  description: string | null;
+  /** 商品特征 */
+  features: string[];
+  /** 商品属性 */
+  attributes: Record<string, string>;
+  /** 变体信息 */
+  variants: Array<{
+    sku: string;
+    asin: string;
+    attributes: Record<string, string>;
+  }>;
+  /** 商品问题/警告 */
+  issues: Array<{
+    code: string;
+    message: string;
+    severity: 'error' | 'warning' | 'info';
+  }>;
+  /** 配送信息 */
+  fulfillment: {
+    channel: 'AFN' | 'MFN';
+    quantity: number;
+    inboundShipments: number;
+    reservedQuantity: number;
+  };
+}
+
+// 响应: ApiResponse<CleanListingDetail>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 |
+|-----------|----------------|
+| `description` | `attributes.product_description[0].value` |
+| `features` | `attributes.bullet_point[].value` |
+| `attributes` | `attributes.*` (扁平化) |
+| `variants` | `relationships[0].variationTheme` |
+| `issues[].code` | `issues[].code` |
+| `issues[].message` | `issues[].message` |
+| `issues[].severity` | `issues[].severity` |
+| `fulfillment.channel` | `fulfillmentAvailability[0].fulfillmentChannelCode` |
+| `fulfillment.quantity` | `fulfillmentAvailability[0].quantity` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "sku": "WH-BT-001",
+    "asin": "B0EXAMPLE1",
+    "title": "Wireless Bluetooth Headphones",
+    "imageUrl": "https://m.media-amazon.com/images/I/example.jpg",
+    "price": 29.99,
+    "currency": "USD",
+    "status": "active",
+    "fbaQuantity": 580,
+    "fbmQuantity": 0,
+    "createdAt": "2024-03-15T00:00:00.000Z",
+    "updatedAt": "2025-01-10T08:00:00.000Z",
+    "marketplaceId": "ATVPDKIKX0DER",
+    "description": "Premium wireless headphones with active noise cancellation...",
+    "features": [
+      "Active Noise Cancellation",
+      "40-hour battery life",
+      "Bluetooth 5.3",
+      "Comfortable over-ear design"
+    ],
+    "attributes": {
+      "color": "Black",
+      "connectivity": "Bluetooth",
+      "brand": "ExampleBrand"
+    },
+    "variants": [
+      { "sku": "WH-BT-001-BK", "asin": "B0EXAMPLE1", "attributes": { "color": "Black" } },
+      { "sku": "WH-BT-001-WH", "asin": "B0EXAMPLE3", "attributes": { "color": "White" } }
+    ],
+    "issues": [],
+    "fulfillment": {
+      "channel": "AFN",
+      "quantity": 580,
+      "inboundShipments": 200,
+      "reservedQuantity": 15
+    },
+    "_source": "amazon"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+### 6.4 类目相关（Sorftime）
+
+#### 6.4.1 `GET /api/clean/categories/tree` — 类目树
+
+获取 Sorftime 类目树结构。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `CategoryApi.getCategoryTree` | `POST /api/sorftime/forward` -> `/api/CategoryTree` |
+
+**请求参数：**
+
+```typescript
+interface CategoryTreeParams {
+  /** 市场域名，如 amazon.com */
+  domain: string;
+  /** 父类目 ID（不传则返回顶级类目） */
+  parentId?: string;
+  /** 展开层级深度，默认 1 */
+  depth?: number;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanCategory {
+  /** 类目 ID */
+  id: string;
+  /** 类目名称 */
+  name: string;
+  /** 父类目 ID */
+  parentId: string | null;
+  /** 层级深度 */
+  level: number;
+  /** 子类目数量 */
+  childCount: number;
+  /** 该类目下产品数量估算 */
+  productCount: number | null;
+  /** 子类目列表 */
+  children: CleanCategory[];
+  _source: 'sorftime';
+}
+
+// 响应: ApiResponse<CleanCategory[]>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Sorftime 原始字段 |
+|-----------|------------------|
+| `id` | `CategoryId` |
+| `name` | `CategoryName` |
+| `parentId` | `ParentCategoryId` |
+| `level` | `Level` |
+| `childCount` | `ChildCount` |
+| `productCount` | `ProductCount` |
+| `children` | `Children[]` (递归映射) |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "172282",
+      "name": "Electronics",
+      "parentId": null,
+      "level": 0,
+      "childCount": 24,
+      "productCount": 5800000,
+      "children": [
+        {
+          "id": "172541",
+          "name": "Headphones, Earbuds & Accessories",
+          "parentId": "172282",
+          "level": 1,
+          "childCount": 8,
+          "productCount": 320000,
+          "children": [],
+          "_source": "sorftime"
+        }
+      ],
+      "_source": "sorftime"
+    }
+  ],
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.4.2 `GET /api/clean/categories/:id/products` — 类目热销产品
+
+获取指定类目下的热销产品列表。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `CategoryApi.getCategoryProducts` | `POST /api/sorftime/forward` -> `/api/CategoryProducts` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = 类目 ID
+interface CategoryProductsParams extends PaginationParams {
+  domain: string;
+  /** 排序字段 */
+  sortBy?: 'sales' | 'price' | 'rating' | 'bsr' | 'reviews';
+  sortOrder?: 'asc' | 'desc';
+  /** 价格范围 */
+  minPrice?: number;
+  maxPrice?: number;
+  /** 评分范围 */
+  minRating?: number;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanCategoryProduct {
+  /** ASIN */
+  id: string;
+  /** 产品标题 */
+  title: string;
+  /** 品牌 */
+  brand: string;
+  /** 主图 URL */
+  imageUrl: string;
+  /** 价格 */
+  price: number | null;
+  /** 货币代码 */
+  currency: string;
+  /** 评分 */
+  rating: number | null;
+  /** 评论数 */
+  reviewCount: number | null;
+  /** BSR 排名 */
+  bsrRank: number | null;
+  /** 月销量估算 */
+  estimatedMonthlySales: number | null;
+  /** 月收入估算 */
+  estimatedMonthlyRevenue: number | null;
+  /** 上架时间 */
+  listedAt: string | null;
+  /** 卖家数量 */
+  sellerCount: number | null;
+  _source: 'sorftime';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanCategoryProduct>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Sorftime 原始字段 |
+|-----------|------------------|
+| `id` | `ASIN` |
+| `title` | `Title` |
+| `brand` | `Brand` |
+| `imageUrl` | `ImageUrl` |
+| `price` | `Price` |
+| `rating` | `Rating` |
+| `reviewCount` | `Reviews` |
+| `bsrRank` | `BSR` |
+| `estimatedMonthlySales` | `MonthlySales` |
+| `estimatedMonthlyRevenue` | `MonthlyRevenue` |
+| `listedAt` | `DateFirstAvailable` |
+| `sellerCount` | `SellerNum` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "id": "B0EXAMPLE1",
+        "title": "Wireless Bluetooth Headphones",
+        "brand": "ExampleBrand",
+        "imageUrl": "https://m.media-amazon.com/images/I/example.jpg",
+        "price": 29.99,
+        "currency": "USD",
+        "rating": 4.5,
+        "reviewCount": 12580,
+        "bsrRank": 1523,
+        "estimatedMonthlySales": 8500,
+        "estimatedMonthlyRevenue": 254915,
+        "listedAt": "2024-03-15T00:00:00.000Z",
+        "sellerCount": 3,
+        "_source": "sorftime"
+      }
+    ],
+    "total": 500,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.4.3 `GET /api/clean/categories/:id/keywords` — 类目关键词
+
+获取指定类目下的热门关键词。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `CategoryApi.getCategoryKeywords` | `POST /api/sorftime/forward` -> `/api/CategoryKeywords` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = 类目 ID
+interface CategoryKeywordsParams extends PaginationParams {
+  domain: string;
+  /** 排序字段 */
+  sortBy?: 'searchVolume' | 'growth' | 'competition';
+  sortOrder?: 'asc' | 'desc';
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanCategoryKeyword {
+  /** 关键词 */
+  keyword: string;
+  /** 月搜索量 */
+  searchVolume: number;
+  /** 搜索量增长率（百分比） */
+  growthRate: number | null;
+  /** 竞争度 0-1 */
+  competition: number | null;
+  /** 点击集中度 */
+  clickConcentration: number | null;
+  /** 关联产品数 */
+  productCount: number | null;
+  _source: 'sorftime';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanCategoryKeyword>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Sorftime 原始字段 |
+|-----------|------------------|
+| `keyword` | `Keyword` |
+| `searchVolume` | `SearchVolume` |
+| `growthRate` | `GrowthRate` |
+| `competition` | `Competition` |
+| `clickConcentration` | `ClickConcentration` |
+| `productCount` | `ProductCount` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "keyword": "wireless headphones",
+        "searchVolume": 1250000,
+        "growthRate": 12.5,
+        "competition": 0.85,
+        "clickConcentration": 0.42,
+        "productCount": 50000,
+        "_source": "sorftime"
+      },
+      {
+        "keyword": "bluetooth headphones noise cancelling",
+        "searchVolume": 680000,
+        "growthRate": 18.3,
+        "competition": 0.72,
+        "clickConcentration": 0.38,
+        "productCount": 28000,
+        "_source": "sorftime"
+      }
+    ],
+    "total": 150,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+### 6.5 关键词相关（Sorftime）
+
+#### 6.5.1 `GET /api/clean/keywords/search` — 关键词查询
+
+搜索关键词并返回搜索量、竞争度等数据。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `KeywordApi.getKeywordSearch` | `POST /api/sorftime/forward` -> `/api/KeywordSearch` |
+
+**请求参数：**
+
+```typescript
+interface KeywordSearchParams extends PaginationParams {
+  /** 搜索关键词 */
+  keyword: string;
+  /** 市场域名 */
+  domain: string;
+  /** 匹配模式 */
+  matchType?: 'exact' | 'broad' | 'phrase';
+  /** 最小搜索量 */
+  minSearchVolume?: number;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanKeyword {
+  /** 关键词 */
+  keyword: string;
+  /** 月搜索量 */
+  searchVolume: number;
+  /** 搜索量趋势（近3个月） */
+  searchTrend: 'up' | 'down' | 'stable';
+  /** 搜索量增长率（百分比） */
+  growthRate: number | null;
+  /** 竞争度 0-1 */
+  competition: number | null;
+  /** 推荐出价（美元） */
+  suggestedBid: number | null;
+  /** 点击集中度 */
+  clickConcentration: number | null;
+  /** 关联产品数 */
+  productCount: number | null;
+  /** 相关关键词 */
+  relatedKeywords: string[];
+  _source: 'sorftime';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanKeyword>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Sorftime 原始字段 |
+|-----------|------------------|
+| `keyword` | `Keyword` |
+| `searchVolume` | `SearchVolume` |
+| `searchTrend` | 根据 `SearchVolumeHistory` 计算 |
+| `growthRate` | `GrowthRate` |
+| `competition` | `Competition` |
+| `suggestedBid` | `SuggestedBid` |
+| `clickConcentration` | `ClickConcentration` |
+| `productCount` | `ProductCount` |
+| `relatedKeywords` | `RelatedKeywords[]` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "keyword": "wireless headphones",
+        "searchVolume": 1250000,
+        "searchTrend": "up",
+        "growthRate": 12.5,
+        "competition": 0.85,
+        "suggestedBid": 2.35,
+        "clickConcentration": 0.42,
+        "productCount": 50000,
+        "relatedKeywords": ["bluetooth headphones", "wireless earbuds", "noise cancelling headphones"],
+        "_source": "sorftime"
+      }
+    ],
+    "total": 85,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.5.2 `GET /api/clean/keywords/:keyword/products` — 关键词产品排名
+
+获取指定关键词下的产品排名列表。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `KeywordApi.getKeywordProducts` | `POST /api/sorftime/forward` -> `/api/KeywordProducts` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: keyword = 关键词（需 URL 编码）
+interface KeywordProductsParams extends PaginationParams {
+  domain: string;
+  /** 排名类型 */
+  rankType?: 'organic' | 'sponsored' | 'all';
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanKeywordProduct {
+  /** 排名位置 */
+  rank: number;
+  /** 排名类型 */
+  rankType: 'organic' | 'sponsored';
+  /** ASIN */
+  id: string;
+  /** 产品标题 */
+  title: string;
+  /** 品牌 */
+  brand: string;
+  /** 主图 URL */
+  imageUrl: string;
+  /** 价格 */
+  price: number | null;
+  /** 货币代码 */
+  currency: string;
+  /** 评分 */
+  rating: number | null;
+  /** 评论数 */
+  reviewCount: number | null;
+  /** BSR 排名 */
+  bsrRank: number | null;
+  /** 月销量估算 */
+  estimatedMonthlySales: number | null;
+  _source: 'sorftime';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanKeywordProduct>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Sorftime 原始字段 |
+|-----------|------------------|
+| `rank` | `Position` |
+| `rankType` | `Type` (`organic` / `sponsored`) |
+| `id` | `ASIN` |
+| `title` | `Title` |
+| `brand` | `Brand` |
+| `imageUrl` | `ImageUrl` |
+| `price` | `Price` |
+| `rating` | `Rating` |
+| `reviewCount` | `Reviews` |
+| `bsrRank` | `BSR` |
+| `estimatedMonthlySales` | `MonthlySales` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "rank": 1,
+        "rankType": "organic",
+        "id": "B0EXAMPLE1",
+        "title": "Wireless Bluetooth Headphones",
+        "brand": "ExampleBrand",
+        "imageUrl": "https://m.media-amazon.com/images/I/example.jpg",
+        "price": 29.99,
+        "currency": "USD",
+        "rating": 4.5,
+        "reviewCount": 12580,
+        "bsrRank": 1523,
+        "estimatedMonthlySales": 8500,
+        "_source": "sorftime"
+      }
+    ],
+    "total": 300,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.5.3 `GET /api/clean/keywords/reverse/:asin` — ASIN 反查关键词
+
+通过 ASIN 反查该产品排名的关键词列表。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `KeywordApi.getReverseAsin` | `POST /api/sorftime/forward` -> `/api/ReverseAsin` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: asin = ASIN
+interface ReverseAsinParams extends PaginationParams {
+  domain: string;
+  /** 最小搜索量筛选 */
+  minSearchVolume?: number;
+  /** 排序字段 */
+  sortBy?: 'searchVolume' | 'rank' | 'competition';
+  sortOrder?: 'asc' | 'desc';
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanReverseKeyword {
+  /** 关键词 */
+  keyword: string;
+  /** 该 ASIN 在此关键词下的排名 */
+  rank: number;
+  /** 排名类型 */
+  rankType: 'organic' | 'sponsored';
+  /** 月搜索量 */
+  searchVolume: number;
+  /** 竞争度 0-1 */
+  competition: number | null;
+  /** 点击集中度 */
+  clickConcentration: number | null;
+  /** 搜索量增长率 */
+  growthRate: number | null;
+  _source: 'sorftime';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanReverseKeyword>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Sorftime 原始字段 |
+|-----------|------------------|
+| `keyword` | `Keyword` |
+| `rank` | `Position` |
+| `rankType` | `Type` |
+| `searchVolume` | `SearchVolume` |
+| `competition` | `Competition` |
+| `clickConcentration` | `ClickConcentration` |
+| `growthRate` | `GrowthRate` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "keyword": "wireless headphones",
+        "rank": 5,
+        "rankType": "organic",
+        "searchVolume": 1250000,
+        "competition": 0.85,
+        "clickConcentration": 0.42,
+        "growthRate": 12.5,
+        "_source": "sorftime"
+      },
+      {
+        "keyword": "bluetooth headphones noise cancelling",
+        "rank": 3,
+        "rankType": "organic",
+        "searchVolume": 680000,
+        "competition": 0.72,
+        "clickConcentration": 0.38,
+        "growthRate": 18.3,
+        "_source": "sorftime"
+      }
+    ],
+    "total": 420,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.5.4 `GET /api/clean/keywords/:keyword/trend` — 关键词趋势
+
+获取关键词的搜索量历史趋势数据。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `KeywordApi.getKeywordTrend` | `POST /api/sorftime/forward` -> `/api/KeywordTrend` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: keyword = 关键词（需 URL 编码）
+interface KeywordTrendParams {
+  domain: string;
+  /** 时间范围 */
+  period?: '3m' | '6m' | '12m' | '24m';
+  /** 时间粒度 */
+  granularity?: 'day' | 'week' | 'month';
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanKeywordTrend {
+  /** 关键词 */
+  keyword: string;
+  /** 当前月搜索量 */
+  currentSearchVolume: number;
+  /** 搜索量变化率 */
+  changeRate: number;
+  /** 趋势方向 */
+  trend: 'up' | 'down' | 'stable';
+  /** 历史数据 */
+  history: Array<{
+    date: string;
+    searchVolume: number;
+    rank: number | null;
+  }>;
+  /** 季节性指数（1-12月） */
+  seasonality: Array<{
+    month: number;
+    index: number;
+  }> | null;
+  _source: 'sorftime';
+}
+
+// 响应: ApiResponse<CleanKeywordTrend>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Sorftime 原始字段 |
+|-----------|------------------|
+| `keyword` | `Keyword` |
+| `currentSearchVolume` | `CurrentSearchVolume` |
+| `changeRate` | `ChangeRate` |
+| `trend` | 根据 `ChangeRate` 计算 |
+| `history[].date` | `History[].Date` |
+| `history[].searchVolume` | `History[].SearchVolume` |
+| `seasonality[].month` | `Seasonality[].Month` |
+| `seasonality[].index` | `Seasonality[].Index` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "keyword": "wireless headphones",
+    "currentSearchVolume": 1250000,
+    "changeRate": 12.5,
+    "trend": "up",
+    "history": [
+      { "date": "2024-11-01", "searchVolume": 980000, "rank": null },
+      { "date": "2024-12-01", "searchVolume": 1150000, "rank": null },
+      { "date": "2025-01-01", "searchVolume": 1250000, "rank": null }
+    ],
+    "seasonality": [
+      { "month": 1, "index": 1.05 },
+      { "month": 2, "index": 0.92 },
+      { "month": 11, "index": 1.35 },
+      { "month": 12, "index": 1.58 }
+    ],
+    "_source": "sorftime"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+### 6.6 监控相关（Sorftime）
+
+#### 6.6.1 `POST /api/clean/monitoring/bestseller/subscribe` — BS 榜单订阅
+
+订阅 Best Seller 榜单监控任务。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `MonitorApi.subscribeBestSeller` | `POST /api/sorftime/forward` -> `/api/BestSellerSubscribe` |
+
+**请求参数：**
+
+```typescript
+interface BestSellerSubscribeParams {
+  /** 市场域名 */
+  domain: string;
+  /** 类目 ID */
+  categoryId: string;
+  /** 监控频率 */
+  frequency: 'hourly' | 'daily' | 'weekly';
+  /** 通知方式 */
+  notifyType?: 'email' | 'webhook' | 'none';
+  /** 通知地址 */
+  notifyUrl?: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanSubscription {
+  /** 订阅任务 ID */
+  id: string;
+  /** 订阅类型 */
+  type: 'bestseller' | 'asin';
+  /** 状态 */
+  status: 'active' | 'paused' | 'expired';
+  /** 监控目标 */
+  target: {
+    domain: string;
+    categoryId?: string;
+    categoryName?: string;
+    asin?: string;
+  };
+  /** 监控频率 */
+  frequency: string;
+  /** 创建时间 */
+  createdAt: string;
+  /** 下次执行时间 */
+  nextRunAt: string;
+  _source: 'sorftime';
+}
+
+// 响应: ApiResponse<CleanSubscription>
+```
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "SUB_BS_001",
+    "type": "bestseller",
+    "status": "active",
+    "target": {
+      "domain": "amazon.com",
+      "categoryId": "172282",
+      "categoryName": "Electronics"
+    },
+    "frequency": "daily",
+    "createdAt": "2025-01-01T12:00:00.000Z",
+    "nextRunAt": "2025-01-02T12:00:00.000Z",
+    "_source": "sorftime"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.6.2 `GET /api/clean/monitoring/bestseller/tasks` — BS 榜单任务
+
+获取 Best Seller 榜单监控任务列表及结果。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `MonitorApi.getBestSellerTasks` | `POST /api/sorftime/forward` -> `/api/BestSellerTasks` |
+
+**请求参数：**
+
+```typescript
+interface BestSellerTasksParams extends PaginationParams {
+  /** 按状态筛选 */
+  status?: 'active' | 'paused' | 'expired';
+  domain?: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanBestSellerTask extends CleanSubscription {
+  /** 最近一次执行结果 */
+  lastResult: {
+    executedAt: string;
+    /** 榜单产品列表（前 N 名） */
+    products: Array<{
+      rank: number;
+      asin: string;
+      title: string;
+      price: number | null;
+      rating: number | null;
+      reviewCount: number | null;
+    }>;
+    /** 与上次对比的变化 */
+    changes: {
+      newEntries: number;
+      removedEntries: number;
+      rankChanges: number;
+    };
+  } | null;
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanBestSellerTask>>
+```
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "id": "SUB_BS_001",
+        "type": "bestseller",
+        "status": "active",
+        "target": {
+          "domain": "amazon.com",
+          "categoryId": "172282",
+          "categoryName": "Electronics"
+        },
+        "frequency": "daily",
+        "createdAt": "2025-01-01T12:00:00.000Z",
+        "nextRunAt": "2025-01-02T12:00:00.000Z",
+        "lastResult": {
+          "executedAt": "2025-01-01T12:00:00.000Z",
+          "products": [
+            { "rank": 1, "asin": "B0EXAMPLE1", "title": "Wireless Headphones", "price": 29.99, "rating": 4.5, "reviewCount": 12580 },
+            { "rank": 2, "asin": "B0EXAMPLE2", "title": "Bluetooth Speaker", "price": 39.99, "rating": 4.6, "reviewCount": 8900 }
+          ],
+          "changes": {
+            "newEntries": 3,
+            "removedEntries": 2,
+            "rankChanges": 15
+          }
+        },
+        "_source": "sorftime"
+      }
+    ],
+    "total": 5,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": false
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.6.3 `POST /api/clean/monitoring/asin/subscribe` — ASIN 订阅
+
+订阅单个 ASIN 的数据变化监控。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Sorftime | `MonitorApi.subscribeAsin` | `POST /api/sorftime/forward` -> `/api/AsinSubscribe` |
+
+**请求参数：**
+
+```typescript
+interface AsinSubscribeParams {
+  /** ASIN */
+  asin: string;
+  /** 市场域名 */
+  domain: string;
+  /** 监控频率 */
+  frequency: 'hourly' | 'daily' | 'weekly';
+  /** 监控指标 */
+  metrics: Array<'price' | 'bsr' | 'rating' | 'reviews' | 'sales' | 'sellers'>;
+  /** 通知方式 */
+  notifyType?: 'email' | 'webhook' | 'none';
+  /** 通知地址 */
+  notifyUrl?: string;
+  /** 变化阈值（百分比），超过阈值才通知 */
+  threshold?: number;
+}
+```
+
+**响应数据：**
+
+```typescript
+// 响应: ApiResponse<CleanSubscription>
+// 复用 CleanSubscription 类型，target 中包含 asin 字段
+```
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "SUB_ASIN_001",
+    "type": "asin",
+    "status": "active",
+    "target": {
+      "domain": "amazon.com",
+      "asin": "B0EXAMPLE1"
+    },
+    "frequency": "daily",
+    "createdAt": "2025-01-01T12:00:00.000Z",
+    "nextRunAt": "2025-01-02T12:00:00.000Z",
+    "_source": "sorftime"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+### 6.7 TikTok 社交媒体（TikHub）
+
+#### 6.7.1 `GET /api/clean/tiktok/users/:uniqueId` — 用户资料
+
+获取 TikTok 用户公开资料信息。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| TikHub | `TikTokUserApi.getUserProfile` | `GET /api/tikhub/tiktok/user/profile` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: uniqueId = TikTok 用户名
+interface TikTokUserParams {
+  /** 无额外参数 */
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanTikTokUser {
+  /** 用户 ID */
+  id: string;
+  /** 用户名 */
+  uniqueId: string;
+  /** 昵称 */
+  nickname: string;
+  /** 头像 URL */
+  avatarUrl: string;
+  /** 个人简介 */
+  bio: string;
+  /** 是否已认证 */
+  verified: boolean;
+  /** 粉丝数 */
+  followerCount: number;
+  /** 关注数 */
+  followingCount: number;
+  /** 获赞数 */
+  likeCount: number;
+  /** 视频数 */
+  videoCount: number;
+  /** 主页链接 */
+  profileUrl: string;
+  /** 关联商业信息 */
+  commerce: {
+    /** 是否开通商品橱窗 */
+    hasShop: boolean;
+    /** 商品数量 */
+    productCount: number | null;
+  } | null;
+  _source: 'tikhub';
+}
+
+// 响应: ApiResponse<CleanTikTokUser>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | TikHub 原始字段 |
+|-----------|----------------|
+| `id` | `user.id` |
+| `uniqueId` | `user.uniqueId` |
+| `nickname` | `user.nickname` |
+| `avatarUrl` | `user.avatarLarger` |
+| `bio` | `user.signature` |
+| `verified` | `user.verified` |
+| `followerCount` | `stats.followerCount` |
+| `followingCount` | `stats.followingCount` |
+| `likeCount` | `stats.heartCount` |
+| `videoCount` | `stats.videoCount` |
+| `commerce.hasShop` | `user.commerceUserInfo.commerceUser` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "6890000000000000000",
+    "uniqueId": "exampleuser",
+    "nickname": "Example Creator",
+    "avatarUrl": "https://p16-sign.tiktokcdn.com/example-avatar.jpg",
+    "bio": "Content creator | Product reviews",
+    "verified": true,
+    "followerCount": 1250000,
+    "followingCount": 320,
+    "likeCount": 45000000,
+    "videoCount": 580,
+    "profileUrl": "https://www.tiktok.com/@exampleuser",
+    "commerce": {
+      "hasShop": true,
+      "productCount": 25
+    },
+    "_source": "tikhub"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.7.2 `GET /api/clean/tiktok/videos/:id` — 视频详情
+
+获取 TikTok 视频详细信息。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| TikHub | `TikTokVideoApi.getVideoDetail` | `GET /api/tikhub/tiktok/video/detail` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = 视频 ID
+interface TikTokVideoParams {
+  /** 无额外参数 */
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanTikTokVideo {
+  /** 视频 ID */
+  id: string;
+  /** 视频描述 */
+  description: string;
+  /** 视频封面 URL */
+  coverUrl: string;
+  /** 视频播放 URL */
+  videoUrl: string;
+  /** 视频时长（秒） */
+  duration: number;
+  /** 创建时间 */
+  createdAt: string;
+  /** 作者信息 */
+  author: {
+    id: string;
+    uniqueId: string;
+    nickname: string;
+    avatarUrl: string;
+  };
+  /** 互动数据 */
+  stats: {
+    playCount: number;
+    likeCount: number;
+    commentCount: number;
+    shareCount: number;
+    collectCount: number;
+  };
+  /** 标签列表 */
+  hashtags: string[];
+  /** 音乐信息 */
+  music: {
+    id: string;
+    title: string;
+    author: string;
+    duration: number;
+  } | null;
+  /** 关联商品（如有） */
+  products: Array<{
+    id: string;
+    title: string;
+    price: number | null;
+    currency: string;
+    imageUrl: string;
+  }>;
+  _source: 'tikhub';
+}
+
+// 响应: ApiResponse<CleanTikTokVideo>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | TikHub 原始字段 |
+|-----------|----------------|
+| `id` | `itemInfo.itemStruct.id` |
+| `description` | `itemInfo.itemStruct.desc` |
+| `coverUrl` | `itemInfo.itemStruct.video.cover` |
+| `videoUrl` | `itemInfo.itemStruct.video.playAddr` |
+| `duration` | `itemInfo.itemStruct.video.duration` |
+| `createdAt` | `itemInfo.itemStruct.createTime` (Unix → ISO) |
+| `author.id` | `itemInfo.itemStruct.author.id` |
+| `author.uniqueId` | `itemInfo.itemStruct.author.uniqueId` |
+| `stats.playCount` | `itemInfo.itemStruct.stats.playCount` |
+| `stats.likeCount` | `itemInfo.itemStruct.stats.diggCount` |
+| `stats.commentCount` | `itemInfo.itemStruct.stats.commentCount` |
+| `stats.shareCount` | `itemInfo.itemStruct.stats.shareCount` |
+| `stats.collectCount` | `itemInfo.itemStruct.stats.collectCount` |
+| `hashtags` | `itemInfo.itemStruct.textExtra[].hashtagName` |
+| `music.id` | `itemInfo.itemStruct.music.id` |
+| `music.title` | `itemInfo.itemStruct.music.title` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "7300000000000000000",
+    "description": "Best wireless headphones under $30! #tech #headphones #review",
+    "coverUrl": "https://p16-sign.tiktokcdn.com/example-cover.jpg",
+    "videoUrl": "https://v16-webapp.tiktok.com/example-video.mp4",
+    "duration": 45,
+    "createdAt": "2025-01-10T15:30:00.000Z",
+    "author": {
+      "id": "6890000000000000000",
+      "uniqueId": "exampleuser",
+      "nickname": "Example Creator",
+      "avatarUrl": "https://p16-sign.tiktokcdn.com/example-avatar.jpg"
+    },
+    "stats": {
+      "playCount": 2500000,
+      "likeCount": 185000,
+      "commentCount": 3200,
+      "shareCount": 12000,
+      "collectCount": 45000
+    },
+    "hashtags": ["tech", "headphones", "review"],
+    "music": {
+      "id": "7200000000000000000",
+      "title": "Original Sound",
+      "author": "exampleuser",
+      "duration": 45
+    },
+    "products": [
+      {
+        "id": "PROD001",
+        "title": "Wireless Bluetooth Headphones",
+        "price": 29.99,
+        "currency": "USD",
+        "imageUrl": "https://p16-sign.tiktokcdn.com/product1.jpg"
+      }
+    ],
+    "_source": "tikhub"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.7.3 `GET /api/clean/tiktok/videos/:id/comments` — 视频评论
+
+获取 TikTok 视频评论列表。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| TikHub | `TikTokVideoApi.getVideoComments` | `GET /api/tikhub/tiktok/video/comments` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = 视频 ID
+interface TikTokCommentsParams extends PaginationParams {
+  /** 排序方式 */
+  sortBy?: 'likes' | 'date';
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanTikTokComment {
+  /** 评论 ID */
+  id: string;
+  /** 评论内容 */
+  content: string;
+  /** 评论时间 */
+  createdAt: string;
+  /** 点赞数 */
+  likeCount: number;
+  /** 回复数 */
+  replyCount: number;
+  /** 评论者信息 */
+  author: {
+    id: string;
+    uniqueId: string;
+    nickname: string;
+    avatarUrl: string;
+  };
+  _source: 'tikhub';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanTikTokComment>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | TikHub 原始字段 |
+|-----------|----------------|
+| `id` | `cid` |
+| `content` | `text` |
+| `createdAt` | `create_time` (Unix → ISO) |
+| `likeCount` | `digg_count` |
+| `replyCount` | `reply_comment_total` |
+| `author.id` | `user.uid` |
+| `author.uniqueId` | `user.unique_id` |
+| `author.nickname` | `user.nickname` |
+| `author.avatarUrl` | `user.avatar_thumb` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "id": "7300000000000000001",
+        "content": "Just bought these, they're amazing!",
+        "createdAt": "2025-01-10T16:00:00.000Z",
+        "likeCount": 520,
+        "replyCount": 12,
+        "author": {
+          "id": "6890000000000000001",
+          "uniqueId": "commenter1",
+          "nickname": "Happy Buyer",
+          "avatarUrl": "https://p16-sign.tiktokcdn.com/commenter1.jpg"
+        },
+        "_source": "tikhub"
+      }
+    ],
+    "total": 3200,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.7.4 `GET /api/clean/tiktok/shop/products/:id` — 商品详情
+
+获取 TikTok Shop 商品详情。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| TikHub | `TikTokShopApi.getProductDetail` | `GET /api/tikhub/tiktok/shop/product/detail` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = TikTok Shop 商品 ID
+interface TikTokShopProductParams {
+  /** 无额外参数 */
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanTikTokShopProduct {
+  /** 商品 ID */
+  id: string;
+  /** 商品标题 */
+  title: string;
+  /** 商品描述 */
+  description: string;
+  /** 商品图片列表 */
+  images: string[];
+  /** 价格 */
+  price: number;
+  /** 原价 */
+  originalPrice: number | null;
+  /** 货币代码 */
+  currency: string;
+  /** 销量 */
+  soldCount: number;
+  /** 评分 */
+  rating: number | null;
+  /** 评论数 */
+  reviewCount: number | null;
+  /** 店铺信息 */
+  shop: {
+    id: string;
+    name: string;
+    rating: number | null;
+    followerCount: number;
+  };
+  /** SKU 变体 */
+  skus: Array<{
+    id: string;
+    name: string;
+    price: number;
+    stock: number | null;
+    attributes: Record<string, string>;
+  }>;
+  /** 关联视频数 */
+  videoCount: number;
+  _source: 'tikhub';
+}
+
+// 响应: ApiResponse<CleanTikTokShopProduct>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | TikHub 原始字段 |
+|-----------|----------------|
+| `id` | `product_id` |
+| `title` | `product_name` |
+| `description` | `description` |
+| `images` | `images[].url_list[0]` |
+| `price` | `price.min_price` / 100 |
+| `originalPrice` | `price.original_price` / 100 |
+| `soldCount` | `sold_count` |
+| `rating` | `star_rating.average` |
+| `reviewCount` | `star_rating.count` |
+| `shop.id` | `shop_info.shop_id` |
+| `shop.name` | `shop_info.shop_name` |
+| `skus[].id` | `skus[].sku_id` |
+| `skus[].name` | `skus[].sku_name` |
+| `skus[].price` | `skus[].price.original_price` / 100 |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "1729000000000000000",
+    "title": "Wireless Bluetooth Headphones V5.3",
+    "description": "Premium wireless headphones with ANC...",
+    "images": [
+      "https://p16-oec-ttp.tiktokcdn.com/product1.jpg",
+      "https://p16-oec-ttp.tiktokcdn.com/product2.jpg"
+    ],
+    "price": 25.99,
+    "originalPrice": 49.99,
+    "currency": "USD",
+    "soldCount": 15800,
+    "rating": 4.7,
+    "reviewCount": 2350,
+    "shop": {
+      "id": "SHOP001",
+      "name": "TechGadgets Official",
+      "rating": 4.8,
+      "followerCount": 85000
+    },
+    "skus": [
+      { "id": "SKU001", "name": "Black", "price": 25.99, "stock": 500, "attributes": { "color": "Black" } },
+      { "id": "SKU002", "name": "White", "price": 25.99, "stock": 320, "attributes": { "color": "White" } }
+    ],
+    "videoCount": 45,
+    "_source": "tikhub"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.7.5 `GET /api/clean/tiktok/ads/:id` — 广告详情
+
+获取 TikTok 广告详情数据。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| TikHub | `TikTokAdsApi.getAdDetail` | `GET /api/tikhub/tiktok/ads/detail` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = 广告 ID
+interface TikTokAdParams {
+  /** 无额外参数 */
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanTikTokAd {
+  /** 广告 ID */
+  id: string;
+  /** 广告标题 */
+  title: string;
+  /** 广告描述 */
+  description: string;
+  /** 广告素材 URL */
+  mediaUrl: string;
+  /** 素材类型 */
+  mediaType: 'video' | 'image';
+  /** 广告主信息 */
+  advertiser: {
+    id: string;
+    name: string;
+    region: string;
+  };
+  /** 投放时间 */
+  startDate: string;
+  endDate: string | null;
+  /** 投放地区 */
+  targetRegions: string[];
+  /** 互动数据 */
+  stats: {
+    impressions: number | null;
+    clicks: number | null;
+    likeCount: number;
+    commentCount: number;
+    shareCount: number;
+  };
+  /** 落地页 URL */
+  landingPageUrl: string | null;
+  /** CTA 按钮文案 */
+  callToAction: string | null;
+  _source: 'tikhub';
+}
+
+// 响应: ApiResponse<CleanTikTokAd>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | TikHub 原始字段 |
+|-----------|----------------|
+| `id` | `ad_id` |
+| `title` | `ad_title` |
+| `description` | `ad_text` |
+| `mediaUrl` | `video_url` 或 `image_url` |
+| `mediaType` | 根据素材类型判断 |
+| `advertiser.id` | `advertiser_id` |
+| `advertiser.name` | `advertiser_name` |
+| `advertiser.region` | `advertiser_region` |
+| `startDate` | `first_shown_date` |
+| `endDate` | `last_shown_date` |
+| `targetRegions` | `target_countries[]` |
+| `stats.likeCount` | `digg_count` |
+| `stats.commentCount` | `comment_count` |
+| `stats.shareCount` | `share_count` |
+| `landingPageUrl` | `landing_page_url` |
+| `callToAction` | `cta_text` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "AD_001",
+    "title": "Best Wireless Headphones 2025",
+    "description": "Experience premium sound quality at an unbeatable price!",
+    "mediaUrl": "https://v16-webapp.tiktok.com/ad-video.mp4",
+    "mediaType": "video",
+    "advertiser": {
+      "id": "ADV001",
+      "name": "TechGadgets Inc.",
+      "region": "US"
+    },
+    "startDate": "2025-01-01T00:00:00.000Z",
+    "endDate": null,
+    "targetRegions": ["US", "CA", "GB"],
+    "stats": {
+      "impressions": null,
+      "clicks": null,
+      "likeCount": 8500,
+      "commentCount": 320,
+      "shareCount": 1200
+    },
+    "landingPageUrl": "https://www.tiktok.com/shop/product/1729000000000000000",
+    "callToAction": "Shop Now",
+    "_source": "tikhub"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+### 6.8 卖家信息（Amazon）
+
+#### 6.8.1 `GET /api/clean/sellers/account` — 卖家账户
+
+获取当前卖家的账户信息。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `SellersApi.getMarketplaceParticipations` | `GET /api/amazon/sellers/participations` |
+
+**请求参数：**
+
+```typescript
+interface SellerAccountParams {
+  /** 无额外参数 */
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanSellerAccount {
+  /** 卖家 ID */
+  id: string;
+  /** 卖家名称 */
+  name: string;
+  /** 账户类型 */
+  accountType: 'individual' | 'professional';
+  /** 已开通的市场列表 */
+  marketplaces: Array<{
+    id: string;
+    name: string;
+    country: string;
+    domain: string;
+    isActive: boolean;
+  }>;
+  /** 主要市场 */
+  primaryMarketplace: {
+    id: string;
+    name: string;
+    country: string;
+  };
+  _source: 'amazon';
+}
+
+// 响应: ApiResponse<CleanSellerAccount>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 |
+|-----------|----------------|
+| `id` | `participation.sellerId` |
+| `name` | `marketplace.name` (主市场) |
+| `marketplaces[].id` | `marketplace.id` |
+| `marketplaces[].name` | `marketplace.name` |
+| `marketplaces[].country` | `marketplace.countryCode` |
+| `marketplaces[].domain` | `marketplace.domainName` |
+| `marketplaces[].isActive` | `participation.isParticipating` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "A1EXAMPLE",
+    "name": "ExampleBrand Store",
+    "accountType": "professional",
+    "marketplaces": [
+      { "id": "ATVPDKIKX0DER", "name": "Amazon.com", "country": "US", "domain": "amazon.com", "isActive": true },
+      { "id": "A2EUQ1WTGCTBG2", "name": "Amazon.ca", "country": "CA", "domain": "amazon.ca", "isActive": true },
+      { "id": "A1F83G8C2ARO7P", "name": "Amazon.co.uk", "country": "GB", "domain": "amazon.co.uk", "isActive": false }
+    ],
+    "primaryMarketplace": {
+      "id": "ATVPDKIKX0DER",
+      "name": "Amazon.com",
+      "country": "US"
+    },
+    "_source": "amazon"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.8.2 `GET /api/clean/sellers/marketplaces` — 市场列表
+
+获取卖家已开通的市场列表及状态。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `SellersApi.getMarketplaceParticipations` | `GET /api/amazon/sellers/participations` |
+
+**请求参数：**
+
+```typescript
+interface MarketplaceListParams {
+  /** 是否只返回已激活的市场 */
+  activeOnly?: boolean;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanMarketplace {
+  /** 市场 ID */
+  id: string;
+  /** 市场名称 */
+  name: string;
+  /** 国家代码 */
+  country: string;
+  /** 域名 */
+  domain: string;
+  /** 默认语言 */
+  language: string;
+  /** 默认货币 */
+  currency: string;
+  /** 是否已激活 */
+  isActive: boolean;
+  /** 是否有 FBA 服务 */
+  hasFBA: boolean;
+  _source: 'amazon';
+}
+
+// 响应: ApiResponse<CleanMarketplace[]>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 |
+|-----------|----------------|
+| `id` | `marketplace.id` |
+| `name` | `marketplace.name` |
+| `country` | `marketplace.countryCode` |
+| `domain` | `marketplace.domainName` |
+| `language` | `marketplace.defaultLanguageCode` |
+| `currency` | `marketplace.defaultCurrencyCode` |
+| `isActive` | `participation.isParticipating` |
+| `hasFBA` | `participation.hasFulfillmentByAmazon` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "ATVPDKIKX0DER",
+      "name": "Amazon.com",
+      "country": "US",
+      "domain": "amazon.com",
+      "language": "en_US",
+      "currency": "USD",
+      "isActive": true,
+      "hasFBA": true,
+      "_source": "amazon"
+    },
+    {
+      "id": "A2EUQ1WTGCTBG2",
+      "name": "Amazon.ca",
+      "country": "CA",
+      "domain": "amazon.ca",
+      "language": "en_CA",
+      "currency": "CAD",
+      "isActive": true,
+      "hasFBA": true,
+      "_source": "amazon"
+    }
+  ],
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+### 6.9 退货相关（Amazon）
+
+#### 6.9.1 `GET /api/clean/returns` — 退货列表
+
+获取 Amazon 退货/退款列表。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `FBAReturnsApi.getReturns` | `GET /api/amazon/fba/returns` |
+
+**请求参数：**
+
+```typescript
+interface ReturnListParams extends PaginationParams {
+  marketplaceId?: string;
+  /** 退货状态 */
+  status?: 'pending' | 'approved' | 'completed' | 'rejected';
+  /** 开始日期 */
+  startDate?: string;
+  /** 结束日期 */
+  endDate?: string;
+  /** 按 ASIN 筛选 */
+  asin?: string;
+  /** 按订单号筛选 */
+  orderId?: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanReturn {
+  /** 退货 ID */
+  id: string;
+  /** 关联订单号 */
+  orderId: string;
+  /** ASIN */
+  asin: string;
+  /** SKU */
+  sku: string;
+  /** 商品标题 */
+  title: string;
+  /** 退货数量 */
+  quantity: number;
+  /** 退货状态 */
+  status: string;
+  /** 退货原因 */
+  reason: string;
+  /** 退货原因详情 */
+  reasonDetail: string | null;
+  /** 退款金额 */
+  refundAmount: number | null;
+  /** 货币代码 */
+  currency: string;
+  /** 退货发起时间 */
+  createdAt: string;
+  /** 退货完成时间 */
+  completedAt: string | null;
+  /** 商品状态 */
+  itemCondition: string | null;
+  _source: 'amazon';
+}
+
+// 响应: ApiResponse<PaginatedResponse<CleanReturn>>
+```
+
+**数据映射关系：**
+
+| 清洗后字段 | Amazon 原始字段 |
+|-----------|----------------|
+| `id` | `returnId` 或 `rmaId` |
+| `orderId` | `orderId` |
+| `asin` | `asin` |
+| `sku` | `sellerSKU` |
+| `title` | `productName` |
+| `quantity` | `quantity` |
+| `status` | `status` |
+| `reason` | `returnReason` |
+| `reasonDetail` | `customerComments` |
+| `refundAmount` | `refundAmount.Amount` |
+| `currency` | `refundAmount.CurrencyCode` |
+| `createdAt` | `returnRequestDate` |
+| `completedAt` | `returnClosedDate` |
+| `itemCondition` | `itemDisposition` |
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "id": "RET001",
+        "orderId": "111-1234567-1234567",
+        "asin": "B0EXAMPLE1",
+        "sku": "WH-BT-001",
+        "title": "Wireless Bluetooth Headphones",
+        "quantity": 1,
+        "status": "completed",
+        "reason": "DEFECTIVE",
+        "reasonDetail": "Left ear speaker not working",
+        "refundAmount": 29.99,
+        "currency": "USD",
+        "createdAt": "2025-01-20T10:00:00.000Z",
+        "completedAt": "2025-01-25T14:30:00.000Z",
+        "itemCondition": "Damaged",
+        "_source": "amazon"
+      }
+    ],
+    "total": 23,
+    "page": 1,
+    "pageSize": 20,
+    "hasMore": true
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+#### 6.9.2 `GET /api/clean/returns/:id` — 退货详情
+
+获取单个退货记录的详细信息。
+
+**数据来源：**
+| 平台 | 原始接口 | 原始路由 |
+|------|---------|---------|
+| Amazon | `FBAReturnsApi.getReturnDetail` | `GET /api/amazon/fba/returns/:returnId` |
+
+**请求参数：**
+
+```typescript
+// URL 参数: id = 退货 ID
+interface ReturnDetailParams {
+  marketplaceId?: string;
+}
+```
+
+**响应数据：**
+
+```typescript
+interface CleanReturnDetail extends CleanReturn {
+  /** 退货物流信息 */
+  shipping: {
+    carrier: string | null;
+    trackingNumber: string | null;
+    returnedAt: string | null;
+    receivedAt: string | null;
+  };
+  /** 退款明细 */
+  refundBreakdown: {
+    itemPrice: number;
+    shippingFee: number;
+    tax: number;
+    total: number;
+    currency: string;
+  } | null;
+  /** 处理记录 */
+  timeline: Array<{
+    date: string;
+    status: string;
+    description: string;
+  }>;
+  /** 替换订单号（如有） */
+  replacementOrderId: string | null;
+}
+
+// 响应: ApiResponse<CleanReturnDetail>
+```
+
+**响应示例：**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "RET001",
+    "orderId": "111-1234567-1234567",
+    "asin": "B0EXAMPLE1",
+    "sku": "WH-BT-001",
+    "title": "Wireless Bluetooth Headphones",
+    "quantity": 1,
+    "status": "completed",
+    "reason": "DEFECTIVE",
+    "reasonDetail": "Left ear speaker not working",
+    "refundAmount": 29.99,
+    "currency": "USD",
+    "createdAt": "2025-01-20T10:00:00.000Z",
+    "completedAt": "2025-01-25T14:30:00.000Z",
+    "itemCondition": "Damaged",
+    "shipping": {
+      "carrier": "UPS",
+      "trackingNumber": "1Z999AA10123456784",
+      "returnedAt": "2025-01-22T09:00:00.000Z",
+      "receivedAt": "2025-01-24T16:00:00.000Z"
+    },
+    "refundBreakdown": {
+      "itemPrice": 29.99,
+      "shippingFee": 0,
+      "tax": 2.70,
+      "total": 32.69,
+      "currency": "USD"
+    },
+    "timeline": [
+      { "date": "2025-01-20T10:00:00.000Z", "status": "requested", "description": "退货申请已提交" },
+      { "date": "2025-01-20T10:05:00.000Z", "status": "approved", "description": "退货申请已批准" },
+      { "date": "2025-01-22T09:00:00.000Z", "status": "shipped", "description": "买家已寄出退货商品" },
+      { "date": "2025-01-24T16:00:00.000Z", "status": "received", "description": "仓库已收到退货商品" },
+      { "date": "2025-01-25T14:30:00.000Z", "status": "completed", "description": "退款已处理完成" }
+    ],
+    "replacementOrderId": null,
+    "_source": "amazon"
+  },
+  "timestamp": "2025-01-01T12:00:00.000Z"
+}
+```
+
+---
+
+## 7. 前端调用示例
+
+### 7.1 创建统一请求客户端
+
+```typescript
+import axios, { AxiosInstance, AxiosResponse } from 'axios';
+
+/** 创建清洗接口专用客户端 */
+const cleanApiClient: AxiosInstance = axios.create({
+  baseURL: 'https://server-msq.fmode.cn/api/clean',
+  timeout: 30000,
+  headers: {
+    'Content-Type': 'application/json',
+  },
+});
+
+/** 响应拦截器：统一错误处理 */
+cleanApiClient.interceptors.response.use(
+  (response: AxiosResponse<ApiResponse<any>>) => {
+    const { data } = response;
+    if (data.code !== 0) {
+      return Promise.reject(new CleanApiError(data.code, data.message));
+    }
+    return response;
+  },
+  (error) => {
+    if (error.response) {
+      const { data } = error.response;
+      return Promise.reject(
+        new CleanApiError(data?.code || error.response.status, data?.message || '请求失败')
+      );
+    }
+    return Promise.reject(new CleanApiError(50001, '网络连接失败'));
+  }
+);
+
+/** 自定义错误类 */
+class CleanApiError extends Error {
+  code: number;
+  constructor(code: number, message: string) {
+    super(message);
+    this.code = code;
+    this.name = 'CleanApiError';
+  }
+}
+
+export { cleanApiClient, CleanApiError };
+```
+
+### 7.2 产品相关调用
+
+```typescript
+import { cleanApiClient } from './cleanApiClient';
+
+/** 搜索产品 */
+async function searchProducts(keyword: string, page = 1) {
+  const { data } = await cleanApiClient.get('/products/search', {
+    params: { keyword, page, pageSize: 20, source: 'all' },
+  });
+  return data.data; // PaginatedResponse<CleanProduct>
+}
+
+/** 获取产品详情（聚合多平台） */
+async function getProductDetail(asin: string) {
+  const { data } = await cleanApiClient.get(`/products/${asin}`, {
+    params: { source: 'all', includeTrend: true, trendStartDate: '2024-10-01', trendEndDate: '2025-01-01' },
+  });
+  return data.data; // CleanProductDetail
+}
+
+/** 获取产品销量数据 */
+async function getProductSales(asin: string, startDate: string, endDate: string) {
+  const { data } = await cleanApiClient.get(`/products/${asin}/sales`, {
+    params: { startDate, endDate, granularity: 'day', source: 'sorftime' },
+  });
+  return data.data; // CleanProductSales
+}
+
+/** 获取同类产品 */
+async function getSimilarProducts(asin: string) {
+  const { data } = await cleanApiClient.get(`/products/${asin}/similar`, {
+    params: { domain: 'amazon.com', page: 1, pageSize: 10 },
+  });
+  return data.data; // PaginatedResponse<CleanSimilarProduct>
+}
+```
+
+### 7.3 订单相关调用
+
+```typescript
+/** 获取订单列表 */
+async function getOrders(params: {
+  status?: string;
+  createdAfter?: string;
+  page?: number;
+}) {
+  const { data } = await cleanApiClient.get('/orders', {
+    params: { marketplaceId: 'ATVPDKIKX0DER', pageSize: 20, ...params },
+  });
+  return data.data; // PaginatedResponse<CleanOrder>
+}
+
+/** 获取订单详情 */
+async function getOrderDetail(orderId: string) {
+  const { data } = await cleanApiClient.get(`/orders/${orderId}`);
+  return data.data; // CleanOrderDetail
+}
+
+/** 获取订单统计 */
+async function getOrderMetrics(startDate: string, endDate: string) {
+  const { data } = await cleanApiClient.get('/orders/metrics', {
+    params: {
+      marketplaceId: 'ATVPDKIKX0DER',
+      granularity: 'week',
+      startDate,
+      endDate,
+    },
+  });
+  return data.data; // CleanOrderMetrics
+}
+```
+
+### 7.4 关键词相关调用
+
+```typescript
+/** 搜索关键词 */
+async function searchKeywords(keyword: string) {
+  const { data } = await cleanApiClient.get('/keywords/search', {
+    params: { keyword, domain: 'amazon.com', matchType: 'broad', page: 1, pageSize: 20 },
+  });
+  return data.data; // PaginatedResponse<CleanKeyword>
+}
+
+/** ASIN 反查关键词 */
+async function getReverseKeywords(asin: string) {
+  const { data } = await cleanApiClient.get(`/keywords/reverse/${asin}`, {
+    params: { domain: 'amazon.com', sortBy: 'searchVolume', sortOrder: 'desc' },
+  });
+  return data.data; // PaginatedResponse<CleanReverseKeyword>
+}
+
+/** 获取关键词趋势 */
+async function getKeywordTrend(keyword: string) {
+  const { data } = await cleanApiClient.get(`/keywords/${encodeURIComponent(keyword)}/trend`, {
+    params: { domain: 'amazon.com', period: '12m', granularity: 'month' },
+  });
+  return data.data; // CleanKeywordTrend
+}
+```
+
+### 7.5 TikTok 相关调用
+
+```typescript
+/** 获取 TikTok 用户资料 */
+async function getTikTokUser(uniqueId: string) {
+  const { data } = await cleanApiClient.get(`/tiktok/users/${uniqueId}`);
+  return data.data; // CleanTikTokUser
+}
+
+/** 获取 TikTok 视频详情 */
+async function getTikTokVideo(videoId: string) {
+  const { data } = await cleanApiClient.get(`/tiktok/videos/${videoId}`);
+  return data.data; // CleanTikTokVideo
+}
+
+/** 获取 TikTok 视频评论 */
+async function getTikTokComments(videoId: string, page = 1) {
+  const { data } = await cleanApiClient.get(`/tiktok/videos/${videoId}/comments`, {
+    params: { page, pageSize: 20, sortBy: 'likes' },
+  });
+  return data.data; // PaginatedResponse<CleanTikTokComment>
+}
+
+/** 获取 TikTok Shop 商品详情 */
+async function getTikTokShopProduct(productId: string) {
+  const { data } = await cleanApiClient.get(`/tiktok/shop/products/${productId}`);
+  return data.data; // CleanTikTokShopProduct
+}
+```
+
+### 7.6 错误处理最佳实践
+
+```typescript
+import { CleanApiError } from './cleanApiClient';
+
+async function fetchWithErrorHandling() {
+  try {
+    const products = await searchProducts('wireless headphones');
+    console.log('产品列表:', products.items);
+  } catch (error) {
+    if (error instanceof CleanApiError) {
+      switch (error.code) {
+        case 40001:
+          console.error('参数错误:', error.message);
+          break;
+        case 40101:
+        case 40102:
+          console.error('认证失败，请重新登录');
+          // 跳转登录页
+          break;
+        case 42901:
+          console.error('请求过于频繁，请稍后重试');
+          break;
+        case 50002:
+        case 50003:
+        case 50004:
+          console.error('上游服务异常:', error.message);
+          // 显示降级提示
+          break;
+        default:
+          console.error('未知错误:', error.code, error.message);
+      }
+    } else {
+      console.error('网络错误:', error);
+    }
+  }
+}
+```
+
+---
+
+## 附录：数据来源映射总表
+
+以下表格汇总了所有 `/api/clean/` 接口与原始平台接口的对应关系：
+
+| 清洗接口 | 方法 | 平台 | 原始接口 | 原始路由 |
+|---------|------|------|---------|---------|
+| `/api/clean/products/search` | GET | Amazon | `CatalogItemsApi.searchCatalogItems` | `GET /api/amazon/catalog/items` |
+| `/api/clean/products/search` | GET | Sorftime | `ProductApi.getProductQuery` | `POST /api/sorftime/forward` → `/api/ProductQuery` |
+| `/api/clean/products/:id` | GET | Amazon | `CatalogItemsApi.getCatalogItem` | `GET /api/amazon/catalog/items/:asin` |
+| `/api/clean/products/:id` | GET | Sorftime | `ProductApi.getProductRequest` | `POST /api/sorftime/forward` → `/api/ProductRequest` |
+| `/api/clean/products/:id/sales` | GET | Amazon | `SalesApi.getOrderMetrics` | `GET /api/amazon/sales/orderMetrics` |
+| `/api/clean/products/:id/sales` | GET | Sorftime | `ProductApi.getAsinSalesVolume` | `POST /api/sorftime/forward` → `/api/AsinSalesVolume` |
+| `/api/clean/products/:id/reviews` | GET | Amazon | `SellersApi.getCustomerFeedback` | `GET /api/amazon/sellers/feedback` |
+| `/api/clean/products/:id/reviews` | GET | Sorftime | `ProductApi.getProductReviewsQuery` | `POST /api/sorftime/forward` → `/api/ProductReviewsQuery` |
+| `/api/clean/products/:id/similar` | GET | Sorftime | `ProductApi.getSimilarProductRealtime` | `POST /api/sorftime/forward` → `/api/SimilarProductRealtimeRequest` |
+| `/api/clean/orders` | GET | Amazon | `OrdersApi.getOrders` | `GET /api/amazon/orders` |
+| `/api/clean/orders/:id` | GET | Amazon | `OrdersApi.getOrder` + `getOrderItems` | `GET /api/amazon/orders/:orderId` + `/items` |
+| `/api/clean/orders/metrics` | GET | Amazon | `SalesApi.getOrderMetrics` | `GET /api/amazon/sales/orderMetrics` |
+| `/api/clean/listings` | GET | Amazon | `ListingsApi.getListingsItems` | `GET /api/amazon/listings` |
+| `/api/clean/listings/:sku` | GET | Amazon | `ListingsApi.getListingsItem` | `GET /api/amazon/listings/:sku` |
+| `/api/clean/categories/tree` | GET | Sorftime | `CategoryApi.getCategoryTree` | `POST /api/sorftime/forward` → `/api/CategoryTree` |
+| `/api/clean/categories/:id/products` | GET | Sorftime | `CategoryApi.getCategoryProducts` | `POST /api/sorftime/forward` → `/api/CategoryProducts` |
+| `/api/clean/categories/:id/keywords` | GET | Sorftime | `CategoryApi.getCategoryKeywords` | `POST /api/sorftime/forward` → `/api/CategoryKeywords` |
+| `/api/clean/keywords/search` | GET | Sorftime | `KeywordApi.getKeywordSearch` | `POST /api/sorftime/forward` → `/api/KeywordSearch` |
+| `/api/clean/keywords/:keyword/products` | GET | Sorftime | `KeywordApi.getKeywordProducts` | `POST /api/sorftime/forward` → `/api/KeywordProducts` |
+| `/api/clean/keywords/reverse/:asin` | GET | Sorftime | `KeywordApi.getReverseAsin` | `POST /api/sorftime/forward` → `/api/ReverseAsin` |
+| `/api/clean/keywords/:keyword/trend` | GET | Sorftime | `KeywordApi.getKeywordTrend` | `POST /api/sorftime/forward` → `/api/KeywordTrend` |
+| `/api/clean/monitoring/bestseller/subscribe` | POST | Sorftime | `MonitorApi.subscribeBestSeller` | `POST /api/sorftime/forward` → `/api/BestSellerSubscribe` |
+| `/api/clean/monitoring/bestseller/tasks` | GET | Sorftime | `MonitorApi.getBestSellerTasks` | `POST /api/sorftime/forward` → `/api/BestSellerTasks` |
+| `/api/clean/monitoring/asin/subscribe` | POST | Sorftime | `MonitorApi.subscribeAsin` | `POST /api/sorftime/forward` → `/api/AsinSubscribe` |
+| `/api/clean/tiktok/users/:uniqueId` | GET | TikHub | `TikTokUserApi.getUserProfile` | `GET /api/tikhub/tiktok/user/profile` |
+| `/api/clean/tiktok/videos/:id` | GET | TikHub | `TikTokVideoApi.getVideoDetail` | `GET /api/tikhub/tiktok/video/detail` |
+| `/api/clean/tiktok/videos/:id/comments` | GET | TikHub | `TikTokVideoApi.getVideoComments` | `GET /api/tikhub/tiktok/video/comments` |
+| `/api/clean/tiktok/shop/products/:id` | GET | TikHub | `TikTokShopApi.getProductDetail` | `GET /api/tikhub/tiktok/shop/product/detail` |
+| `/api/clean/tiktok/ads/:id` | GET | TikHub | `TikTokAdsApi.getAdDetail` | `GET /api/tikhub/tiktok/ads/detail` |
+| `/api/clean/sellers/account` | GET | Amazon | `SellersApi.getMarketplaceParticipations` | `GET /api/amazon/sellers/participations` |
+| `/api/clean/sellers/marketplaces` | GET | Amazon | `SellersApi.getMarketplaceParticipations` | `GET /api/amazon/sellers/participations` |
+| `/api/clean/returns` | GET | Amazon | `FBAReturnsApi.getReturns` | `GET /api/amazon/fba/returns` |
+| `/api/clean/returns/:id` | GET | Amazon | `FBAReturnsApi.getReturnDetail` | `GET /api/amazon/fba/returns/:returnId` |

docs/api/instagram/api接口.md

@@ -1,6 +1,6 @@
 # 搜索用户/话题/地点/Search users/hashtags/places
 - GET
-https://api.tikhub.io/api/v1/instagram/v1/fetch_search
+https://server.fmode.cn/thapi/v1/instagram/v1/fetch_search
 Instagram-V1-API
 Last modified:
 2 days ago
@@ -70,7 +70,7 @@ var requestOptions = {
    redirect: 'follow'
 };
 
-fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_search?query=taylorswift&select", requestOptions)
+fetch("https://server.fmode.cn/thapi/v1/instagram/v1/fetch_search?query=taylorswift&select", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
@@ -78,7 +78,7 @@ fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_search?query=taylorswift&
 
 # 根据用户名获取用户数据V3/Get user data by username V3
 - GET
-https://api.tikhub.io/api/v1/instagram/v1/fetch_user_info_by_username_v3
+https://server.fmode.cn/thapi/v1/instagram/v1/fetch_user_info_by_username_v3
 Instagram-V1-API
 Last modified:
 2 days ago
@@ -151,7 +151,7 @@ var requestOptions = {
    redirect: 'follow'
 };
 
-fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_user_info_by_username_v3?username=instagram", requestOptions)
+fetch("https://server.fmode.cn/thapi/v1/instagram/v1/fetch_user_info_by_username_v3?username=instagram", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
@@ -159,7 +159,7 @@ fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_user_info_by_username_v3?
 
 # 获取用户Reels列表/Get user Reels list
 - GET
-https://api.tikhub.io/api/v1/instagram/v1/fetch_user_reels
+https://server.fmode.cn/thapi/v1/instagram/v1/fetch_user_reels
 Instagram-V1-API
 Last modified:
 2 days ago
@@ -229,14 +229,14 @@ var requestOptions = {
    redirect: 'follow'
 };
 
-fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_user_reels?user_id=25025320&count&max_id", requestOptions)
+fetch("https://server.fmode.cn/thapi/v1/instagram/v1/fetch_user_reels?user_id=25025320&count&max_id", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
 
 # 获取用户帖子列表V2/Get user posts list V2
 - GET
-https://api.tikhub.io/api/v1/instagram/v1/fetch_user_posts_v2
+https://server.fmode.cn/thapi/v1/instagram/v1/fetch_user_posts_v2
 Instagram-V1-API
 Last modified:
 2 days ago
@@ -304,7 +304,7 @@ var requestOptions = {
    redirect: 'follow'
 };
 
-fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_user_posts_v2?user_id=25025320&count&end_cursor", requestOptions)
+fetch("https://server.fmode.cn/thapi/v1/instagram/v1/fetch_user_posts_v2?user_id=25025320&count&end_cursor", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
@@ -312,7 +312,7 @@ fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_user_posts_v2?user_id=250
 
 # 获取帖子评论列表V2/Get post comments V2
 - GET
-https://api.tikhub.io/api/v1/instagram/v1/fetch_post_comments_v2
+https://server.fmode.cn/thapi/v1/instagram/v1/fetch_post_comments_v2
 Instagram-V1-API
 Last modified:
 2 days ago
@@ -409,7 +409,7 @@ var requestOptions = {
    redirect: 'follow'
 };
 
-fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_post_comments_v2?media_id=3766120364183949816&sort_order=recent&min_id=", requestOptions)
+fetch("https://server.fmode.cn/thapi/v1/instagram/v1/fetch_post_comments_v2?media_id=3766120364183949816&sort_order=recent&min_id=", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
@@ -417,7 +417,7 @@ fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_post_comments_v2?media_id
 # 获取评论的子评论列表/Get comment replies
 
 - GET
-https://api.tikhub.io/api/v1/instagram/v1/fetch_comment_replies
+https://server.fmode.cn/thapi/v1/instagram/v1/fetch_comment_replies
 Instagram-V1-API
 Last modified:
 2 days ago
@@ -507,14 +507,14 @@ var requestOptions = {
    redirect: 'follow'
 };
 
-fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_comment_replies?media_id=3766120364183949816&comment_id=17871667485468098&min_id=", requestOptions)
+fetch("https://server.fmode.cn/thapi/v1/instagram/v1/fetch_comment_replies?media_id=3766120364183949816&comment_id=17871667485468098&min_id=", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
 
 # 通过ID获取帖子详情/Get post by ID
 GET
-https://api.tikhub.io/api/v1/instagram/v1/fetch_post_by_id
+https://server.fmode.cn/thapi/v1/instagram/v1/fetch_post_by_id
 Instagram-V1-API
 Last modified:
 2 days ago
@@ -564,7 +564,7 @@ var requestOptions = {
    redirect: 'follow'
 };
 
-fetch("https://api.tikhub.io/api/v1/instagram/v1/fetch_post_by_id?post_id=3742637871112032100", requestOptions)
+fetch("https://server.fmode.cn/thapi/v1/instagram/v1/fetch_post_by_id?post_id=3742637871112032100", requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));

docs/api/sorftime/frontend_guide.md

@@ -0,0 +1,312 @@
+# 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: "积分余额不足"}`

modules/fmode-tikhub-server/src/client.ts

@@ -3,7 +3,7 @@ import { TikHubConfig } from './types.ts';
 
 /**
  * TikHub 客户端
- * 直接调用 api.tikhub.io 的 API
+ * 直接调用 server.fmode.cn/thapi 代理 API
  * 使用原生 fetch 替代 axios
  */
 export class TikHubClient {