超腾开源平台商业模块

商业模块提供完整的电子商务功能，包括商品管理、订单管理、评价管理、收藏、购物车、软件销售和支付功能。

目录

• 商品管理
• 订单管理
• 评价管理
• 收藏管理
• 购物车管理
• 软件管理
• 支付管理

商品管理

商品模块提供商品的创建、编辑、删除、图片管理、附件管理等功能。

商品主表 CRUD

获取商品详情

接口地址: GET /api/commerce/items/detail

需要认证: 是

请求参数:

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "1",
    "code": "ITEM001",
    "name": "商品名称",
    "description": "商品描述",
    "detail": "商品详情",
    "price": 99.99,
    "discount_price": 89.99,
    "stock": 100,
    "category": "电子产品",
    "version": "1.0.0",
    "thumbnail": "https://example.com/thumb.jpg",
    "status": "available",
    "is_active": true,
    "create_time": "2026-01-01T00:00:00Z",
    "update_time": "2026-01-01T00:00:00Z"
  }
}

获取商品列表

接口地址: GET /api/commerce/items/list

需要认证: 是

请求参数:

获取商品分页

接口地址: GET /api/commerce/items/page

需要认证: 是

请求参数:

创建商品

接口地址: POST /api/commerce/items/create

需要认证: 是

请求体:

{
  "code": "ITEM001",
  "name": "商品名称",
  "description": "商品描述",
  "detail": "商品详情",
  "price": 99.99,
  "discount_price": 89.99,
  "stock": 100,
  "category": "电子产品",
  "version": "1.0.0",
  "status": "available",
  "is_active": true
}

请求字段说明:

更新商品

接口地址: POST /api/commerce/items/update

需要认证: 是

请求体: 同创建商品，需包含 id 字段。

删除商品

接口地址: POST /api/commerce/items/delete

需要认证: 是

请求参数:

商品文档管理

商品图片管理

上传商品图片

接口地址: POST /api/commerce/items/image/upload

需要认证: 是

请求参数: multipart/form-data

商品附件管理

上传商品附件

接口地址: POST /api/commerce/items/attachment/upload

需要认证: 是

请求参数: multipart/form-data

订单管理

订单模块提供订单的创建、查询、更新等功能。

订单主表 CRUD

获取订单详情

接口地址: GET /api/commerce/orders/detail

需要认证: 是

请求参数:

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "1",
    "user_id": "1",
    "order_number": "ORD202601010001",
    "total_amount": 99.99,
    "status": "pending_payment",
    "payment_method": "alipay",
    "shipping_address": "配送地址",
    "shipping_fee": 10.0,
    "note": "订单备注",
    "create_time": "2026-01-01T00:00:00Z",
    "update_time": "2026-01-01T00:00:00Z",
    "paid_time": null,
    "shipped_time": null,
    "completed_time": null,
    "items": [
      {
        "id": "1",
        "item_id": "1",
        "item_name": "商品名称",
        "quantity": 1,
        "price": 99.99,
        "subtotal": 99.99
      }
    ]
  }
}

创建订单

接口地址: POST /api/commerce/orders/create

需要认证: 是

请求体:

{
  "items": [
    {
      "item_id": "1",
      "quantity": 1
    }
  ],
  "shipping_address": "配送地址",
  "note": "订单备注"
}

订单项管理

交易记录管理

评价管理

评价模块提供商品评价的创建、查询、回复等功能。

评价 CRUD

获取评价列表

接口地址: GET /api/commerce/reviews/list

需要认证: 是

请求参数:

创建评价

接口地址: POST /api/commerce/reviews/create

需要认证: 是

请求体:

{
  "item_id": "1",
  "order_id": "1",
  "rating": 5,
  "content": "商品很好用，非常满意！",
  "images": ["https://example.com/review1.jpg"],
  "is_anonymous": false
}

请求字段说明:

评价回复管理

创建评价回复

接口地址: POST /api/commerce/reviews/reply/create

需要认证: 是

请求参数:

收藏管理

收藏模块提供商品收藏功能。

添加收藏

接口地址: POST /api/commerce/favorites/add

需要认证: 是

请求体:

{
  "item_id": "1"
}

检查是否已收藏

接口地址: GET /api/commerce/favorites/check

需要认证: 是

请求参数:

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "操作成功",
  "data": true
}

购物车管理

购物车模块提供购物车的管理功能。

添加到购物车

接口地址: POST /api/commerce/carts/add

需要认证: 是

请求体:

{
  "item_id": "1",
  "quantity": 2
}

更新购物车项

接口地址: PUT /api/commerce/carts/update/{cart_id}

需要认证: 是

路径参数:

请求体:

{
  "quantity": 3,
  "is_selected": true
}

获取用户购物车

接口地址: GET /api/commerce/carts/list

需要认证: 是

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": "1",
      "user_id": "1",
      "item_id": "1",
      "item_name": "商品名称",
      "item_price": 99.99,
      "item_thumbnail": "https://example.com/thumb.jpg",
      "quantity": 2,
      "is_selected": true,
      "subtotal": 199.98,
      "create_time": "2026-01-01T00:00:00Z",
      "update_time": "2026-01-01T00:00:00Z"
    }
  ]
}

软件管理

软件模块提供软件产品的销售和管理功能。

软件 CRUD

获取软件详情

接口地址: GET /api/commerce/software/detail

需要认证: 是

