# @fmode/amazon-sp-api

Amazon Selling Partner API (SP-API) 集成模块，支持多店铺动态配置（基于 Parse Server）。

## 功能特性

- **多店铺支持**：基于 `Shop` 表（Parse Server）动态获取 SP-API 配置。
- **动态路由**：请求头携带 `shopId` 和 `marketplaceId`，自动路由到正确的 API 端点和店铺配置。
- **Token 管理**：自动处理 LWA Token 的获取、缓存（数据库持久化）和刷新。
- **完整接口覆盖**：包括 Orders, Listings, Reports, Notifications, Catalog, Sales, Inventory, Pricing, ExternalFulfillment, CustomerFeedback。
- **企业级特性**：请求重试（429 处理）、日志记录、类型安全。

## 安装

```bash
npm install @fmode/amazon-sp-api
```

## 初始化

在应用启动时，初始化 Parse 配置：

```typescript
import express from 'express';
import { createSpApiRouter, initParse } from '@fmode/amazon-sp-api';

const app = express();

// 1. 初始化 Parse (连接到配置中心)
initParse({
  appId: 'msq-voc', // 或从环境变量读取
  serverURL: 'https://server-msq.fmode.cn/parse',
  // masterKey: 'YOUR_MASTER_KEY' // 如果需要 Server-to-Server 权限
});

// 2. 挂载 SP-API 路由
// 注意：不再需要传入静态 client，模块会自动处理动态配置
app.use('/api/amazon', createSpApiRouter());

app.listen(3000, () => {
  console.log('Server started on port 3000');
});
```

## 请求示例

前端或调用方需要在 Header 中携带 `shopId` 和 `marketplaceId`。

### 获取订单列表

```http
GET /api/amazon/orders?CreatedAfter=2023-10-01T00:00:00Z
Headers:
  shopId: <PARSE_SHOP_OBJECT_ID>
  marketplaceId: ATVPDKIKX0DER
```

### 响应格式

```json
{
  "success": true,
  "data": {
    "payload": {
      "Orders": [...]
    }
  },
  "timestamp": "2023-10-27T10:00:00.000Z"
}
```

## 数据库配置 (Parse Shop 表)

在 Parse Dashboard 中，`Shop` 表需要包含以下字段：

| Field | Type | Description |
|Data Type| Field Name | Description |
|---|---|---|
| Object | `config` | 包含 SP-API 凭证: `{ "clientId": "...", "clientSecret": "...", "refreshToken": "..." }` |
| String | `sp_api_access_token` | (自动维护) 当前有效的 Access Token |
| Date | `sp_api_token_expires_at` | (自动维护) Token 过期时间 |

## 错误处理

- **400 Bad Request**: 缺少 `shopId` 头，或 `shopId` 无效，或 Shop 配置不完整。
- **429 Too Many Requests**: 模块会自动重试（指数退避），如果重试多次仍失败，返回错误。
- **500 Internal Server Error**: 服务器内部错误或 SP-API 异常。