AI智能销售平台API接口规范

文档信息

文档版本：v1.1.0
作者：Architect Agent
更新日期：2024-12-13
引用来源：docs/PRD.md, docs/User_Story_Map.md, backend/src/routes

1. API概览

1.1 API基础信息

API版本：v1
基础URL：https://api.ecommerce-ai.com/api/v1
数据格式：JSON
字符编码：UTF-8
认证方式：JWT Bearer Token

1.2 响应格式规范

成功响应

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

错误响应

{
  "code": 400,
  "message": "请求参数错误",
  "errors": [
    {
      "field": "username",
      "message": "用户名不能为空"
    }
  ],
  "timestamp": 1640332800000
}

1.3 通用状态码

状态码	说明	业务场景
200	成功	请求成功处理
201	创建成功	资源创建成功
400	请求错误	参数验证失败
401	未授权	未提供有效Token
403	禁止访问	权限不足
404	资源不存在	请求的资源不存在
429	请求过多	频率限制
500	服务器错误	服务器内部错误

1.4 健康检查

接口：GET /health

响应数据：

{
  "status": "ok",
  "service": "ecommerce-api",
  "version": "v1",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

2. 认证授权API

路由前缀：`/auth` 或 `/users`

2.1 用户注册

接口：POST /auth/register

请求参数（支持两种注册方式）：

传统注册

{
  "username": "user123",
  "email": "user@example.com",
  "password": "password123",
  "role": "buyer"
}

手机验证码注册

{
  "phone": "13800138000",
  "code": "123456",
  "password": "password123",
  "role": "buyer"
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | username | string | ❌ | 用户名(3-20字符)，传统注册必填 | | email | string | ❌ | 邮箱地址 | | phone | string | ❌ | 手机号，验证码注册必填 | | code | string | ❌ | 6位验证码，验证码注册必填 | | password | string | ❌ | 密码 | | role | string | ❌ | 角色(buyer/seller)，默认buyer |

响应数据：

{
  "code": 201,
  "message": "注册成功",
  "data": {
    "user": {
      "id": "user123",
      "username": "user123",
      "email": "user@example.com",
      "role": "buyer",
      "createdAt": "2024-01-01T00:00:00Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "timestamp": 1640332800000
}

2.2 用户登录

接口：POST /auth/login

请求参数：

{
  "username": "user123",
  "password": "password123"
}

响应数据：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user": {
      "id": "user123",
      "username": "user123",
      "email": "user@example.com",
      "role": "buyer"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 86400
  },
  "timestamp": 1640332800000
}

2.3 用户登出

接口：POST /auth/logout

请求头：

Authorization: Bearer {token}

响应数据：

{
  "code": 200,
  "message": "登出成功",
  "timestamp": 1640332800000
}

2.4 刷新Token

接口：POST /auth/refresh-token

请求参数：

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应数据：

{
  "code": 200,
  "message": "Token刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 86400
  },
  "timestamp": 1640332800000
}

2.5 获取用户信息

接口：GET /auth/profile

请求头：

Authorization: Bearer {token}

响应数据：

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": "user123",
    "username": "user123",
    "email": "user@example.com",
    "phone": "13800138000",
    "avatar": "https://oss.example.com/avatars/user123.jpg",
    "role": "buyer",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  "timestamp": 1640332800000
}

2.6 更新用户信息

接口：PUT /auth/profile

请求头：

Authorization: Bearer {token}

请求参数：

{
  "username": "newUsername",
  "email": "newemail@example.com",
  "phone": "13900139000",
  "avatar": "https://oss.example.com/avatars/new.jpg"
}

响应数据：

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": "user123",
    "username": "newUsername",
    "email": "newemail@example.com"
  },
  "timestamp": 1640332800000
}

2.7 删除账号

接口：DELETE /auth/profile

请求头：

Authorization: Bearer {token}

响应数据：

{
  "code": 200,
  "message": "账号已删除",
  "timestamp": 1640332800000
}

2.8 获取所有用户（管理员）

接口：GET /users

请求头：

Authorization: Bearer {token}

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | number | ❌ | 页码，默认1 | | limit | number | ❌ | 每页数量，默认20 |

响应数据：

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5
    }
  },
  "timestamp": 1640332800000
}

2.9 根据ID获取用户

接口：GET /users/{id}

请求头：

Authorization: Bearer {token}

2.10 更新用户（管理员）

接口：PUT /users/{id}

请求头：

Authorization: Bearer {token}

权限：admin

2.11 删除用户（管理员）

接口：DELETE /users/{id}

请求头：

Authorization: Bearer {token}

权限：admin

3. 手机验证码认证API

路由前缀：`/phone-auth`

