TakeoutSaaS.Docs/Document/04_API接口设计.md

# 外卖SaaS系统 - API接口设计

## 1. API设计规范

### 1.1 RESTful规范
- 使用标准HTTP方法：GET、POST、PUT、DELETE、PATCH
- URL使用名词复数形式，如：`/api/orders`
- 使用HTTP状态码表示请求结果
- 版本控制：`/api/v1/orders`

### 1.2 请求规范
- **Content-Type**：`application/json`
- **认证方式**：Bearer Token (JWT)
- **租户识别**：通过Header `X-Tenant-Id` 或从Token中解析

### 1.3 响应规范
```json
{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": "2024-01-01T12:00:00Z"
}
```

### 1.4 错误响应
```json
{
  "success": false,
  "code": 400,
  "message": "参数错误",
  "errors": [
    {
      "field": "phone",
      "message": "手机号格式不正确"
    }
  ],
  "timestamp": "2024-01-01T12:00:00Z"
}
```

### 1.5 HTTP状态码
- **200 OK**：请求成功
- **201 Created**：创建成功
- **204 No Content**：删除成功
- **400 Bad Request**：参数错误
- **401 Unauthorized**：未认证
- **403 Forbidden**：无权限
- **404 Not Found**：资源不存在
- **409 Conflict**：资源冲突
- **422 Unprocessable Entity**：业务逻辑错误
- **500 Internal Server Error**：服务器错误

### 1.6 分页规范
```json
// 请求参数
{
  "pageIndex": 1,
  "pageSize": 20,
  "sortBy": "createdAt",
  "sortOrder": "desc"
}

// 响应格式
{
  "success": true,
  "data": {
    "items": [],
    "totalCount": 100,
    "pageIndex": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}
```

## 2. 认证授权接口

### 2.1 用户登录
```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "phone": "13800138000",
  "password": "password123",
  "loginType": "customer" // customer, merchant, system
}

Response:
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 7200,
    "tokenType": "Bearer",
    "userInfo": {
      "id": "uuid",
      "phone": "13800138000",
      "nickname": "张三",
      "avatar": "https://..."
    }
  }
}
```

### 2.2 刷新Token
```http
POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response:
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 7200
  }
}
```

### 2.3 用户注册
```http
POST /api/v1/auth/register
Content-Type: application/json

{
  "phone": "13800138000",
  "password": "password123",
  "verificationCode": "123456",
  "nickname": "张三"
}
```

### 2.4 发送验证码
```http
POST /api/v1/auth/send-code
Content-Type: application/json

{
  "phone": "13800138000",
  "type": "register" // register, login, reset_password
}
```

## 3. 商家管理接口

### 3.1 获取商家列表
```http
GET /api/v1/merchants?pageIndex=1&pageSize=20&keyword=&status=1
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "美味餐厅",
        "logo": "https://...",
        "rating": 4.5,
        "totalSales": 1000,
        "status": 1,
        "createdAt": "2024-01-01T12:00:00Z"
      }
    ],
    "totalCount": 50,
    "pageIndex": 1,
    "pageSize": 20
  }
}
```

### 3.2 获取商家详情
```http
GET /api/v1/merchants/{id}
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "美味餐厅",
    "logo": "https://...",
    "description": "专注美食20年",
    "contactPhone": "400-123-4567",
    "rating": 4.5,
    "totalSales": 1000,
    "status": 1,
    "stores": [
      {
        "id": "uuid",
        "name": "总店",
        "address": "北京市朝阳区...",
        "phone": "010-12345678"
      }
    ]
  }
}
```

### 3.3 创建商家
```http
POST /api/v1/merchants
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "美味餐厅",
  "logo": "https://...",
  "description": "专注美食20年",
  "contactPhone": "400-123-4567",
  "contactPerson": "张三",
  "businessLicense": "91110000..."
}
```

### 3.4 更新商家信息
```http
PUT /api/v1/merchants/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "美味餐厅",
  "logo": "https://...",
  "description": "专注美食20年"
}
```

### 3.5 删除商家
```http
DELETE /api/v1/merchants/{id}
Authorization: Bearer {token}
```

## 4. 菜品管理接口

