HomeLease/api/README.md

# API 模块使用说明

## 概述

本项目使用统一的API请求工具 `@/utils/request.js`，所有API请求都通过该工具进行，无需重复配置基地址和请求头。

## 目录结构

```
api/
├── index.js          # API模块统一导出
├── account.js        # 银行卡账户管理API
├── lease/            # 租赁相关API
│   └── lease.js
├── device/           # 设备相关API
│   └── device.js
├── banner/           # 轮播图相关API
│   └── banner.js
├── article/          # 文章相关API
│   └── article.js
└── auth/             # 认证相关API
    └── auth.js
```

## 银行卡账户管理API

### 接口说明

银行卡账户管理模块提供了完整的银行卡CRUD操作，支持银行卡和收款二维码两种类型。

### 主要接口

#### 1. 添加银行卡号
```javascript
import { addBankAccount } from '@/api/account.js'

// 添加银行卡
const params = {
  type: 'BANK',                    // 类型：BANK=银行卡, QR=收款二维码
  no: '6217002490009046470',       // 银行卡号或收款码图片URL
  name: '刘芙杰',                  // 收款人姓名
  idCard: '411303198912184826',    // 身份证号
  mobile: '18913873357'            // 手机号
}

const response = await addBankAccount(params)
```

#### 2. 删除银行卡号
```javascript
import { deleteBankAccount } from '@/api/account.js'

// 删除单个银行卡
await deleteBankAccount('15')

// 删除多个银行卡
await deleteBankAccount(['15', '14'])
// 或者
await deleteBankAccount('15,14')
```

#### 3. 获取银行卡列表
```javascript
import { getBankAccountList } from '@/api/account.js'

const response = await getBankAccountList()
```

#### 4. 更新银行卡信息
```javascript
import { updateBankAccount } from '@/api/account.js'

const params = {
  id: '15',                        // 银行卡ID
  type: 'BANK',
  no: '6217002490009046470',
  name: '刘芙杰',
  idCard: '411303198912184826',
  mobile: '18913873357'
}

const response = await updateBankAccount(params)
```

### 参数说明

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | string | 是 | BANK=线下银行卡, QR=线下收款二维码 |
| no | string | 是 | type是银行卡:银行卡号。type是二维码收款:收款码图片URL |
| name | string | 是 | 收款人姓名 |
| idCard | string | 是 | 身份证号 |
| mobile | string | 是 | 手机号 |

## 使用方法

### 1. 导入API方法

```javascript
// 方式1：从具体模块导入
import { getDeviceTypes, getPeriodPackages } from '@/api/lease/lease.js'

// 方式2：从统一入口导入
import { getDeviceTypes, getPeriodPackages } from '@/api/index.js'
```

### 2. 在组件中使用

```javascript
export default {
  methods: {
    async fetchData() {
      try {
        const response = await getDeviceTypes()
        
        if (response.code === 200) {
          this.deviceTypes = response.data
        } else {
          throw new Error(response.message || '请求失败')
        }
      } catch (error) {
        console.error('获取数据失败:', error)
        uni.showToast({
          title: error.message || '获取数据失败',
          icon: 'error',
        })
      }
    }
  }
}
```

## API方法命名规范

- 获取列表：`getXxxList`
- 获取详情：`getXxxDetail`
- 创建：`createXxx`
- 更新：`updateXxx`
- 删除：`deleteXxx`

## 请求工具特性

### 自动处理
- ✅ 基地址配置
- ✅ 请求头设置
- ✅ Token管理
- ✅ Loading状态
- ✅ 错误处理
- ✅ 超时处理

### 配置选项
```javascript
request({
  url: '/api/endpoint',
  method: 'GET',
  params: { id: 1 },
  loadingText: '加载中...',    // 自定义loading文本
  showLoading: true,          // 是否显示loading
  timeout: 60000,            // 超时时间
  noToken: false,            // 是否需要token
})
```

## 环境配置

请求工具会根据当前环境自动选择对应的配置：

- **开发环境**：`http://192.168.2.114:4601`
- **体验版**：`http://192.168.2.114:4601`
- **正式版**：`http://192.168.2.114:4601`

## 错误处理

所有API请求都会自动处理以下错误：

- 401：登录过期，自动跳转登录页
- 403：权限不足
- 404：资源不存在
- 500：服务器错误
- 网络错误：超时、连接失败等

## 注意事项

1. **方法名冲突**：避免页面方法名与API方法名相同，建议使用别名导入
2. **Loading管理**：请求工具已内置loading管理，无需手动处理
3. **错误提示**：统一使用 `uni.showToast` 显示错误信息
4. **Token处理**：开发环境支持临时token，生产环境使用真实token