# 任务：亚马逊 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 配置接口、请求参数接口和响应数据接口。

```typescript
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` 中添加：

```typescript
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. 测试端点可用性

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

### 2. 测试获取评论主题

```bash
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)。

## 响应格式

**成功响应**:
```json
{
  "success": true,
  "data": {
    "asin": "B0BT5K9B2T",
    "topics": {
      "positiveTopics": [...],
      "negativeTopics": [...]
    }
  }
}
```

**错误响应**:
```json
{
  "success": false,
  "error": {
    "code": "InvalidInput",
    "message": "The ASIN is invalid."
  }
}
```