# API接口使用指南

> **文件**: `api/miao.js`  
> **创建时间**: 2025-11-08  
> **接口总数**: 50+ 个

---

## 📋 目录

1. [快速开始](#快速开始)
2. [模块说明](#模块说明)
3. [使用示例](#使用示例)
4. [错误处理](#错误处理)
5. [最佳实践](#最佳实践)

---

## 🚀 快速开始

### 1. 导入API

```javascript
// 方式一：按需导入（推荐）
import { userLogin, getGoodsList, buyGoods } from '@/api/miao.js';

// 方式二：全部导入
import * as miaoApi from '@/api/miao.js';

// 方式三：默认导入
import miaoApi from '@/api/miao.js';
```

### 2. 基本使用

```javascript
// 在Vue组件中使用
export default {
  methods: {
    async login() {
      try {
        const res = await userLogin({
          account: '18379637515',
          password: '123456'
        });
        
        if (res.code === 0) {
          // 登录成功
          uni.setStorageSync('token', res.data.token);
        }
      } catch (error) {
        console.error('登录失败:', error);
      }
    }
  }
}
```

---

## 📚 模块说明

### 一、用户认证模块（7个接口）

| 函数名 | 说明 | 参数 | 需要登录 |
|--------|------|------|---------|
| `userLogin` | 用户登录 | {account, password} | ❌ |
| `userRegister` | 用户注册 | {mobile, code, password, invite_code} | ❌ |
| `userInfo` | 获取用户信息 | - | ✅ |
| `updateNickname` | 修改昵称 | {nickname} | ✅ |
| `changePassword` | 修改密码 | {old_password, new_password, code} | ✅ |
| `resetPassword` | 重置密码 | {mobile, code, password} | ❌ |
| `uploadAvatar` | 上传头像 | {file} | ✅ |

---

### 二、商品模块（3个接口）

| 函数名 | 说明 | 参数 | 需要登录 |
|--------|------|------|---------|
| `getGoodsCategory` | 商品分类 | - | ❌ |
| `getGoodsList` | 商品列表 | {page, limit, category_id, keyword} | ❌ |
| `getGoodsDetail` | 商品详情 | id | ❌ |

---

### 三、订单模块（10个接口）

| 函数名 | 说明 | 参数 | 需要登录 |
|--------|------|------|---------|
| `getOrderIndex` | 订单首页 | - | ✅ |
| `getOrderGoods` | 可购买商品 | {page, limit, type} | ✅ |
| `buyGoods` | 购买商品 | {goods_id, address_id} | ✅ |
| `getOrderList` | 订单列表 | {page, limit, type, status} | ✅ |
| `getOrderDetail` | 订单详情 | id | ✅ |
| `payOrder` | 支付订单 | {id} | ✅ |
| `confirmOrder` | 确认订单 | {id} | ✅ |
| `cancelOrder` | 取消订单 | {id} | ✅ |
| `resellOrder` | 转卖订单 | {id} | ✅ |
| `getOrderCount` | 订单统计 | - | ✅ |

---

### 四、地址管理模块（6个接口）

| 函数名 | 说明 | 参数 | 需要登录 |
|--------|------|------|---------|
| `getAddressList` | 地址列表 | - | ✅ |
| `getDefaultAddress` | 默认地址 | - | ✅ |
| `addAddress` | 新增地址 | {name, mobile, province, city, district, detail, is_default} | ✅ |
| `updateAddress` | 更新地址 | {id, name, mobile, ...} | ✅ |
| `deleteAddress` | 删除地址 | {id} | ✅ |
| `getAddressDetail` | 地址详情 | id | ✅ |

---

### 五、财务模块（3个接口）

| 函数名 | 说明 | 参数 | 需要登录 |
|--------|------|------|---------|
| `getMoneyList` | 财务记录 | {page, limit, cate, type} | ✅ |
| `getWithdrawLog` | 提现记录 | {page, limit} | ✅ |
| `applyWithdraw` | 申请提现 | {amount, type} | ✅ |

---

### 六、支付方式模块（4个接口）

| 函数名 | 说明 | 参数 | 需要登录 |
|--------|------|------|---------|
| `getAlipayInfo` | 支付宝信息 | - | ✅ |
| `bindAlipay` | 绑定支付宝 | {account, real_name} | ✅ |
| `getBankInfo` | 银行卡信息 | - | ✅ |
| `bindBank` | 绑定银行卡 | {bank_name, card_no, real_name, bank_branch} | ✅ |

---

### 七、分享推广模块（2个接口）

| 函数名 | 说明 | 参数 | 需要登录 |
|--------|------|------|---------|
| `getShareIndex` | 分享首页 | - | ✅ |
| `getFansList` | 粉丝列表 | {page, limit, level} | ✅ |

---

### 八、首页模块（2个接口）

| 函数名 | 说明 | 参数 | 需要登录 |
|--------|------|------|---------|
| `getBannerList` | 轮播图 | - | ❌ |
| `getIndexConfig` | 首页配置 | - | ❌ |

---

### 九、其他模块（5个接口）

| 函数名 | 说明 | 参数 | 需要登录 |
|--------|------|------|---------|
| `sendSms` | 发送验证码 | {mobile, event} | ❌ |
| `getAgreement` | 协议内容 | {type} | ❌ |
| `getSetting` | 系统配置 | - | ❌ |
| `getContractList` | 合同列表 | - | ✅ |
| `getPrizeList` | 奖品列表 | {page, limit} | ✅ |

---

## 💡 使用示例

### 1. 用户登录流程

```javascript
import { userLogin, sendSms, userRegister } from '@/api/miao.js';

export default {
  data() {
    return {
      formData: {
        mobile: '',
        code: '',
        password: ''
      }
    }
  },
  
  methods: {
    // 发送验证码
    async sendCode() {
      try {
        await sendSms({
          mobile: this.formData.mobile,
          event: 'register'
        });
        
        uni.showToast({
          title: '验证码已发送',
          icon: 'success'
        });
      } catch (error) {
        uni.showToast({
          title: error.msg || '发送失败',
          icon: 'none'
        });
      }
    },
    
    // 注册
    async register() {
      try {
        const res = await userRegister({
          mobile: this.formData.mobile,
          code: this.formData.code,
          password: this.formData.password
        });
        
        if (res.code === 0) {
          // 保存token
          uni.setStorageSync('token', res.data.token);
          
          // 跳转首页
          uni.switchTab({
            url: '/pages/index/index'
          });
        }
      } catch (error) {
        uni.showToast({
          title: error.msg || '注册失败',
          icon: 'none'
        });
      }
    },
    
    // 登录
    async login() {
      try {
        const res = await userLogin({
          account: this.formData.mobile,
          password: this.formData.password
        });
        
        if (res.code === 0) {
          uni.setStorageSync('token', res.data.token);
          uni.setStorageSync('userInfo', res.data.user_info);
          
          uni.showToast({
            title: '登录成功',
            icon: 'success'
          });
        }
      } catch (error) {
        uni.showToast({
          title: error.msg || '登录失败',
          icon: 'none'
        });
      }
    }
  }
}
```

---

### 2. 商品列表加载

```javascript
import { getGoodsList } from '@/api/miao.js';

export default {
  data() {
    return {
      goodsList: [],
      page: 1,
      limit: 10,
      loading: false,
      noMore: false
    }
  },
  
  onLoad() {
    this.loadGoodsList();
  },
  
  methods: {
    async loadGoodsList() {
      if (this.loading || this.noMore) return;
      
      this.loading = true;
      
      try {
        const res = await getGoodsList({
          page: this.page,
          limit: this.limit,
          category_id: 1 // 可选
        });
        
        if (res.code === 0) {
          const list = res.data.list || [];
          
          if (list.length < this.limit) {
            this.noMore = true;
          }
          
          this.goodsList = this.page === 1 
            ? list 
            : [...this.goodsList, ...list];
        }
      } catch (error) {
        console.error('加载失败:', error);
      } finally {
        this.loading = false;
      }
    },
    
    // 加载更多
    loadMore() {
      if (!this.loading && !this.noMore) {
        this.page++;
        this.loadGoodsList();
      }
    }
  }
}
```

---

### 3. 抢购下单流程

```javascript
import { getOrderGoods, buyGoods, payOrder } from '@/api/miao.js';

export default {
  data() {
    return {
      goodsId: null,
      addressId: null,
      orderId: null
    }
  },
  
  methods: {
    // 1. 加载可购买商品
    async loadGoods() {
      try {
        const res = await getOrderGoods({
          page: 1,
          limit: 20,
          type: 1 // 1:可购买
        });
        
        if (res.code === 0) {
          this.goodsList = res.data.list;
        }
      } catch (error) {
        console.error('加载失败:', error);
      }
    },
    
    // 2. 抢单
    async handleBuy() {
      try {
        const res = await buyGoods({
          goods_id: this.goodsId,
          address_id: this.addressId
        });
        
        if (res.code === 0) {
          this.orderId = res.data.order_id;
          
          uni.showToast({
            title: '抢购成功',
            icon: 'success'
          });
          
          // 继续支付
          await this.handlePay();
        }
      } catch (error) {
        uni.showToast({
          title: error.msg || '抢购失败',
          icon: 'none'
        });
      }
    },
    
    // 3. 支付
    async handlePay() {
      try {
        const res = await payOrder({
          id: this.orderId
        });
        
        if (res.code === 0) {
          uni.showToast({
            title: '支付成功',
            icon: 'success'
          });
          
          // 跳转订单详情
          uni.navigateTo({
            url: `/pages/sub-pages/rushing-order/detail?id=${this.orderId}`
          });
        }
      } catch (error) {
        uni.showToast({
          title: error.msg || '支付失败',
          icon: 'none'
        });
      }
    }
  }
}
```

---

### 4. 地址管理

```javascript
import { getAddressList, addAddress, updateAddress, deleteAddress } from '@/api/miao.js';

export default {
  data() {
    return {
      addressList: []
    }
  },
  
  methods: {
    // 加载地址列表
    async loadAddressList() {
      try {
        const res = await getAddressList();
        if (res.code === 0) {
          this.addressList = res.data.list;
        }
      } catch (error) {
        console.error('加载失败:', error);
      }
    },
    
    // 新增地址
    async addNewAddress() {
      try {
        const res = await addAddress({
          name: '张三',
          mobile: '13800138000',
          province: '江苏省',
          city: '苏州市',
          district: '工业园区',
          detail: '星湖街328号',
          is_default: 1
        });
        
        if (res.code === 0) {
          uni.showToast({
            title: '添加成功',
            icon: 'success'
          });
          
          this.loadAddressList();
        }
      } catch (error) {
        uni.showToast({
          title: error.msg || '添加失败',
          icon: 'none'
        });
      }
    },
    
    // 删除地址
    async deleteAddr(id) {
      try {
        const res = await deleteAddress({ id });
        if (res.code === 0) {
          uni.showToast({
            title: '删除成功',
            icon: 'success'
          });
          
          this.loadAddressList();
        }
      } catch (error) {
        uni.showToast({
          title: error.msg || '删除失败',
          icon: 'none'
        });
      }
    }
  }
}
```

---

### 5. 文件上传

```javascript
import { uploadFile } from '@/api/miao.js';

export default {
  methods: {
    // 选择并上传图片
    chooseAndUpload() {
      uni.chooseImage({
        count: 1,
        success: async (res) => {
          const filePath = res.tempFilePaths[0];
          
          uni.showLoading({ title: '上传中...' });
          
          try {
            const uploadRes = await uploadFile(filePath, 'user/avatar');
            
            if (uploadRes.code === 0) {
              uni.showToast({
                title: '上传成功',
                icon: 'success'
              });
              
              // 使用上传后的图片URL
              const imageUrl = uploadRes.data.url;
              console.log('图片URL:', imageUrl);
            }
          } catch (error) {
            uni.showToast({
              title: '上传失败',
              icon: 'none'
            });
          } finally {
            uni.hideLoading();
          }
        }
      });
    }
  }
}
```

---

## ❌ 错误处理

### 1. 统一错误处理

```javascript
import { userLogin } from '@/api/miao.js';

async function login(data) {
  try {
    const res = await userLogin(data);
    
    // 成功处理
    if (res.code === 0) {
      return res.data;
    } else {
      // 业务错误
      throw new Error(res.msg || '操作失败');
    }
  } catch (error) {
    // 网络错误或其他错误
    console.error('请求失败:', error);
    
    uni.showToast({
      title: error.message || '网络错误',
      icon: 'none'
    });
    
    throw error;
  }
}
```

### 2. 登录过期处理

```javascript
// 在 utils/request.js 中统一处理
request.interceptors.response.use(
  response => {
    const res = response.data;
    
    // Token过期
    if (res.code === 401 || res.code === 403) {
      uni.removeStorageSync('token');
      uni.removeStorageSync('userInfo');
      
      uni.showToast({
        title: '登录已过期',
        icon: 'none'
      });
      
      setTimeout(() => {
        uni.navigateTo({
          url: '/pages/sub-pages/login/index'
        });
      }, 1500);
      
      return Promise.reject(res);
    }
    
    return res;
  },
  error => {
    return Promise.reject(error);
  }
);
```

---

## ✨ 最佳实践

### 1. 封装成Mixin

```javascript
// mixins/apiMixin.js
import * as miaoApi from '@/api/miao.js';

export default {
  data() {
    return {
      $api: miaoApi
    }
  }
}

// 在页面中使用
export default {
  mixins: [apiMixin],
  
  methods: {
    async loadData() {
      const res = await this.$api.getGoodsList({ page: 1 });
    }
  }
}
```

---

### 2. 全局挂载

```javascript
// main.js
import * as miaoApi from '@/api/miao.js';

// 方式一：挂载到Vue原型
Vue.prototype.$miaoApi = miaoApi;

// 方式二：挂载到全局
uni.$miaoApi = miaoApi;

// 使用
export default {
  methods: {
    async loadData() {
      // 方式一
      const res1 = await this.$miaoApi.getGoodsList({ page: 1 });
      
      // 方式二
      const res2 = await uni.$miaoApi.getGoodsList({ page: 1 });
    }
  }
}
```

---

### 3. TypeScript支持

```typescript
// api/miao.d.ts
declare module '@/api/miao' {
  export function userLogin(data: {
    account: string;
    password: string;
  }): Promise<any>;
  
  export function getGoodsList(params: {
    page: number;
    limit: number;
    category_id?: number;
    keyword?: string;
  }): Promise<any>;
  
  // ... 其他接口定义
}
```

---

## 📝 注意事项

### 1. 认证头名称

⚠️ **重要**: 本项目使用的认证头是 `Authori-zation`（不是标准的 `Authorization`）

```javascript
// 在 request.js 中配置
header: {
  'Authori-zation': 'Bearer ' + token
}
```

### 2. POST方法查询

以下接口虽然是查询操作，但使用POST方法：
- `userInfo()` - 获取用户信息
- `getIndexConfig()` - 获取首页配置
- `getOrderIndex()` - 获取订单首页
- `getDefaultAddress()` - 获取默认地址

### 3. 分页参数

统一使用以下分页参数：
```javascript
{
  page: 1,     // 页码，从1开始
  limit: 20    // 每页数量
}
```

### 4. 响应格式

统一响应格式：
```javascript
{
  code: 0,           // 0表示成功
  msg: 'success',    // 提示信息
  data: {}           // 返回数据
}
```

---

## 📚 相关文档

- [后端API接口文档](./后端API接口文档.md) - 详细接口文档
- [API接口速查表](./API接口速查表.md) - 快速查询表
- [API分析总结](./API分析总结-2025-11-08.md) - 分析报告

---

**最后更新**: 2025-11-08  
**文档版本**: v1.0