makemd/docs/02_Backend/API_Specs/Product_API.md

# Product API Specification

> **定位**：商品管理 API 规范 - 包含商品 CRUD、采集、定价、审核等接口。
> **更新日期**: 2026-03-18
> **版本**: v1.0

---

## 1. 接口概览

| 方法 | 路径 | 功能 | 权限 |
|------|------|------|------|
| GET | `/api/v1/products` | 获取商品列表 | product:read |
| GET | `/api/v1/products/:id` | 获取商品详情 | product:read |
| POST | `/api/v1/products` | 创建商品 | product:create |
| PUT | `/api/v1/products/:id` | 更新商品 | product:update |
| DELETE | `/api/v1/products/:id` | 删除商品 | product:delete |
| POST | `/api/v1/products/:id/approve` | 审核商品 | product:review |
| POST | `/api/v1/products/collect` | 采集商品 | product:create |
| POST | `/api/v1/products/:id/pricing` | 动态调价 | product:update |
| POST | `/api/v1/products/autonomous-listing` | 自治上架 | product:create |

---

## 2. 接口详情

### 2.1 获取商品列表

**请求**
```http
GET /api/v1/products?platform=AMAZON&status=ACTIVE&page=1&limit=20
```

**请求头**
```
Authorization: Bearer {token}
X-Tenant-Id: {tenantId}
X-Trace-Id: {traceId}
```

**查询参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| platform | string | 否 | 平台筛选 (AMAZON, EBAY, SHOPIFY, etc.) |
| status | string | 否 | 状态筛选 (DRAFTED, PENDING_REVIEW, APPROVED, etc.) |
| page | number | 否 | 页码，默认 1 |
| limit | number | 否 | 每页数量，默认 20 |

**响应**
```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "title": "Product Name",
        "platform": "AMAZON",
        "platformProductId": "B08N5WRWNW",
        "status": "APPROVED",
        "sellingPrice": 29.99,
        "purchasePrice": 15.00,
        "stock": 100,
        "createdAt": "2026-03-18T10:00:00Z",
        "updatedAt": "2026-03-18T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}
```

---

### 2.2 获取商品详情

**请求**
```http
GET /api/v1/products/:id
```

**响应**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "Product Name",
    "description": "Product description...",
    "platform": "AMAZON",
    "platformProductId": "B08N5WRWNW",
    "status": "APPROVED",
    "sellingPrice": 29.99,
    "purchasePrice": 15.00,
    "currency": "USD",
    "stock": 100,
    "images": ["url1", "url2"],
    "attributes": {
      "color": "black",
      "size": "M"
    },
    "profitMargin": 45.5,
    "roi": 99.9,
    "createdAt": "2026-03-18T10:00:00Z",
    "updatedAt": "2026-03-18T10:00:00Z"
  }
}
```

---

### 2.3 创建商品

**请求**
```http
POST /api/v1/products
```

**请求体**
```json
{
  "title": "Product Name",
  "description": "Product description",
  "platform": "AMAZON",
  "platformProductId": "B08N5WRWNW",
  "sellingPrice": 29.99,
  "purchasePrice": 15.00,
  "currency": "USD",
  "stock": 100,
  "images": ["url1", "url2"],
  "attributes": {
    "color": "black",
    "size": "M"
  },
  "category": "Electronics",
  "tags": ["new", "hot"]
}
```

**响应**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "message": "Product created successfully"
  }
}
```

---

### 2.4 更新商品

**请求**
```http
PUT /api/v1/products/:id
```

**请求体**
```json
{
  "title": "Updated Product Name",
  "sellingPrice": 34.99,
  "stock": 150,
  "status": "PENDING_REVIEW"
}
```

**状态机校验**
- 商品状态流转必须符合预定义状态机
- 非法状态流转返回 400 错误

