DQM API Client

🏸 一个用于球场预订 API 服务的 Node.js 客户端库，包含认证、短信验证和场馆管理功能。

🌟 特性

• 🔐 身份认证: 微信小程序登录和用户管理
• 📱 短信服务: 短信验证码发送和验证
• 🏟️ 场馆管理: 场馆查询和预订功能
• 🛡️ 类型安全: 完整的 TypeScript 类型定义
• 🧩 模块化设计: 继承结构，易于扩展
• ⚡ 现代化: ES2022+ 语法，私有字段
• 🛠️ 工具丰富: 签名生成、编码解码等实用函数

📦 安装

npm install dqm-api-client

🚀 快速开始

基础用法

const { createClient } = require('dqm-api-client');

// 创建客户端实例
const client = createClient({
  appId: 'your_wechat_app_id',
  appSecret: 'your_wechat_app_secret',
  paymentKey: 'your_payment_key', // 可选
});

// 使用场馆服务
async function bookCourt() {
  try {
    // 查询可用场馆
    const courts = await client.court.getCourt('2024-01-15');
    console.log('可用场馆:', courts);

    // 预订场馆
    const booking = await client.court.bookCourt({
      courtId: 'court_001',
      date: '2024-01-15',
      timeSlot: '14:00-16:00',
      memberInfo: {
        name: '张三',
        phone: '13800138000',
      },
    });
    console.log('预订结果:', booking);
  } catch (error) {
    console.error('操作失败:', error.message);
  }
}

bookCourt();

短信验证

// 发送短信验证码
async function sendVerificationCode() {
  try {
    const result = await client.sms.sendSmsCode('13800138000');
    if (result.success) {
      console.log('短信发送成功');
    }
  } catch (error) {
    console.error('短信发送失败:', error.message);
  }
}

用户认证

// 微信小程序登录
async function loginUser() {
  try {
    const loginResult = await client.api.login('wx_code_from_miniprogram');
    console.log('登录成功:', loginResult);
  } catch (error) {
    console.error('登录失败:', error.message);
  }
}

📖 API 文档

DQMClient 主类

构造函数

const client = new DQMClient({
  appId: string,           // 必需: 微信小程序 App ID
  appSecret: string,       // 必需: 微信小程序 App Secret
  paymentKey?: string,     // 可选: 微信支付密钥
  baseUrl?: string,        // 可选: API 基础URL
  timeout?: number,        // 可选: 请求超时时间(毫秒)，默认10000
  headers?: object         // 可选: 自定义请求头
});

服务实例访问

client.api; // ApiService 实例 - 基础API服务
client.court; // CourtService 实例 - 场馆服务
client.sms; // SmsService 实例 - 短信服务

ApiService 基础服务

提供认证、用户管理和基础API功能。

// 微信小程序登录
await api.login(code: string)

// 添加会员信息
await api.addMember(memberInfo: object)

// 发送短信验证码
await api.sendSmsCode(phone: string)

// 验证短信验证码
await api.verifySmsCode(phone: string, code: string)

// 获取场馆列表
await api.getCourtList(date?: string)

// 创建订单
await api.createOrder(orderInfo: object)

CourtService 场馆服务

继承自 ApiService，提供场馆相关的高级功能。

// 获取场馆信息（带业务逻辑处理）
await court.getCourt(date?: string)

// 预订场馆（完整预订流程）
await court.bookCourt({
  courtId: string,
  date: string,
  timeSlot: string,
  memberInfo: {
    name: string,
    phone: string,
    idCard?: string
  }
})

SmsService 短信服务

继承自 ApiService，专门处理短信相关功能。

// 发送短信验证码
await sms.sendSmsCode(phone: string)

🛠️ 工具函数

const { utils } = require('dqm-api-client');

// 生成微信支付签名
const sign = utils.generateWxPaySign(params, key);

// OpenID 编码/解码
const encoded = utils.encodeOpenId(openId);
const decoded = utils.decodeOpenId(encodedOpenId);

// 查找可用时段
const available = utils.findAvailableSlots(slots);

// 生成时间戳和随机数
const timestamp = utils.generateTimestamp();
const nonce = utils.generateNonce();

// HTTP 请求工具
await utils.request(options);
await utils.get(url, headers, options);
await utils.post(url, data, headers, options);
// ... 其他 HTTP 方法

🏗️ 高级用法

直接使用服务类

const { ApiService, CourtService, SmsService } = require('dqm-api-client');

const config = {
  appId: 'your_app_id',
  appSecret: 'your_app_secret',
};

const apiService = new ApiService(config);
const courtService = new CourtService(config);
const smsService = new SmsService(config);

配置更新

// 更新客户端配置
client.updateConfig({
  timeout: 15000,
  headers: {
    'Custom-Header': 'value',
  },
});

错误处理

try {
  const result = await client.court.getCourt();
} catch (error) {
  if (error.message.includes('HTTP')) {
    console.error('网络错误:', error.message);
  } else {
    console.error('业务错误:', error.message);
  }
}

🧪 运行测试

npm test

📝 TypeScript 支持

本包包含完整的 TypeScript 类型定义，支持自动补全和类型检查。

import {
  DQMClient,
  ApiConfig,
  CourtInfo,
  BookingRequest,
} from 'dqm-api-client';

const config: ApiConfig = {
  appId: 'your_app_id',
  appSecret: 'your_app_secret',
};

const client = new DQMClient(config);

const courts: CourtInfo[] = await client.court.getCourt();

🏗️ 项目结构

dqm-api-client/
├── lib/
│   ├── services/
│   │   ├── ApiService.js      # 基础API服务
│   │   ├── CourtService.js    # 场馆服务
│   │   └── SmsService.js      # 短信服务
│   └── utils/
│       ├── common.js          # 通用工具函数
│       └── request.js         # HTTP请求工具
├── test/
│   └── test.js               # 测试文件
├── index.js                  # 主入口文件
├── index.d.ts               # TypeScript 类型定义
└── package.json             # 包配置文件

🤝 贡献指南

1. Fork 这个项目
2. 创建你的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交你的修改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🆘 支持

如果您遇到任何问题或有功能请求，请在 GitHub Issues 中提出。

📚 更新日志

v1.0.0

• 🎉 初始版本发布
• ✨ 基础API服务功能
• ✨ 场馆预订功能
• ✨ 短信验证功能
• ✨ 完整的 TypeScript 支持
• 📖 详细的文档和示例