新增 MCP 工具 district.paper.statistics.query(客户用纸统计)并引入 ES 7.17 客户端

- 复刻老 MonthlyStatisticsController.getMonthlyStatisticsMap:m0 monthly_statistics 按 gender/按日聚合(用纸长度米、人次、台日),district_strategy.rfid_use_flag 分口径统计 ES paperuselog 换纸卷数
- ES 双集群(云/本地,Dictionary.LocalEsDate 分界)+ 冷热索引(90 天),terms 聚合统计 rfid 去重数替代老 scroll 拉全量
- 引入 co.elastic.clients:elasticsearch-java 7.17.29(显式钉版本,覆盖 Boot BOM 8.x),EsClientConfig 双集群客户端
- 字典缺失/ES 异常 fail fast 抛 IllegalStateException(老系统静默为 0);district_strategy 缺失按未使用 rfid 口径(老系统 NPE)
- 新增单测 16 个(工具 13 + planner 3),全套 303 个单测通过
This commit is contained in:
my_local_kimi_dev2
2026-09-20 18:48:30 +08:00
parent 68fd71edbb
commit 8d8e71e45c
18 changed files with 1335 additions and 0 deletions
@@ -744,6 +744,34 @@
---
## 30. district.paper.statistics.query
客户用纸统计,1:1 复刻老系统 `POST /MonthlyStatistics/getMonthlyStatisticsMap`(MonthlyStatisticsController),
分主体统计(DB)与换纸卷数(ES)两部分。
- 分类:hardware | 类型:读
- 主体数据来源:m0 `monthly_statistics`(XXL-Job 预聚合的站点日汇总,每站点每厕位/厕每天一行),
`statistics_time` 范围 [startDate 00:00:00, endDate 23:59:59],可选 `buildingId/floor/toiletId/deviceType` 精确过滤。
- 入参:`districtId`(必填正整数)、`startDate`/`endDate`(必填 yyyy-MM-dd,startDate≤endDate≤今天)、
`positionMode`(position=仅厕位/wall=仅厕墙,只作用于 ES 换纸卷数口径)、`deviceType`(0/1)、`buildingId`、`floor`、`toiletId`。
- 聚合维度 gender(0男1女2母婴3残卫4第三5其他99未知):
`paperLengthM`=Σpaper_length/100(米,3 位小数)、`useCount`=Σuse_count(厕墙行恒 0 直接求和)、
`deviceDayCount`=按日 distinct 厕位/厕数之和(老系统 perPositionsCount,输出改名)、
`perUseLengthM`=paperLengthM/useCount(useCount=0 为 null);另输出按日明细(date/gender/paperLengthM/useCount/deviceDayCount)。
- 换纸卷数 `rfidCount`(ES):读 `district_strategy.rfid_use_flag`(行 id=站点 id)——
=1 时 state∈{2上纸,4撤纸} 合并后 rfid 去重数(terms 聚合 size 10000 统计 bucket 数,超出部分不计);
≠1 或记录缺失时取 state=2 精确 count(不含撤纸、不去重)。仅对 DB 结果中出现过的 gender 逐组查询。
- ES 口径:索引按 startDate 距今 90 天分冷热(`paperuselog` / `paperuselog_all`,老 isHotTime 硬编码);
集群按 Redis `Dictionary.LocalEsDate`(yyyy-MM-dd)分界——分界日 > endDate 走本地集群,
startDate < 分界日 < endDate 拒绝查询;`Dictionary.StatisticsDays` 限制查询天数上限;字典缺失 fail fast 抛 `IllegalStateException`。
endDate=今天时 ES 上界取今天 00:00(当天数据未跑完),否则 23:59:59(含边界)。
- 行级权限:站点可见性沿用 `district.detail.get` 模式(id + soft_delete=0 + applyDistrictRowFilter),
查不到统一抛 `站点不存在或无权访问`。
- 与老系统的差异(详见 `district-paper-statistics-design.md`):ES 异常不静默为 0 而是抛错;
rfid 去重用 terms 聚合替代 scroll 拉全量;district_strategy 缺失/空 rfid_use_flag 按"未使用 rfid"口径而非 NPE。
---
## 附录:在线查看工具清单
```bash