rhb-server/mes-ui/rhb-app/utils/README.md

# HTTP工具类使用说明

本项目提供了基于Vue2和uni-app的HTTP请求工具类，用于统一管理API请求。

## 文件结构

```
utils/
├── https.js          # HTTP工具类核心文件
├── config.js         # 配置文件
├── api.js           # API接口配置
├── api-demo.js      # API调用示例
├── UserUtil.js      # 用户信息管理工具类
├── UserUtil-demo.js # UserUtil使用示例
└── README.md        # 使用说明
```

## 快速开始

### 1. 引入HTTP工具类

在需要使用API的组件中引入：

```javascript
// 引入具体的API模块
import { userApi, householdApi } from '../../utils/api.js'

// 或者引入所有API
import api from '../../utils/api.js'
```

### 2. 引入用户信息管理工具类

```javascript
// 引入UserUtil
import userUtil from '@/utils/UserUtil.js'
```

### 2. 基本使用

```javascript
export default {
  data() {
    return {
      userInfo: null,
      householdList: []
    }
  },
  
  async mounted() {
    // 获取用户信息
    try {
      this.userInfo = await userApi.getUserInfo()
    } catch (error) {
      console.error('获取用户信息失败:', error)
    }
  },
  
  methods: {
    // 创建家庭登记
    async createHousehold() {
      try {
        const data = {
          householdName: '张三家庭',
          contactPhone: '13800138000',
          address: '北京市朝阳区xxx街道'
        }
        
        const result = await householdApi.createHousehold(data)
        console.log('创建成功:', result)
        
        uni.showToast({
          title: '创建成功',
          icon: 'success'
        })
      } catch (error) {
        console.error('创建失败:', error)
      }
    }
  }
}
```

## 配置说明

### 环境配置

在 `config.js` 中配置不同环境的API地址：

```javascript
const ENV = {
  development: {
    baseURL: 'http://localhost:8080/admin-api',
    uploadURL: 'http://localhost:8080/admin-api/upload'
  },
  production: {
    baseURL: 'https://your-production-domain.com/admin-api',
    uploadURL: 'https://your-production-domain.com/admin-api/upload'
  }
}
```

### 请求拦截器

HTTP工具类自动添加了以下拦截器功能：

1. **自动拼接基础URL**：非http开头的请求会自动拼接baseURL
2. **请求超时设置**：默认1000000ms
3. **请求头设置**：自动添加tenant-id和Authorization
4. **Token管理**：自动从本地存储获取token

### 响应处理

- **成功响应**：自动提取 `res.data.data` 作为返回结果
- **错误处理**：自动显示错误提示
- **401错误**：自动跳转到登录页
- **网络错误**：显示网络错误提示

## API接口说明

### 用户相关接口

```javascript
import { userApi } from '../../utils/api.js'

// 用户登录
const loginResult = await userApi.login({
  username: 'admin',
  password: '123456'
})

// 获取用户信息
const userInfo = await userApi.getUserInfo()

// 用户登出
await userApi.logout()
```

### 家庭登记相关接口

```javascript
import { householdApi } from '../../utils/api.js'

// 获取家庭列表
const list = await householdApi.getHouseholdList({
  page: 1,
  size: 10,
  status: 'PENDING'
})

// 创建家庭登记
const result = await householdApi.createHousehold({
  householdName: '张三家庭',
  contactPhone: '13800138000',
  address: '北京市朝阳区'
})

// 上传签名
const uploadResult = await householdApi.uploadSignature(
  filePath, 
  { signatureType: 'HOLDER' }
)
```

### 文件上传接口

```javascript
import { uploadApi } from '../../utils/api.js'

// 上传图片
const imageResult = await uploadApi.uploadImage(filePath, {
  type: 'household_photo'
})

// 上传文档
const docResult = await uploadApi.uploadDocument(filePath, {
  type: 'household_document'
})
```

## 错误处理

### 全局错误处理

HTTP工具类已经内置了错误处理机制：

```javascript
// 自动处理常见错误
try {
  const result = await userApi.getUserInfo()
} catch (error) {
  // 错误已经被自动处理，这里可以添加额外逻辑
  console.error('自定义错误处理:', error)
}
```

### 自定义错误处理

```javascript
// 在组件中自定义错误处理
methods: {
  async handleRequest() {
    try {
      const result = await householdApi.createHousehold(this.formData)
      // 成功处理
      this.handleSuccess(result)
    } catch (error) {
      // 自定义错误处理
      if (error.statusCode === 403) {
        uni.showModal({
          title: '权限不足',
          content: '您没有权限执行此操作'
        })
      } else {
        uni.showToast({
          title: '操作失败',
          icon: 'none'
        })
      }
    }
  }
}
```

## 文件上传

### 选择并上传图片

```javascript
methods: {
  selectAndUploadImage() {
    uni.chooseImage({
      count: 1,
      sizeType: ['compressed'],
      sourceType: ['album', 'camera'],
      success: async (res) => {
        const filePath = res.tempFilePaths[0]
        try {
          const result = await uploadApi.uploadImage(filePath, {
            type: 'household_photo'
          })
          console.log('上传成功:', result)
        } catch (error) {
          console.error('上传失败:', error)
        }
      }
    })
  }
}
```

