chore: 初始化项目基础文件
This commit is contained in:
885
0_Document/04_API接口设计.md
Normal file
885
0_Document/04_API接口设计.md
Normal file
@@ -0,0 +1,885 @@
|
||||
# 外卖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`：支付成功通知
|
||||
|
||||
Reference in New Issue
Block a user