# FWH Pro 上游直查 API（`data_fwh_*`）

`data_fwh_*` 直接调用 FranklinWH Pro 的上游 API，返回原始数据，跳过本地 Service 层的聚合与格式化。**全部只读**。

**何时用**：`service_*` 无法满足时，例如需要事件/告警日志、MQTT 日志、故障录波、升级记录明细、告警快照等 service 层未封装的原始数据。

**通用参数约定**：
- `sn`：站点 SN。
- 日期：`yyyy-MM-dd`；时间范围：`start_time` / `end_time` 为 `yyyy-MM-dd HH:mm:ss`。
- `country`：国家 ID，0-全部（默认）、2-美国、3-澳大利亚。
- `page` / `size`：分页，page 从 1 开始，size 默认 20。
- ⚠️ 大时间范围的日志类查询（事件/告警、MQTT）可能较慢，尽量收窄时间窗。

## 站点信息

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_fwh_query_site_list` | `sn`(搜索,可空)、`page`、`size` | 站点列表（支持 SN 搜索） |
| `data_fwh_query_site_base_info_list` | `sn`(多个逗号分隔,可空)、`page`、`size` | 站点基本信息列表 |
| `data_fwh_query_site_mode_info` | `sn` | 站点工作模式信息 |
| `data_fwh_query_site_power_flow` | `sn`、`date` | 指定日期功率流数据 |

## 告警

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_fwh_query_site_alarm_list` | `sn` | 站点当前告警列表 |
| `data_fwh_query_alarm_statistics` | `country`、`page` | 实时告警统计数据 |
| `data_fwh_query_alarm_statistics_from_code` | `alarm_code`(必填)、`country`、`page` | 按告警码查触发站点列表 |
| `data_fwh_query_alarm_snapshot` | `sn`、`date` | 站点告警快照信息 |
| `data_fwh_query_shutdown_list` | `date`(必填)、`country` | Shutdown 站点列表 |

## 日志

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_fwh_query_event_alarm_list` | `sn`、`start_time`、`end_time`、`type`(all/event/alarm) | 时间范围内事件/告警日志 |
| `data_fwh_query_mqtt_log_list` | `sn`、`cmd_type`(如 0/101/201)、`start_time`、`end_time` | 时间范围内 MQTT 日志 |
| `data_fwh_query_ems_log_record` | `sn` | EMS 日志召唤记录 |

## 故障录波（Fault Record）

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_fwh_query_fault_record_list` | `sn`、`start_time`、`end_time` | 故障录波日志列表 |
| `data_fwh_query_fault_record_sub_list` | `fault_id` | 故障录波子记录 |
| `data_fwh_query_fault_record_callable_list` | `sn`、`dev_type`(0-aPower/1-aGate/2-MPPT/3-aHub，默认1) | 设备可召唤的故障录波数据列表 |
| `data_fwh_query_fault_record_call_record_list` | 无 | 故障录波召唤记录 |

典型流程：`callable_list` 看可召唤项 → `list` 查已生成录波 → `sub_list` 展开某条记录的子项；`call_record_list` 查召唤动作历史。

## 升级记录

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_fwh_query_system_update_log` | `sn` | 系统升级记录 |
| `data_fwh_query_system_update_log_detail` | `order_id` | 系统升级记录详情（升级单） |
| `data_fwh_query_ahub_update_log` | `sn` | aHub 升级记录 |

流程：`system_update_log` 拿到升级单 → 用其 `order_id` 调 `_detail` 看明细。

## TOU 模板（上游）

| 工具 | 参数 | 说明 |
|------|------|------|
| `data_fwh_query_tou_template_list` | `search`、`page`、`size` | 上游 TOU 模板列表 |
| `data_fwh_query_tou_template_detail` | `id` | 上游 TOU 模板详情 |

> 平台本地的 TOU 模板请优先用 `service_tou_template_list` / `service_tou_template_detail`（见主 SKILL.md 第 8 节）。