wurenzhi
2b86715c09
- 移除未使用的TabPane组件 - 修复类型定义和导入方式 - 优化mock数据源的环境变量判断逻辑 - 更新文档结构并归档旧文件 - 添加新的UI组件和Memo组件 - 调整API路径和响应处理
349 lines
14 KiB
Markdown
349 lines
14 KiB
Markdown
# 多平台API集成方案
|
||
|
||
> **状态**: 🗄️ 已归档
|
||
> **归档原因**: 方案未实施，代码中不存在相关实现
|
||
> **归档日期**: 2026-03-23
|
||
> **原位置**: docs/API_Integration_Plan.md
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
本方案旨在将Shopee、Temu和TikTok三个跨境电商平台的API集成到现有代码中，实现统一的接口调用和数据管理。通过构建一个抽象层，屏蔽不同平台API的差异，为应用提供统一的访问接口。
|
||
|
||
## 2. 架构设计
|
||
|
||
### 2.1 整体架构
|
||
|
||
```
|
||
┌───────────────────────────────────────────────────────────┐
|
||
│ 应用层 │
|
||
│ (业务逻辑、UI组件、数据展示) │
|
||
└───────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌───────────────────────────────────────────────────────────┐
|
||
│ 服务层 (Service) │
|
||
│ (业务逻辑编排、数据转换、错误处理) │
|
||
└───────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌───────────────────────────────────────────────────────────┐
|
||
│ API客户端层 (Client) │
|
||
│ (平台特定API调用、认证管理、请求构建) │
|
||
└───────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌───────────────────────────────────────────────────────────┐
|
||
│ 平台API (External) │
|
||
│ (Shopee API / Temu API / TikTok API) │
|
||
└───────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 目录结构
|
||
|
||
```
|
||
src/
|
||
├── services/ # 服务层
|
||
│ ├── ShopeeService.ts # Shopee平台服务
|
||
│ ├── TemuService.ts # Temu平台服务
|
||
│ ├── TikTokService.ts # TikTok平台服务
|
||
│ └── MultiPlatformService.ts # 多平台统一服务
|
||
├── clients/ # API客户端层
|
||
│ ├── shopee/ # Shopee API客户端
|
||
│ │ ├── index.ts
|
||
│ │ ├── auth.ts
|
||
│ │ ├── product.ts
|
||
│ │ ├── order.ts
|
||
│ │ └── logistics.ts
|
||
│ ├── temu/ # Temu API客户端
|
||
│ │ ├── index.ts
|
||
│ │ ├── auth.ts
|
||
│ │ ├── product.ts
|
||
│ │ ├── order.ts
|
||
│ │ └── logistics.ts
|
||
│ └── tiktok/ # TikTok API客户端
|
||
│ ├── index.ts
|
||
│ ├── auth.ts
|
||
│ ├── product.ts
|
||
│ ├── order.ts
|
||
│ └── logistics.ts
|
||
├── models/ # 数据模型
|
||
│ ├── common/ # 通用数据模型
|
||
│ │ ├── Product.ts
|
||
│ │ ├── Order.ts
|
||
│ │ ├── Inventory.ts
|
||
│ │ └── Logistics.ts
|
||
│ └── platform/ # 平台特定数据模型
|
||
│ ├── Shopee.ts
|
||
│ ├── Temu.ts
|
||
│ └── TikTok.ts
|
||
├── utils/ # 工具函数
|
||
│ ├── auth.ts # 认证相关工具
|
||
│ ├── http.ts # HTTP请求工具
|
||
│ └── sign.ts # 签名生成工具
|
||
└── config/ # 配置文件
|
||
├── platforms.ts # 平台配置
|
||
└── api.ts # API配置
|
||
```
|
||
|
||
## 3. 核心组件设计
|
||
|
||
### 3.1 认证管理
|
||
|
||
| 组件 | 功能 | 实现方式 |
|
||
|------|------|----------|
|
||
| AuthManager | 管理不同平台的认证流程 | 工厂模式，根据平台类型创建对应认证管理器 |
|
||
| ShopeeAuth | Shopee平台认证 | 实现OAuth 2.0流程，支持v1和v2版本 |
|
||
| TemuAuth | Temu平台认证 | 实现API密钥认证和OAuth 2.0 |
|
||
| TikTokAuth | TikTok平台认证 | 实现OAuth 2.0流程，支持令牌刷新 |
|
||
|
||
### 3.2 API客户端
|
||
|
||
| 组件 | 功能 | 实现方式 |
|
||
|------|------|----------|
|
||
| ShopeeClient | Shopee API调用 | 封装Shopee API的所有端点，处理请求签名和认证 |
|
||
| TemuClient | Temu API调用 | 封装Temu API的所有端点，处理请求签名和认证 |
|
||
| TikTokClient | TikTok API调用 | 封装TikTok API的所有端点，处理请求签名和认证 |
|
||
| ClientFactory | 客户端工厂 | 根据平台类型创建对应API客户端 |
|
||
|
||
### 3.3 服务层
|
||
|
||
| 组件 | 功能 | 实现方式 |
|
||
|------|------|----------|
|
||
| ShopeeService | Shopee平台业务逻辑 | 调用ShopeeClient，处理业务逻辑，转换数据模型 |
|
||
| TemuService | Temu平台业务逻辑 | 调用TemuClient，处理业务逻辑，转换数据模型 |
|
||
| TikTokService | TikTok平台业务逻辑 | 调用TikTokClient，处理业务逻辑，转换数据模型 |
|
||
| MultiPlatformService | 多平台统一服务 | 整合多个平台服务，提供统一接口 |
|
||
|
||
### 3.4 数据模型
|
||
|
||
| 组件 | 功能 | 实现方式 |
|
||
|------|------|----------|
|
||
| BaseProduct | 基础商品模型 | 定义通用商品属性 |
|
||
| BaseOrder | 基础订单模型 | 定义通用订单属性 |
|
||
| BaseInventory | 基础库存模型 | 定义通用库存属性 |
|
||
| BaseLogistics | 基础物流模型 | 定义通用物流属性 |
|
||
| PlatformProduct | 平台特定商品模型 | 继承BaseProduct，添加平台特定属性 |
|
||
| PlatformOrder | 平台特定订单模型 | 继承BaseOrder，添加平台特定属性 |
|
||
|
||
## 4. 功能模块设计
|
||
|
||
### 4.1 商品管理
|
||
|
||
| 功能 | 实现方式 | 涉及API |
|
||
|------|----------|----------|
|
||
| 商品列表 | 统一调用各平台商品列表API，转换为通用数据模型 | Shopee: /product/get_list<br>Temu: /api/v1/product/search<br>TikTok: /product/202405/products |
|
||
| 商品详情 | 统一调用各平台商品详情API，转换为通用数据模型 | Shopee: /product/get<br>Temu: /api/v1/product/detail<br>TikTok: /product/202405/product/detail |
|
||
| 商品创建 | 统一调用各平台商品创建API，转换为平台特定格式 | Shopee: /product/create<br>Temu: /api/v1/product/create<br>TikTok: /product/202405/product/create |
|
||
| 商品更新 | 统一调用各平台商品更新API，转换为平台特定格式 | Shopee: /product/update<br>Temu: /api/v1/product/update<br>TikTok: /product/202405/product/update |
|
||
| 商品上下架 | 统一调用各平台商品状态更新API | Shopee: /product/update_status<br>Temu: /api/v1/product/status/update<br>TikTok: /product/202405/product/status/update |
|
||
|
||
### 4.2 订单管理
|
||
|
||
| 功能 | 实现方式 | 涉及API |
|
||
|------|----------|----------|
|
||
| 订单列表 | 统一调用各平台订单列表API，转换为通用数据模型 | Shopee: /order/list<br>Temu: /api/v1/order/list<br>TikTok: /order/202405/orders |
|
||
| 订单详情 | 统一调用各平台订单详情API，转换为通用数据模型 | Shopee: /order/detail<br>Temu: /api/v1/order/detail<br>TikTok: /order/202405/order/detail |
|
||
| 订单发货 | 统一调用各平台订单发货API，转换为平台特定格式 | Shopee: /order/ship<br>Temu: /api/v1/order/ship<br>TikTok: /order/202405/order/ship |
|
||
| 订单取消 | 统一调用各平台订单取消API，转换为平台特定格式 | Shopee: /order/cancel<br>Temu: /api/v1/order/cancel<br>TikTok: /order/202405/order/cancel |
|
||
|
||
### 4.3 库存管理
|
||
|
||
| 功能 | 实现方式 | 涉及API |
|
||
|------|----------|----------|
|
||
| 库存查询 | 统一调用各平台库存查询API，转换为通用数据模型 | Shopee: /inventory/get<br>Temu: /api/v1/inventory/query<br>TikTok: /inventory/202405/inventory |
|
||
| 库存更新 | 统一调用各平台库存更新API，转换为平台特定格式 | Shopee: /inventory/update<br>Temu: /api/v1/inventory/update<br>TikTok: /inventory/202405/inventory/update |
|
||
| 批量库存更新 | 统一调用各平台批量库存更新API | Shopee: /inventory/batch_update<br>Temu: /api/v1/inventory/batch/update<br>TikTok: /inventory/202405/inventory/batch/update |
|
||
|
||
### 4.4 物流管理
|
||
|
||
| 功能 | 实现方式 | 涉及API |
|
||
|------|----------|----------|
|
||
| 物流查询 | 统一调用各平台物流查询API，转换为通用数据模型 | Shopee: /logistics/tracking<br>Temu: /api/v1/logistics/tracking<br>TikTok: /logistics/202405/logistics/tracking |
|
||
| 物流公司列表 | 统一调用各平台物流公司列表API | Shopee: /logistics/companies<br>Temu: /api/v1/logistics/companies<br>TikTok: /logistics/202405/logistics/companies |
|
||
|
||
### 4.5 财务管理
|
||
|
||
| 功能 | 实现方式 | 涉及API |
|
||
|------|----------|----------|
|
||
| 账户余额 | 统一调用各平台账户余额API，转换为通用数据模型 | Shopee: /finance/balance<br>Temu: /api/v1/finance/balance<br>TikTok: /finance/202405/balance |
|
||
| 交易记录 | 统一调用各平台交易记录API，转换为通用数据模型 | Shopee: /finance/transactions<br>Temu: /api/v1/finance/transactions<br>TikTok: /finance/202405/transactions |
|
||
| 结算单 | 统一调用各平台结算单API，转换为通用数据模型 | Shopee: /finance/settlements<br>Temu: /api/v1/finance/settlements<br>TikTok: /finance/202405/settlements |
|
||
|
||
## 5. 技术实现细节
|
||
|
||
### 5.1 认证流程
|
||
|
||
1. **Shopee认证流程**:
|
||
- 生成授权链接
|
||
- 用户授权获取code
|
||
- 使用code获取access_token
|
||
- 保存access_token和refresh_token
|
||
- 定期刷新access_token
|
||
|
||
2. **Temu认证流程**:
|
||
- 使用API Key和API Secret进行认证
|
||
- 生成签名
|
||
- 调用API时携带认证信息
|
||
|
||
3. **TikTok认证流程**:
|
||
- 生成授权链接
|
||
- 用户授权获取code
|
||
- 使用code获取access_token
|
||
- 保存access_token和refresh_token
|
||
- 定期刷新access_token
|
||
|
||
### 5.2 请求签名
|
||
|
||
1. **Shopee签名**:
|
||
- 按字典序排序参数
|
||
- 拼接参数
|
||
- 添加secret
|
||
- 使用SHA256生成签名
|
||
|
||
2. **Temu签名**:
|
||
- 按字典序排序参数
|
||
- 拼接参数
|
||
- 添加api_secret
|
||
- 使用SHA256生成签名
|
||
|
||
3. **TikTok签名**:
|
||
- 按字典序排序参数
|
||
- 拼接参数
|
||
- 添加app_secret
|
||
- 使用MD5或SHA256生成签名
|
||
|
||
### 5.3 数据转换
|
||
|
||
1. **商品数据转换**:
|
||
- 定义通用商品模型
|
||
- 实现平台特定模型到通用模型的转换
|
||
- 实现通用模型到平台特定模型的转换
|
||
|
||
2. **订单数据转换**:
|
||
- 定义通用订单模型
|
||
- 实现平台特定模型到通用模型的转换
|
||
- 实现通用模型到平台特定模型的转换
|
||
|
||
3. **库存数据转换**:
|
||
- 定义通用库存模型
|
||
- 实现平台特定模型到通用模型的转换
|
||
- 实现通用模型到平台特定模型的转换
|
||
|
||
### 5.4 错误处理
|
||
|
||
1. **统一错误码**:
|
||
- 定义跨平台的统一错误码
|
||
- 映射平台特定错误码到统一错误码
|
||
- 提供统一的错误处理机制
|
||
|
||
2. **重试机制**:
|
||
- 实现请求重试逻辑
|
||
- 处理网络错误和临时错误
|
||
- 设置合理的重试间隔和次数
|
||
|
||
### 5.5 缓存策略
|
||
|
||
1. **访问令牌缓存**:
|
||
- 缓存access_token
|
||
- 定期检查过期时间
|
||
- 自动刷新即将过期的令牌
|
||
|
||
2. **API响应缓存**:
|
||
- 缓存频繁访问的数据
|
||
- 设置合理的缓存过期时间
|
||
- 提供缓存失效机制
|
||
|
||
## 6. 配置管理
|
||
|
||
### 6.1 平台配置
|
||
|
||
| 配置项 | 描述 | 示例值 |
|
||
|--------|------|--------|
|
||
| apiKey | 平台API密钥 | "1234567890" |
|
||
| apiSecret | 平台API密钥密钥 | "abcdefghij" |
|
||
| redirectUrl | 授权回调URL | "https://example.com/callback" |
|
||
| apiBaseUrl | API基础URL | "https://partner.shopeemobile.com" |
|
||
| authBaseUrl | 认证基础URL | "https://auth.tiktok-shops.com" |
|
||
| scope | 授权范围 | ["seller.product.read", "seller.order.read"] |
|
||
| rateLimit | API调用频率限制 | { "requests": 60, "interval": "minute" } |
|
||
|
||
### 6.2 环境配置
|
||
|
||
| 配置项 | 描述 | 开发环境 | 生产环境 |
|
||
|--------|------|----------|----------|
|
||
| API环境 | API调用环境 | sandbox | production |
|
||
| 日志级别 | 日志记录级别 | debug | info |
|
||
| 缓存时间 | 缓存有效期 | 5分钟 | 30分钟 |
|
||
| 重试次数 | 请求失败重试次数 | 3 | 5 |
|
||
|
||
## 7. 集成步骤
|
||
|
||
### 7.1 准备工作
|
||
|
||
1. **注册开发者账号**:
|
||
- 在Shopee Open Platform注册账号
|
||
- 在Temu Partner Platform注册账号
|
||
- 在TikTok Shop Partner Center注册账号
|
||
|
||
2. **创建应用**:
|
||
- 在各平台创建应用
|
||
- 获取API密钥和密钥
|
||
- 配置回调URL
|
||
|
||
3. **配置权限**:
|
||
- 在各平台申请必要的API权限
|
||
- 确保应用通过审核
|
||
|
||
### 7.2 代码实现
|
||
|
||
1. **创建目录结构**:
|
||
- 按照设计的目录结构创建文件
|
||
- 初始化基础代码框架
|
||
|
||
2. **实现认证管理**:
|
||
- 实现各平台的认证流程
|
||
- 实现令牌刷新机制
|
||
- 实现签名生成
|
||
|
||
3. **实现API客户端**:
|
||
- 实现各平台的API客户端
|
||
- 实现请求签名
|
||
- 实现错误处理
|
||
|
||
4. **实现服务层**:
|
||
- 实现各平台的服务
|
||
- 实现数据转换
|
||
- 实现业务逻辑
|
||
|
||
5. **实现多平台统一服务**:
|
||
- 整合各平台服务
|
||
- 提供统一接口
|
||
- 实现平台切换
|
||
|
||
## 8. 测试策略
|
||
|
||
### 8.1 单元测试
|
||
|
||
- 测试认证流程
|
||
- 测试API客户端
|
||
- 测试数据转换
|
||
- 测试错误处理
|
||
|
||
### 8.2 集成测试
|
||
|
||
- 测试完整的API调用流程
|
||
- 测试多平台切换
|
||
- 测试错误恢复
|
||
|
||
### 8.3 端到端测试
|
||
|
||
- 测试完整的业务场景
|
||
- 测试性能
|
||
- 测试稳定性
|
||
|
||
---
|
||
|
||
*本文档已归档，仅作为历史参考*
|