### 4.1 获取菜品列表
```http
GET /api/v1/dishes?merchantId={merchantId}&categoryId={categoryId}&keyword=&status=1&pageIndex=1&pageSize=20
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "宫保鸡丁",
        "description": "经典川菜",
        "image": "https://...",
        "price": 38.00,
        "originalPrice": 48.00,
        "salesCount": 500,
        "rating": 4.8,
        "status": 1,
        "tags": ["热销", "招牌菜"]
      }
    ],
    "totalCount": 100
  }
}
```

### 4.2 获取菜品详情
```http
GET /api/v1/dishes/{id}
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "宫保鸡丁",
    "description": "经典川菜，选用优质鸡肉...",
    "image": "https://...",
    "price": 38.00,
    "originalPrice": 48.00,
    "unit": "份",
    "stock": 100,
    "salesCount": 500,
    "rating": 4.8,
    "status": 1,
    "tags": ["热销", "招牌菜"],
    "specs": [
      {
        "id": "uuid",
        "name": "大份",
        "price": 48.00,
        "stock": 50
      },
      {
        "id": "uuid",
        "name": "小份",
        "price": 28.00,
        "stock": 50
      }
    ]
  }
}
```

### 4.3 创建菜品
```http
POST /api/v1/dishes
Authorization: Bearer {token}
Content-Type: application/json

{
  "merchantId": "uuid",
  "categoryId": "uuid",
  "name": "宫保鸡丁",
  "description": "经典川菜",
  "image": "https://...",
  "price": 38.00,
  "originalPrice": 48.00,
  "unit": "份",
  "stock": 100,
  "tags": ["热销", "招牌菜"],
  "specs": [
    {
      "name": "大份",
      "price": 48.00,
      "stock": 50
    }
  ]
}
```

### 4.4 更新菜品
```http
PUT /api/v1/dishes/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "宫保鸡丁",
  "price": 38.00,
  "stock": 100,
  "status": 1
}
```

### 4.5 批量上下架
```http
PATCH /api/v1/dishes/batch-status
Authorization: Bearer {token}
Content-Type: application/json

{
  "dishIds": ["uuid1", "uuid2"],
  "status": 1 // 1:上架 2:下架
}
```

## 5. 订单管理接口

### 5.1 创建订单
```http
POST /api/v1/orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "merchantId": "uuid",
  "storeId": "uuid",
  "items": [
    {
      "dishId": "uuid",
      "specId": "uuid",
      "quantity": 2,
      "price": 38.00
    }
  ],
  "deliveryAddress": {
    "contactName": "张三",
    "contactPhone": "13800138000",
    "address": "北京市朝阳区...",
    "latitude": 39.9042,
    "longitude": 116.4074
  },
  "remark": "少辣",
  "couponId": "uuid"
}

Response:
{
  "success": true,
  "data": {
    "orderId": "uuid",
    "orderNo": "202401010001",
    "totalAmount": 76.00,
    "deliveryFee": 5.00,
    "discountAmount": 10.00,
    "actualAmount": 71.00,
    "paymentInfo": {
      "paymentNo": "PAY202401010001",
      "qrCode": "https://..." // 支付二维码
    }
  }
}
```

### 5.2 获取订单列表
```http
GET /api/v1/orders?status=&startDate=&endDate=&pageIndex=1&pageSize=20
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "orderNo": "202401010001",
        "merchantName": "美味餐厅",
        "totalAmount": 76.00,
        "actualAmount": 71.00,
        "status": 2,
        "statusText": "待接单",
        "createdAt": "2024-01-01T12:00:00Z",
        "items": [
          {
            "dishName": "宫保鸡丁",
            "specName": "大份",
            "quantity": 2,
            "price": 38.00
          }
        ]
      }
    ],
    "totalCount": 50
  }
}
```

