dqm-api-client/README.md

A Node.js client library for court booking API services including authentication, SMS verification, and court management

# DQM API Client

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

## 🌟 特性

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

## 📦 安装

```bash
npm install dqm-api-client
```

## 🚀 快速开始

### 基础用法

```javascript
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();
```

### 短信验证

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

### 用户认证

```javascript
// 微信小程序登录
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 主类

#### 构造函数

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

#### 服务实例访问

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

### ApiService 基础服务

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

```javascript
// 微信小程序登录
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，提供场馆相关的高级功能。

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

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

### SmsService 短信服务

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

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

## 🛠️ 工具函数

```javascript
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 方法
```

## 🏗️ 高级用法

### 直接使用服务类

```javascript
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);
```

### 配置更新

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

### 错误处理

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

## 🧪 运行测试

```bash
npm test
```

## 📝 TypeScript 支持

本包包含完整的 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](LICENSE) 文件了解详情。

## 🆘 支持

如果您遇到任何问题或有功能请求，请在 [GitHub Issues](https://github.com/your-username/dqm-api-client/issues) 中提出。

## 📚 更新日志

### v1.0.0

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