aeon_business_back/document/skills/query-device-data/SKILL.md

---
name: "query-device-data"
description: "Queries device raw data from Aurora by device IDs and time range via /common/queryDeviceData API. Invoke when user needs to retrieve device telemetry/historical data with device ID list and time range."
---

# Query Device Data

通过设备ID列表和时间范围查询 Aurora 中的设备原始数据。

## 触发条件

当用户需要按设备ID列表和时间范围查询设备原始数据时调用此 skill。

用户可能用自然语言表达，例如：
- "查询设备A和设备B昨天的数据"
- "查一下FT0001最近3天的数据"
- "看看FFFF0001今天的数据"
- "获取设备A和C在2024年1月1日到1月5日的数据"

## API 信息

| 项目 | 内容 |
|------|------|
| 接口路径 | `POST /common/queryDeviceData` |
| 认证方式 | Header 传入 `Apikey` |
| Referer 校验 | Header 需传入 `Referer`（值为服务端域名），否则被过滤器拦截返回 403 |
| 时间范围限制 | 最多7天 |
| 数据源 | Aurora 数据库 `rawData_yyyy_MM_dd` 分表 |

## 自然语言转 API 参数

### 1. 时间范围解析

用户可能会用各种方式描述时间，需要根据当前时间（`Today's date`）计算出对应的毫秒时间戳。

| 自然语言表达 | 转换为 API 参数 |
|:-------------|:----------------|
| "最近 X 天 / 近 X 天 / 过去 X 天" | `startTime` = 当前日期往前推 X 天 的 00:00:00（时区 Asia/Tokyo），`endTime` = 当前时间的 23:59:59 |
| "昨天" | `startTime` = 昨天 00:00:00，`endTime` = 昨天 23:59:59 |
| "今天" | `startTime` = 今天 00:00:00，`endTime` = 当前时间 |
| "今天 x 点到 y 点" | `startTime` = 今天 x:00:00，`endTime` = 今天 y:59:59 |
| "2024年1月1日到2024年1月5日" | `startTime` = 2024-01-01 00:00:00，`endTime` = 2024-01-05 23:59:59 |
| "X月Y日到X月Y日" | 根据当前年份推算，`startTime` = X月Y日 00:00:00，`endTime` = X月Y日 23:59:59 |
| "上个月" | `startTime` = 上个月1号 00:00:00，`endTime` = 上个月最后一天 23:59:59 |
| "最近X小时" | `startTime` = 当前时间往前推X小时，`endTime` = 当前时间 |

**注意**：
- 所有时间戳需要转换为 **毫秒**（13位数字）
- 时区统一使用 `Asia/Tokyo`
- `startTime` 和 `endTime` 之间的跨度不能超过 **7 天**

### 2. 设备ID解析

请求参数要求传入 `deviceIds`（设备ID列表），用户可能会用不同方式描述设备：

| 自然语言表达 | 转换方式 |
|:-------------|:---------|
| "设备A"、"设备B" | 如果用户提及设备名/编号，先根据上下文尝试确定是否为已知设备ID |
| "FFFF0001"、"FT0001" | 直接作为设备ID使用 |
| "所有设备"、"全部设备" | **不支持**，需要用户提供具体的设备ID列表 |
| "传感器A"、"温度计1" | 如果已知设备ID和名称的映射关系，转换为对应设备ID |

如果用户只说了设备名称但没有提供具体ID，需要向用户确认具体的设备ID。

### 3. 请求头解析

- `Apikey` 由用户提供，**不设置默认值**
- 如果用户没有提供 Apikey，需要向用户询问具体的 Apikey 值

## 自然语言处理流程

当收到自然语言请求时，按以下步骤执行：

```
1. 提取时间描述 → 计算 startTime/endTime（毫秒时间戳）
2. 提取设备描述 → 构建设备ID列表 deviceIds
3. 检查参数完整性：如有缺漏，向用户询问补齐
4. 检查 Apikey：如用户未提供，向用户询问
5. 检查 Referer：如用户未提供，向用户询问
6. 构建请求体 JSON 并设置请求头（Apikey、Referer）
7. 调用 POST /common/queryDeviceData
8. 返回结果给用户
```

### 参数不完整时的处理

**所有参数不设默认值**，缺失时需向用户询问。

| 缺失参数 | 询问示例 |
|:---------|:---------|
| 未提供 `deviceIds` | "请问要查询哪些设备的ID？请提供设备ID列表。" |
| 未提供时间范围 | "请问要查询什么时间范围的数据？例如：最近3天、昨天、或指定日期区间。" |
| 仅提供开始/结束时间之一 | 补齐另一个时间点，例如：用户只说"从2024年1月1日开始"，则询问"请问结束时间是什么时候？" |
| 未提供 `Apikey` | "请提供用于认证的 Apikey。" |
| 未提供 `Referer` | "请提供请求来源域名（Referer），例如服务的域名地址。" |

### 处理后响应模板

