Merge remote-tracking branch 'origin/main' into feat/REQ-20260922-0004-paper-percapita

# Conflicts:
#	xiaoqu-agent-service/README.md
#	xiaoqu-agent-service/doc/agent-mcp-tools-reference.md

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

@@ -782,7 +782,44 @@
 
 ---
 
-## 31. district.paper.percapita.query
+## 31. battery.fault.list.query
+
+分页查询电池故障记录，对应旧系统 `POST /batteryFault/batteryFaultLogList`。
+
+- 分类：hardware ｜ 类型：读
+- 数据来源：m0 `battery_fault_log`，固定 `soft_delete=0`。
+- 入参：`districtId/propertyId/agentId`（正整数）、`snCode`（模糊匹配）、`deviceType`（0 厕纸机/出纸机、1 擦手纸机）、`faultType`（0 温度、1 电压、2 电流、3 充电次数）、`faultState`（0 未恢复、1 已恢复）、`faultDateFrom/faultDateTo`（yyyy-MM-dd，结束日期含当天）、`page/rows`。
+- 分页默认 1/20、上限 100，固定按 `fault_start_time DESC, id DESC` 稳定排序。
+- 行级权限与 `hardware.list.query` 一致：总部查看全部；代理查看自己、直属下级、代管代理及代管物业；销售非负责人限自己创建及授权范围内物业。服务身份仍由 MCP scope 控制。
+- 返回 `id/snCode/deviceType/deviceTypeText/faultType/faultTypeText/faultState/faultStateText/peakValue/standardValue/faultStartTime/faultAddTime/faultRecoveryTime/installPosition/agentId/agentName/propertyId/propertyName/districtId/districtName`。时间按 Asia/Shanghai 输出；峰值和标准值保留数据库原始整数，不推断单位。
+
+详细设计见 `battery-fault-mcp-tool-design.md`。
+
+---
+
+## 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。
+
+---
+
+## 33. district.paper.percapita.query
 
 查询站点人均用纸统计，覆盖老 `StatisticsReportController` 的五个接口。
 
@@ -805,7 +842,7 @@
 
 ---
 
-## 32. district.paper.device_average.query
+## 34. district.paper.device_average.query
 
 查询站点设备日均用纸统计，覆盖老 `StatisticsReportController` 的五个硬件统计接口。
 
@@ -847,6 +884,8 @@
 
 ---
 
+---
+
 ## 附录：在线查看工具清单
 
 ```bash