# 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 响应格式规范

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

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

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

### 1.4 健康检查
**接口**：`GET /health`

**响应数据**：
```json
{
  "status": "ok",
  "service": "ecommerce-api",
  "version": "v1",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```


---

## 2. 认证授权API

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

### 2.1 用户注册

**接口**：`POST /auth/register`

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

#### 传统注册
```json
{
  "username": "user123",
  "email": "user@example.com",
  "password": "password123",
  "role": "buyer"
}
```

#### 手机验证码注册
```json
{
  "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 |

**响应数据**：
```json
{
  "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`

**请求参数**：
```json
{
  "username": "user123",
  "password": "password123"
}
```

**响应数据**：
```json
{
  "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}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "登出成功",
  "timestamp": 1640332800000
}
```

### 2.4 刷新Token

**接口**：`POST /auth/refresh-token`

**请求参数**：
```json
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "Token刷新成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 86400
  },
  "timestamp": 1640332800000
}
```

### 2.5 获取用户信息

**接口**：`GET /auth/profile`

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

**响应数据**：
```json
{
  "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}
```

**请求参数**：
```json
{
  "username": "newUsername",
  "email": "newemail@example.com",
  "phone": "13900139000",
  "avatar": "https://oss.example.com/avatars/new.jpg"
}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": "user123",
    "username": "newUsername",
    "email": "newemail@example.com"
  },
  "timestamp": 1640332800000
}
```

### 2.7 删除账号

**接口**：`DELETE /auth/profile`

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

**响应数据**：
```json
{
  "code": 200,
  "message": "账号已删除",
  "timestamp": 1640332800000
}
```

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

**接口**：`GET /users`

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

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

**响应数据**：
```json
{
  "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`

**请求参数**：
```json
{
  "phone": "13800138000"
}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "验证码发送成功",
  "data": {
    "verificationCode": "123456",
    "expiresIn": 300
  },
  "timestamp": 1640332800000
}
```

> 注：`verificationCode` 仅在开发环境返回

### 3.2 手机号验证码注册

**接口**：`POST /phone-auth/register`

**请求参数**：
```json
{
  "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 |

**响应数据**：
```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "user": {
      "id": "user123",
      "phone": "13800138000",
      "username": "user123"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "timestamp": 1640332800000
}
```

### 3.3 发送登录验证码

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

**请求参数**：
```json
{
  "phone": "13800138000"
}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "验证码发送成功",
  "data": {
    "verificationCode": "123456",
    "expiresIn": 300
  },
  "timestamp": 1640332800000
}
```

### 3.4 手机号验证码登录

**接口**：`POST /phone-auth/login`

**请求参数**：
```json
{
  "phone": "13800138000",
  "code": "123456"
}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user": {
      "id": "user123",
      "phone": "13800138000",
      "username": "user123"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "timestamp": 1640332800000
}
```

---

## 4. 验证码服务API

### 路由前缀：`/verification`

### 4.1 发送验证码

**接口**：`POST /verification/send-code`

**请求参数**：
```json
{
  "phone": "13800138000",
  "type": "register"
}
```

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

**响应数据**：
```json
{
  "code": 200,
  "message": "验证码发送成功",
  "data": {
    "verificationCode": "123456",
    "expiresIn": 300
  },
  "timestamp": 1640332800000
}
```

### 4.2 验证验证码

**接口**：`POST /verification/verify`

**请求参数**：
```json
{
  "phone": "13800138000",
  "code": "123456",
  "type": "register"
}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "验证码验证成功",
  "data": {
    "verified": true
  },
  "timestamp": 1640332800000
}
```

### 4.3 获取验证码剩余时间

**接口**：`GET /verification/remaining-time`

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

**响应数据**：
```json
{
  "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) |

**响应数据**：
```json
{
  "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 |

**响应数据**：
```json
{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 50,
      "pages": 3
    }
  },
  "timestamp": 1640332800000
}
```

### 5.3 获取商品详情

**接口**：`GET /products/{id}`

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

**响应数据**：
```json
{
  "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

**请求参数**：
```json
{
  "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[] | ❌ | 标签数组 |

**响应数据**：
```json
{
  "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

**请求参数**：
```json
{
  "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) |

**响应数据**：
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": "prod002",
    "name": "更新后的商品名称",
    "price": 189
  },
  "timestamp": 1640332800000
}
```

### 5.6 删除商品

**接口**：`DELETE /products/{id}`

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

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

**响应数据**：
```json
{
  "code": 200,
  "message": "删除成功",
  "timestamp": 1640332800000
}
```

### 5.7 获取分类列表

**接口**：`GET /products/categories`

**响应数据**：
```json
{
  "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) |

**响应数据**：
```json
{
  "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 |

**响应数据**：
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    "iPhone 15",
    "iPhone 15 Pro",
    "iPhone 15 Pro Max"
  ],
  "timestamp": 1640332800000
}
```

### 6.3 获取热门搜索词

**接口**：`GET /search/hot-keywords`

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

**响应数据**：
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    { "keyword": "iPhone", "count": 1000 },
    { "keyword": "华为", "count": 800 }
  ],
  "timestamp": 1640332800000
}
```

### 6.4 获取搜索历史

**接口**：`GET /search/history`

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

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

**响应数据**：
```json
{
  "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}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "清空成功",
  "timestamp": 1640332800000
}
```

### 6.6 删除单条搜索历史

**接口**：`DELETE /search/history/item`

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

**请求参数**：
```json
{
  "keyword": "iPhone"
}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "删除成功",
  "timestamp": 1640332800000
}
```


---

## 7. 订单管理API

### 路由前缀：`/orders`

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

### 7.1 获取订单列表

**接口**：`GET /orders`

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

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

**响应数据**：
```json
{
  "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}
```

**请求参数**：
```json
{
  "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字符) |

**响应数据**：
```json
{
  "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}
```

**请求参数**：
```json
{
  "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}
```

**请求参数**：
```json
{
  "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}
```

**请求参数**：
```json
{
  "question": "这个商品有优惠吗？",
  "productId": "prod001",
  "orderId": "order001"
}
```

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

**响应数据**：
```json
{
  "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 |

**响应数据**：
```json
{
  "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}
```

**请求参数**：
```json
{
  "content": "可以包邮吗？"
}
```

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

**响应数据**：
```json
{
  "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}
```

**响应数据**：
```json
{
  "code": 200,
  "message": "转接成功",
  "data": {
    "sessionId": "session001",
    "status": "pending"
  }
}
```

### 10.7 关闭会话

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

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

**响应数据**：
```json
{
  "code": 200,
  "message": "会话已关闭",
  "data": {
    "sessionId": "session001",
    "status": "closed",
    "closedAt": "2024-01-01T01:00:00Z"
  }
}
```

### 10.8 评价会话

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

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

**请求参数**：
```json
{
  "rating": 5,
  "comment": "服务很好"
}
```

**响应数据**：
```json
{
  "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

**响应数据**：
```json
{
  "code": 200,
  "message": "已接受会话",
  "data": {
    "sessionId": "session001",
    "agentId": "agent001",
    "status": "active"
  }
}
```

### 11.3 获取客服统计

**接口**：`GET /chat/agent/stats`

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

**权限**：customer_service, admin

**响应数据**：
```json
{
  "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

**请求参数**：
```json
{
  "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`

**房间订阅**：
```javascript
socket.join(`session:${sessionId}`);
```

**消息事件**：
```javascript
// 接收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*