### 5.3 获取订单详情
```http
GET /api/v1/orders/{id}
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "id": "uuid",
    "orderNo": "202401010001",
    "merchant": {
      "id": "uuid",
      "name": "美味餐厅",
      "phone": "400-123-4567"
    },
    "items": [
      {
        "dishName": "宫保鸡丁",
        "dishImage": "https://...",
        "specName": "大份",
        "quantity": 2,
        "price": 38.00,
        "amount": 76.00
      }
    ],
    "deliveryAddress": {
      "contactName": "张三",
      "contactPhone": "13800138000",
      "address": "北京市朝阳区..."
    },
    "dishAmount": 76.00,
    "deliveryFee": 5.00,
    "packageFee": 2.00,
    "discountAmount": 10.00,
    "totalAmount": 83.00,
    "actualAmount": 73.00,
    "status": 2,
    "statusText": "待接单",
    "paymentStatus": 1,
    "paymentMethod": "wechat",
    "estimatedDeliveryTime": "2024-01-01T13:00:00Z",
    "createdAt": "2024-01-01T12:00:00Z",
    "paidAt": "2024-01-01T12:05:00Z",
    "remark": "少辣",
    "timeline": [
      {
        "status": "created",
        "statusText": "订单创建",
        "time": "2024-01-01T12:00:00Z"
      },
      {
        "status": "paid",
        "statusText": "支付成功",
        "time": "2024-01-01T12:05:00Z"
      }
    ]
  }
}
```

### 5.4 商家接单
```http
POST /api/v1/orders/{id}/accept
Authorization: Bearer {token}
Content-Type: application/json

{
  "estimatedTime": 30 // 预计制作时长（分钟）
}
```

### 5.5 开始制作
```http
POST /api/v1/orders/{id}/cooking
Authorization: Bearer {token}
```

### 5.6 订单完成
```http
POST /api/v1/orders/{id}/complete
Authorization: Bearer {token}
```

### 5.7 取消订单
```http
POST /api/v1/orders/{id}/cancel
Authorization: Bearer {token}
Content-Type: application/json

{
  "reason": "用户取消",
  "cancelBy": "customer" // customer, merchant, system
}
```

## 6. 支付接口

### 6.1 创建支付
```http
POST /api/v1/payments
Authorization: Bearer {token}
Content-Type: application/json

{
  "orderId": "uuid",
  "paymentMethod": "wechat", // wechat, alipay, balance
  "amount": 71.00
}

Response:
{
  "success": true,
  "data": {
    "paymentNo": "PAY202401010001",
    "qrCode": "https://...", // 支付二维码
    "deepLink": "weixin://..." // 唤起支付的深度链接
  }
}
```

### 6.2 查询支付状态
```http
GET /api/v1/payments/{paymentNo}
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "paymentNo": "PAY202401010001",
    "status": 2, // 0:待支付 1:支付中 2:成功 3:失败
    "amount": 71.00,
    "paidAt": "2024-01-01T12:05:00Z"
  }
}
```

### 6.3 支付回调（第三方调用）
```http
POST /api/v1/payments/callback/wechat
Content-Type: application/json

{
  "out_trade_no": "PAY202401010001",
  "transaction_id": "4200001234567890",
  "total_fee": 7100,
  "result_code": "SUCCESS"
}
```

### 6.4 申请退款
```http
POST /api/v1/refunds
Authorization: Bearer {token}
Content-Type: application/json

{
  "orderId": "uuid",
  "amount": 71.00,
  "reason": "不想要了"
}
```

## 7. 配送管理接口

### 7.1 获取配送任务列表
```http
GET /api/v1/delivery-tasks?status=&driverId=&pageIndex=1&pageSize=20
Authorization: Bearer {token}
```

### 7.2 分配配送员
```http
POST /api/v1/delivery-tasks/{id}/assign
Authorization: Bearer {token}
Content-Type: application/json

{
  "driverId": "uuid"
}
```

### 7.3 配送员接单
```http
POST /api/v1/delivery-tasks/{id}/accept
Authorization: Bearer {token}
```

### 7.4 确认取餐
```http
POST /api/v1/delivery-tasks/{id}/pickup
Authorization: Bearer {token}
```

### 7.5 确认送达
```http
POST /api/v1/delivery-tasks/{id}/deliver
Authorization: Bearer {token}
Content-Type: application/json

{
  "deliveryCode": "123456" // 取餐码
}
```

### 7.6 更新配送员位置
```http
POST /api/v1/delivery-drivers/location
Authorization: Bearer {token}
Content-Type: application/json

{
  "latitude": 39.9042,
  "longitude": 116.4074
}
```

## 8. 营销管理接口

### 8.1 获取优惠券列表
```http
GET /api/v1/coupons?merchantId=&status=1&pageIndex=1&pageSize=20
Authorization: Bearer {token}
```