3.1 发送注册验证码

接口：POST /phone-auth/send-register-code

请求参数：

{
  "phone": "13800138000"
}

响应数据：

{
  "code": 200,
  "message": "验证码发送成功",
  "data": {
    "verificationCode": "123456",
    "expiresIn": 300
  },
  "timestamp": 1640332800000
}

注：verificationCode 仅在开发环境返回

3.2 手机号验证码注册

接口：POST /phone-auth/register

请求参数：

{
  "phone": "13800138000",
  "code": "123456",
  "username": "user123",
  "email": "user@example.com",
  "password": "password123",
  "role": "buyer"
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | phone | string | ✅ | 手机号 | | code | string | ✅ | 6位验证码 | | username | string | ❌ | 用户名(3-20字符) | | email | string | ❌ | 邮箱地址 | | password | string | ❌ | 密码(最少6位) | | role | string | ❌ | 角色(buyer/seller)，默认buyer |

响应数据：

{
  "code": 200,
  "message": "注册成功",
  "data": {
    "user": {
      "id": "user123",
      "phone": "13800138000",
      "username": "user123"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "timestamp": 1640332800000
}

3.3 发送登录验证码

接口：POST /phone-auth/send-login-code

请求参数：

{
  "phone": "13800138000"
}

响应数据：

{
  "code": 200,
  "message": "验证码发送成功",
  "data": {
    "verificationCode": "123456",
    "expiresIn": 300
  },
  "timestamp": 1640332800000
}

3.4 手机号验证码登录

接口：POST /phone-auth/login

请求参数：

{
  "phone": "13800138000",
  "code": "123456"
}

响应数据：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user": {
      "id": "user123",
      "phone": "13800138000",
      "username": "user123"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "timestamp": 1640332800000
}

4. 验证码服务API

路由前缀：`/verification`

4.1 发送验证码

接口：POST /verification/send-code

请求参数：

{
  "phone": "13800138000",
  "type": "register"
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | phone | string | ✅ | 手机号 | | type | string | ❌ | 类型(register/login/reset-password/change-phone)，默认register |

响应数据：

{
  "code": 200,
  "message": "验证码发送成功",
  "data": {
    "verificationCode": "123456",
    "expiresIn": 300
  },
  "timestamp": 1640332800000
}

4.2 验证验证码

接口：POST /verification/verify

请求参数：

{
  "phone": "13800138000",
  "code": "123456",
  "type": "register"
}

响应数据：

{
  "code": 200,
  "message": "验证码验证成功",
  "data": {
    "verified": true
  },
  "timestamp": 1640332800000
}

4.3 获取验证码剩余时间

接口：GET /verification/remaining-time

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | phone | string | ✅ | 手机号 | | type | string | ❌ | 类型，默认register |

响应数据：

{
  "code": 200,
  "message": "获取验证码剩余时间成功",
  "data": {
    "remainingTime": 180,
    "hasCode": true
  },
  "timestamp": 1640332800000
}

5. 商品管理API

路由前缀：`/products`

5.1 获取商品列表

接口：GET /products

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | number | ❌ | 页码，默认1 | | limit | number | ❌ | 每页数量，默认20 | | category | string | ❌ | 分类ID | | sortBy | string | ❌ | 排序字段 | | sortOrder | string | ❌ | 排序方向(asc/desc) |

响应数据：

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": "prod001",
        "name": "iPhone 15 Pro",
        "description": "最新款iPhone",
        "price": 7999,
        "originalPrice": 8999,
        "stock": 100,
        "images": ["https://oss.example.com/products/iphone15.jpg"],
        "category": {
          "id": "cat001",
          "name": "手机"
        },
        "seller": {
          "id": "seller001",
          "username": "apple官方"
        },
        "status": "active",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5
    }
  },
  "timestamp": 1640332800000
}

5.2 搜索商品

接口：GET /products/search

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | keyword | string | ✅ | 搜索关键词 | | page | number | ❌ | 页码，默认1 | | limit | number | ❌ | 每页数量，默认20 |

响应数据：

{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 50,
      "pages": 3
    }
  },
  "timestamp": 1640332800000
}

5.3 获取商品详情

接口：GET /products/{id}

路径参数： | 参数 | 类型 | 说明 | |------|------|------| | id | string | 商品ID |