**响应**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "Updated Product Name",
    "status": "PENDING_REVIEW",
    "updatedAt": "2026-03-18T11:00:00Z"
  }
}
```

---

### 2.5 删除商品

**请求**
```http
DELETE /api/v1/products/:id
```

**响应**
```json
{
  "success": true,
  "message": "Product deleted successfully"
}
```

---

### 2.6 审核商品 [UX_REVIEW_01]

**请求**
```http
POST /api/v1/products/:id/approve
```

**请求体**
```json
{
  "decision": "APPROVE",
  "reason": "符合上架标准"
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| decision | string | 是 | APPROVE 或 REJECT |
| reason | string | 否 | 审核意见 |

**响应**
```json
{
  "success": true,
  "message": "Product approved successfully"
}
```

---

### 2.7 采集商品 [CORE_WORK_01]

**请求**
```http
POST /api/v1/products/collect
```

**请求体**
```json
{
  "url": "https://www.1688.com/product/123456.html",
  "sandbox": false
}
```

**参数说明**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| url | string | 是 | 商品链接 |
| sandbox | boolean | 否 | 是否使用沙箱模式 |

**响应**
```json
{
  "success": true,
  "data": {
    "jobId": "job-uuid",
    "status": "PENDING",
    "message": "Crawl job submitted successfully"
  }
}
```

---

### 2.8 动态调价 [BIZ_MKT_30]

**请求**
```http
POST /api/v1/products/:id/pricing
```

**响应**
```json
{
  "success": true,
  "data": {
    "productId": 1,
    "oldPrice": 29.99,
    "newPrice": 32.99,
    "reason": "Competitor price increased",
    "profitMargin": 48.5,
    "updatedAt": "2026-03-18T12:00:00Z"
  }
}
```

---

### 2.9 自治上架 [CORE_AUTO_01]

**请求**
```http
POST /api/v1/products/autonomous-listing
```

**请求体**
```json
{
  "url": "https://www.1688.com/product/123456.html",
  "targetPlatforms": ["AMAZON", "EBAY"]
}
```

**响应**
```json
{
  "success": true,
  "data": {
    "instanceId": "pipeline-uuid",
    "status": "RUNNING",
    "steps": [
      { "id": "crawl", "status": "PENDING" },
      { "id": "optimize", "status": "PENDING" },
      { "id": "publish", "status": "PENDING" }
    ]
  }
}
```

---

## 3. 数据模型

### 3.1 Product (商品)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | number | 主键 |
| tenantId | string | 租户ID |
| title | string | 商品标题 |
| description | string | 商品描述 |
| platform | string | 平台 (AMAZON, EBAY, etc.) |
| platformProductId | string | 平台商品ID |
| status | string | 状态 |
| sellingPrice | number | 售价 |
| purchasePrice | number | 采购价 |
| currency | string | 币种 |
| stock | number | 库存 |
| images | string[] | 图片URL列表 |
| attributes | object | 属性 |
| category | string | 类目 |
| tags | string[] | 标签 |
| profitMargin | number | 利润率 |
| roi | number | ROI |
| createdAt | string | 创建时间 |
| updatedAt | string | 更新时间 |

### 3.2 状态枚举

```typescript
enum ProductStatus {
  DRAFTED = 'DRAFTED',           // 草稿
  PENDING_REVIEW = 'PENDING_REVIEW', // 待审核
  APPROVED = 'APPROVED',         // 已通过
  REJECTED = 'REJECTED',         // 已拒绝
  LISTED = 'LISTED',             // 已上架
  DELISTED = 'DELISTED'          // 已下架
}
```

---

## 4. 错误码

| 错误码 | 说明 | HTTP状态 |
|--------|------|----------|
| PRODUCT_NOT_FOUND | 商品不存在 | 404 |
| INVALID_STATUS_TRANSITION | 非法状态流转 | 400 |
| UNAUTHORIZED | 未授权 | 401 |
| FORBIDDEN | 无权限 | 403 |
| VALIDATION_ERROR | 参数校验失败 | 400 |
| INTERNAL_ERROR | 内部错误 | 500 |

---

## 5. 相关服务

- [Backend Design](../Backend_Design.md)
- [Order API](./Order_API.md)
- [Finance API](./Finance_API.md)

---

*本文档基于代码自动生成，最后更新: 2026-03-18*