任务：亚马逊 SP-API 模块开发

任务概述

开发 fmode-amazon-sp-api 模块，集成亚马逊 Selling Partner API (SP-API)，首期对接客户反馈 (Customer Feedback) 相关接口。 注意：本模块采用 2023 年 10 月 2 日后的简化授权流程，无需 AWS IAM 配置，仅需 LWA Access Token。

API 规格

Customer Feedback (客户反馈)

API 名称: getItemReviewTopics
功能: 检索某件商品的十个最正面和十个最负面的评论主题。
API 地址: https://sellingpartnerapi-na.amazon.com/customerFeedback/2024-06-01/items/{asin}/reviews/topics
请求方法: GET
认证方式: LWA (Login with Amazon) Access Token (无需 AWS Signature V4)
参考文档: docs/亚马逊需要对接的接口.md

模块结构

modules/fmode-amazon-sp-api/
├── src/
│   ├── mod.ts           # 主模块导出
│   ├── client.ts        # SP-API 基础客户端（处理 LWA 认证）
│   ├── api/
│   │   └── customerFeedback.ts # Customer Feedback API 实现
│   ├── types.ts         # 类型定义
│   └── routes.ts        # Express 路由定义
├── docs/
│   ├── task.md          # 任务文档
│   ├── config.md        # 配置说明
│   └── 亚马逊需要对接的接口.md # 需求文档
├── deno.json            # Deno 配置
├── package.json         # 包元数据
└── README.md            # 项目文档

实现方案

文件 1: src/types.ts - 类型定义

定义 SP-API 配置接口、请求参数接口和响应数据接口。

export interface SpApiConfig {
  clientId: string;
  clientSecret: string;
  refreshToken: string;
  region: string; // e.g., 'us-east-1'
  sandbox?: boolean; // 可选：是否使用沙箱
}

export interface GetItemReviewTopicsParams {
  asin: string;
  itemName?: string;
  marketplaceId: string;
  countryCode?: string;
  dateRange?: {
    startDate: string;
    endDate: string;
  };
}

文件 2: src/client.ts - 基础客户端

实现 SpApiClient 类，封装 SP-API 通用逻辑：

认证: 实现 LWA (Login with Amazon) Token 获取与自动刷新机制。
签名: 无需 AWS Signature V4 签名。
请求: 封装统一的 HTTP 请求方法，自动在 Header 中添加 x-amz-access-token。

文件 3: src/api/customerFeedback.ts - 业务 API

实现 CustomerFeedbackApi 类，继承或使用 SpApiClient：

async getItemReviewTopics(params: GetItemReviewTopicsParams): 调用 getItemReviewTopics 接口。

文件 4: src/routes.ts - Express 路由

实现以下端点：

方法	路径	描述
GET	/customerFeedback/reviews/topics	获取商品评论主题
GET	/health	健康状态检查

文件 5: src/mod.ts - 模块导出

导出所有公共接口：

SpApiClient 类
CustomerFeedbackApi 类
createSpApiRoutes 函数
类型定义

配置文件

package.json: 依赖管理 (axios)
deno.json: Deno 兼容性配置

集成步骤

在 api/routes.ts 中添加：

import { createSpApiRoutes } from "../modules/fmode-amazon-sp-api/src/mod.ts";

const spApiConfig = {
  clientId: process.env.SP_API_CLIENT_ID,
  clientSecret: process.env.SP_API_CLIENT_SECRET,
  refreshToken: process.env.SP_API_REFRESH_TOKEN,
  region: "us-east-1"
};

router.use("/amazon-sp-api", createSpApiRoutes(spApiConfig));

测试方案

1. 测试端点可用性

curl http://localhost:10003/api/amazon-sp-api/health

2. 测试获取评论主题

curl "http://localhost:10003/api/amazon-sp-api/customerFeedback/reviews/topics?asin=B0BT5K9B2T&marketplaceId=ATVPDKIKX0DER"

错误处理

参数验证: 验证 asin 和 marketplaceId 等必填参数。
API 错误: 捕获 SP-API 返回的错误 (如 403, 429)，并转换为标准化错误响应。
认证错误: 处理 Token 过期情况。

日志格式

[SP-API] Request: GET /customerFeedback/2024-06-01/items/B0BT5K9B2T/reviews/topics
[SP-API] Params: {"marketplaceId": "ATVPDKIKX0DER"}
[SP-API] Response: 200 OK

安全考虑

敏感信息 (Client Secret) 必须通过环境变量或安全配置传递，禁止硬编码。
确保 Access Token 不被泄露。
遵循 Amazon 的数据保护政策 (DPP)。

响应格式

成功响应:

{
  "success": true,
  "data": {
    "asin": "B0BT5K9B2T",
    "topics": {
      "positiveTopics": [...],
      "negativeTopics": [...]
    }
  }
}

错误响应:

{
  "success": false,
  "error": {
    "code": "InvalidInput",
    "message": "The ASIN is invalid."
  }
}

task.md 4.7 KB History Raw