appointment_system/modules/api/API_GUIDE.md

AppServer API 使用指南

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

初始化

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

const appServer = new AppServer();

认证相关接口

1. 微信登录

const data = await appServer.WechatLogin(code);
// 返回: { success: true, data: { token, refreshToken, user } }

2. 刷新Token

const data = await appServer.RefreshToken(refreshToken);
// 返回: { success: true, data: { token, refreshToken } }

3. 登出

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

用户相关接口

1. 获取用户信息

const data = await appServer.GetUserProfile();
// 返回: { success: true, data: { id, nickname, avatar, ... } }

2. 更新用户信息

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

3. 设置语言偏好

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

服务相关接口

1. 获取服务分类列表

const data = await appServer.GetCategories();
// 返回: { success: true, data: [{ id, key, nameZh, nameEn, namePt, ... }] }

2. 获取服务列表

const data = await appServer.GetServices({
  page: 1,
  limit: 10,
  categoryId: 'uuid',  // 可选
  language: 'zh'       // 可选
});
// 返回: { success: true, data: { items: [...], total, page, limit } }

3. 获取服务详情

const data = await appServer.GetServiceById(serviceId, 'zh');
// 返回: { success: true, data: { id, title, description, price, ... } }

预约相关接口

1. 创建预约

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. 获取预约列表

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. 获取预约详情

const data = await appServer.GetAppointmentById(appointmentId);
// 返回: { success: true, data: { id, service, user, status, ... } }

4. 更新预约

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

5. 取消预约

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

通知相关接口

1. 获取通知列表

const data = await appServer.GetNotifications({
  page: 1,
  limit: 10,
  type: 'system'  // 可选: 'system', 'activity', 'service'
});
// 返回: { success: true, data: { items: [...], total, page, limit } }

2. 标记通知为已读

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

3. 全部标记为已读

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

4. 删除通知

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

邀请相关接口

1. 生成邀请码

const data = await appServer.GenerateInvitationCode();
// 返回: { success: true, data: { invitationCode: 'ABC123' } }

2. 获取邀请统计

const data = await appServer.GetInvitationStats();
// 返回: { success: true, data: { totalInvites, totalRewards, availableBalance } }

3. 获取邀请记录

const data = await appServer.GetInvitationRecords();
// 返回: { success: true, data: [{ invitee, registeredAt, firstPaymentAmount, ... }] }

提现相关接口

1. 申请提现

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. 获取提现记录

const data = await appServer.GetWithdrawals({
  page: 1,
  limit: 10,
  status: 'waiting'  // 可选: 'waiting', 'processing', 'completed', 'rejected'
});
// 返回: { success: true, data: { items: [...], total, page, limit } }

3. 获取提现详情

const data = await appServer.GetWithdrawalById(withdrawalId);
// 返回: { success: true, data: { id, amount, status, paymentDetails, ... } }

上传相关接口

1. 上传图片

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

错误处理

所有接口返回格式统一：

成功响应:

{
  success: true,
  data: { ... },
  message: '操作成功'
}

失败响应:

{
  success: false,
  error: {
    code: 'ERROR_CODE',
    message: '错误信息',
    details: { ... }  // 可选
  }
}

使用示例:

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 格式

完整示例

// 登录流程
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);
  }
}