### 上传签名

```javascript
methods: {
  async uploadSignature(signatureBase64) {
    try {
      // 将base64转换为文件路径
      const filePath = await this.base64ToFilePath(signatureBase64)
      
      const result = await householdApi.uploadSignature(filePath, {
        signatureType: 'HOLDER'
      })
      
      console.log('签名上传成功:', result)
    } catch (error) {
      console.error('签名上传失败:', error)
    }
  }
}
```

## 最佳实践

### 1. 组件中的使用

```javascript
export default {
  data() {
    return {
      loading: false,
      data: null
    }
  },
  
  async mounted() {
    await this.loadData()
  },
  
  methods: {
    async loadData() {
      this.loading = true
      try {
        this.data = await api.household.getHouseholdList()
      } catch (error) {
        // 错误已被自动处理
      } finally {
        this.loading = false
      }
    }
  }
}
```

### 2. 表单提交

```javascript
methods: {
  async submitForm() {
    try {
      // 表单验证
      await this.validateForm()
      
      // 提交数据
      const result = await householdApi.createHousehold(this.formData)
      
      // 成功处理
      uni.showToast({ title: '提交成功', icon: 'success' })
      uni.navigateBack()
      
    } catch (error) {
      // 错误处理
    }
  }
}
```

### 3. 并行请求

```javascript
methods: {
  async loadInitialData() {
    try {
      const [userInfo, householdList, dictData] = await Promise.all([
        userApi.getUserInfo(),
        householdApi.getHouseholdList(),
        systemApi.getDictData('household_type')
      ])
      
      this.userInfo = userInfo
      this.householdList = householdList
      this.dictData = dictData
      
    } catch (error) {
      console.error('加载数据失败:', error)
    }
  }
}
```

## 注意事项

1. **Token管理**：确保登录后正确保存token到本地存储
2. **错误处理**：虽然工具类会自动处理常见错误，但建议在关键操作中添加自定义错误处理
3. **文件上传**：注意文件大小限制和格式要求
4. **网络状态**：在弱网环境下注意请求超时设置
5. **数据格式**：确保提交的数据格式符合后端API要求

## 用户信息管理 (UserUtil)

### 基本使用

```javascript
import userUtil from '@/utils/UserUtil.js'

// 保存登录信息
userUtil.setLoginInfo({
  accessToken: 'token123',
  refreshToken: 'refresh123',
  userId: 'user123',
  username: 'admin',
  userInfo: { name: '张三', role: 'admin' }
})

// 检查登录状态
const isLoggedIn = userUtil.isLoggedIn()

// 获取用户信息
const userInfo = userUtil.getFullUserInfo()
const loginInfo = userUtil.getLoginInfo()
const accessToken = userUtil.getAccessToken()

// 清除用户信息
userUtil.clearAll()
```

### 登录流程示例

```javascript
export default {
  methods: {
    async handleLogin() {
      try {
        // 调用登录接口
        const loginResult = await userApi.login(this.loginForm)
        
        // 保存登录信息
        userUtil.setLoginInfo({
          accessToken: loginResult.accessToken,
          refreshToken: loginResult.refreshToken,
          userId: loginResult.userId,
          username: this.loginForm.username,
          userInfo: loginResult.userInfo
        })
        
        // 保存用户名密码（可选）
        userUtil.setCredentials(this.loginForm.username, this.loginForm.password)
        
        // 跳转到主页
        uni.reLaunch({ url: '/pages/index/index' })
        
      } catch (error) {
        console.error('登录失败:', error)
      }
    }
  }
}
```

### 用户信息管理

```javascript
// 更新用户信息
userUtil.updateUserInfo({ 
  nickname: '新昵称',
  avatar: 'new-avatar.jpg' 
})

// 保存字典信息
userUtil.setDictInfo([
  { dictType: 'household_type', dictLabel: '家庭', dictValue: 'FAMILY' }
])

// 获取字典信息
const dictInfo = userUtil.getDictInfo()
```

### 自动登录

```javascript
export default {
  async mounted() {
    // 检查是否有保存的凭据
    const credentials = userUtil.getCredentials()
    
    if (credentials.username && credentials.password) {
      try {
        // 尝试自动登录
        await this.autoLogin(credentials.username, credentials.password)
      } catch (error) {
        // 自动登录失败，清除凭据
        userUtil.clearCredentials()
      }
    }
  },
  
  methods: {
    async autoLogin(username, password) {
      const loginResult = await userApi.login({ username, password })
      userUtil.setLoginInfo({
        accessToken: loginResult.accessToken,
        userId: loginResult.userId,
        username: username,
        userInfo: loginResult.userInfo
      })
    }
  }
}
```

## 更新日志

- v1.0.0: 初始版本，支持基本的HTTP请求和文件上传
- 支持Vue2语法和uni-app框架
- 内置请求拦截器和响应处理
- 统一的错误处理机制
- v1.1.0: 新增UserUtil用户信息管理工具类