feat(mcp): 新增设备日均用纸统计工具 (REQ-20260922-0007)

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

@@ -782,6 +782,71 @@
 
 ---
 
+## 31. district.paper.percapita.query
+
+查询站点人均用纸统计，覆盖老 `StatisticsReportController` 的五个接口。
+
+- 分类：district ｜ 类型：读
+- 数据来源：m0 `monthly_statistics` 日汇总表，固定 `soft_delete=0`、指定站点及日期范围；不查 ES。
+- 入参：`districtId`、`startDate`、`endDate`、`groupBy`（gender/floor/floorGender），以及可选
+  `daily`、`deviceType`、`idStrList`。`floorGender+daily=true` 会报参数错误。
+- `idStrList` 每项严格使用 `buildingId_floor_toiletId` 格式；building、floor、toilet 三列分别独立 IN 过滤，
+  保留老系统语义。
+- 口径：`paperLengthMeters=Σpaper_length/100`，`perCapita=paperLengthMeters/Σuse_count`，保留两位小数；
+  useCount=0 时 perCapita 取 paperLengthMeters。
+- 返回固定为扁平 `rows`：每行包含 `date/floor/gender/paperLengthMeters/useCount/perCapita`，
+  未参与的维度为 null；无数据日期或分组不补零。`daily=false` 另返回区间 `totalPerCapita`。
+- gender 文案：0男卫、1女卫、2母婴室、3无障碍、4第三卫、5其他。
+- 行级权限：先用 `applyDistrictRowFilter` 校验站点可见性；不可见统一返回“站点不存在或无权访问”。
+- 日期不得晚于今天，查询天数受 Redis `Dictionary.StatisticsDays` 限制。
+- scope：仅绑定 `service_enabled=0` 的用户委托作用域，不向服务身份作用域开放。
+
+详细设计见 `paper-percapita-statistics-mcp-design.md`。
+
+---
+
+## 32. district.paper.device_average.query
+
+查询站点设备日均用纸统计，覆盖老 `StatisticsReportController` 的五个硬件统计接口。
+
+- 分类：hardware ｜ 类型：读
+- 数据来源：m0 `monthly_statistics`，固定 `soft_delete=0`、指定站点和日期范围，在数据库中完成聚合；不查 ES。
+- 入参：`districtId`、`startDate`、`endDate`、`view`，以及可选的 `deviceType`、`buildingIds`、
+  `floors`、`toiletIds`。位置列表内部使用 IN，三个位置维度之间使用 AND。
+- `view` 固定为：`gender`（卫生间类型）、`daily_gender`（日期×卫生间类型）、`floor`（楼层）、
+  `daily_floor`（日期×楼层）、`floor_gender`（楼层×卫生间类型）。
+- 口径：`paperLengthMeters=SUM(COALESCE(paper_length,0))/100`，
+  `recordCount=COUNT(*)`，`averagePaperMeters=paperLengthMeters/recordCount`，最终按 HALF_UP 保留两位小数。
+  `use_count` 不参与该指标计算。
+- 返回 `summary` 和统一的 `rows`。每行包含
+  `date/floor/genderCode/gender/paperLengthMeters/recordCount/averagePaperMeters`，未参与当前 view 的维度为 null；
+  `daily_*` 不补缺失日期。无数据时 `rows=[]`，summary 平均值为 null，并在 notice 说明。
+- gender 文案：0男卫、1女卫、2母婴室、3无障碍、4第三卫、5其他；null 为未配置，其他整数显示 `未知(code)`。
+- 行级权限：先用 `applyDistrictRowFilter` 校验站点可见性；不可见统一返回 `NOT_FOUND_OR_FORBIDDEN`。
+  tenant_service 仅可通过 `ops-query` 调用，按总部视角查询。
+- 日期不得晚于上海时区当天，查询自然日数受 Redis `Dictionary.StatisticsDays` 限制。
+
+示例响应：
+
+```json
+{
+  "districtId": 12610,
+  "districtName": "望京SOHO",
+  "dateRange": {"startDate": "2026-09-01", "endDate": "2026-09-21", "days": 21},
+  "view": "gender",
+  "unit": "米/设备日统计记录",
+  "summary": {"paperLengthMeters": 250.00, "recordCount": 200, "averagePaperMeters": 1.25},
+  "total": 1,
+  "rows": [
+    {"date": null, "floor": null, "genderCode": 0, "gender": "男卫",
+     "paperLengthMeters": 250.00, "recordCount": 200, "averagePaperMeters": 1.25}
+  ],
+  "notice": "统计分母为 monthly_statistics 记录数 COUNT(*)，不是使用人次 SUM(use_count)"
+}
+```
+
+---
+
 ## 附录：在线查看工具清单
 
 ```bash