makemd/docs/02_Backend/api/04_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 获取商品列表

请求

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

响应

{
  "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 获取商品详情

请求

GET /api/v1/products/:id

响应

{
  "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 创建商品

请求

POST /api/v1/products

请求体

{
  "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"]
}

响应

{
  "success": true,
  "data": {
    "id": 1,
    "message": "Product created successfully"
  }
}

---

2.4 更新商品

请求

PUT /api/v1/products/:id

请求体

{
  "title": "Updated Product Name",
  "sellingPrice": 34.99,
  "stock": 150,
  "status": "PENDING_REVIEW"
}

状态机校验

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

响应

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

---

2.5 删除商品

请求

DELETE /api/v1/products/:id

响应

{
  "success": true,
  "message": "Product deleted successfully"
}

---

2.6 审核商品 [UX_REVIEW_01]

请求

POST /api/v1/products/:id/approve

请求体

{
  "decision": "APPROVE",
  "reason": "符合上架标准"
}

参数说明

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

响应

{
  "success": true,
  "message": "Product approved successfully"
}

---

2.7 采集商品 [CORE_WORK_01]

请求

POST /api/v1/products/collect

请求体

{
  "url": "https://www.1688.com/product/123456.html",
  "sandbox": false
}

参数说明

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

响应

{
  "success": true,
  "data": {
    "jobId": "job-uuid",
    "status": "PENDING",
    "message": "Crawl job submitted successfully"
  }
}

---

2.8 动态调价 [BIZ_MKT_30]

请求

POST /api/v1/products/:id/pricing

响应

{
  "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]

请求

POST /api/v1/products/autonomous-listing

请求体

{
  "url": "https://www.1688.com/product/123456.html",
  "targetPlatforms": ["AMAZON", "EBAY"]
}

响应

{
  "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 状态枚举

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
• Order API
• Finance API

---

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