docs: 更新项目文档，完善需求和技术细节
This commit is contained in:
ylweng
372
docs/API接口文档.md
372
docs/API接口文档.md
@@ -9,6 +9,46 @@
|
||||
- **Base URL**: `http://localhost:3200/api/v1`
|
||||
- **认证方式**: Bearer Token (JWT)
|
||||
- **响应格式**: JSON
|
||||
- **字符编码**: UTF-8
|
||||
|
||||
## 通用响应格式
|
||||
|
||||
### 成功响应
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "操作成功",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "参数错误",
|
||||
"error": "详细错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 成功 |
|
||||
| 201 | 创建成功 |
|
||||
| 400 | 参数错误 |
|
||||
| 401 | 未授权 |
|
||||
| 403 | 禁止访问 |
|
||||
| 404 | 资源不存在 |
|
||||
| 409 | 资源冲突 |
|
||||
| 500 | 服务器内部错误 |
|
||||
| 1001 | 识别失败 |
|
||||
| 1002 | 图片格式不支持 |
|
||||
| 2001 | 推广奖励不足 |
|
||||
| 2002 | 提现频率限制 |
|
||||
| 3001 | 库存不足 |
|
||||
| 3002 | 订单状态异常 |
|
||||
|
||||
## 认证接口
|
||||
|
||||
@@ -189,9 +229,337 @@ Authorization: Bearer <token>
|
||||
]
|
||||
```
|
||||
|
||||
## 购物车接口
|
||||
|
||||
### 1. 获取购物车
|
||||
|
||||
**GET** `/cart`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "获取成功",
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"product_id": 1,
|
||||
"product_name": "玫瑰花束",
|
||||
"product_image": "/uploads/products/rose_bouquet.jpg",
|
||||
"price": 29.9,
|
||||
"quantity": 2,
|
||||
"subtotal": 59.8,
|
||||
"stock": 100
|
||||
}
|
||||
],
|
||||
"total_amount": 59.8,
|
||||
"total_quantity": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 添加商品到购物车
|
||||
|
||||
**POST** `/cart/items`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||||
|--------|------|------|------|------|
|
||||
| product_id | integer | 是 | 商品ID | 1 |
|
||||
| quantity | integer | 是 | 数量 | 2 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "添加成功",
|
||||
"data": {
|
||||
"cart_item_id": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 更新购物车商品数量
|
||||
|
||||
**PUT** `/cart/items/{id}`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 说明 | 示例 |
|
||||
|--------|------|------|------|
|
||||
| id | integer | 购物车项ID | 1 |
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||||
|--------|------|------|------|------|
|
||||
| quantity | integer | 是 | 数量 | 3 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "更新成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 删除购物车商品
|
||||
|
||||
**DELETE** `/cart/items/{id}`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 说明 | 示例 |
|
||||
|--------|------|------|------|
|
||||
| id | integer | 购物车项ID | 1 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
## 收货地址接口
|
||||
|
||||
### 1. 获取收货地址列表
|
||||
|
||||
**GET** `/addresses`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "获取成功",
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"recipient": "张三",
|
||||
"phone": "13800138000",
|
||||
"province": "北京市",
|
||||
"city": "北京市",
|
||||
"district": "海淀区",
|
||||
"detail": "中关村大街1号",
|
||||
"is_default": true,
|
||||
"created_at": "2023-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 添加收货地址
|
||||
|
||||
**POST** `/addresses`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||||
|--------|------|------|------|------|
|
||||
| recipient | string | 是 | 收货人 | "张三" |
|
||||
| phone | string | 是 | 手机号 | "13800138000" |
|
||||
| province | string | 是 | 省份 | "北京市" |
|
||||
| city | string | 是 | 城市 | "北京市" |
|
||||
| district | string | 是 | 区县 | "海淀区" |
|
||||
| detail | string | 是 | 详细地址 | "中关村大街1号" |
|
||||
| is_default | boolean | 否 | 是否默认 | true |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 201,
|
||||
"message": "添加成功",
|
||||
"data": {
|
||||
"address_id": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 更新收货地址
|
||||
|
||||
**PUT** `/addresses/{id}`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 说明 | 示例 |
|
||||
|--------|------|------|------|
|
||||
| id | integer | 地址ID | 1 |
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||||
|--------|------|------|------|------|
|
||||
| recipient | string | 否 | 收货人 | "张三" |
|
||||
| phone | string | 否 | 手机号 | "13800138000" |
|
||||
| province | string | 否 | 省份 | "北京市" |
|
||||
| city | string | 否 | 城市 | "北京市" |
|
||||
| district | string | 否 | 区县 | "海淀区" |
|
||||
| detail | string | 否 | 详细地址 | "中关村大街1号" |
|
||||
| is_default | boolean | 否 | 是否默认 | true |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "更新成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 删除收货地址
|
||||
|
||||
**DELETE** `/addresses/{id}`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 说明 | 示例 |
|
||||
|--------|------|------|------|
|
||||
| id | integer | 地址ID | 1 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
## 支付接口
|
||||
|
||||
### 1. 发起支付
|
||||
|
||||
**POST** `/pay/orders/{order_no}`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 说明 | 示例 |
|
||||
|--------|------|------|------|
|
||||
| order_no | string | 订单编号 | "ORDER202301010001" |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "支付参数生成成功",
|
||||
"data": {
|
||||
"payment_params": {
|
||||
"timeStamp": "1672531200",
|
||||
"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
|
||||
"package": "prepay_id=wx201410272009395522fsd8f8f8f8f8f8",
|
||||
"signType": "MD5",
|
||||
"paySign": "C380BEC2BFD727A4B6845133519F3AD6"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 查询支付结果
|
||||
|
||||
**GET** `/pay/orders/{order_no}/status`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 说明 | 示例 |
|
||||
|--------|------|------|------|
|
||||
| order_no | string | 订单编号 | "ORDER202301010001" |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "查询成功",
|
||||
"data": {
|
||||
"order_no": "ORDER202301010001",
|
||||
"payment_status": "paid",
|
||||
"paid_amount": 59.8,
|
||||
"paid_at": "2023-01-01T10:05:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 文件上传接口
|
||||
|
||||
### 1. 上传文件
|
||||
|
||||
**POST** `/upload`
|
||||
|
||||
**请求格式**: `multipart/form-data`
|
||||
|
||||
**请求参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||||
|--------|------|------|------|------|
|
||||
| file | file | 是 | 上传文件 | - |
|
||||
| type | string | 否 | 文件类型 | "avatar" |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "上传成功",
|
||||
"data": {
|
||||
"url": "/uploads/avatars/avatar_123.jpg",
|
||||
"filename": "avatar_123.jpg",
|
||||
"size": 102400,
|
||||
"mime_type": "image/jpeg"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 花卉识别接口
|
||||
|
||||
### 花卉识别
|
||||
### 1. 花卉识别
|
||||
|
||||
**POST** `/identifications/identify`
|
||||
|
||||
@@ -228,7 +596,7 @@ Authorization: Bearer <token>
|
||||
}
|
||||
```
|
||||
|
||||
### 获取识别历史
|
||||
### 2. 获取识别历史
|
||||
|
||||
**GET** `/identifications/history`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user