# homestay_cloud

**Repository Path**: WhatIsTheMatrix/homestay_cloud

## Basic Information

- **Project Name**: homestay_cloud
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-13
- **Last Updated**: 2025-11-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 微信云托管后端服务 - 手机号实时登录功能

## 功能说明
该服务提供了手机号实时登录功能，前端可以通过调用微信小程序的 `getRealtimePhoneNumber` API 获取动态令牌 `code`，然后将 `code` 发送到后端的 API 接口，后端会调用微信 API 换取手机号并返回给前端。

## 前端使用步骤

### 步骤一：在小程序中添加按钮
在需要获取手机号的页面中添加以下代码：

```wxml
<button
  open-type="getRealtimePhoneNumber"
  bindgetrealtimephonenumber="handleGetPhoneNumber"
>获取手机号</button>
```

### 步骤二：处理按钮点击事件
在对应页面的 JavaScript 文件中添加以下代码。您可以选择使用微信云托管推荐的 `callContainer` API，或传统的 HTTP 请求：

##### 方式一：使用微信云托管 callContainer API（推荐）
使用该 API 无需填写具体的服务地址，直接调用云托管服务：

```javascript
// 处理手机号实时登录事件
handleGetPhoneNumber(e) {
  // 获取动态令牌 code
  const code = e.detail.code;
  if (!code) {
    console.error('获取手机号失败：', e.detail.errmsg);
    return;
  }

  // 使用 callContainer 调用云托管服务
  wx.cloud.callContainer({
    path: '/api/getPhoneNumber', // 后端 API 路径
    method: 'POST',
    header: {
      'content-type': 'application/json',
      'X-WX-SERVICE': 'wxcloudrun-demo' // 云托管服务名，需替换为实际服务名
    },
    data: {
      code: code
    },
    success(res) {
      if (res.statusCode === 200 && res.data.phoneInfo) {
        // 成功获取手机号
        const phoneInfo = res.data.phoneInfo;
        console.log('手机号信息：', phoneInfo);
        // 在这里处理登录逻辑
      } else {
        console.error('换取手机号失败：', res.data.errmsg || '服务器内部错误');
      }
    },
    fail(err) {
      console.error('请求后端 API 失败：', err);
    }
  });
}
```

## API 接口说明

### 接口地址
`POST /api/getPhoneNumber`

### 请求参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| code | string | 动态令牌，由前端调用 `getRealtimePhoneNumber` API 获取 |

### 返回结果

#### 成功返回示例
```json
{
  "phoneInfo": {
    "phoneNumber": "138xxxx1234",
    "purePhoneNumber": "138xxxx1234",
    "countryCode": "86",
    "watermark": {
      "timestamp": 1600000000,
      "appid": "wx1234567890"
    }
  }
}
```

#### 失败返回示例
```json
{
  "error": "换取手机号失败",
  "errmsg": "invalid code"
}
```

### 返回字段说明
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| phoneInfo | object | 手机号信息对象 |
| phoneInfo.phoneNumber | string | 用户绑定的手机号（国外手机号会有区号） |
| phoneInfo.purePhoneNumber | string | 用户绑定的手机号（去除区号） |
| phoneInfo.countryCode | string | 国家区号 |
| phoneInfo.watermark | object | 水印信息 |
| phoneInfo.watermark.timestamp | number | 时间戳 |
| phoneInfo.watermark.appid | string | 小程序 AppID |

## 注意事项

1. **AppID 和 AppSecret 配置**
   - 后端需要配置微信小程序的 AppID 和 AppSecret 才能调用微信 API
   - 配置文件位置：`config.js`
   - 建议将 AppID 和 AppSecret 存储在环境变量中，提高安全性

2. **code 有效期**
   - 前端获取到的 code 有效期为 5 分钟
   - 每个 code 只能使用一次

3. **权限要求**
   - 该功能需要小程序已经完成认证（非个人主体）
   - 小程序需要开通手机号实时验证组件权限

4. **收费说明**
   - 该功能自 2023 年 8 月 28 日起需要付费使用，标准单价为每次 0.04 元
   - 每个小程序账号有 1000 次体验额度
   - 政府、非营利组织等部分类型的小程序可以免费使用

5. **错误处理**
   - 前端需要处理用户拒绝授权的情况
   - 后端会对各种错误情况返回相应的错误信息
   - 建议前端根据错误信息给用户提供友好的提示

## 服务器启动

1. 安装依赖
   ```bash
   npm install
   ```

2. 启动服务器
   ```bash
   npm start
   ```

3. 服务器将在 http://localhost:80 运行

## 房间号检查接口

### 接口地址
`POST /api/checkRoomNumber`

### 功能说明
该接口用于检查房间号是否存在，并根据房间号在不同座号中的存在情况返回相应的结果。当房间号在A、B座都存在时，会返回标志需要前端指定座号。

### 请求参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| roomNo | string | 房间号，例如："201"、"801"等 |

### 返回结果

