appointment_system/modules/api/API_GUIDE.md

# AppServer API 使用指南

本文档说明如何使用 AppServer.js 中封装的 API 接口。

## 初始化

```javascript
import { AppServer } from '@/modules/api/AppServer';

const appServer = new AppServer();
```

## 认证相关接口

### 1. 微信登录
```javascript
const data = await appServer.WechatLogin(code);
// 返回: { success: true, data: { token, refreshToken, user } }
```

### 2. 刷新Token
```javascript
const data = await appServer.RefreshToken(refreshToken);
// 返回: { success: true, data: { token, refreshToken } }
```

### 3. 登出
```javascript
const data = await appServer.Logout();
// 返回: { success: true, message: '登出成功' }
```

## 用户相关接口

### 1. 获取用户信息
```javascript
const data = await appServer.GetUserProfile();
// 返回: { success: true, data: { id, nickname, avatar, ... } }
```

### 2. 更新用户信息
```javascript
const data = await appServer.UpdateUserProfile({
  nickname: '新昵称',
  avatar: 'https://...',
  realName: '真实姓名',
  phone: '13800138000',
  whatsapp: '+86138...',
  wechatId: 'wechat123'
});
// 返回: { success: true, data: { ...更新后的用户信息 } }
```

### 3. 设置语言偏好
```javascript
const data = await appServer.SetLanguage('zh'); // 'zh', 'en', 'pt'
// 返回: { success: true, message: '语言设置成功' }
```

## 服务相关接口

### 1. 获取服务分类列表
```javascript
const data = await appServer.GetCategories();
// 返回: { success: true, data: [{ id, key, nameZh, nameEn, namePt, ... }] }
```

### 2. 获取服务列表
```javascript
const data = await appServer.GetServices({
  page: 1,
  limit: 10,
  categoryId: 'uuid',  // 可选
  language: 'zh'       // 可选
});
// 返回: { success: true, data: { items: [...], total, page, limit } }
```

### 3. 获取服务详情
```javascript
const data = await appServer.GetServiceById(serviceId, 'zh');
// 返回: { success: true, data: { id, title, description, price, ... } }
```

## 预约相关接口

### 1. 创建预约
```javascript
const data = await appServer.CreateAppointment({
  serviceId: 'uuid',
  realName: '张三',
  contactMethod: 'phone',  // 'phone', 'whatsapp', 'wechat'
  contactValue: '13800138000',
  appointmentDate: '2025-12-31',  // 可选
  appointmentTime: '14:30:00',    // 可选
  notes: '备注信息',               // 可选
  amount: 100.00                  // 可选
});
// 返回: { success: true, data: { id, appointmentNo, ... } }
```

### 2. 获取预约列表
```javascript
const data = await appServer.GetAppointments({
  page: 1,
  limit: 10,
  status: 'pending'  // 可选: 'pending', 'confirmed', 'in-progress', 'completed', 'cancelled'
});
// 返回: { success: true, data: { items: [...], total, page, limit } }
```

### 3. 获取预约详情
```javascript
const data = await appServer.GetAppointmentById(appointmentId);
// 返回: { success: true, data: { id, service, user, status, ... } }
```

### 4. 更新预约
```javascript
const data = await appServer.UpdateAppointment(appointmentId, {
  realName: '李四',
  contactMethod: 'whatsapp',
  contactValue: '+8613800138000',
  notes: '更新备注'
});
// 返回: { success: true, data: { ...更新后的预约信息 } }
```

### 5. 取消预约
```javascript
const data = await appServer.CancelAppointment(appointmentId);
// 返回: { success: true, message: '预约已取消' }
```

## 通知相关接口

### 1. 获取通知列表
```javascript
const data = await appServer.GetNotifications({
  page: 1,
  limit: 10,
  type: 'system'  // 可选: 'system', 'activity', 'service'
});
// 返回: { success: true, data: { items: [...], total, page, limit } }
```

### 2. 标记通知为已读
```javascript
const data = await appServer.MarkNotificationAsRead(notificationId);
// 返回: { success: true, message: '已标记为已读' }
```

### 3. 全部标记为已读
```javascript
const data = await appServer.MarkAllNotificationsAsRead();
// 返回: { success: true, message: '全部已标记为已读' }
```

### 4. 删除通知
```javascript
const data = await appServer.DeleteNotification(notificationId);
// 返回: { success: true, message: '通知已删除' }
```

## 邀请相关接口

