HomeLease/api/user/README.md

# 用户API模块

## 概述

用户API模块提供了用户信息、财务数据和统计信息的获取功能。

## API列表

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

// 获取用户基本信息
const response = await getUserInfo()
if (response.code === 200) {
  const userInfo = response.data
  // userInfo包含：userId, nickName, phonenumber, avatar等
}
```

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

// 获取用户财务信息
const response = await getUserFinancialData()
if (response.code === 200) {
  const financialData = response.data
  // financialData包含：balance, waitBalance, withdrawBalance, withdrawedBalance等
}
```

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

// 获取代理统计信息
const response = await getAgentCount()
if (response.code === 200) {
  const agentStats = response.data
  // agentStats包含：userNum, deviceNum, rentAmount等
}
```

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

// 获取用户列表
const response = await getUserList()
if (response.code === 200) {
  const userList = response.data
  // userList包含用户列表数据
}
```

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

// 更新用户信息
const userData = {
  nickName: '新昵称',
  phonenumber: '13800138000'
}
const response = await updateUserInfo(userData)
```

## 数据结构

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

### 财务数据 (FinancialData)
```javascript
{
  balance: 10000.00,              // 可提现金额
  waitBalance: 0,                 // 待入账金额
  withdrawBalance: 0,             // 提现中金额
  withdrawedBalance: 0            // 已提现金额
}
```

### 代理统计 (AgentStats)
```javascript
{
  userNum: 4,                     // 名下用户数
  deviceNum: 1,                   // 设备数量
  rentAmount: 2                   // 租赁数量
}
```

### 用户列表 (UserList)
```javascript
[
  {
    id: 1,                        // 用户ID
    username: '张三',             // 用户名
    totalAmount: '5000',          // 总金额
    deviceCount: 2,               // 设备数量
    devices: [                    // 设备列表
      {
        type: '智能门锁',         // 设备类型
        amount: '1000',           // 金额
        rentDate: '2025.01.15',   // 租赁日期
        period: '1年',            // 租赁周期
        expiryDate: '2026.01.15'  // 到期日期
      }
    ]
  }
]
```

## 错误处理

所有API都包含错误处理机制：

1. **网络错误**：自动使用模拟数据
2. **API错误**：返回错误信息
3. **数据验证**：确保返回数据格式正确

## 模拟数据

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

- 用户信息：超级管理员
- 财务数据：预设的金额数据
- 用户统计：预设的统计数据

## 使用示例

在Vue组件中使用：

```javascript
export default {
  data() {
    return {
      userInfo: {},
      financialData: {},
      userStats: {}
    }
  },
  
  async onLoad() {
    await this.fetchUserData()
  },
  
  methods: {
    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)
      }
    }
  }
}
```

## 注意事项

1. 所有API都需要有效的token
2. 财务数据需要用户登录后才能获取
3. 统计数据可能有缓存，建议定期刷新
4. 头像URL需要网络访问权限