#### 房间不存在时返回示例
```json
{
  "status": "error",
  "message": "房间不存在",
  "needSelectBlock": false
}
```

#### 房间只在一个座存在时返回示例
```json
{
  "status": "ok",
  "message": "房间存在",
  "needSelectBlock": false,
  "roomInfo": {
    "room_no": "202",
    "building_block": "A",
    "floor": 20,
    "path_id": 5
  }
}
```

#### 房间在多个座存在时返回示例
```json
{
  "status": "multiple_blocks",
  "message": "该房间号在多个座中存在，请指定座号",
  "needSelectBlock": true,
  "availableBlocks": ["A", "B"]
}
```

### 返回字段说明
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| status | string | 接口返回状态（error/ok/multiple_blocks） |
| message | string | 返回消息描述 |
| needSelectBlock | boolean | 是否需要用户选择座号 |
| roomInfo | object | 房间信息对象（当needSelectBlock为false时返回） |
| availableBlocks | array | 可用座号数组（当needSelectBlock为true时返回） |

## 房间号检查接口前端使用方法

### 方式一：使用微信云托管 callContainer API（推荐）

```javascript
// 检查房间号
checkRoomNumber(roomNo, buildingBlock = null) {
  if (!roomNo) {
    wx.showToast({
      title: '请输入房间号',
      icon: 'none'
    });
    return;
  }

  // 准备请求数据
  const requestData = {
    roomNo: roomNo
  };
  
  // 如果提供了座号，则添加到请求数据中
  if (buildingBlock) {
    requestData.buildingBlock = buildingBlock;
  }

  // 使用 callContainer 调用云托管服务
  wx.cloud.callContainer({
    path: '/api/checkRoomNumber', // 后端 API 路径
    method: 'POST',
    header: {
      'content-type': 'application/json',
      'X-WX-SERVICE': 'wxcloudrun-demo' // 云托管服务名，需替换为实际服务名
    },
    data: requestData,
    success(res) {
      if (res.statusCode === 200) {
        const result = res.data;
        
        if (result.status === 'error') {
          // 房间不存在
          wx.showToast({
            title: result.message,
            icon: 'none'
          });
        } else if (result.status === 'ok') {
          // 房间只在一个座存在，直接使用
          console.log('房间信息：', result.roomInfo);
          wx.showToast({
            title: `找到房间：${result.roomInfo.building_block}座${result.roomInfo.floor}楼`,
            icon: 'success'
          });
          // 在这里处理房间信息
        } else if (result.status === 'multiple_blocks') {
          // 房间在多个座存在，需要用户选择
          console.log('可用座号：', result.availableBlocks);
          // 显示选择座号的弹窗或页面
          wx.showModal({
            title: '请选择座号',
            content: `该房间号在以下座中存在：${result.availableBlocks.join('、')}`,
            showCancel: false,
            success(res) {
              // 跳转到选择座号的页面或显示选择器
            }
          });
        }
      } else {
        console.error('请求失败：', res.data.error || '服务器内部错误');
        wx.showToast({
          title: res.data.error || '请求失败',
          icon: 'none'
        });
      }
    },
    fail(err) {
      console.error('请求后端 API 失败：', err);
      wx.showToast({
        title: '网络请求失败',
        icon: 'none'
      });
    }
  });
}
```

### 方式二：使用传统 HTTP 请求

```javascript
// 检查房间号（传统HTTP请求）
checkRoomNumberHttp(roomNo, buildingBlock = null) {
  if (!roomNo) {
    wx.showToast({
      title: '请输入房间号',
      icon: 'none'
    });
    return;
  }

  // 准备请求数据
  const requestData = {
    roomNo: roomNo
  };
  
  // 如果提供了座号，则添加到请求数据中
  if (buildingBlock) {
    requestData.buildingBlock = buildingBlock;
  }

  wx.request({
    url: 'https://your-service-url/api/checkRoomNumber', // 替换为实际服务地址
    method: 'POST',
    header: {
      'content-type': 'application/json'
    },
    data: requestData,
    success(res) {
      if (res.statusCode === 200) {
        const result = res.data;
        // 处理逻辑与方式一相同
        // ...
      } else {
        console.error('请求失败：', res.data.error || '服务器内部错误');
        wx.showToast({
          title: res.data.error || '请求失败',
          icon: 'none'
        });
      }
    },
    fail(err) {
      console.error('请求后端 API 失败：', err);
      wx.showToast({
        title: '网络请求失败',
        icon: 'none'
      });
    }
  });
}
```

## 开发建议

1. **安全性**
   - 不要在前端代码中直接暴露 AppID 和 AppSecret
   - 建议在后端添加身份验证机制，确保只有合法的请求才能调用 API

2. **性能优化**
   - 可以将获取到的 access_token 进行缓存，避免频繁调用微信 API
   - 建议对 API 请求进行限流，防止恶意请求

3. **日志记录**
   - 建议在后端添加日志记录功能，方便排查问题

4. **版本控制**
   - 建议对 API 接口进行版本控制，方便后续升级和维护