# 后端API接口文档

## 1. 接口概述

### 1.1 基本信息
- **项目名称**: vizee电商后端服务
- **技术栈**: Go + Gin + GORM + MySQL
- **API版本**: v1
- **Base URL**: 
  - 开发环境: `http://localhost:8080/api/v1`
  - 测试环境: `配置中`
  - 生产环境: `配置中`

### 1.2 通用说明
- **数据格式**: JSON
- **字符编码**: UTF-8
- **认证方式**: JWT Token
- **时间格式**: ISO 8601 (YYYY-MM-DDTHH:mm:ss.SSSZ)

### 1.3 通用响应格式

**成功响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

**错误响应**:
```json
{
  "code": 400,
  "message": "错误信息描述",
  "data": null
}
```

### 1.4 状态码说明
| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，需要登录 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 2. 认证接口

### 2.1 用户登录

**接口地址**: `POST /auth/login`

**请求参数**:
```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1,
      "email": "user@example.com",
      "nickname": "用户昵称",
      "avatar": "头像URL",
      "created_at": "2024-01-01T00:00:00Z"
    }
  }
}
```

### 2.2 用户注册

**接口地址**: `POST /auth/register`

**请求参数**:
```json
{
  "email": "user@example.com",
  "password": "password123",
  "nickname": "用户昵称"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "user_id": 1
  }
}
```

### 2.3 微信登录

**接口地址**: `POST /auth/wechat/login`

**请求参数**:
```json
{
  "code": "微信登录code"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 1,
      "openid": "微信openid",
      "nickname": "微信昵称",
      "avatar": "微信头像"
    }
  }
}
```

---

## 3. 用户接口

### 3.1 获取用户信息

**接口地址**: `GET /users/profile`

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "email": "user@example.com",
    "nickname": "用户昵称",
    "avatar": "头像URL",
    "phone": "手机号",
    "gender": 1,
    "points": 100,
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

### 3.2 更新用户信息

**接口地址**: `PUT /users/profile`

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "nickname": "新昵称",
  "avatar": "新头像URL",
  "phone": "手机号",
  "gender": 1
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

### 3.3 获取用户地址列表

**接口地址**: `GET /users/addresses`

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "收货人",
      "phone": "13800138000",
      "province": "广东省",
      "city": "深圳市",
      "district": "南山区",
      "detail": "详细地址",
      "is_default": true
    }
  ]
}
```

### 3.4 添加收货地址

**接口地址**: `POST /users/addresses`

**请求参数**:
```json
{
  "name": "收货人",
  "phone": "13800138000",
  "province": "广东省",
  "city": "深圳市",
  "district": "南山区",
  "detail": "详细地址",
  "is_default": false
}
```

---

## 4. 商品接口

### 4.1 获取商品列表

**接口地址**: `GET /products`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
| category_id | int | 否 | 分类ID |
| keyword | string | 否 | 搜索关键词 |
| sort | string | 否 | 排序方式：price_asc/price_desc/sales/new |
| min_price | float | 否 | 最低价格 |
| max_price | float | 否 | 最高价格 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "商品名称",
        "cover": "封面图URL",
        "price": 99.00,
        "original_price": 199.00,
        "sales": 1000,
        "stock": 500,
        "rating": 4.8,
        "comment_count": 100
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 100
    }
  }
}
```

### 4.2 获取商品详情

**接口地址**: `GET /products/:id`

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "商品名称",
    "cover": "封面图URL",
    "images": ["图片1", "图片2"],
    "price": 99.00,
    "original_price": 199.00,
    "sales": 1000,
    "stock": 500,
    "rating": 4.8,
    "comment_count": 100,
    "description": "商品描述",
    "detail": "商品详情HTML",
    "category": {
      "id": 1,
      "name": "分类名称"
    },
    "skus": [
      {
        "id": 1,
        "name": "规格名称",
        "price": 99.00,
        "stock": 100,
        "image": "规格图片"
      }
    ],
    "specs": [
      {
        "name": "颜色",
        "values": ["红色", "蓝色"]
      }
    ]
  }
}
```

### 4.3 获取商品评价

**接口地址**: `GET /products/:id/comments`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| page_size | int | 否 | 每页数量 |
| rating | int | 否 | 评分筛选：1-5 |
| has_image | bool | 否 | 是否有图 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "stats": {
      "total": 100,
      "rating_5": 80,
      "rating_4": 15,
      "rating_3": 3,
      "rating_2": 1,
      "rating_1": 1,
      "avg_rating": 4.8
    },
    "list": [
      {
        "id": 1,
        "user": {
          "nickname": "用户昵称",
          "avatar": "头像URL"
        },
        "rating": 5,
        "content": "评价内容",
        "images": ["图片1", "图片2"],
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 100
    }
  }
}
```