请求参数:

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "1",
    "code": "SOFT001",
    "name": "软件名称",
    "version": "1.0.0",
    "description": "软件描述",
    "detail": "软件详情",
    "category": "工具软件",
    "file_url": "https://example.com/software.zip",
    "file_size": 1024000,
    "file_type": "zip",
    "programming_language": "Python",
    "system_requirements": "Python 3.8+",
    "license_type": "MIT",
    "release_date": "2026-01-01",
    "status": "available",
    "is_active": true,
    "create_time": "2026-01-01T00:00:00Z",
    "update_time": "2026-01-01T00:00:00Z"
  }
}

上传软件文件

接口地址: POST /api/commerce/software/upload

需要认证: 是

请求参数: multipart/form-data

下载软件文件

接口地址: GET /api/commerce/software/download

需要认证: 是

请求参数:

响应: 文件下载

支付管理

支付模块提供支付宝和微信支付功能。

支付宝支付

支付宝支付下单

接口地址: POST /api/commerce/payments/alipay

需要认证: 是

请求体:

{
  "order_id": "1",
  "subject": "商品订单",
  "return_url": "https://example.com/return"
}

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "下单成功",
  "data": {
    "provider": "alipay",
    "order_number": "ORD202601010001",
    "pay_url": "https://openapi.alipay.com/gateway.do?...",
    "code_url": null
  }
}

支付宝支付回调

接口地址: POST /api/commerce/payments/notify/alipay

需要认证: 否

说明: 支付宝异步回调接口，由支付宝服务器调用。

微信支付

微信支付下单

接口地址: POST /api/commerce/payments/wechat

需要认证: 是

请求体:

{
  "order_id": "1",
  "subject": "商品订单",
  "return_url": "https://example.com/return"
}

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "下单成功",
  "data": {
    "provider": "wechat",
    "order_number": "ORD202601010001",
    "pay_url": "weixin://wxpay/bizpayurl?...",
    "code_url": "weixin://wxpay/bizpayurl?..."
  }
}

微信支付回调

接口地址: POST /api/commerce/payments/notify/wechat

需要认证: 否

说明: 微信支付异步回调接口，由微信支付服务器调用。

枚举类型说明

商品状态 (ItemStatus)

订单状态 (OrderStatus)

支付方式 (PaymentMethod)

评价状态 (ReviewStatus)

软件许可证类型 (SoftwareLicenseType)

使用示例

Python 示例

import requests

base_url = 'http://localhost:8000/api/commerce'
token = 'your_access_token'
headers = {'Authorization': f'Bearer {token}'}

# 创建商品
response = requests.post(
    f'{base_url}/items/create',
    headers=headers,
    json={
        'code': 'ITEM001',
        'name': '商品名称',
        'price': 99.99,
        'category': '电子产品',
        'status': 'available'
    }
)
print(response.json())

# 添加到购物车
response = requests.post(
    f'{base_url}/carts/add',
    headers=headers,
    json={
        'item_id': '1',
        'quantity': 2
    }
)
print(response.json())

# 创建订单
response = requests.post(
    f'{base_url}/orders/create',
    headers=headers,
    json={
        'items': [{'item_id': '1', 'quantity': 2}],
        'shipping_address': '配送地址'
    }
)
print(response.json())

# 支付宝支付
response = requests.post(
    f'{base_url}/payments/alipay',
    headers=headers,
    json={
        'order_id': '1',
        'subject': '商品订单',
        'return_url': 'https://example.com/return'
    }
)
print(response.json())

# 创建评价
response = requests.post(
    f'{base_url}/reviews/create',
    headers=headers,
    json={
        'item_id': '1',
        'order_id': '1',
        'rating': 5,
        'content': '商品很好用！'
    }
)
print(response.json())

JavaScript 示例

// 获取商品列表
async function getItems(token, filters = {}) {
  const params = new URLSearchParams(filters);
  const response = await fetch(
    `http://localhost:8000/api/commerce/items/list?${params}`,
    {
      headers: { Authorization: `Bearer ${token}` },
    }
  );
  return await response.json();
}

// 添加到购物车
async function addToCart(token, itemId, quantity) {
  const response = await fetch("http://localhost:8000/api/commerce/carts/add", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ item_id: itemId, quantity }),
  });
  return await response.json();
}

// 创建订单
async function createOrder(token, orderData) {
  const response = await fetch(
    "http://localhost:8000/api/commerce/orders/create",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(orderData),
    }
  );
  return await response.json();
}

// 支付
async function alipay(token, paymentData) {
  const response = await fetch(
    "http://localhost:8000/api/commerce/payments/alipay",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(paymentData),
    }
  );
  return await response.json();
}

注意事项

1. 订单创建: 创建订单时会自动扣减库存，订单取消或超时会自动释放库存。
2. 支付回调: 支付回调接口不需要认证，但需要验证签名的合法性。
3. 评价规则: 每个订单每个商品只能评价一次，评价后不可修改。
4. 库存管理: 库存不足时商品不可购买，需要管理员补充库存。
5. 文件上传: 图片和附件上传使用 multipart/form-data 格式，注意文件大小限制。
6. 软件下载: 已购买的软件才能下载，下载权限通过购买记录验证。
7. 价格计算: 订单总金额 = 商品价格 × 数量 + 运费 - 优惠金额。
8. 购物车清理: 创建订单后，已选中的购物车项会自动清空。

相关文档

• 数据模型参考
• 系统模块 API
• AI 模块 API
• API 概览