feat(hardware): 新增设备电量消息记录查询工具 (REQ-20260921-0007)

xiaoqu-agent-service/doc/agent-mcp-tools-reference.md

@@ -797,6 +797,28 @@
 
 ---
 
+## 32. hardware.electricity.message.list.query
+
+分页查询设备电量/信号/温度/充电循环次数/电压/电流消息记录，对应旧系统
+`POST /batteryAnalyse/batteryAnalyseList`（BatteryAnalyseController）的数据查询语义，并修掉其坑。
+
+- 分类：hardware ｜ 类型：读
+- 数据来源：本地 ES 集群 `electricitymessage_yyyyMM` 月索引（索引名 = electricitymessage_ + startTime 月份 yyyyMM）；
+  **只走 esLocal 客户端**（索引只在本地集群，不走 esCloud）；**无任何权限校验**（对齐老系统，用户拍板 2026-09-21）。
+- 入参：`snCode`（必填非空）、`startTime`/`endTime`（必填，严格 `yyyy-MM-dd HH:mm:ss`，
+  **服务端强校验两者同一天，跨天直接拒绝**——老系统跨月范围静默丢数据、只按开始时间月份选索引；
+  startTime 不得晚于 endTime）、`messageType`（可选 0-5，0 电量/1 信号/2 温度/3 充电循环次数/4 电压/5 电流，
+  **不传=查全部类型**——老系统默认值 0 把"不传"歧义成"电量"，此处为刻意的显式设计差异）、
+  `page`/`rows`（默认 1/500，rows 上限 1000，超出截断为 1000 并返回 notice）。
+- 查询构造：`snCode` 用 **match_phrase**（老系统 matchQuery 经 standard analyzer 会把 AB-123 切成 ab/123 误配）；
+  messageType 传了才加 term；createTime 闭区间 range；createTime ASC 排序；from+size 分页（老系统 scroll 拉全量后内存抽样，本工具全量分页、不做抽样）。
+- 深分页防御：from+size 超 ES `max_result_window`(10000) 时截断为窗口内可用范围并在 notice 说明（整页越过窗口截断为最后可用窗口；部分越界截断本页条数）。
+- 返回 `snCode/index/total/page/rows/records`；record 含 `createTime`（yyyy-MM-dd HH:mm:ss，
+  epoch 毫秒形态归一为 Asia/Shanghai 文本）、`messageType`、`messageTypeText`（服务端映射）、`value`（原始 Integer，不加单位标注）。
+- 与老系统的差异（详见 `electricity-message-mcp-tool-design.md`）：ES 异常不静默为返回空，抛错 fail fast。
+
+---
+
 ## 附录：在线查看工具清单
 
 ```bash