人均用纸统计 MCP 工具设计

需求：REQ-20260922-0004

工具：district.paper.percapita.query

1. 覆盖范围

一个 MCP 工具通过 groupBy 与 daily 覆盖老 StatisticsReportController 的五个接口：

老接口	groupBy	daily
perPaperLengthStatistics	gender	false
perPaperLengthStatisticsDetail	gender	true
perPaperLengthStatisticsByFloor	floor	false
perPaperLengthStatisticsDetailByFloor	floor	true
perPaperLengthStatisticsByToilet	floorGender	false

floorGender+daily=true 不在老接口范围内，直接返回参数错误。

2. 数据与口径

数据源：m0 monthly_statistics 日汇总表，不查 ES。
固定过滤：soft_delete=0、district_id、日期左闭右开区间。
可选过滤：device_type；idStrList 中 building、floor、toilet 分别独立 IN。
paperLengthMeters=Σpaper_length/100，表内 paper_length 单位为厘米。
perCapita=paperLengthMeters/Σuse_count，四舍五入保留两位小数。
当 useCount=0 时，perCapita 取 paperLengthMeters，延续老系统语义。
日期上限读取 Redis Dictionary.StatisticsDays，缺失或非法时拒绝查询。

3. 参数

参数	必填	说明
districtId	是	正整数站点 ID
startDate/endDate	是	yyyy-MM-dd，含首尾日期，endDate 不晚于今天
groupBy	是	gender / floor / floorGender
daily	否	默认 false；true 时增加日期维度
deviceType	否	0 出纸机，1 擦手纸机
idStrList	否	每项严格为 buildingId_floor_toiletId

4. 面向 LLM 的返回结构

返回结构不随分组方式变化。维度和指标位于同一个行对象，无数据日期或分组不生成行。

{
  "districtId": 12610,
  "districtName": "望京SOHO",
  "dateRange": "2026-09-01 ~ 2026-09-21",
  "unit": "米/人次",
  "groupBy": "gender",
  "daily": false,
  "totalPerCapita": 1.32,
  "rows": [
    {
      "date": null,
      "floor": null,
      "gender": "男卫",
      "paperLengthMeters": 120.5,
      "useCount": 96,
      "perCapita": 1.26
    }
  ]
}

未参与分组的 date/floor/gender 保持为 null。
daily=true 时 totalPerCapita 为 null；非按日查询时为整个区间的总人均。
gender 映射：0男卫、1女卫、2母婴室、3无障碍、4第三卫、5其他，其他值显示未知。
楼层按数据库字符串值的字典序输出。

5. 权限与作用域

查询前用 PermissionService.applyDistrictRowFilter 校验当前用户能否查看站点。
站点不存在和无权访问统一返回“站点不存在或无权访问”。
工具只绑定 service_enabled=0 的用户委托作用域，不向 sync、ops-query 等服务身份作用域开放。

6. 实现文件

src/main/java/me/iiv/agent/mcp/tool/PaperPerCapitaStatisticsTools.java
src/test/java/me/iiv/agent/mcp/tool/PaperPerCapitaStatisticsToolsTest.java
sql/seed-dev.sql
doc/agent-mcp-tools-reference.md
README.md

3.0 KiB Raw Blame History Unescape Escape