Files

wurenzhi 2b86715c09 refactor: 优化代码结构并修复类型问题

- 移除未使用的TabPane组件
- 修复类型定义和导入方式
- 优化mock数据源的环境变量判断逻辑
- 更新文档结构并归档旧文件
- 添加新的UI组件和Memo组件
- 调整API路径和响应处理

2026-03-23 12:41:35 +08:00

14 KiB

Raw Blame History

多平台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 Temu: /api/v1/product/search TikTok: /product/202405/products
商品详情	统一调用各平台商品详情API，转换为通用数据模型	Shopee: /product/get Temu: /api/v1/product/detail TikTok: /product/202405/product/detail
商品创建	统一调用各平台商品创建API，转换为平台特定格式	Shopee: /product/create Temu: /api/v1/product/create TikTok: /product/202405/product/create
商品更新	统一调用各平台商品更新API，转换为平台特定格式	Shopee: /product/update Temu: /api/v1/product/update TikTok: /product/202405/product/update
商品上下架	统一调用各平台商品状态更新API	Shopee: /product/update_status Temu: /api/v1/product/status/update TikTok: /product/202405/product/status/update

4.2 订单管理

功能	实现方式	涉及API
订单列表	统一调用各平台订单列表API，转换为通用数据模型	Shopee: /order/list Temu: /api/v1/order/list TikTok: /order/202405/orders
订单详情	统一调用各平台订单详情API，转换为通用数据模型	Shopee: /order/detail Temu: /api/v1/order/detail TikTok: /order/202405/order/detail
订单发货	统一调用各平台订单发货API，转换为平台特定格式	Shopee: /order/ship Temu: /api/v1/order/ship TikTok: /order/202405/order/ship
订单取消	统一调用各平台订单取消API，转换为平台特定格式	Shopee: /order/cancel Temu: /api/v1/order/cancel TikTok: /order/202405/order/cancel

4.3 库存管理

功能	实现方式	涉及API
库存查询	统一调用各平台库存查询API，转换为通用数据模型	Shopee: /inventory/get Temu: /api/v1/inventory/query TikTok: /inventory/202405/inventory
库存更新	统一调用各平台库存更新API，转换为平台特定格式	Shopee: /inventory/update Temu: /api/v1/inventory/update TikTok: /inventory/202405/inventory/update
批量库存更新	统一调用各平台批量库存更新API	Shopee: /inventory/batch_update Temu: /api/v1/inventory/batch/update TikTok: /inventory/202405/inventory/batch/update

4.4 物流管理

功能	实现方式	涉及API
物流查询	统一调用各平台物流查询API，转换为通用数据模型	Shopee: /logistics/tracking Temu: /api/v1/logistics/tracking TikTok: /logistics/202405/logistics/tracking
物流公司列表	统一调用各平台物流公司列表API	Shopee: /logistics/companies Temu: /api/v1/logistics/companies TikTok: /logistics/202405/logistics/companies

4.5 财务管理

功能	实现方式	涉及API
账户余额	统一调用各平台账户余额API，转换为通用数据模型	Shopee: /finance/balance Temu: /api/v1/finance/balance TikTok: /finance/202405/balance
交易记录	统一调用各平台交易记录API，转换为通用数据模型	Shopee: /finance/transactions Temu: /api/v1/finance/transactions TikTok: /finance/202405/transactions
结算单	统一调用各平台结算单API，转换为通用数据模型	Shopee: /finance/settlements Temu: /api/v1/finance/settlements TikTok: /finance/202405/settlements

5. 技术实现细节

5.1 认证流程

Shopee认证流程:
- 生成授权链接
- 用户授权获取code
- 使用code获取access_token
- 保存access_token和refresh_token
- 定期刷新access_token
Temu认证流程:
- 使用API Key和API Secret进行认证
- 生成签名
- 调用API时携带认证信息
TikTok认证流程:
- 生成授权链接
- 用户授权获取code
- 使用code获取access_token
- 保存access_token和refresh_token
- 定期刷新access_token

5.2 请求签名

Shopee签名:
- 按字典序排序参数
- 拼接参数
- 添加secret
- 使用SHA256生成签名
Temu签名:
- 按字典序排序参数
- 拼接参数
- 添加api_secret
- 使用SHA256生成签名
TikTok签名:
- 按字典序排序参数
- 拼接参数
- 添加app_secret
- 使用MD5或SHA256生成签名

5.3 数据转换

商品数据转换:
- 定义通用商品模型
- 实现平台特定模型到通用模型的转换
- 实现通用模型到平台特定模型的转换
订单数据转换:
- 定义通用订单模型
- 实现平台特定模型到通用模型的转换
- 实现通用模型到平台特定模型的转换
库存数据转换:
- 定义通用库存模型
- 实现平台特定模型到通用模型的转换
- 实现通用模型到平台特定模型的转换

5.4 错误处理

统一错误码:
- 定义跨平台的统一错误码
- 映射平台特定错误码到统一错误码
- 提供统一的错误处理机制
重试机制:
- 实现请求重试逻辑
- 处理网络错误和临时错误
- 设置合理的重试间隔和次数

5.5 缓存策略

访问令牌缓存:
- 缓存access_token
- 定期检查过期时间
- 自动刷新即将过期的令牌
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 准备工作

注册开发者账号:
- 在Shopee Open Platform注册账号
- 在Temu Partner Platform注册账号
- 在TikTok Shop Partner Center注册账号
创建应用:
- 在各平台创建应用
- 获取API密钥和密钥
- 配置回调URL
配置权限:
- 在各平台申请必要的API权限
- 确保应用通过审核

7.2 代码实现

创建目录结构:
- 按照设计的目录结构创建文件
- 初始化基础代码框架
实现认证管理:
- 实现各平台的认证流程
- 实现令牌刷新机制
- 实现签名生成
实现API客户端:
- 实现各平台的API客户端
- 实现请求签名
- 实现错误处理
实现服务层:
- 实现各平台的服务
- 实现数据转换
- 实现业务逻辑
实现多平台统一服务:
- 整合各平台服务
- 提供统一接口
- 实现平台切换

8. 测试策略

8.1 单元测试

测试认证流程
测试API客户端
测试数据转换
测试错误处理

8.2 集成测试

测试完整的API调用流程
测试多平台切换
测试错误恢复

8.3 端到端测试

测试完整的业务场景
测试性能
测试稳定性

本文档已归档，仅作为历史参考

14 KiB Raw Blame History Unescape Escape

多平台API集成方案

1. 概述

2. 架构设计

2.1 整体架构

2.2 目录结构

3. 核心组件设计

3.1 认证管理

3.2 API客户端

3.3 服务层

3.4 数据模型

4. 功能模块设计

4.1 商品管理

4.2 订单管理

4.3 库存管理

4.4 物流管理

4.5 财务管理

5. 技术实现细节

5.1 认证流程

5.2 请求签名

5.3 数据转换

5.4 错误处理

5.5 缓存策略

6. 配置管理

6.1 平台配置

6.2 环境配置

7. 集成步骤

7.1 准备工作

7.2 代码实现

8. 测试策略

8.1 单元测试

8.2 集成测试

8.3 端到端测试

14 KiB

Raw Blame History