feat(mcp): hardware.statistics.query 按物业统计设备数/在线/故障/离线

背景:CRM 经营画像需要"每客户设备数、离线数"。当前做法同步 devices 全量
(71,034 行,抽样 1000 台仅 13 台绑定物业,其余 property_id="0"),代价远大于收益。

本工具直接返回聚合结果:
- 入参 propertyId 或 propertyIds(≤20,去重),includeUnbound 默认 false
- 返回每物业 total/online/fault/offline + data_cutoff_at + notice
- 口径与 hardware.list.query 一致:hardware_view、soft_delete=0、status 1/2/3
- 行级权限复用 PermissionService.applyHardwareRowFilter
- 每物业 4 次 selectCount(项目未注册分页拦截器;无 clone 先例,重建 wrapper)

测试:DeviceStatisticsToolsTest 5 例(参数校验/超限/计数/权限调用/去重)全过。
设计文档:doc/hardware-statistics-query-mcp-tool-design.md(含待评审三问)。
This commit is contained in:
xiaoqu-ai
2026-10-20 16:34:08 +08:00
parent 417c388eac
commit 91d8e6e7a8
3 changed files with 325 additions and 0 deletions
@@ -0,0 +1,125 @@
package me.iiv.agent.mcp.tool;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import me.iiv.agent.entity.m0.HardwareView;
import me.iiv.agent.entity.m0.User;
import me.iiv.agent.mapper.m0.HardwareViewMapper;
import me.iiv.agent.mcp.ToolObject;
import me.iiv.agent.mcp.XqTool;
import me.iiv.agent.permission.PermissionService;
import me.iiv.agent.security.AuthContextHolder;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
import java.time.Instant;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 按物业统计出纸机数量(总数 / 在线 / 故障 / 离线)。
*
* <p>为什么需要它:下游(CRM 经营画像)只需要"某客户有几台设备、几台离线",
* 如果为此同步整张 hardware_view(7 万行,其中 98% 未绑定物业),代价远大于收益。
* 本工具一次调用直接给出统计结果,下游按客户查询 + 缓存即可。</p>
*
* <p>口径与 hardware.list.query 完全一致:
* <ul>
* <li>数据源 m0.hardware_view(当前状态视图,非历史);</li>
* <li>status:1=在线 2=故障 3=离线;</li>
* <li>soft_delete=0;</li>
* <li>行级权限复用 {@link PermissionService#applyHardwareRowFilter};</li>
* <li>默认排除未绑定物业设备(property_id=0),可用 includeUnbound 打开。</li>
* </ul></p>
*/
@Component
public class DeviceStatisticsTools implements ToolObject {
/** 单次最多统计 20 个物业,避免一次请求打出上百条 count 查询。 */
private static final int MAX_PROPERTIES = 20;
final HardwareViewMapper hardwareViewMapper;
final PermissionService permissionService;
public DeviceStatisticsTools(HardwareViewMapper hardwareViewMapper, PermissionService permissionService) {
this.hardwareViewMapper = hardwareViewMapper;
this.permissionService = permissionService;
}
@XqTool(category = "hardware", kind = "read")
@Tool(name = "hardware.statistics.query", description = "按物业统计出纸机数量:总数、在线、故障、离线。"
+ "一次最多统计 20 个物业(propertyId 与 propertyIds 二选一);"
+ "默认排除未绑定物业的设备(property_id=0),includeUnbound=true 时计入。"
+ "数据来源 m0.hardware_view 当前状态视图,仅反映调用时刻,不是历史统计。"
+ "行级权限与 hardware.list.query 一致(当前用户可见范围)。")
public Map<String, Object> hardwareStatisticsQuery(
@ToolParam(required = false, description = "物业 id,正整数;与 propertyIds 二选一") Long propertyId,
@ToolParam(required = false, description = "物业 id 列表,上限 20 个") List<Long> propertyIds,
@ToolParam(required = false, description = "是否统计未绑定物业的设备,默认 false") Boolean includeUnbound) {
validatePositive(propertyId, "propertyId");
List<Long> targets = new ArrayList<>();
if (propertyId != null) {
targets.add(propertyId);
}
if (propertyIds != null) {
for (Long id : propertyIds) {
validatePositive(id, "propertyIds");
if (id != null && !targets.contains(id)) {
targets.add(id);
}
}
}
if (targets.isEmpty()) {
throw new IllegalArgumentException("propertyId 或 propertyIds 至少提供一个");
}
if (targets.size() > MAX_PROPERTIES) {
throw new IllegalArgumentException("一次最多统计 " + MAX_PROPERTIES + " 个物业");
}
boolean withUnbound = Boolean.TRUE.equals(includeUnbound);
User user = AuthContextHolder.get().getUser();
List<Map<String, Object>> items = new ArrayList<>(targets.size());
for (Long target : targets) {
Map<String, Object> row = new LinkedHashMap<>();
row.put("property_id", target);
// 每个计数重建 wrapper:项目内没有 clone() 使用先例,避免依赖未验证的克隆语义。
row.put("total", countFor(user, target, withUnbound, null));
row.put("online", countFor(user, target, withUnbound, 1));
row.put("fault", countFor(user, target, withUnbound, 2));
row.put("offline", countFor(user, target, withUnbound, 3));
items.add(row);
}
Map<String, Object> result = new LinkedHashMap<>();
result.put("items", items);
result.put("data_cutoff_at", Instant.now().toString());
result.put("notice", "数据源为 hardware_view 当前状态视图,仅反映调用时刻;未绑定物业设备"
+ (withUnbound ? "已计入" : "未计入"));
return result;
}
/** 统计某物业在指定状态下的设备数;status 为 null 表示不按状态过滤。 */
private Long countFor(User user, Long target, boolean withUnbound, Integer status) {
LambdaQueryWrapper<HardwareView> wrapper = new LambdaQueryWrapper<HardwareView>()
.eq(HardwareView::getSoftDelete, 0)
.eq(HardwareView::getPropertyId, target);
if (!withUnbound) {
wrapper.gt(HardwareView::getPropertyId, 0);
}
if (status != null) {
wrapper.eq(HardwareView::getStatus, status);
}
permissionService.applyHardwareRowFilter(wrapper, user);
return hardwareViewMapper.selectCount(wrapper);
}
private static void validatePositive(Long value, String name) {
if (value != null && value < 1) {
throw new IllegalArgumentException(name + " 必须为正整数");
}
}
}