### 1. 生成邀请码
```javascript
const data = await appServer.GenerateInvitationCode();
// 返回: { success: true, data: { invitationCode: 'ABC123' } }
```

### 2. 获取邀请统计
```javascript
const data = await appServer.GetInvitationStats();
// 返回: { success: true, data: { totalInvites, totalRewards, availableBalance } }
```

### 3. 获取邀请记录
```javascript
const data = await appServer.GetInvitationRecords();
// 返回: { success: true, data: [{ invitee, registeredAt, firstPaymentAmount, ... }] }
```

## 提现相关接口

### 1. 申请提现
```javascript
const data = await appServer.CreateWithdrawal({
  amount: 100.00,
  paymentMethod: 'wechat',  // 'wechat', 'alipay', 'bank'
  paymentDetails: {
    // 微信/支付宝
    qrcodeImage: 'https://...',
    // 或银行卡
    bankCardNumber: '6222...',
    cardholderName: '张三',
    bankName: '中国银行',
    swiftCode: 'BKCH...'  // 可选
  }
});
// 返回: { success: true, data: { id, withdrawalNo, status, ... } }
```

### 2. 获取提现记录
```javascript
const data = await appServer.GetWithdrawals({
  page: 1,
  limit: 10,
  status: 'waiting'  // 可选: 'waiting', 'processing', 'completed', 'rejected'
});
// 返回: { success: true, data: { items: [...], total, page, limit } }
```

### 3. 获取提现详情
```javascript
const data = await appServer.GetWithdrawalById(withdrawalId);
// 返回: { success: true, data: { id, amount, status, paymentDetails, ... } }
```

## 上传相关接口

### 1. 上传图片
```javascript
// 选择图片
uni.chooseImage({
  count: 1,
  success: async (res) => {
    const filePath = res.tempFilePaths[0];
    const data = await appServer.UploadImage(filePath);
    // 返回: { success: true, data: { url: 'https://...', filename: '...' } }
  }
});
```

## 错误处理

所有接口返回格式统一：

**成功响应:**
```javascript
{
  success: true,
  data: { ... },
  message: '操作成功'
}
```

**失败响应:**
```javascript
{
  success: false,
  error: {
    code: 'ERROR_CODE',
    message: '错误信息',
    details: { ... }  // 可选
  }
}
```

**使用示例:**
```javascript
const data = await appServer.GetUserProfile();
if (data.success) {
  // 成功处理
  console.log('用户信息:', data.data);
} else {
  // 错误处理
  uni.showToast({
    title: data.error?.message || '操作失败',
    icon: 'none'
  });
}
```

## 注意事项

1. **Token 管理**: 所有需要认证的接口会自动从 `globalData` 或 `localStorage` 获取 token
2. **语言设置**: 部分接口支持 `language` 参数，可传入 'zh', 'en', 'pt'
3. **分页参数**: 列表接口通常支持 `page` 和 `limit` 参数
4. **日期格式**: 日期使用 'YYYY-MM-DD' 格式，时间使用 'HH:MM:SS' 格式
5. **UUID**: 所有 ID 字段均为 UUID 格式

## 完整示例

```javascript
// 登录流程
async function handleLogin() {
  try {
    // 1. 获取微信登录code
    const loginRes = await uni.login({ provider: 'weixin' });
    
    // 2. 调用登录接口
    const appServer = new AppServer();
    const data = await appServer.WechatLogin(loginRes.code);
    
    if (data.success) {
      // 3. 保存token
      const token = "Bearer " + data.data.token;
      uni.setStorageSync("token", token);
      
      // 4. 跳转首页
      uni.switchTab({ url: '/pages/index/index' });
    } else {
      uni.showToast({
        title: data.error?.message || '登录失败',
        icon: 'none'
      });
    }
  } catch (error) {
    console.error('登录错误:', error);
  }
}

// 创建预约流程
async function createAppointment() {
  try {
    const appServer = new AppServer();
    const data = await appServer.CreateAppointment({
      serviceId: 'service-uuid',
      realName: '张三',
      contactMethod: 'phone',
      contactValue: '13800138000',
      notes: '请尽快联系我'
    });
    
    if (data.success) {
      uni.showToast({
        title: '预约成功',
        icon: 'success'
      });
      // 跳转到预约详情页
      uni.navigateTo({
        url: `/pages/appointment/detail?id=${data.data.id}`
      });
    }
  } catch (error) {
    console.error('创建预约错误:', error);
  }
}
```