响应数据：

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": "prod001",
    "name": "iPhone 15 Pro",
    "description": "最新款iPhone，搭载A17芯片",
    "price": 7999,
    "originalPrice": 8999,
    "stock": 100,
    "images": [
      "https://oss.example.com/products/iphone15-1.jpg",
      "https://oss.example.com/products/iphone15-2.jpg"
    ],
    "category": {
      "id": "cat001",
      "name": "手机",
      "parent": null
    },
    "seller": {
      "id": "seller001",
      "username": "apple官方",
      "avatar": "https://oss.example.com/avatars/apple.jpg"
    },
    "specifications": [
      {
        "name": "颜色",
        "value": "深空黑"
      },
      {
        "name": "存储",
        "value": "256GB"
      }
    ],
    "tags": ["新品", "热销"],
    "status": "active",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  "timestamp": 1640332800000
}

5.4 创建商品（商家）

接口：POST /products

请求头：

Authorization: Bearer {token}

权限：seller, admin

请求参数：

{
  "name": "商品名称",
  "description": "商品描述",
  "price": 199,
  "originalPrice": 299,
  "stock": 50,
  "category": "cat001",
  "images": ["https://oss.example.com/products/image.jpg"],
  "specifications": [
    {
      "name": "颜色",
      "value": "黑色"
    }
  ],
  "tags": ["新品"]
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | ✅ | 商品名称(1-200字符) | | description | string | ❌ | 商品描述(最多5000字符) | | price | number | ✅ | 价格(正数) | | originalPrice | number | ❌ | 原价 | | stock | number | ✅ | 库存(非负整数) | | category | string | ✅ | 分类ID | | images | string[] | ❌ | 商品图片URL数组 | | specifications | object[] | ❌ | 规格数组 | | tags | string[] | ❌ | 标签数组 |

响应数据：

{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": "prod002",
    "name": "商品名称",
    "price": 199,
    "stock": 50,
    "status": "pending",
    "createdAt": "2024-01-01T00:00:00Z"
  },
  "timestamp": 1640332800000
}

5.5 更新商品

接口：PUT /products/{id}

请求头：

Authorization: Bearer {token}

权限：seller(仅自己的商品), admin

请求参数：

{
  "name": "更新后的商品名称",
  "price": 189,
  "stock": 100,
  "status": "active"
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | ❌ | 商品名称 | | description | string | ❌ | 商品描述 | | price | number | ❌ | 价格 | | originalPrice | number | ❌ | 原价 | | stock | number | ❌ | 库存 | | category | string | ❌ | 分类ID | | images | string[] | ❌ | 商品图片 | | specifications | object[] | ❌ | 规格 | | tags | string[] | ❌ | 标签 | | status | string | ❌ | 状态(active/inactive/sold_out) |

响应数据：

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": "prod002",
    "name": "更新后的商品名称",
    "price": 189
  },
  "timestamp": 1640332800000
}

5.6 删除商品

接口：DELETE /products/{id}

请求头：

Authorization: Bearer {token}

权限：seller(仅自己的商品), admin

响应数据：

{
  "code": 200,
  "message": "删除成功",
  "timestamp": 1640332800000
}

5.7 获取分类列表

接口：GET /products/categories

响应数据：

{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": "cat001",
      "name": "手机",
      "parent": null,
      "children": [
        {
          "id": "cat002",
          "name": "智能手机"
        }
      ]
    }
  ],
  "timestamp": 1640332800000
}

5.8 创建分类（管理员）

接口：POST /products/categories

请求头：

Authorization: Bearer {token}

权限：admin

5.9 更新分类（管理员）

接口：PUT /products/categories/{id}

权限：admin

5.10 删除分类（管理员）

接口：DELETE /products/categories/{id}

权限：admin

5.11 获取用户推荐商品

接口：GET /products/recommendations/user

请求头：

Authorization: Bearer {token}

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | limit | number | ❌ | 数量，默认20 |

5.12 获取相关商品

接口：GET /products/recommendations/{id}

路径参数： | 参数 | 类型 | 说明 | |------|------|------| | id | string | 商品ID |

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | limit | number | ❌ | 数量，默认10 |

6. 搜索服务API

路由前缀：`/search`

6.1 搜索商品（Elasticsearch）

接口：GET /search

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | keyword | string | ✅ | 搜索关键词 | | page | number | ❌ | 页码，默认1 | | limit | number | ❌ | 每页数量，默认20 | | category | string | ❌ | 分类筛选 | | minPrice | number | ❌ | 最低价格 | | maxPrice | number | ❌ | 最高价格 | | brand | string | ❌ | 品牌筛选 | | sortBy | string | ❌ | 排序字段(price/sales/rating) | | sortOrder | string | ❌ | 排序方向(asc/desc) |

响应数据：

{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "items": [
      {
        "id": "prod001",
        "name": "iPhone 15 Pro",
        "price": 7999,
        "images": ["..."],
        "score": 15.5
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5
    },
    "aggregations": {
      "categories": [...],
      "brands": [...],
      "priceRanges": [...]
    }
  },
  "timestamp": 1640332800000
}