### 8.2 领取优惠券
```http
POST /api/v1/coupons/{id}/receive
Authorization: Bearer {token}
```

### 8.3 获取用户优惠券
```http
GET /api/v1/user-coupons?status=1&pageIndex=1&pageSize=20
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "couponName": "满50减10",
        "discountValue": 10.00,
        "minOrderAmount": 50.00,
        "status": 1,
        "expiredAt": "2024-12-31T23:59:59Z"
      }
    ]
  }
}
```

### 8.4 获取可用优惠券
```http
GET /api/v1/user-coupons/available?merchantId={merchantId}&amount={amount}
Authorization: Bearer {token}
```

## 9. 评价管理接口

### 9.1 创建评价
```http
POST /api/v1/reviews
Authorization: Bearer {token}
Content-Type: application/json

{
  "orderId": "uuid",
  "rating": 5,
  "tasteRating": 5,
  "packageRating": 5,
  "deliveryRating": 5,
  "content": "非常好吃",
  "images": ["https://...", "https://..."],
  "isAnonymous": false
}
```

### 9.2 获取商家评价列表
```http
GET /api/v1/reviews?merchantId={merchantId}&rating=&pageIndex=1&pageSize=20

Response:
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "userName": "张三",
        "userAvatar": "https://...",
        "rating": 5,
        "content": "非常好吃",
        "images": ["https://..."],
        "createdAt": "2024-01-01T12:00:00Z",
        "replyContent": "感谢支持",
        "replyAt": "2024-01-01T13:00:00Z"
      }
    ],
    "totalCount": 100,
    "statistics": {
      "avgRating": 4.8,
      "totalReviews": 100,
      "rating5Count": 80,
      "rating4Count": 15,
      "rating3Count": 3,
      "rating2Count": 1,
      "rating1Count": 1
    }
  }
}
```

### 9.3 商家回复评价
```http
POST /api/v1/reviews/{id}/reply
Authorization: Bearer {token}
Content-Type: application/json

{
  "replyContent": "感谢您的支持"
}
```

## 10. 数据统计接口

### 10.1 商家数据概览
```http
GET /api/v1/statistics/merchant/overview?merchantId={merchantId}&startDate=&endDate=
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "totalOrders": 1000,
    "totalRevenue": 50000.00,
    "avgOrderAmount": 50.00,
    "completionRate": 0.95,
    "todayOrders": 50,
    "todayRevenue": 2500.00,
    "orderTrend": [
      {
        "date": "2024-01-01",
        "orders": 50,
        "revenue": 2500.00
      }
    ],
    "topDishes": [
      {
        "dishId": "uuid",
        "dishName": "宫保鸡丁",
        "salesCount": 200,
        "revenue": 7600.00
      }
    ]
  }
}
```

### 10.2 平台数据大盘
```http
GET /api/v1/statistics/platform/dashboard?startDate=&endDate=
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "totalMerchants": 100,
    "totalUsers": 10000,
    "totalOrders": 50000,
    "totalRevenue": 2500000.00,
    "activeMerchants": 80,
    "activeUsers": 5000,
    "todayOrders": 500,
    "todayRevenue": 25000.00
  }
}
```

## 11. 文件上传接口

### 11.1 上传图片
```http
POST /api/v1/files/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: <binary>
type: dish_image // dish_image, merchant_logo, user_avatar, review_image

Response:
{
  "success": true,
  "data": {
    "url": "https://cdn.example.com/images/xxx.jpg",
    "fileName": "xxx.jpg",
    "fileSize": 102400
  }
}
```

## 12. WebSocket实时通知

### 12.1 连接WebSocket
```javascript
// 连接地址
ws://api.example.com/ws?token={jwt_token}

// 订阅主题
{
  "action": "subscribe",
  "topics": ["order.new", "order.status", "delivery.location"]
}

// 接收消息
{
  "topic": "order.new",
  "data": {
    "orderId": "uuid",
    "orderNo": "202401010001",
    "merchantId": "uuid"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}
```

### 12.2 消息主题
- `order.new`：新订单通知
- `order.status`：订单状态变更
- `delivery.location`：配送员位置更新
- `payment.success`：支付成功通知