## 场景二：POI 详细搜索

使用 `tmap-lbs search` 命令进行 POI 搜索，支持关键词搜索、城市限定、周边搜索等。

**前置条件：** 需要配置腾讯位置服务 API Key。

### 检查 API Key

- 如果用户之前未提供过 Key，**先提示用户配置腾讯地图 API Key**，等待用户回复后再继续
- 如果用户已提供 Key，直接使用

**请求 Key 的回复模板：**

```
🔑 POI 搜索需要使用腾讯地图 API

（如果还没有 Key，可以在 https://lbs.qq.com 注册并创建应用获取）
```

### 命令格式

```bash
tmap-lbs search --keywords <关键词> [options]
```

### 参数说明

| 参数          | 说明                         | 必填 | 示例                  |
| ------------- | ---------------------------- | ---- | --------------------- |
| `--keywords`  | 搜索关键词                   | 是   | `肯德基`              |
| `--city`      | 城市名称（城市搜索时必填）   | 否   | `北京`                |
| `--location`  | 中心点坐标 "经度,纬度"       | 否   | `116.397428,39.90923` |
| `--radius`    | 搜索半径(米)，周边搜索时必填 | 否   | `1000`                |
| `--types`     | POI 分类筛选                 | 否   | `餐饮`                |
| `--page`      | 页码，从 1 开始              | 否   | `1`                   |
| `--page-size` | 每页数量（最大 20）          | 否   | `10`                  |
| `--raw`       | 输出包含原始 API 响应的 JSON | 否   | -                     |

**注意：** `--location` 使用 `经度,纬度` 格式（经度在前，纬度在后），工具内部会自动转换为腾讯地图所需的 `纬度,经度` 格式。

### 使用示例

**城市关键词搜索：**

```bash
tmap-lbs search --keywords 肯德基 --city 北京
```

**周边搜索（指定坐标和半径）：**

```bash
tmap-lbs search --keywords 酒店 --location 116.397428,39.90923 --radius 1000
```

**带分类筛选的搜索：**

```bash
tmap-lbs search --keywords 餐厅 --city 上海 --types 餐饮 --page-size 20
```

**输出完整 JSON 数据：**

```bash
tmap-lbs search --keywords 肯德基 --city 北京 --raw
```

### 返回数据格式

默认输出格式化的文本列表。使用 `--raw` 输出 JSON：

```json
{
  "status": "1",
  "count": 100,
  "pois": [
    {
      "name": "肯德基(王府井店)",
      "address": "北京市东城区王府井大街...",
      "type": "餐饮:快餐",
      "tel": "010-12345678",
      "location": "116.41,39.914",
      "distance": 500,
      "id": "..."
    }
  ]
}
```

### 返回字段说明

| 字段       | 说明                               |
| ---------- | ---------------------------------- |
| `status`   | 状态码，`"1"` 表示成功             |
| `count`    | 结果总数                           |
| `pois`     | POI 结果数组                       |
| `name`     | 地点名称                           |
| `address`  | 地址                               |
| `type`     | 分类                               |
| `tel`      | 电话                               |
| `location` | 坐标 `"经度,纬度"` 格式            |
| `distance` | 距中心点距离（周边搜索时），单位米 |

### 错误处理

- 如果 Key 未设置，会提示配置命令
- 常见错误：Key 无效、配额不足、参数格式错误