订单管理 API 接口文档

本文档描述了车辆订单管理相关的API接口使用方法和集成指南。

文件结构

src/api/
├── orders.js          # 订单相关API接口
├── index.js           # 通用API接口
├── fn.js              # API工具函数
└── README.md          # 本文档

订单API接口 (orders.js)

主要功能

• ✅ 获取我的订单列表
• ✅ 获取订单详情
• ✅ 删除订单
• ✅ 取消订单
• ✅ 确认收货
• ✅ 提交评价
• ✅ 申请退款

使用示例

1. 删除订单

import { deleteOrderAPI } from '@/api/orders'

// 删除订单
const handleDeleteOrder = async (orderId) => {
  try {
    const response = await deleteOrderAPI({ orderId })
    if (response.success) {
      console.log('删除成功:', response.message)
      // 更新UI状态
    }
  } catch (error) {
    console.error('删除失败:', error.message)
  }
}

2. 提交评价

import { submitReviewAPI } from '@/api/orders'

// 提交评价
const handleSubmitReview = async (orderData) => {
  try {
    const response = await submitReviewAPI({
      orderId: orderData.id,
      rating: 5,
      comment: '车况很好，推荐！',
      images: [] // 可选
    })
    if (response.success) {
      console.log('评价提交成功:', response.message)
    }
  } catch (error) {
    console.error('评价提交失败:', error.message)
  }
}

集成真实API的步骤

1. 更新API端点

在 orders.js 文件中，将 OrderApi 对象中的端点URL替换为真实的后端API地址：

const OrderApi = {
  DELETE_ORDER: 'https://your-api-domain.com/api/orders/delete',
  SUBMIT_REVIEW: 'https://your-api-domain.com/api/orders/review',
  // ... 其他端点
};

2. 取消注释API调用代码

在页面组件中（如 myOrders/index.vue），找到相关方法并取消注释真实API调用的代码：

// 在 performDeleteOrder 方法中
const response = await deleteOrderAPI({ orderId })
if (response.success) {
  // 处理成功响应
} else {
  throw new Error(response.message || '删除失败')
}

3. 错误处理

确保处理以下常见错误情况：

• 网络连接错误
• 服务器错误 (5xx)
• 客户端错误 (4xx)
• 权限验证失败
• 数据验证失败

4. 响应格式标准化

建议后端API返回统一的响应格式：

// 成功响应
{
  success: true,
  message: '操作成功',
  data: { /* 具体数据 */ }
}

// 错误响应
{
  success: false,
  message: '错误描述',
  error: {
    code: 'ERROR_CODE',
    details: '详细错误信息'
  }
}

安全注意事项

1. 权限验证: 确保用户只能操作自己的订单
2. 数据验证: 在前端和后端都要进行数据验证
3. 防重复提交: 避免用户重复提交相同的操作
4. 敏感信息: 不要在前端暴露敏感的API密钥
5. HTTPS: 生产环境必须使用HTTPS协议

测试建议

1. 单元测试: 为每个API方法编写单元测试
2. 集成测试: 测试API与UI组件的集成
3. 错误场景测试: 测试网络错误、服务器错误等异常情况
4. 性能测试: 测试API响应时间和并发处理能力

开发模式 vs 生产模式

当前代码支持开发模式（使用模拟数据）和生产模式（使用真实API）的切换：

• 开发模式: 注释掉真实API调用，使用模拟数据和延迟
• 生产模式: 取消注释真实API调用，注释掉模拟代码

建议使用环境变量来控制模式切换，例如：

const isDevelopment = process.env.NODE_ENV === 'development'

if (isDevelopment) {
  // 使用模拟数据
} else {
  // 使用真实API
}

更新日志

• v1.0.0: 初始版本，包含基础的订单管理API接口
• 支持删除订单、提交评价等核心功能
• 提供完整的使用示例和集成指南