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:
@@ -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 + " 必须为正整数");
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user