6.2 获取搜索建议

接口：GET /search/suggestions

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | q | string | ✅ | 搜索前缀 | | limit | number | ❌ | 数量，默认10 |

响应数据：

{
  "code": 200,
  "message": "获取成功",
  "data": [
    "iPhone 15",
    "iPhone 15 Pro",
    "iPhone 15 Pro Max"
  ],
  "timestamp": 1640332800000
}

6.3 获取热门搜索词

接口：GET /search/hot-keywords

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | limit | number | ❌ | 数量，默认10 |

响应数据：

{
  "code": 200,
  "message": "获取成功",
  "data": [
    { "keyword": "iPhone", "count": 1000 },
    { "keyword": "华为", "count": 800 }
  ],
  "timestamp": 1640332800000
}

6.4 获取搜索历史

接口：GET /search/history

请求头：

Authorization: Bearer {token}

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | limit | number | ❌ | 数量，默认10 |

响应数据：

{
  "code": 200,
  "message": "获取成功",
  "data": [
    { "keyword": "iPhone", "timestamp": "2024-01-01T00:00:00Z" },
    { "keyword": "手机壳", "timestamp": "2024-01-01T00:00:00Z" }
  ],
  "timestamp": 1640332800000
}

6.5 清空搜索历史

接口：DELETE /search/history

请求头：

Authorization: Bearer {token}

响应数据：

{
  "code": 200,
  "message": "清空成功",
  "timestamp": 1640332800000
}

6.6 删除单条搜索历史

接口：DELETE /search/history/item

请求头：

Authorization: Bearer {token}

请求参数：

{
  "keyword": "iPhone"
}

响应数据：

{
  "code": 200,
  "message": "删除成功",
  "timestamp": 1640332800000
}

7. 订单管理API

路由前缀：`/orders`

⚠️ 注意：订单相关接口目前为占位符实现，返回 "Not implemented yet"

7.1 获取订单列表

接口：GET /orders

请求头：

Authorization: Bearer {token}

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | number | ❌ | 页码 | | limit | number | ❌ | 每页数量 | | status | string | ❌ | 订单状态 |

响应数据：

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "order001",
        "orderNo": "202401010001",
        "totalAmount": 7999,
        "status": "pending",
        "paymentStatus": "pending",
        "items": [
          {
            "product": {
              "id": "prod001",
              "name": "iPhone 15 Pro",
              "image": "https://oss.example.com/products/iphone15.jpg"
            },
            "quantity": 1,
            "price": 7999
          }
        ],
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 5,
      "pages": 1
    }
  },
  "timestamp": 1640332800000
}

7.2 获取订单详情

接口：GET /orders/{id}

请求头：

Authorization: Bearer {token}

7.3 获取订单统计

接口：GET /orders/stats

请求头：

Authorization: Bearer {token}

7.4 创建订单

接口：POST /orders

请求头：

Authorization: Bearer {token}

请求参数：

{
  "items": [
    {
      "productId": "prod001",
      "quantity": 1,
      "price": 7999
    }
  ],
  "shippingAddress": {
    "name": "张三",
    "phone": "13800138000",
    "province": "北京市",
    "city": "北京市",
    "district": "朝阳区",
    "detail": "某某街道123号"
  },
  "paymentMethod": "alipay",
  "couponCode": "DISCOUNT10",
  "note": "请尽快发货"
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | items | array | ✅ | 订单商品列表 | | items[].productId | string | ✅ | 商品ID | | items[].quantity | number | ✅ | 数量(正整数) | | items[].price | number | ✅ | 单价(正数) | | shippingAddress | object | ✅ | 收货地址 | | shippingAddress.name | string | ✅ | 收货人姓名 | | shippingAddress.phone | string | ✅ | 收货人电话 | | shippingAddress.province | string | ✅ | 省份 | | shippingAddress.city | string | ✅ | 城市 | | shippingAddress.district | string | ✅ | 区县 | | shippingAddress.detail | string | ✅ | 详细地址 | | paymentMethod | string | ✅ | 支付方式(alipay/wechat/card) | | couponCode | string | ❌ | 优惠券码 | | note | string | ❌ | 订单备注(最多500字符) |

响应数据：

{
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "id": "order001",
    "orderNo": "202401010001",
    "totalAmount": 7999,
    "status": "pending",
    "paymentStatus": "pending",
    "createdAt": "2024-01-01T00:00:00Z"
  },
  "timestamp": 1640332800000
}

7.5 取消订单

接口：PUT /orders/{id}/cancel

请求头：

Authorization: Bearer {token}

