# 用户端与平台端深度集成API规范

## 1. 概述

本文档定义了用户端（Flutter）与平台端（React+TypeScript）深度集成的统一数据模型和API规范，旨在实现两端的无缝交互和数据同步，提升用户体验和运营效率�?

## 2. 核心数据模型

### 2.1 用户模型 (User)

```typescript
interface User {
  id: string;
  username: string;
  phone: string;
  email?: string;
  avatar?: string;
  nickname?: string;
  gender?: 'male' | 'female' | 'other';
  birthday?: string;
  level: number;
  points: number;
  balance: number;
  status: 'active' | 'inactive' | 'banned';
  createdAt: string;
  updatedAt: string;
  lastLoginAt?: string;
  roles: string[];
  tags: string[];
}
```

### 2.2 订单模型 (Order)

```typescript
interface Order {
  id: string;
  userId: string;
  merchantId: string;
  riderId?: string;
  type: 'takeout' | 'errand' | 'local_merchant';
  status: 'pending' | 'accepted' | 'processing' | 'delivering' | 'completed' | 'cancelled' | 'refunded';
  totalAmount: number;
  actualAmount: number;
  paymentMethod: 'alipay' | 'wechat' | 'card' | 'cash';
  paymentStatus: 'unpaid' | 'paid' | 'refunding' | 'refunded';
  addressId?: string;
  deliveryFee: number;
  discountAmount: number;
  items: OrderItem[];
  notes?: string;
  estimatedDeliveryTime?: string;
  actualDeliveryTime?: string;
  createdAt: string;
  updatedAt: string;
  merchant?: Merchant;
  rider?: Rider;
  user?: User;
}

interface OrderItem {
  id: string;
  productId: string;
  productName: string;
  quantity: number;
  price: number;
  totalPrice: number;
  options?: string;
}
```

### 2.3 商家模型 (Merchant)

```typescript
interface Merchant {
  id: string;
  name: string;
  phone: string;
  address: string;
  latitude: number;
  longitude: number;
  category: string;
  rating: number;
  sales: number;
  status: 'open' | 'closed' | 'pending' | 'suspended';
  description?: string;
  logo?: string;
  coverImage?: string;
  businessHours: string;
  minOrderAmount: number;
  deliveryFee: number;
  deliveryTime: string;
  createdAt: string;
  updatedAt: string;
}
```

### 2.4 骑手模型 (Rider)

```typescript
interface Rider {
  id: string;
  name: string;
  phone: string;
  avatar?: string;
  status: 'online' | 'offline' | 'busy';
  rating: number;
  completedOrders: number;
  earnings: number;
  latitude?: number;
  longitude?: number;
  vehicleType: 'bicycle' | 'motorcycle' | 'car';
  licensePlate?: string;
  idCardNumber: string;
  bankCardNumber: string;
  createdAt: string;
  updatedAt: string;
}
```

### 2.5 营销活动模型 (MarketingActivity)

```typescript
interface MarketingActivity {
  id: string;
  name: string;
  type: 'coupon' | 'discount' | 'flash_sale' | 'member';
  status: 'active' | 'inactive' | 'expired';
  startTime: string;
  endTime: string;
  description: string;
  rules: string;
  targetUsers: 'all' | 'new' | 'regular' | 'vip';
  discountAmount?: number;
  discountPercentage?: number;
  minimumSpend?: number;
  createdAt: string;
  updatedAt: string;
}
```

## 3. API接口规范

### 3.1 认证相关接口

| 接口路径                 | 方法   | 模块 | 功能描述    | 请求参数                                | 成功响应 (200 OK)              |
|----------------------|------|----|---------|-------------------------------------|----------------------------|
| `/api/auth/login`    | POST | 认证 | 用户登录    | `{username, password, platform}`    | `{token, user, expiresAt}` |
| `/api/auth/register` | POST | 认证 | 用户注册    | `{username, password, phone, code}` | `{token, user, expiresAt}` |
| `/api/auth/refresh`  | POST | 认证 | 刷新Token | `{refreshToken}`                    | `{token, expiresAt}`       |
| `/api/auth/logout`   | POST | 认证 | 用户登出    | N/A                                 | `{success: true}`          |
| `/api/auth/verify`   | GET  | 认证 | 验证Token | N/A                                 | `{valid: true, user}`      |

### 3.2 用户管理接口

| 接口路径                    | 方法     | 模块   | 功能描述     | 请求参数                             | 成功响应 (200 OK)           |
|-------------------------|--------|------|----------|----------------------------------|-------------------------|
| `/api/users`            | GET    | 用户管理 | 获取用户列表   | `{page, pageSize, status, role}` | `{total, list: User[]}` |
| `/api/users/:id`        | GET    | 用户管理 | 获取用户详情   | N/A                              | `User`                  |
| `/api/users/:id`        | PUT    | 用户管理 | 更新用户信息   | `User`                           | `User`                  |
| `/api/users/:id`        | DELETE | 用户管理 | 删除用户     | N/A                              | `{success: true}`       |
| `/api/users/:id/status` | PUT    | 用户管理 | 更新用户状�?  | `{status}`                       | `{success: true}`       |
| `/api/users/me`         | GET    | 用户管理 | 获取当前用户信息 | N/A                              | `User`                  |
| `/api/users/me`         | PUT    | 用户管理 | 更新当前用户信息 | `User`                           | `User`                  |