调用接口后将结果以自然语言呈现给用户：
- 查询到数据时：告知用户共查询到多少条数据，以及设备的主要信息摘要
- 未查询到数据时：告知用户在指定时间范围内没有找到对应设备的数据
- 接口报错时：将错误信息展示给用户

## 请求参数

### Header

| 参数名 | 必填 | 说明 |
|--------|:----:|------|
| `Apikey` | 是 | API key，用于认证，由用户提供 |
| `Referer` | 是 | 请求来源域名，需与服务端配置的 `accessControlAllowOrigin` 匹配（例如 `https://bilplartform-stg.ifmservice.jp`），否则返回 403 |

### Request Body (JSON)

| 字段 | 类型 | 必填 | 说明 |
|------|:----:|:----:|------|
| `deviceIds` | `List<String>` | 是 | 设备ID列表，由用户提供 |
| `startTime` | `Long` | 是 | 开始时间戳（毫秒，也支持秒级自动转换），由用户提供或根据用户描述计算 |
| `endTime` | `Long` | 是 | 结束时间戳（毫秒，也支持秒级自动转换），与 startTime 跨度不能超过7天，由用户提供或根据用户描述计算 |

## 返回数据

返回 `SimpleDataResponse<List<DeviceDataVO>>`，其中 `data` 为设备数据列表：

| 字段 | 类型 | 说明 |
|------|:----:|------|
| `deviceId` | String | 设备ID |
| `deviceName` | String | 设备名称 |
| `rawData` | String | 原始数据 JSON |
| `dataValue` | String | 从 rawData 解析出的数值，逗号拼接 |
| `receiveTs` | Long | 接收时间戳（毫秒） |
| `status` | String | 状态 |
| `alertLevel` | String | 告警级别 |
| `alertContent` | String | 告警内容 |
| `buildingInfo` | String | 楼宇信息 |
| `floorInfo` | String | 楼层信息 |
| `spaceInfo` | String | 空间信息 |

## 调用示例

### 请求

```
POST /common/queryDeviceData
Apikey: <用户提供的Apikey>
Referer: <服务端域名，例如 https://bilplartform-stg.ifmservice.jp>
```

```json
{
  "deviceIds": ["FFFF0001", "FFFF0002"],
  "startTime": 1709870240425,
  "endTime": 1709889240425
}
```

### 成功响应

```json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "deviceId": "FFFF0001",
      "deviceName": "温度传感器",
      "rawData": "{\"temp\":25.5}",
      "dataValue": "25.5",
      "receiveTs": 1709870240425,
      "status": "UP",
      "alertLevel": null,
      "alertContent": null,
      "buildingInfo": "东京建物日本桥ビル",
      "floorInfo": "3F",
      "spaceInfo": "会議室A"
    }
  ]
}
```

### 错误响应示例

```json
{
  "code": 20001,
  "msg": "[deviceIds] is required",
  "data": null
}
```

## 自然语言用例映射

### 用例1：查询某设备最近N天的数据

> 用户说：**"查一下设备FFFF0001最近3天的数据"**

```
步骤：
1. 假设 Today's date = 2026-06-01
2. 计算 startTime = 2026-05-30 00:00:00 JST → 毫秒时间戳
3. 计算 endTime = 2026-06-01 23:59:59 JST → 毫秒时间戳
4. deviceIds = ["FFFF0001"]
5. 调用接口
```

### 用例2：查询多个设备特定日期的数据

> 用户说：**"查询FFFF0001和FT0002在2024年1月1日的数据"**

```
步骤：
1. 计算 startTime = 2024-01-01 00:00:00 JST → 毫秒时间戳
2. 计算 endTime = 2024-01-01 23:59:59 JST → 毫秒时间戳
3. deviceIds = ["FFFF0001", "FT0002"]
4. 调用接口
```

### 用例3：查询设备今天的数据

> 用户说：**"看看FT0001今天的监测数据"**

```
步骤：
1. 假设 Today's date = 2026-06-01
2. 计算 startTime = 2026-06-01 00:00:00 JST → 毫秒时间戳
3. 计算 endTime = 当前时间 JST → 毫秒时间戳
4. deviceIds = ["FT0001"]
5. 调用接口
```

## 注意事项

1. `startTime` 和 `endTime` 支持毫秒和秒级时间戳（< 10000000000L 时自动按秒处理）
2. 时间跨度不能超过 **7 天**，否则接口会返回错误
3. 跨天查询时自动查询多张 `rawData_yyyy_MM_dd` 分表并合并结果
4. 使用 Apikey 认证，与 `/common/queryDeviceInfo` 相同的方式
5. 所有时间计算都基于 `Asia/Tokyo` 时区
6. Apikey 和所有请求参数均**不设置默认值**，缺失时需向用户询问补齐
7. **Referer 头必传**：请求必须携带 `Referer` 头，否则被 `CrosXssFilter` 过滤器拦截返回 403。Referer 值需与服务端配置的 `accessControlAllowOrigin` 匹配（通常为服务域名本身，如 `https://bilplartform-stg.ifmservice.jp`）