msumshk/TakeoutSaaS.AdminApi

Fork 0

Files

MSuMshk cd52131c34 chore: 更改文件夹结构

2025-11-23 09:55:11 +08:00

16 KiB

Raw Blame History

外卖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 响应规范

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": "2024-01-01T12:00:00Z"
}

1.4 错误响应

{
  "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 分页规范

// 请求参数
{
  "pageIndex": 1,
  "pageSize": 20,
  "sortBy": "createdAt",
  "sortOrder": "desc"
}

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

2. 认证授权接口

2.1 用户登录

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

POST /api/v1/auth/refresh
Content-Type: application/json

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

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

2.3 用户注册

POST /api/v1/auth/register
Content-Type: application/json

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

2.4 发送验证码

POST /api/v1/auth/send-code
Content-Type: application/json

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

3. 商家管理接口

3.1 获取商家列表

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 获取商家详情

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 创建商家

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 更新商家信息

PUT /api/v1/merchants/{id}
Authorization: Bearer {token}
Content-Type: application/json

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

3.5 删除商家

DELETE /api/v1/merchants/{id}
Authorization: Bearer {token}

4. 菜品管理接口

4.1 获取菜品列表

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 获取菜品详情

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 创建菜品

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 更新菜品

PUT /api/v1/dishes/{id}
Authorization: Bearer {token}
Content-Type: application/json

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

4.5 批量上下架

PATCH /api/v1/dishes/batch-status
Authorization: Bearer {token}
Content-Type: application/json

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

5. 订单管理接口

5.1 创建订单

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 获取订单列表

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 获取订单详情

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 商家接单

POST /api/v1/orders/{id}/accept
Authorization: Bearer {token}
Content-Type: application/json

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

5.5 开始制作

POST /api/v1/orders/{id}/cooking
Authorization: Bearer {token}

5.6 订单完成

POST /api/v1/orders/{id}/complete
Authorization: Bearer {token}

5.7 取消订单

POST /api/v1/orders/{id}/cancel
Authorization: Bearer {token}
Content-Type: application/json

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

6. 支付接口

6.1 创建支付

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 查询支付状态

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 支付回调（第三方调用）

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 申请退款

POST /api/v1/refunds
Authorization: Bearer {token}
Content-Type: application/json

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

7. 配送管理接口

7.1 获取配送任务列表

GET /api/v1/delivery-tasks?status=&driverId=&pageIndex=1&pageSize=20
Authorization: Bearer {token}

7.2 分配配送员

POST /api/v1/delivery-tasks/{id}/assign
Authorization: Bearer {token}
Content-Type: application/json

{
  "driverId": "uuid"
}

7.3 配送员接单

POST /api/v1/delivery-tasks/{id}/accept
Authorization: Bearer {token}

7.4 确认取餐

POST /api/v1/delivery-tasks/{id}/pickup
Authorization: Bearer {token}

7.5 确认送达

POST /api/v1/delivery-tasks/{id}/deliver
Authorization: Bearer {token}
Content-Type: application/json

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

7.6 更新配送员位置

POST /api/v1/delivery-drivers/location
Authorization: Bearer {token}
Content-Type: application/json

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

8. 营销管理接口

8.1 获取优惠券列表

GET /api/v1/coupons?merchantId=&status=1&pageIndex=1&pageSize=20
Authorization: Bearer {token}

8.2 领取优惠券

POST /api/v1/coupons/{id}/receive
Authorization: Bearer {token}

8.3 获取用户优惠券

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 获取可用优惠券

GET /api/v1/user-coupons/available?merchantId={merchantId}&amount={amount}
Authorization: Bearer {token}

9. 评价管理接口

9.1 创建评价

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 获取商家评价列表

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 商家回复评价

POST /api/v1/reviews/{id}/reply
Authorization: Bearer {token}
Content-Type: application/json

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

10. 数据统计接口

10.1 商家数据概览

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 平台数据大盘

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 上传图片

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

// 连接地址
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：支付成功通知

16 KiB Raw Blame History Unescape Escape

外卖SaaS系统 - API接口设计

1. API设计规范

1.1 RESTful规范

1.2 请求规范

1.3 响应规范

1.4 错误响应

1.5 HTTP状态码

1.6 分页规范

2. 认证授权接口

2.1 用户登录

2.2 刷新Token

2.3 用户注册

2.4 发送验证码

3. 商家管理接口

3.1 获取商家列表

3.2 获取商家详情

3.3 创建商家

3.4 更新商家信息

3.5 删除商家

4. 菜品管理接口

4.1 获取菜品列表

4.2 获取菜品详情

4.3 创建菜品

4.4 更新菜品

4.5 批量上下架

5. 订单管理接口

5.1 创建订单

5.2 获取订单列表

5.3 获取订单详情

5.4 商家接单

5.5 开始制作

5.6 订单完成

5.7 取消订单

6. 支付接口

6.1 创建支付

6.2 查询支付状态

6.3 支付回调（第三方调用）

6.4 申请退款

7. 配送管理接口

7.1 获取配送任务列表

7.2 分配配送员

7.3 配送员接单

7.4 确认取餐

7.5 确认送达

7.6 更新配送员位置

8. 营销管理接口

8.1 获取优惠券列表

8.2 领取优惠券

8.3 获取用户优惠券

8.4 获取可用优惠券

9. 评价管理接口

9.1 创建评价

9.2 获取商家评价列表

9.3 商家回复评价

10. 数据统计接口

10.1 商家数据概览

10.2 平台数据大盘

11. 文件上传接口

11.1 上传图片

12. WebSocket实时通知

12.1 连接WebSocket

12.2 消息主题

16 KiB

Raw Blame History