### 3.3 订单管理接口

| 接口路径                      | 方法   | 模块   | 功能描述    | 请求参数                                                 | 成功响应 (200 OK)            |
|---------------------------|------|------|---------|------------------------------------------------------|--------------------------|
| `/api/orders`             | GET  | 订单管理 | 获取订单列表  | `{page, pageSize, status, type, userId, merchantId}` | `{total, list: Order[]}` |
| `/api/orders/:id`         | GET  | 订单管理 | 获取订单详情  | N/A                                                  | `Order`                  |
| `/api/orders`             | POST | 订单管理 | 创建订单    | `Order`                                              | `Order`                  |
| `/api/orders/:id`         | PUT  | 订单管理 | 更新订单信息  | `Order`                                              | `Order`                  |
| `/api/orders/:id/status`  | PUT  | 订单管理 | 更新订单状�? | `{status}`                                           | `{success: true}`        |
| `/api/orders/:id/payment` | PUT  | 订单管理 | 更新支付状�? | `{paymentStatus, paymentMethod}`                     | `{success: true}`        |
| `/api/orders/:id/cancel`  | POST | 订单管理 | 取消订单    | `{reason}`                                           | `{success: true}`        |

### 3.4 商家管理接口

| 接口路径                        | 方法     | 模块   | 功能描述    | 请求参数                                 | 成功响应 (200 OK)               |
|-----------------------------|--------|------|---------|--------------------------------------|-----------------------------|
| `/api/merchants`            | GET    | 商家管理 | 获取商家列表  | `{page, pageSize, status, category}` | `{total, list: Merchant[]}` |
| `/api/merchants/:id`        | GET    | 商家管理 | 获取商家详情  | N/A                                  | `Merchant`                  |
| `/api/merchants`            | POST   | 商家管理 | 创建商家    | `Merchant`                           | `Merchant`                  |
| `/api/merchants/:id`        | PUT    | 商家管理 | 更新商家信息  | `Merchant`                           | `Merchant`                  |
| `/api/merchants/:id`        | DELETE | 商家管理 | 删除商家    | N/A                                  | `{success: true}`           |
| `/api/merchants/:id/status` | PUT    | 商家管理 | 更新商家状�? | `{status}`                           | `{success: true}`           |

### 3.5 骑手管理接口

| 接口路径                     | 方法     | 模块   | 功能描述    | 请求参数                                    | 成功响应 (200 OK)            |
|--------------------------|--------|------|---------|-----------------------------------------|--------------------------|
| `/api/riders`            | GET    | 骑手管理 | 获取骑手列表  | `{page, pageSize, status, vehicleType}` | `{total, list: Rider[]}` |
| `/api/riders/:id`        | GET    | 骑手管理 | 获取骑手详情  | N/A                                     | `Rider`                  |
| `/api/riders`            | POST   | 骑手管理 | 创建骑手    | `Rider`                                 | `Rider`                  |
| `/api/riders/:id`        | PUT    | 骑手管理 | 更新骑手信息  | `Rider`                                 | `Rider`                  |
| `/api/riders/:id`        | DELETE | 骑手管理 | 删除骑手    | N/A                                     | `{success: true}`        |
| `/api/riders/:id/status` | PUT    | 骑手管理 | 更新骑手状�? | `{status, latitude, longitude}`         | `{success: true}`        |

### 3.6 营销管理接口

| 接口路径                                   | 方法     | 模块   | 功能描述     | 请求参数                               | 成功响应 (200 OK)                        |
|----------------------------------------|--------|------|----------|------------------------------------|--------------------------------------|
| `/api/marketing/activities`            | GET    | 营销管理 | 获取活动列表   | `{page, pageSize, type, status}`   | `{total, list: MarketingActivity[]}` |
| `/api/marketing/activities/:id`        | GET    | 营销管理 | 获取活动详情   | N/A                                | `MarketingActivity`                  |
| `/api/marketing/activities`            | POST   | 营销管理 | 创建活动     | `MarketingActivity`                | `MarketingActivity`                  |
| `/api/marketing/activities/:id`        | PUT    | 营销管理 | 更新活动信息   | `MarketingActivity`                | `MarketingActivity`                  |
| `/api/marketing/activities/:id`        | DELETE | 营销管理 | 删除活动     | N/A                                | `{success: true}`                    |
| `/api/marketing/activities/:id/status` | PUT    | 营销管理 | 更新活动状�?  | `{status}`                         | `{success: true}`                    |
| `/api/marketing/coupons`               | GET    | 营销管理 | 获取优惠券列�? | `{page, pageSize, status, userId}` | `{total, list: Coupon[]}`            |
| `/api/marketing/coupons`               | POST   | 营销管理 | 发放优惠�?   | `{userId, couponId, quantity}`     | `{success: true}`                    |

