# API接口集成说明

## 已集成的接口

### 1. 用户详情接口 `/user/detail`

**请求方式**: POST  
**请求参数**:
```json
{
  "user_id": "string" // 可选，不传则获取当前用户信息
}
```

**响应格式**:
```json
{
  "code": 0,
  "message": "string",
  "data": {
    "openid": "",
    "user_code": "",
    "unionid": "",
    "session_key": "",
    "nickname": "张三",
    "avatar_url": "https://example.com/avatar.jpg",
    "gender": "",
    "country": "",
    "province": "",
    "city": "",
    "language": "",
    "phone": "13800138000",
    "is_subscribed": "0",
    "latitude": "0",
    "longitude": "0",
    "subscribe_time": "2024-06-15 14:00:00",
    "last_login_time": "2024-06-15 14:00:00"
  }
}
```

### 2. 用户信息更新接口 `/user/update`

**请求方式**: POST  
**请求参数**:
```json
{
  "nickname": "string",
  "avatar_url": "string",
  "gender": "string",
  "phone": "string",
  "latitude": 31.2304,
  "longitude": 121.4737,
  "city": "string",
  "province": "string",
  "country": "string"
}
```

**响应格式**:
```json
{
  "code": 0,
  "message": "string",
  "data": {}
}
```

### 3. 头像上传接口 `/gallery/upload`

**请求方式**: POST (multipart/form-data)  
**请求参数**:
- `file`: 图片文件

**响应格式**:
```json
{
  "code": 0,
  "message": "请求成功！",
  "data": {
    "create_time": "2025-09-06 19:41:18",
    "last_modify_time": "2025-09-06 19:41:18",
    "duration": "0",
    "thumbnail_url": "",
    "view_count": "0",
    "download_count": "0",
    "is_delete": 0,
    "id": 67,
    "user_id": 1,
    "resource_type": "image",
    "file_name": "front/ball/images/f1bd8f63-a1e0-4750-9656-1e8405753416.jpg",
    "original_name": "微信图片_20250505175522.jpg",
    "file_path": "http://bimwe.oss-cn-shanghai.aliyuncs.com/front/ball/images/f1bd8f63-a1e0-4750-9656-1e8405753416.jpg",
    "file_url": "http://bimwe.oss-cn-shanghai.aliyuncs.com/front/ball/images/f1bd8f63-a1e0-4750-9656-1e8405753416.jpg",
    "file_size": 264506,
    "mime_type": "image/jpeg",
    "description": "用户图像",
    "tags": "用户图像",
    "is_public": "1",
    "width": 0,
    "height": 0,
    "uploadInfo": {
      "success": true,
      "name": "front/ball/images/f1bd8f63-a1e0-4750-9656-1e8405753416.jpg",
      "path": "http://bimwe.oss-cn-shanghai.aliyuncs.com/front/ball/images/f1bd8f63-a1e0-4750-9656-1e8405753416.jpg",
      "ossPath": "http://bimwe.oss-cn-shanghai.aliyuncs.com/front/ball/images/f1bd8f63-a1e0-4750-9656-1e8405753416.jpg",
      "fileType": "image/jpeg",
      "fileSize": 264506,
      "originalName": "微信图片_20250505175522.jpg",
      "suffix": "jpg",
      "storagePath": "front/ball/images/f1bd8f63-a1e0-4750-9656-1e8405753416.jpg"
    }
  }
}
```

**说明**: 上传成功后，使用 `data.file_url` 字段作为头像URL。

## 使用方式

### 在页面中调用

```typescript
import { UserService } from '@/services/userService';

// 获取用户信息
const userInfo = await UserService.get_user_info('user_id');

// 更新用户信息
await UserService.save_user_info({
  nickname: '新昵称',
  phone: '13800138000',
  gender: '男'
});

// 上传头像
const avatarUrl = await UserService.upload_avatar('/path/to/image.jpg');
```

### API配置

API配置位于 `src/config/api.ts`，可以根据环境自动切换接口地址：

```typescript
export const API_CONFIG = {
  BASE_URL: process.env.NODE_ENV === 'development' 
    ? 'http://localhost:3000' 
    : 'https://api.example.com',
  // ...
};
```

## 错误处理

所有API调用都包含完整的错误处理：

1. **网络错误**: 自动捕获并显示友好提示
2. **业务错误**: 根据返回的 `code` 和 `message` 处理
3. **超时处理**: 10秒超时设置
4. **降级处理**: API失败时返回默认数据

## 数据映射

### 用户信息映射

API返回的用户数据会自动映射到前端组件使用的格式：

```typescript
// API数据 -> 前端组件数据
{
  user_code -> id,
  nickname -> nickname,
  avatar_url -> avatar,
  subscribe_time -> join_date,
  city -> location,
  // ...
}
```

## 注意事项

1. **位置信息**: 更新用户信息时会自动获取当前位置
2. **头像处理**: 上传失败时自动使用默认头像
3. **表单验证**: 编辑资料页面包含完整的表单验证
4. **类型安全**: 所有接口都有完整的TypeScript类型定义

## 扩展接口

如需添加新的用户相关接口，可以在 `UserService` 中添加新方法：

```typescript
static async new_api_method(params: any): Promise<any> {
  try {
    const response = await Taro.request({
      url: `${API_CONFIG.BASE_URL}/new/endpoint`,
      method: 'POST',
      data: params,
      ...REQUEST_CONFIG
    });
    
    if (response.data.code === 0) {
      return response.data.data;
    } else {
      throw new Error(response.data.message);
    }
  } catch (error) {
    console.error('API调用失败:', error);
    throw error;
  }
}
```