7.6 确认收货

接口：PUT /orders/{id}/confirm

请求头：

Authorization: Bearer {token}

7.7 更新订单状态（商家/管理员）

接口：PUT /orders/{id}/status

请求头：

Authorization: Bearer {token}

权限：seller, admin

7.8 获取所有订单（商家/管理员）

接口：GET /orders/manage/all

请求头：

Authorization: Bearer {token}

权限：seller, admin

8. 购物车API

路由前缀：`/orders/cart`

⚠️ 注意：购物车相关接口目前为占位符实现

8.1 获取购物车商品

接口：GET /orders/cart/items

请求头：

Authorization: Bearer {token}

8.2 添加商品到购物车

接口：POST /orders/cart/add

请求头：

Authorization: Bearer {token}

8.3 更新购物车商品

接口：PUT /orders/cart/update

请求头：

Authorization: Bearer {token}

8.4 移除购物车商品

接口：DELETE /orders/cart/{itemId}

请求头：

Authorization: Bearer {token}

8.5 清空购物车

接口：DELETE /orders/cart/clear

请求头：

Authorization: Bearer {token}

9. 支付服务API

路由前缀：`/payments`

⚠️ 注意：支付相关接口目前为占位符实现

9.1 创建支付

接口：POST /payments/create

请求头：

Authorization: Bearer {token}

请求参数：