---

## 5. 分类接口

### 5.1 获取分类列表

**接口地址**: `GET /categories`

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "艺术手工",
      "icon": "图标URL",
      "sort": 1,
      "children": [
        {
          "id": 11,
          "name": "陶艺",
          "parent_id": 1
        }
      ]
    }
  ]
}
```

---

## 6. 购物车接口

### 6.1 获取购物车

**接口地址**: `GET /cart`

**请求头**:
```
Authorization: Bearer {token}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "sku_id": 1,
        "product_name": "商品名称",
        "sku_name": "规格名称",
        "image": "图片URL",
        "price": 99.00,
        "quantity": 2,
        "stock": 100,
        "selected": true
      }
    ],
    "total_price": 198.00,
    "total_count": 2
  }
}
```

### 6.2 添加到购物车

**接口地址**: `POST /cart`

**请求参数**:
```json
{
  "product_id": 1,
  "sku_id": 1,
  "quantity": 1
}
```

### 6.3 更新购物车数量

**接口地址**: `PUT /cart/:id`

**请求参数**:
```json
{
  "quantity": 2
}
```

### 6.4 删除购物车商品

**接口地址**: `DELETE /cart/:id`

### 6.5 清空购物车

**接口地址**: `DELETE /cart/clear`

---

## 7. 订单接口

### 7.1 创建订单

**接口地址**: `POST /orders`

**请求参数**:
```json
{
  "address_id": 1,
  "items": [
    {
      "product_id": 1,
      "sku_id": 1,
      "quantity": 2
    }
  ],
  "coupon_id": 1,
  "remark": "备注信息"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "下单成功",
  "data": {
    "order_id": "ORD20240101123456",
    "total_amount": 198.00,
    "pay_amount": 188.00
  }
}
```

### 7.2 获取订单列表

**接口地址**: `GET /orders`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| page_size | int | 否 | 每页数量 |
| status | string | 否 | 订单状态：pending/paid/shipped/completed/cancelled |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "ORD20240101123456",
        "status": "paid",
        "status_text": "已支付",
        "total_amount": 198.00,
        "pay_amount": 188.00,
        "items": [
          {
            "product_name": "商品名称",
            "sku_name": "规格名称",
            "image": "图片URL",
            "price": 99.00,
            "quantity": 2
          }
        ],
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 50
    }
  }
}
```

### 7.3 获取订单详情

**接口地址**: `GET /orders/:id`

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "ORD20240101123456",
    "status": "paid",
    "status_text": "已支付",
    "total_amount": 198.00,
    "pay_amount": 188.00,
    "shipping_fee": 10.00,
    "discount_amount": 20.00,
    "address": {
      "name": "收货人",
      "phone": "13800138000",
      "province": "广东省",
      "city": "深圳市",
      "district": "南山区",
      "detail": "详细地址"
    },
    "items": [
      {
        "product_name": "商品名称",
        "sku_name": "规格名称",
        "image": "图片URL",
        "price": 99.00,
        "quantity": 2
      }
    ],
    "created_at": "2024-01-01T00:00:00Z",
    "paid_at": "2024-01-01T00:05:00Z"
  }
}
```

### 7.4 取消订单

**接口地址**: `POST /orders/:id/cancel`

**请求参数**:
```json
{
  "reason": "取消原因"
}
```

### 7.5 确认收货

**接口地址**: `POST /orders/:id/confirm`

---

## 8. 支付接口

### 8.1 创建支付

**接口地址**: `POST /pay/create`

**请求参数**:
```json
{
  "order_id": "ORD20240101123456",
  "pay_type": "wechat"
}
```

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "pay_params": {
      "timeStamp": "1234567890",
      "nonceStr": "random_string",
      "package": "prepay_id=xxx",
      "signType": "MD5",
      "paySign": "signature"
    }
  }
}
```

### 8.2 支付回调

**接口地址**: `POST /pay/callback`

**说明**: 由支付平台调用，处理支付结果

---

## 9. 退款接口

### 9.1 申请退款

**接口地址**: `POST /refunds`

**请求参数**:
```json
{
  "order_id": "ORD20240101123456",
  "reason": "退款原因",
  "description": "详细说明",
  "images": ["图片1", "图片2"]
}
```

### 9.2 获取退款列表