### 3.7 数据统计接口

| 接口路径                        | 方法  | 模块   | 功能描述   | 请求参数                                     | 成功响应 (200 OK)                                           |
|-----------------------------|-----|------|--------|------------------------------------------|---------------------------------------------------------|
| `/api/statistics/overview`  | GET | 数据统计 | 获取概览数据 | `{startDate, endDate}`                   | `{orders, users, merchants, riders, revenue}`           |
| `/api/statistics/orders`    | GET | 数据统计 | 获取订单统计 | `{startDate, endDate, type, status}`     | `{total, completed, cancelled, revenue, averageAmount}` |
| `/api/statistics/users`     | GET | 数据统计 | 获取用户统计 | `{startDate, endDate, status}`           | `{total, new, active, retention}`                       |
| `/api/statistics/merchants` | GET | 数据统计 | 获取商家统计 | `{startDate, endDate, status, category}` | `{total, active, sales, revenue}`                       |
| `/api/statistics/riders`    | GET | 数据统计 | 获取骑手统计 | `{startDate, endDate, status}`           | `{total, active, completedOrders, earnings}`            |
| `/api/statistics/marketing` | GET | 数据统计 | 获取营销统计 | `{startDate, endDate, type}`             | `{total, used, revenue, conversionRate}`                |

## 4. 实时通信接口

### 4.1 WebSocket 连接

- 连接地址: `wss://api.example.com/ws`
- 认证: 通过查询参数 `token` 传递认证信�?
- 心跳间隔: 30�?

### 4.2 消息类型

| 消息类型                     | 方向       | 描述       | 数据结构                                         |
|--------------------------|----------|----------|----------------------------------------------|
| `order:created`          | 服务器→客户�? | 新订单创�?   | `{orderId, type, merchantName, totalAmount}` |
| `order:updated`          | 服务器→客户�? | 订单状态更�?  | `{orderId, status, message}`                 |
| `order:assigned`         | 服务器→客户�? | 订单分配给骑�? | `{orderId, riderId, riderName}`              |
| `rider:location`         | 服务器→客户�? | 骑手位置更新   | `{riderId, latitude, longitude, orderId}`    |
| `message:user`           | 双向       | 用户消息     | `{userId, message, timestamp}`               |
| `notification:system`    | 服务器→客户�? | 系统通知     | `{title, content, type, timestamp}`          |
| `notification:marketing` | 服务器→客户�? | 营销通知     | `{title, content, activityId, timestamp}`    |

## 5. 错误处理规范

### 5.1 错误响应格式

```json
{
  "code": "ERROR_CODE",
  "message": "错误描述",
  "details": {
    "field": "具体错误字段",
    "value": "错误�?,
    "reason": "错误原因"
  }
}
```

### 5.2 常见错误代码

| 错误代码                  | 描述       | HTTP状态码 |
|-----------------------|----------|---------|
| `AUTH_FAILED`         | 认证失败     | 401     |
| `PERMISSION_DENIED`   | 权限不足     | 403     |
| `RESOURCE_NOT_FOUND`  | 资源不存�?   | 404     |
| `VALIDATION_ERROR`    | 参数验证错误   | 400     |
| `DUPLICATE_RESOURCE`  | 资源重复     | 409     |
| `SERVER_ERROR`        | 服务器内部错�? | 500     |
| `NETWORK_ERROR`       | 网络错误     | 503     |
| `RATE_LIMIT_EXCEEDED` | 请求过于频繁   | 429     |

## 6. 安全规范

### 6.1 认证与授�?

- 使用JWT进行身份认证
- 实现基于角色的访问控�?(RBAC)
- 敏感操作需要二次验�?

### 6.2 数据安全

- 所有API请求使用HTTPS
- 敏感数据加密存储
- 防止SQL注入和XSS攻击
- 实现请求速率限制

### 6.3 日志与监�?

- 记录所有API请求和响�?
- 监控系统性能和错误率
- 实现异常告警机制

## 7. 版本控制

- API版本通过URL路径前缀区分，如 `/api/v1/`
- 向后兼容旧版本API
- 版本更新通知机制

## 8. 实现计划

1. **第一阶段**: 实现统一的认证系统和基础数据模型
2. **第二阶段**: 实现核心功能的API接口
3. **第三阶段**: 实现实时通信和消息系�?
4. **第四阶段**: 实现数据统计和分析功�?
5. **第五阶段**: 测试和优化集成效�?

## 9. 结论

本规范旨在为用户端与平台端的深度集成提供统一的标准，确保两端能够无缝协作，提升系统的整体性能和用户体验。通过遵循本规范，我们可以实现平台端对用户端的有效控制和管理，同时为用户提供更加便捷、高效的服务