# 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*