**接口地址**: `GET /refunds`

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "order_id": "ORD20240101123456",
        "status": "pending",
        "status_text": "待审核",
        "amount": 188.00,
        "reason": "退款原因",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}
```

### 9.3 取消退款申请

**接口地址**: `POST /refunds/:id/cancel`

---

## 10. Banner接口

### 10.1 获取Banner列表

**接口地址**: `GET /banners`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| position | string | 否 | 位置：home/category |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "title": "Banner标题",
      "image": "图片URL",
      "link": "跳转链接",
      "sort": 1
    }
  ]
}
```

---

## 11. 优惠券接口

### 11.1 获取优惠券列表

**接口地址**: `GET /coupons`

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "优惠券名称",
      "type": "discount",
      "discount": 0.9,
      "min_amount": 100.00,
      "max_discount": 50.00,
      "start_time": "2024-01-01T00:00:00Z",
      "end_time": "2024-12-31T23:59:59Z",
      "total_count": 1000,
      "received_count": 500,
      "is_received": false
    }
  ]
}
```

### 11.2 领取优惠券

**接口地址**: `POST /coupons/:id/receive`

### 11.3 获取我的优惠券

**接口地址**: `GET /coupons/my`

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | string | 否 | unused/used/expired |

---

## 12. 文件上传接口

### 12.1 上传图片

**接口地址**: `POST /upload/image`

**请求头**:
```
Content-Type: multipart/form-data
Authorization: Bearer {token}
```

**请求参数**:
- file: 图片文件（支持jpg、png、gif，最大5MB）

**响应数据**:
```json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "https://cdn.example.com/images/xxx.jpg"
  }
}
```

**说明**:
- 图片自动压缩优化
- 自动生成缩略图
- 设置正确的Content-Type和Content-Disposition
- 返回OSS访问URL

---

## 13. 统计接口（管理端）

### 13.1 获取销售统计

**接口地址**: `GET /admin/stats/sales`

**请求头**:
```
Authorization: Bearer {admin_token}
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| start_date | string | 是 | 开始日期 |
| end_date | string | 是 | 结束日期 |

**响应数据**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total_amount": 100000.00,
    "total_orders": 1000,
    "avg_order_amount": 100.00,
    "daily_stats": [
      {
        "date": "2024-01-01",
        "amount": 1000.00,
        "orders": 10
      }
    ]
  }
}
```

---

## 14. 错误码说明

| 错误码 | 说明 |
|--------|------|
| 10001 | 参数错误 |
| 10002 | 用户不存在 |
| 10003 | 密码错误 |
| 10004 | Token无效 |
| 10005 | Token过期 |
| 20001 | 商品不存在 |
| 20002 | 库存不足 |
| 20003 | 商品已下架 |
| 30001 | 订单不存在 |
| 30002 | 订单状态错误 |
| 30003 | 订单已取消 |
| 40001 | 支付失败 |
| 40002 | 退款失败 |
| 50001 | 文件上传失败 |
| 50002 | 文件类型不支持 |
| 50003 | 文件大小超限 |

---

## 15. 开发调试

### 15.1 本地环境配置

**配置文件**: `server/configs/config.yaml`

```yaml
server:
  port: 8080
  mode: debug

database:
  host: localhost
  port: 3306
  username: root
  password: password
  database: dianshang

jwt:
  secret: your-secret-key
  expire: 7200

oss:
  endpoint: oss-cn-shenzhen.aliyuncs.com
  access_key_id: your-access-key-id
  access_key_secret: your-access-key-secret
  bucket: your-bucket-name
```

### 15.2 API调试工具
- Postman
- Apifox
- Swagger UI (开发中)

### 15.3 测试账号
- **普通用户**: test@example.com / 123456
- **管理员**: admin@example.com / admin123

---

## 16. 注意事项

### 16.1 请求限制
- 同一IP每分钟最多60次请求
- 文件上传大小限制5MB
- 批量操作最多100条

### 16.2 数据安全
- 敏感信息传输使用HTTPS
- 密码使用bcrypt加密
- Token有效期2小时
- 软删除数据需显式过滤

### 16.3 性能优化
- 列表接口支持分页
- 使用Redis缓存热点数据
- 数据库连接池优化
- 图片CDN加速

### 16.4 数据库规范
- GORM预加载需显式过滤软删除数据
- SKU价格优先级：SKU价格 > 商品价格
- 订单数据按用户隔离存储
- 所有时间字段使用UTC时间

---

**文档版本**: v1.0  
**创建日期**: 2024-11-19  
**最后更新**: 2024-11-19  
**维护团队**: 后端开发组