HomeLease/api/user/README.md

# 用户模块 API 文档

## 接口列表

### 1. 获取用户信息
```javascript
import { getUserInfo } from '@/api/user/user.js'

const response = await getUserInfo()
```

**接口地址:** `GET /app/user/info`

**响应数据:**
```javascript
{
  userId: '1',                    // 用户ID
  nickName: '超级管理员',         // 用户昵称
  phonenumber: '15888888888',     // 手机号
  avatar: 'https://...',          // 头像URL
  email: null,                    // 邮箱
  sex: null,                      // 性别
  status: '0',                    // 状态
  createTime: null,               // 创建时间
  updateTime: null                // 更新时间
}
```

### 2. 获取用户财务数据
```javascript
import { getUserFinancialData } from '@/api/user/user.js'

const response = await getUserFinancialData()
```

**接口地址:** `GET /app/user/financial`

**响应数据:**
```javascript
{
  balance: 10000.00,              // 余额
  waitBalance: 0,                 // 待结算余额
  withdrawBalance: 0,             // 可提现余额
  withdrawedBalance: 0            // 已提现余额
}
```

### 3. 获取代理统计
```javascript
import { getAgentCount } from '@/api/user/user.js'

const response = await getAgentCount()
```

**接口地址:** `GET /app/order/agentCount`

**响应数据:**
```javascript
{
  userNum: 4,                     // 名下用户数
  deviceNum: 1,                   // 设备数量
  rentAmount: 2                   // 租赁数量
}
```

### 4. 获取代理用户列表
```javascript
import { getAgentList } from '@/api/user/user.js'

const response = await getAgentList({
  beginTime: '2024-10-10 12:10:00',  // 开始时间(筛选)
  endTime: '2026-10-10 12:10:00',    // 结束时间(筛选)
  name: '李'                         // 用户昵称(搜索)
})
```

**接口地址:** `GET /app/order/agentList`

**请求参数:**
- `beginTime` (string, 可选): 开始时间，格式: YYYY-MM-DD HH:mm:ss
- `endTime` (string, 可选): 结束时间，格式: YYYY-MM-DD HH:mm:ss
- `name` (string, 可选): 用户昵称，支持模糊搜索

**响应数据:**
```javascript
[
  {
    userId: '28',                 // 用户ID
    nickName: '李四',             // 用户昵称
    avatar: '',                   // 头像
    totalAmount: 730.00,          // 总金额
    deviceNum: 2,                 // 设备数量
    orders: [                     // 订单列表
      {
        id: '3',                  // 订单ID
        userId: '28',             // 用户ID
        name: '派大星',           // 联系人姓名
        phone: '13777777777',     // 联系电话
        address: '广西南宁市西乡塘区', // 地址
        detailed: '详细地址',      // 详细地址
        typeName: '单头灶',       // 设备类型名称
        suitName: '一年',         // 套餐名称
        suitDay: '365',           // 套餐天数
        amount: 365.00,           // 金额
        status: '2',              // 订单状态
        leaseTime: '2025-08-15 10:50:22',      // 租赁时间
        expirationTime: '2025-11-15 10:50:25', // 到期时间
        orderNumber: '123456789101114'         // 订单号
      }
    ]
  }
]
```

### 5. 获取提现信息
```javascript
import { getWithdrawInfo } from '@/api/user/user.js'

const response = await getWithdrawInfo()
```

**接口地址:** `GET /app/withdraw`

**响应数据:**
```javascript
{
  balance: 10000.00,              // 账户余额
  waitVerify: 0,                  // 待验证金额
  available: 10000.00,            // 可提现金额
  unsettled: 0,                   // 未结算金额
  fee: 1.00,                      // 提现手续费
  minAmount: 100.00,              // 最小提现金额
  maxAmount: 50000.00             // 最大提现金额
}
```

### 6. 提交提现申请
```javascript
import { submitWithdraw } from '@/api/user/user.js'

const response = await submitWithdraw({
  amount: 1000.00,                // 提现金额
  bankId: '1'                     // 银行ID
})
```

**接口地址:** `POST /app/withdraw`

**请求参数:**
- `amount` (number, 必填): 提现金额
- `bankId` (string, 必填): 银行ID

**响应数据:**
```javascript
{
  msg: "操作成功",
  code: 200,
  data: {
    balance: 9000.00,             // 提现后余额
    waitVerify: 1000.00           // 待验证金额
  }
}
```

### 7. 更新用户信息
```javascript
import { updateUserInfo } from '@/api/user/user.js'

const response = await updateUserInfo({
  nickName: '新昵称',
  email: 'new@example.com'
})
```

**接口地址:** `PUT /app/user/info`

## 使用示例

### 在提现页面中
```javascript
// 在提现页面中
async fetchWithdrawInfo() {
  try {
    const response = await getWithdrawInfo()
    if (response.code === 200) {
      this.withdrawInfo = response.data
    }
  } catch (error) {
    console.error('获取提现信息失败:', error)
  }
}

async submitWithdrawal() {
  try {
    const response = await submitWithdraw({
      amount: 1000.00,
      bankId: '1'
    })
    
    if (response.code === 200) {
      uni.showToast({
        title: '提现申请已提交',
        icon: 'success'
      })
    }
  } catch (error) {
    console.error('提现申请失败:', error)
  }
}
```

### 在页面中获取用户数据
```javascript
// 在 Profile 页面中
async fetchUserData() {
  try {
    const [userInfo, financial, stats] = await Promise.all([
      getUserInfo(),
      getUserFinancialData(),
      getAgentCount()
    ])
    
    this.userInfo = userInfo.data
    this.financialData = financial.data
    this.userStats = stats.data
  } catch (error) {
    console.error('获取用户数据失败:', error)
  }
}
```

### 在用户列表页面中
```javascript
// 在用户列表页面中
async fetchUserList() {
  try {
    const params = {
      beginTime: '2024-10-10 00:00:00',
      endTime: '2026-10-10 23:59:59',
      name: '李'
    }
    
    const response = await getAgentList(params)
    if (response.code === 200) {
      // 转换数据格式
      this.users = response.data.map(user => ({
        ...user,
        devices: user.orders.map(order => ({
          type: order.typeName,
          amount: order.amount,
          rentDate: this.formatDate(order.leaseTime),
          period: order.suitName,
          expiryDate: this.formatDate(order.expirationTime)
        }))
      }))
    }
  } catch (error) {
    console.error('获取用户列表失败:', error)
  }
}
```

## 错误处理

所有API函数都包含错误处理机制，如果API调用失败，会自动返回模拟数据：

```javascript
// 如果API调用失败，会返回模拟数据
const response = await getUserInfo()
// 即使网络错误，也会返回模拟的用户信息
```

## 模拟数据

当API不可用时，系统会自动使用模拟数据：

- `mockUserInfo`: 用户基本信息
- `mockFinancialData`: 财务数据
- `mockAgentStats`: 代理统计数据
- `mockAgentList`: 代理用户列表数据
- `mockWithdrawInfo`: 提现信息数据
- `mockBanks`: 银行列表数据