yunqueai/ai_dianshang

Fork 0

Files

sjk 5683f35942 web

2025-11-28 15:18:10 +08:00

15 KiB

Raw Permalink Blame History

后端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 通用响应格式

成功响应:

{
  "code": 200,
  "message": "success",
  "data": {}
}

错误响应:

{
  "code": 400,
  "message": "错误信息描述",
  "data": null
}

1.4 状态码说明

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

2. 认证接口

2.1 用户登录

接口地址: POST /auth/login

请求参数:

{
  "email": "user@example.com",
  "password": "password123"
}

响应数据:

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

请求参数:

{
  "email": "user@example.com",
  "password": "password123",
  "nickname": "用户昵称"
}

响应数据:

{
  "code": 200,
  "message": "注册成功",
  "data": {
    "user_id": 1
  }
}

2.3 微信登录

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

请求参数:

{
  "code": "微信登录code"
}

响应数据:

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

3. 用户接口

3.1 获取用户信息

接口地址: GET /users/profile

请求头:

Authorization: Bearer {token}

响应数据:

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

请求参数:

{
  "nickname": "新昵称",
  "avatar": "新头像URL",
  "phone": "手机号",
  "gender": 1
}

响应数据:

{
  "code": 200,
  "message": "更新成功",
  "data": null
}

3.3 获取用户地址列表

接口地址: GET /users/addresses

请求头:

Authorization: Bearer {token}

响应数据:

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

3.4 添加收货地址

接口地址: POST /users/addresses

请求参数:

{
  "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	否	最高价格

响应数据:

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

响应数据:

{
  "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	否	是否有图

响应数据:

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

响应数据:

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

响应数据:

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

请求参数:

{
  "product_id": 1,
  "sku_id": 1,
  "quantity": 1
}

6.3 更新购物车数量

接口地址: PUT /cart/:id

请求参数:

{
  "quantity": 2
}

6.4 删除购物车商品

接口地址: DELETE /cart/:id

6.5 清空购物车

接口地址: DELETE /cart/clear

7. 订单接口

7.1 创建订单

接口地址: POST /orders

请求参数:

{
  "address_id": 1,
  "items": [
    {
      "product_id": 1,
      "sku_id": 1,
      "quantity": 2
    }
  ],
  "coupon_id": 1,
  "remark": "备注信息"
}

响应数据:

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

响应数据:

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

响应数据:

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

请求参数:

{
  "reason": "取消原因"
}

7.5 确认收货

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

8. 支付接口

8.1 创建支付

接口地址: POST /pay/create

请求参数:

{
  "order_id": "ORD20240101123456",
  "pay_type": "wechat"
}

响应数据:

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

请求参数:

{
  "order_id": "ORD20240101123456",
  "reason": "退款原因",
  "description": "详细说明",
  "images": ["图片1", "图片2"]
}

9.2 获取退款列表

接口地址: GET /refunds

响应数据:

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

响应数据:

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

11. 优惠券接口

11.1 获取优惠券列表

接口地址: GET /coupons

响应数据:

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

响应数据:

{
  "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	是	结束日期

响应数据:

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

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
维护团队: 后端开发组

15 KiB Raw Permalink Blame History Unescape Escape

后端API接口文档

1. 接口概述

1.1 基本信息

1.2 通用说明

1.3 通用响应格式

1.4 状态码说明

2. 认证接口

2.1 用户登录

2.2 用户注册

2.3 微信登录

3. 用户接口

3.1 获取用户信息

3.2 更新用户信息

3.3 获取用户地址列表

3.4 添加收货地址

4. 商品接口

4.1 获取商品列表

4.2 获取商品详情

4.3 获取商品评价

5. 分类接口

5.1 获取分类列表

6. 购物车接口

6.1 获取购物车

6.2 添加到购物车

6.3 更新购物车数量

6.4 删除购物车商品

6.5 清空购物车

7. 订单接口

7.1 创建订单

7.2 获取订单列表

7.3 获取订单详情

7.4 取消订单

7.5 确认收货

8. 支付接口

8.1 创建支付

8.2 支付回调

9. 退款接口

9.1 申请退款

9.2 获取退款列表

9.3 取消退款申请

10. Banner接口

10.1 获取Banner列表

11. 优惠券接口

11.1 获取优惠券列表

11.2 领取优惠券

11.3 获取我的优惠券

12. 文件上传接口

12.1 上传图片

13. 统计接口（管理端）

13.1 获取销售统计

14. 错误码说明

15. 开发调试

15.1 本地环境配置

15.2 API调试工具

15.3 测试账号

16. 注意事项

16.1 请求限制

16.2 数据安全

16.3 性能优化

16.4 数据库规范

15 KiB

Raw Permalink Blame History