{
  "orderId": "order001",
  "paymentMethod": "alipay",
  "amount": 7999
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | orderId | string | ✅ | 订单ID | | paymentMethod | string | ✅ | 支付方式(alipay/wechat/card) | | amount | number | ✅ | 支付金额(正数) |

9.2 查询支付状态

接口：GET /payments/query/{paymentId}

请求头：

Authorization: Bearer {token}

9.3 申请退款

接口：POST /payments/refund

请求头：

Authorization: Bearer {token}

请求参数：

{
  "orderId": "order001",
  "amount": 7999,
  "reason": "商品质量问题"
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | orderId | string | ✅ | 订单ID | | amount | number | ✅ | 退款金额(正数) | | reason | string | ✅ | 退款原因(最多500字符) |

9.4 支付宝回调

接口：POST /payments/notify/alipay

公开接口，由支付宝服务器调用

9.5 微信支付回调

接口：POST /payments/notify/wechat

公开接口，由微信支付服务器调用

9.6 获取交易记录（管理员）

接口：GET /payments/transactions

请求头：

Authorization: Bearer {token}

权限：admin

9.7 对账（管理员）

接口：GET /payments/reconciliation

请求头：

Authorization: Bearer {token}

权限：admin

10. 客服系统API

路由前缀：`/chat`

10.1 创建客服会话

接口：POST /chat/sessions

请求头（可选）：

Authorization: Bearer {token}

请求参数：

{
  "question": "这个商品有优惠吗？",
  "productId": "prod001",
  "orderId": "order001"
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | question | string | ✅ | 问题内容(1-1000字符) | | productId | string | ❌ | 关联商品ID | | orderId | string | ❌ | 关联订单ID |

响应数据：

{
  "code": 201,
  "message": "会话创建成功",
  "data": {
    "id": "session001",
    "sessionId": "session001",
    "userId": "user123",
    "userName": "用户",
    "userAvatar": "https://...",
    "status": "active",
    "source": "web",
    "aiType": "coze",
    "messageCount": 2,
    "unreadCount": 0,
    "messages": [
      {
        "id": "msg001",
        "type": "user",
        "content": "这个商品有优惠吗？",
        "timestamp": "2024-01-01T00:00:00Z"
      },
      {
        "id": "msg002",
        "type": "ai",
        "content": "您好！目前这款商品正在参加双十一活动...",
        "timestamp": "2024-01-01T00:00:01Z"
      }
    ],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

10.2 获取会话列表

接口：GET /chat/sessions

请求头：

Authorization: Bearer {token}

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | number | ❌ | 页码，默认1 | | limit | number | ❌ | 每页数量，默认20 |

响应数据：

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 10,
      "pages": 1
    }
  }
}

10.3 获取会话详情

接口：GET /chat/sessions/{id}

请求头：

Authorization: Bearer {token}

10.4 获取消息历史

接口：GET /chat/sessions/{id}/messages

请求头：

Authorization: Bearer {token}

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | number | ❌ | 页码，默认1 | | limit | number | ❌ | 每页数量，默认20 |

10.5 发送消息

接口：POST /chat/sessions/{id}/messages

请求头：

Authorization: Bearer {token}

请求参数：

{
  "content": "可以包邮吗？"
}

参数说明： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | content | string | ✅ | 消息内容(1-1000字符) |

响应数据：

{
  "code": 201,
  "message": "消息发送成功",
  "data": {
    "messageId": "msg003",
    "content": "可以包邮吗？",
    "type": "user",
    "timestamp": "2024-01-01T00:00:02Z",
    "status": "sent",
    "transferred": false
  }
}

10.6 转接人工客服

接口：PUT /chat/sessions/{id}/transfer

请求头：

Authorization: Bearer {token}

响应数据：

{
  "code": 200,
  "message": "转接成功",
  "data": {
    "sessionId": "session001",
    "status": "pending"
  }
}

10.7 关闭会话

接口：PUT /chat/sessions/{id}/close

请求头：

Authorization: Bearer {token}

响应数据：

{
  "code": 200,
  "message": "会话已关闭",
  "data": {
    "sessionId": "session001",
    "status": "closed",
    "closedAt": "2024-01-01T01:00:00Z"
  }
}

10.8 评价会话

接口：POST /chat/sessions/{id}/rating

请求头：

Authorization: Bearer {token}

请求参数：

{
  "rating": 5,
  "comment": "服务很好"
}

响应数据：

{
  "code": 200,
  "message": "评价成功",
  "data": {
    "sessionId": "session001",
    "rating": 5,
    "comment": "服务很好"
  }
}

11. 客服管理API（客服人员）

路由前缀：`/chat/agent`

11.1 获取客服会话列表

接口：GET /chat/agent/sessions

请求头：

Authorization: Bearer {token}

权限：customer_service, admin

查询参数： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | number | ❌ | 页码，默认1 | | limit | number | ❌ | 每页数量，默认20 |

11.2 接受会话

接口：PUT /chat/agent/sessions/{id}/accept

请求头：

Authorization: Bearer {token}

权限：customer_service, admin

响应数据：

{
  "code": 200,
  "message": "已接受会话",
  "data": {
    "sessionId": "session001",
    "agentId": "agent001",
    "status": "active"
  }
}

11.3 获取客服统计

接口：GET /chat/agent/stats

请求头：

Authorization: Bearer {token}

权限：customer_service, admin

响应数据：

{
  "code": 200,
  "message": "success",
  "data": {
    "agentId": "agent001",
    "totalSessions": 100,
    "activeSessions": 5,
    "avgRating": 4.8,
    "avgResponseTime": 30
  }
}

12. 知识库管理API（管理员）

路由前缀：`/chat/knowledge`

12.1 获取知识库列表

接口：GET /chat/knowledge

请求头：

Authorization: Bearer {token}

权限：admin

12.2 创建知识库条目

接口：POST /chat/knowledge

请求头：

Authorization: Bearer {token}

权限：admin

请求参数：

{
  "question": "如何退货？",
  "answer": "您可以在订单详情页面申请退货...",
  "category": "售后服务"
}

12.3 更新知识库条目

接口：PUT /chat/knowledge/{id}

请求头：

Authorization: Bearer {token}

权限：admin

12.4 删除知识库条目

接口：DELETE /chat/knowledge/{id}

请求头：

Authorization: Bearer {token}

权限：admin

13. API安全规范

13.1 认证机制

JWT Token：Bearer Token认证
Token刷新：支持Token刷新机制
会话管理：支持多设备登录管理

13.2 权限控制

角色	说明	权限范围
buyer	买家	浏览商品、下单、管理自己的订单
seller	商家	管理自己的商品、处理订单
customer_service	客服	处理客服会话
admin	管理员	全部权限

13.3 安全防护

频率限制：认证接口有频率限制（authLimiter）
订单限制：订单创建有频率限制（orderLimiter）
参数验证：使用Joi进行输入参数严格验证
SQL注入防护：参数化查询
XSS防护：输出内容转义

14. API接口汇总表

14.1 认证相关 `/auth` `/users`

方法	路径	说明	认证	权限	状态
POST	/auth/register	用户注册	❌	-	✅
POST	/auth/login	用户登录	❌	-	✅
POST	/auth/logout	用户登出	✅	-	✅
POST	/auth/refresh-token	刷新Token	❌	-	✅
POST	/auth/send-register-code	发送注册验证码	❌	-	✅
POST	/auth/send-login-code	发送登录验证码	❌	-	✅
GET	/auth/profile	获取用户信息	✅	-	✅
PUT	/auth/profile	更新用户信息	✅	-	✅
DELETE	/auth/profile	删除账号	✅	-	✅
GET	/users	获取所有用户	✅	admin	✅
GET	/users/:id	获取用户详情	✅	-	✅
PUT	/users/:id	更新用户	✅	admin	✅
DELETE	/users/:id	删除用户	✅	admin	✅

14.2 手机验证码认证 `/phone-auth`

方法	路径	说明	认证	状态
POST	/phone-auth/send-register-code	发送注册验证码	❌	✅
POST	/phone-auth/register	手机号注册	❌	✅
POST	/phone-auth/send-login-code	发送登录验证码	❌	✅
POST	/phone-auth/login	手机号登录	❌	✅

14.3 验证码服务 `/verification`

方法	路径	说明	认证	状态
POST	/verification/send-code	发送验证码	❌	✅
POST	/verification/verify	验证验证码	❌	✅
GET	/verification/remaining-time	获取剩余时间	❌	✅

14.4 商品管理 `/products`

方法	路径	说明	认证	权限	状态
GET	/products	获取商品列表	可选	-	✅
GET	/products/search	搜索商品	可选	-	✅
GET	/products/categories	获取分类列表	❌	-	✅
GET	/products/:id	获取商品详情	可选	-	✅
GET	/products/recommendations/user	用户推荐	✅	-	✅
GET	/products/recommendations/:id	相关商品	❌	-	✅
POST	/products	创建商品	✅	seller/admin	✅
PUT	/products/:id	更新商品	✅	seller/admin	✅
DELETE	/products/:id	删除商品	✅	seller/admin	✅
POST	/products/categories	创建分类	✅	admin	✅
PUT	/products/categories/:id	更新分类	✅	admin	✅
DELETE	/products/categories/:id	删除分类	✅	admin	✅

14.5 搜索服务 `/search`

方法	路径	说明	认证	状态
GET	/search	搜索商品	可选	✅
GET	/search/suggestions	搜索建议	❌	✅
GET	/search/hot-keywords	热门搜索词	❌	✅
GET	/search/history	搜索历史	✅	✅
DELETE	/search/history	清空搜索历史	✅	✅
DELETE	/search/history/item	删除单条历史	✅	✅

14.6 订单管理 `/orders`

方法	路径	说明	认证	权限	状态
GET	/orders	获取订单列表	✅	-	⏳
GET	/orders/stats	订单统计	✅	-	⏳
GET	/orders/:id	获取订单详情	✅	-	⏳
POST	/orders	创建订单	✅	-	⏳
PUT	/orders/:id/cancel	取消订单	✅	-	⏳
PUT	/orders/:id/confirm	确认收货	✅	-	⏳
PUT	/orders/:id/status	更新订单状态	✅	seller/admin	⏳
GET	/orders/manage/all	获取所有订单	✅	seller/admin	⏳

14.7 购物车 `/orders/cart`

方法	路径	说明	认证	状态
GET	/orders/cart/items	获取购物车	✅	⏳
POST	/orders/cart/add	添加商品	✅	⏳
PUT	/orders/cart/update	更新商品	✅	⏳
DELETE	/orders/cart/:itemId	移除商品	✅	⏳
DELETE	/orders/cart/clear	清空购物车	✅	⏳

14.8 支付服务 `/payments`

方法	路径	说明	认证	权限	状态
POST	/payments/create	创建支付	✅	-	⏳
GET	/payments/query/:paymentId	查询支付	✅	-	⏳
POST	/payments/refund	申请退款	✅	-	⏳
POST	/payments/notify/alipay	支付宝回调	❌	-	⏳
POST	/payments/notify/wechat	微信回调	❌	-	⏳
GET	/payments/transactions	交易记录	✅	admin	⏳
GET	/payments/reconciliation	对账	✅	admin	⏳

14.9 客服系统 `/chat`

方法	路径	说明	认证	权限	状态
POST	/chat/sessions	创建会话	可选	-	✅
GET	/chat/sessions	获取会话列表	✅	-	✅
GET	/chat/sessions/:id	获取会话详情	✅	-	✅
GET	/chat/sessions/:id/messages	获取消息历史	✅	-	✅
POST	/chat/sessions/:id/messages	发送消息	✅	-	✅
PUT	/chat/sessions/:id/transfer	转接人工	✅	-	✅
PUT	/chat/sessions/:id/close	关闭会话	✅	-	✅
POST	/chat/sessions/:id/rating	评价会话	✅	-	✅
GET	/chat/agent/sessions	客服会话列表	✅	cs/admin	✅
PUT	/chat/agent/sessions/:id/accept	接受会话	✅	cs/admin	✅
GET	/chat/agent/stats	客服统计	✅	cs/admin	✅
GET	/chat/knowledge	知识库列表	✅	admin	✅
POST	/chat/knowledge	创建知识库	✅	admin	✅
PUT	/chat/knowledge/:id	更新知识库	✅	admin	✅
DELETE	/chat/knowledge/:id	删除知识库	✅	admin	✅

状态说明：✅ 已实现 | ⏳ 占位符实现（待开发）

15. 错误码详细说明

15.1 通用错误码

错误码	说明	解决方案
400	参数验证失败	检查请求参数格式
401	未授权	检查Token是否有效
403	权限不足	检查用户权限
404	资源不存在	检查资源ID是否正确
429	请求过于频繁	降低请求频率
500	服务器内部错误	联系技术支持

15.2 业务错误码

错误码	说明	业务场景
20001	商品库存不足	下单时商品库存不足
20002	订单状态异常	订单无法进行当前操作
20003	支付失败	支付过程中出现错误
20004	验证码错误	验证码不正确或已过期
20005	手机号已注册	注册时手机号已存在
20006	手机号未注册	登录时手机号不存在

16. WebSocket接口

16.1 客服消息推送

连接地址：wss://api.ecommerce-ai.com/socket.io

房间订阅：

socket.join(`session:${sessionId}`);

消息事件：

// 接收AI消息
socket.on('message', (data) => {
  // data: {
  //   id: string,
  //   sessionId: string,
  //   content: string,
  //   type: 'ai' | 'user' | 'agent',
  //   senderType: string,
  //   senderId: string,
  //   senderName: string,
  //   createdAt: string,
  //   isRead: boolean
  // }
});

API规范审批

后端架构师：___________ 日期：___________
前端开发负责人：___________ 日期：___________
测试负责人：___________ 日期：___________

注：本API规范将根据业务需求和技术发展定期更新 最后更新：2024-12-13

API_Spec.md 39 KB Permalink Riwayat Mentahan

AI智能销售平台API接口规范

文档信息

1. API概览

1.1 API基础信息

1.2 响应格式规范

成功响应

错误响应

1.3 通用状态码

1.4 健康检查

2. 认证授权API

路由前缀：/auth 或 /users

2.1 用户注册

传统注册

手机验证码注册

2.2 用户登录

2.3 用户登出

2.4 刷新Token

2.5 获取用户信息

2.6 更新用户信息

2.7 删除账号

2.8 获取所有用户（管理员）

2.9 根据ID获取用户

2.10 更新用户（管理员）

2.11 删除用户（管理员）

3. 手机验证码认证API

路由前缀：/phone-auth

3.1 发送注册验证码

3.2 手机号验证码注册

3.3 发送登录验证码

3.4 手机号验证码登录

4. 验证码服务API

路由前缀：/verification

4.1 发送验证码

4.2 验证验证码

4.3 获取验证码剩余时间

5. 商品管理API

路由前缀：/products

5.1 获取商品列表

5.2 搜索商品

5.3 获取商品详情

5.4 创建商品（商家）

5.5 更新商品

5.6 删除商品

5.7 获取分类列表

5.8 创建分类（管理员）

5.9 更新分类（管理员）

5.10 删除分类（管理员）

5.11 获取用户推荐商品

5.12 获取相关商品

6. 搜索服务API

路由前缀：/search

6.1 搜索商品（Elasticsearch）

6.2 获取搜索建议

6.3 获取热门搜索词

6.4 获取搜索历史

6.5 清空搜索历史

6.6 删除单条搜索历史

7. 订单管理API

路由前缀：/orders

7.1 获取订单列表

7.2 获取订单详情

7.3 获取订单统计

7.4 创建订单

7.5 取消订单

7.6 确认收货

7.7 更新订单状态（商家/管理员）

7.8 获取所有订单（商家/管理员）

8. 购物车API

路由前缀：/orders/cart

8.1 获取购物车商品

8.2 添加商品到购物车

8.3 更新购物车商品

8.4 移除购物车商品

8.5 清空购物车

9. 支付服务API

路由前缀：/payments

9.1 创建支付

9.2 查询支付状态

9.3 申请退款

API_Spec.md 39 KB

Permalink Riwayat Mentahan

路由前缀：`/auth` 或 `/users`

路由前缀：`/phone-auth`

路由前缀：`/verification`

路由前缀：`/products`

路由前缀：`/search`

路由前缀：`/orders`

路由前缀：`/orders/cart`

路由前缀：`/payments`

路由前缀：`/chat`

路由前缀：`/chat/agent`

路由前缀：`/chat/knowledge`

14.1 认证相关 `/auth` `/users`

14.2 手机验证码认证 `/phone-auth`

14.3 验证码服务 `/verification`

14.4 商品管理 `/products`

14.5 搜索服务 `/search`

14.6 订单管理 `/orders`

14.7 购物车 `/orders/cart`

14.8 支付服务 `/payments`

14.9 客服系统 `/chat`