# 腾讯地图 API 配置指南

## 问题

```
❌ 逆地理编码API返回失败: {status: 199, message: "此key未开启WebserviceAPI功能"}
```

## 原因

当前使用的 API Key `Q7CBZ-CC2C5-5O6IA-IU5VM-KJGAF-IKBRO` 没有开启 **WebService API** 权限。

## 解决步骤

### 方案1：开启现有Key的WebService权限（推荐）

1. **登录腾讯地图开放平台**
   - 网址：https://lbs.qq.com/console/mykey.html
   - 使用你的腾讯账号登录

2. **找到你的Key**
   - 在"我的应用"中找到 Key：`Q7CBZ-CC2C5-5O6IA-IU5VM-KJGAF-IKBRO`

3. **编辑Key配置**
   - 点击"设置"或"编辑"按钮
   - 找到"可用服务"或"服务类型"

4. **勾选WebService API**
   - ✅ 勾选 **WebService API**
   - ✅ 特别确保勾选 **逆地理编码（地址解析）**

5. **保存配置**
   - 点击保存
   - 等待1-2分钟生效

### 方案2：创建新的Key（备选）

如果无法修改现有Key，可以创建一个新的：

1. **创建新应用**
   - 进入：https://lbs.qq.com/console/mykey.html
   - 点击"创建应用"

2. **填写应用信息**
   - 应用名称：习正陪伴小程序
   - 应用类型：微信小程序

3. **添加Key**
   - 点击"添加Key"
   - Key名称：习正陪伴-地图服务
   - 勾选服务类型：
     - ✅ WebService API
     - ✅ 逆地理编码
     - ✅ 地点搜索（可选）

4. **配置域名白名单**
   - 在"域名白名单"中添加：`*.qq.com`
   - 或者留空（不限制）

5. **获取新Key**
   - 复制生成的Key
   - 替换到代码中

### 方案3：使用微信小程序的位置API（临时方案）

如果暂时无法配置腾讯地图API，可以使用微信小程序自带的位置API：

```javascript
// 使用微信小程序的逆地理编码
wx.chooseLocation({
  success: (res) => {
    console.log('地址:', res.address)
    console.log('详细地址:', res.name)
    this.address = res.address + res.name
  }
})
```

但这个方案需要用户手动选择位置，体验不如自动获取。

## 配置新Key到代码

如果创建了新Key，需要更新以下文件：

### 1. 更新 map.js 配置

```javascript
// peidu/uniapp/src/config/map.js
export const TENCENT_MAP = {
  key: '你的新Key', // 替换这里
  geocoderUrl: 'https://apis.map.qq.com/ws/geocoder/v1/',
  directionUrl: 'https://apis.map.qq.com/ws/direction/v1/',
}
```

### 2. 更新签到页面中的Key

需要更新以下文件中硬编码的Key：

- `peidu/uniapp/src/teacher-package/pages/teacher/checkin.vue`
- `peidu/uniapp/src/teacher-package/pages/teacher/checkout.vue`
- `peidu/uniapp/teacher-package/pages/teacher/checkin.vue`

搜索 `Q7CBZ-CC2C5-5O6IA-IU5VM-KJGAF-IKBRO` 并替换为新Key。

## 验证配置

配置完成后，可以通过以下方式验证：

### 1. 浏览器测试

在浏览器中访问：
```
https://apis.map.qq.com/ws/geocoder/v1/?location=31.230416,121.473701&key=你的Key&get_poi=0
```

**成功响应示例：**
```json
{
  "status": 0,
  "message": "query ok",
  "result": {
    "address": "上海市黄浦区南京东路",
    "address_component": {
      "province": "上海市",
      "city": "上海市",
      "district": "黄浦区",
      "street": "南京东路"
    }
  }
}
```

**失败响应示例：**
```json
{
  "status": 199,
  "message": "此key未开启WebserviceAPI功能"
}
```

### 2. 小程序测试

1. 重新编译小程序
2. 进入签到页面
3. 查看控制台日志
4. 应该看到：`✅ 地址解析成功: 安徽省合肥市蜀山区xxx`

## 常见问题

### Q1: 为什么我的Key无法开启WebService？

**A:** 可能是以下原因：
- Key类型不支持（需要是"微信小程序"类型）
- 账号权限不足
- 需要实名认证

**解决：** 创建一个新的Key，选择正确的应用类型。

### Q2: 开启后还是报错？

**A:** 可能需要等待1-2分钟生效，或者：
- 清除小程序缓存
- 重新编译小程序
- 检查域名白名单配置

### Q3: 有配额限制吗？

**A:** 腾讯地图API有免费配额：
- 个人开发者：10,000次/天
- 企业开发者：100,000次/天

如果超出配额，需要购买套餐或申请提额。

## 微信小程序域名配置

别忘了在微信小程序后台配置域名白名单：

**路径：** 微信公众平台 → 开发 → 开发管理 → 开发设置 → 服务器域名

**添加：**
```
request合法域名：https://apis.map.qq.com
```

## 相关链接

- 腾讯地图开放平台：https://lbs.qq.com/
- 控制台：https://lbs.qq.com/console/mykey.html
- WebService API文档：https://lbs.qq.com/service/webService/webServiceGuide/webServiceGcoder
- 逆地理编码文档：https://lbs.qq.com/service/webService/webServiceGuide/webServiceGcoder

---

**创建时间：** 2026-01-26
**问题：** 此key未开启WebserviceAPI功能
**解决：** 在腾讯地图控制台开启WebService API权限