chore: 清理归档文件和文档模板
删除不再需要的归档文件和过时的文档模板，包括多个README、安全策略、前端集成蓝图等文件，同时移除了未使用的业务文档和项目结构文件。 优化项目结构，移除冗余文件，保持代码库整洁。主要删除archive/handover目录下的多个文件及doc目录下的部分文档模板。
This commit is contained in:
399
docs/02_Backend/API_Specs/Product_API.md
Normal file
399
docs/02_Backend/API_Specs/Product_API.md
Normal file
@@ -0,0 +1,399 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user