@@ -0,0 +1,395 @@
package me.iiv.agent.mcp.tool ;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper ;
import me.iiv.agent.entity.m0.HardwareCleanLog ;
import me.iiv.agent.entity.m0.HardwareCleanPic ;
import me.iiv.agent.entity.m0.User ;
import me.iiv.agent.mapper.m0.HardwareCleanLogMapper ;
import me.iiv.agent.mapper.m0.HardwareCleanPicMapper ;
import me.iiv.agent.mapper.m0.UserMapper ;
import me.iiv.agent.mcp.McpErrorCode ;
import me.iiv.agent.mcp.ToolCallException ;
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.data.redis.core.StringRedisTemplate ;
import org.springframework.stereotype.Component ;
import org.springframework.util.StringUtils ;
import java.text.SimpleDateFormat ;
import java.time.LocalDateTime ;
import java.time.format.DateTimeFormatter ;
import java.time.format.DateTimeParseException ;
import java.time.format.ResolverStyle ;
import java.util.ArrayList ;
import java.util.Arrays ;
import java.util.Date ;
import java.util.LinkedHashMap ;
import java.util.List ;
import java.util.Map ;
import java.util.Objects ;
import java.util.function.Function ;
import java.util.stream.Collectors ;
/**
* 清机记录查询工具,仿老系统 HardwareCleanLogController /listByPage。
* 修正老接口坑(设计文档 doc/hardware-cleanlog-mcp-design.md §5):
* agentId 传了仍叠加行级 ACL(老接口会绕过);富化/图片按页批量(老接口逐条 N+1);
* type=0 用行内 picurl, type≠0 批量查 hardware_clean_pic( type=0 图片行,按 order_no 拼 OSS URL)。
*/
@Component
public class HardwareCleanLogTools implements ToolObject {
private static final int DEFAULT_ROWS = 20 ;
private static final int MAX_ROWS = 100 ;
/** 老接口 Redis 字典 key( HardwareCleanLogController /listByPage :99-104, Properyt 为老拼写) */
private static final String NAME_AGENT_PREFIX = " name:Agent: " ;
private static final String NAME_PROPERTY_PREFIX = " name:Properyt: " ;
private static final String NAME_DISTRICT_PREFIX = " name:District: " ;
private static final DateTimeFormatter TIME_FORMAT =
DateTimeFormatter . ofPattern ( " uuuu-MM-dd HH:mm:ss " ) . withResolverStyle ( ResolverStyle . STRICT ) ;
final HardwareCleanLogMapper hardwareCleanLogMapper ;
final HardwareCleanPicMapper hardwareCleanPicMapper ;
final UserMapper userMapper ;
final PermissionService permissionService ;
final StringRedisTemplate redisTemplate ;
public HardwareCleanLogTools ( HardwareCleanLogMapper hardwareCleanLogMapper ,
HardwareCleanPicMapper hardwareCleanPicMapper ,
UserMapper userMapper ,
PermissionService permissionService ,
StringRedisTemplate redisTemplate ) {
this . hardwareCleanLogMapper = hardwareCleanLogMapper ;
this . hardwareCleanPicMapper = hardwareCleanPicMapper ;
this . userMapper = userMapper ;
this . permissionService = permissionService ;
this . redisTemplate = redisTemplate ;
}
/**
* 分页查询清机记录。硬过滤 soft_delete=0 + status=1(仅返回有效清机记录),固定 id DESC,
* selectCount + LIMIT 物理分页(项目未注册 MP 分页拦截器,禁用 selectPage)。
* 名称富化走 Redis multiGet、user 按页批量 IN、图片按页批量查,无 N+1。
*/
@XqTool ( category = " hardware " , kind = " read " )
@Tool ( name = " hardware.cleanlog.list.query " , description = " 清机记录分页查询,对应老系统 /hardwareCleanLog/listByPage。 "
+ " 仅返回有效清机记录(soft_delete=0 且 status=1),固定按 id 倒序。 "
+ " 支持 districtId/propertyId/agentId/userId 精确匹配,snCode 模糊匹配, "
+ " type( 0=大清洁 1=小清洁)/userRoleType( 0=代理 1=物业 2=保洁)精确匹配, "
+ " startTime/endTime 按记录修改时间(即清机时间,modify_time)过滤,minCleanRfidCount/maxCleanRfidCount 清理卷数范围。 "
+ " 传了 agentId 也仍然叠加当前身份的行级数据权限(修正老接口绕过 ACL 的 bug),无权数据返回空。 "
+ " page 默认 1, rows 默认 20、上限 100(超出截断为 100 并在 notice 提示)。 "
+ " 每行返回清机记录全字段 + agentName/propertyName/districtName/userName 富化(Redis/按页批量) "
+ " + userRoleTypeText/typeText/poweredTypeText 中文文案 + beforeCleanPics/afterCleanPics 图片 URL 列表 "
+ " (type=0 大清洁取行内图片字段;type≠0 从清机图片表按 order_no 拼 OSS URL,归入 afterCleanPics, beforeCleanPics 恒空)。 " )
public Map < String , Object > hardwareCleanLogListQuery (
@ToolParam ( required = false , description = " 站点 id,正整数,精确匹配 " ) Long districtId ,
@ToolParam ( required = false , description = " 物业 id,正整数,精确匹配 " ) Long propertyId ,
@ToolParam ( required = false , description = " 代理 id,正整数,精确匹配;传了也仍叠加行级数据权限 " ) Long agentId ,
@ToolParam ( required = false , description = " sn码,模糊匹配 " ) String snCode ,
@ToolParam ( required = false , description = " 操作人 id,正整数,精确匹配 " ) Long userId ,
@ToolParam ( required = false , description = " 清机方式:0=大清洁 1=小清洁 " ) Integer type ,
@ToolParam ( required = false , description = " 操作人身份:0=代理 1=物业 2=保洁 " ) Integer userRoleType ,
@ToolParam ( required = false , description = " 开始时间,yyyy-MM-dd HH:mm:ss,按记录修改时间(即清机时间)过滤,含 " ) String startTime ,
@ToolParam ( required = false , description = " 结束时间,yyyy-MM-dd HH:mm:ss,按记录修改时间(即清机时间)过滤,含 " ) String endTime ,
@ToolParam ( required = false , description = " 清理卷数下限,非负整数,含 " ) Integer minCleanRfidCount ,
@ToolParam ( required = false , description = " 清理卷数上限,非负整数,含 " ) Integer maxCleanRfidCount ,
@ToolParam ( required = false , description = " 页码,从 1 开始,默认 1 " ) Integer page ,
@ToolParam ( required = false , description = " 每页条数,默认 20,上限 100(超出截断为 100) " ) Integer rows ) {
validatePositive ( districtId , " districtId " ) ;
validatePositive ( propertyId , " propertyId " ) ;
validatePositive ( agentId , " agentId " ) ;
validatePositive ( userId , " userId " ) ;
validateEnum ( type , " type " , 0 , 1 ) ;
validateEnum ( userRoleType , " userRoleType " , 0 , 1 , 2 ) ;
LocalDateTime start = parseTime ( startTime , " startTime " ) ;
LocalDateTime end = parseTime ( endTime , " endTime " ) ;
if ( start ! = null & & end ! = null & & start . isAfter ( end ) ) {
throw invalid ( " startTime 不能晚于 endTime " ) ;
}
validateCountRange ( minCleanRfidCount , " minCleanRfidCount " ) ;
validateCountRange ( maxCleanRfidCount , " maxCleanRfidCount " ) ;
if ( minCleanRfidCount ! = null & & maxCleanRfidCount ! = null
& & minCleanRfidCount > maxCleanRfidCount ) {
throw invalid ( " minCleanRfidCount 不能大于 maxCleanRfidCount " ) ;
}
User user = AuthContextHolder . get ( ) . getUser ( ) ;
int pageNo = page = = null | | page < 1 ? 1 : page ;
boolean truncated = rows ! = null & & rows > MAX_ROWS ;
int pageSize = rows = = null | | rows < 1 ? DEFAULT_ROWS : Math . min ( rows , MAX_ROWS ) ;
LambdaQueryWrapper < HardwareCleanLog > wrapper = new LambdaQueryWrapper < HardwareCleanLog > ( )
. eq ( HardwareCleanLog : : getSoftDelete , 0 )
. eq ( HardwareCleanLog : : getStatus , 1 ) ;
if ( districtId ! = null ) {
wrapper . eq ( HardwareCleanLog : : getDistrictId , districtId ) ;
}
if ( propertyId ! = null ) {
wrapper . eq ( HardwareCleanLog : : getPropertyId , propertyId ) ;
}
if ( agentId ! = null ) {
wrapper . eq ( HardwareCleanLog : : getAgentId , agentId ) ;
}
if ( StringUtils . hasText ( snCode ) ) {
wrapper . like ( HardwareCleanLog : : getSnCode , snCode ) ;
}
if ( userId ! = null ) {
wrapper . eq ( HardwareCleanLog : : getUserId , userId ) ;
}
if ( type ! = null ) {
wrapper . eq ( HardwareCleanLog : : getType , type ) ;
}
if ( userRoleType ! = null ) {
wrapper . eq ( HardwareCleanLog : : getUserRoleType , userRoleType ) ;
}
if ( start ! = null ) {
wrapper . ge ( HardwareCleanLog : : getModifyTime , startTime . trim ( ) ) ;
}
if ( end ! = null ) {
wrapper . le ( HardwareCleanLog : : getModifyTime , endTime . trim ( ) ) ;
}
if ( minCleanRfidCount ! = null ) {
wrapper . ge ( HardwareCleanLog : : getCleanRfidCount , minCleanRfidCount ) ;
}
if ( maxCleanRfidCount ! = null ) {
wrapper . le ( HardwareCleanLog : : getCleanRfidCount , maxCleanRfidCount ) ;
}
permissionService . applyHardwareCleanLogRowFilter ( wrapper , user ) ;
Long total = hardwareCleanLogMapper . selectCount ( wrapper ) ;
wrapper . orderByDesc ( HardwareCleanLog : : getId )
. last ( " LIMIT " + ( long ) ( pageNo - 1 ) * pageSize + " , " + pageSize ) ;
List < HardwareCleanLog > list = hardwareCleanLogMapper . selectList ( wrapper ) ;
Enrichment enrichment = enrich ( list ) ;
Map < Long , List < String > > afterCleanPicsById = afterCleanPics ( list ) ;
List < Map < String , Object > > records = new ArrayList < > ( ) ;
for ( HardwareCleanLog log : list ) {
records . add ( toRecord ( log , enrichment , afterCleanPicsById ) ) ;
}
Map < String , Object > result = new LinkedHashMap < > ( ) ;
result . put ( " total " , total ) ;
result . put ( " page " , pageNo ) ;
result . put ( " rows " , pageSize ) ;
if ( truncated ) {
result . put ( " notice " , " rows 超过上限 100,已截断为 100 " ) ;
}
result . put ( " records " , records ) ;
return result ;
}
/** 批量富化上下文:Redis 名称 multiGet + 本页 user 批量 IN(修老接口 :99-106 逐条 N+1)。 */
private Enrichment enrich ( List < HardwareCleanLog > list ) {
Enrichment enrichment = new Enrichment ( ) ;
if ( list . isEmpty ( ) ) {
return enrichment ;
}
enrichment . agentNames = redisNames ( list , HardwareCleanLog : : getAgentId , NAME_AGENT_PREFIX ) ;
enrichment . propertyNames = redisNames ( list , HardwareCleanLog : : getPropertyId , NAME_PROPERTY_PREFIX ) ;
enrichment . districtNames = redisNames ( list , HardwareCleanLog : : getDistrictId , NAME_DISTRICT_PREFIX ) ;
List < Long > userIds = list . stream ( ) . map ( HardwareCleanLog : : getUserId )
. filter ( Objects : : nonNull ) . distinct ( ) . collect ( Collectors . toList ( ) ) ;
if ( ! userIds . isEmpty ( ) ) {
enrichment . userNames = userMapper . selectBatchIds ( userIds ) . stream ( )
. collect ( Collectors . toMap ( User : : getId , User : : getName , ( a , b ) - > a ) ) ;
}
return enrichment ;
}
private Map < Long , String > redisNames ( List < HardwareCleanLog > list ,
Function < HardwareCleanLog , Long > idGetter , String prefix ) {
List < Long > ids = list . stream ( ) . map ( idGetter )
. filter ( Objects : : nonNull ) . distinct ( ) . collect ( Collectors . toList ( ) ) ;
if ( ids . isEmpty ( ) ) {
return Map . of ( ) ;
}
List < String > keys = ids . stream ( ) . map ( id - > prefix + id ) . collect ( Collectors . toList ( ) ) ;
List < String > values = redisTemplate . opsForValue ( ) . multiGet ( keys ) ;
Map < Long , String > names = new LinkedHashMap < > ( ) ;
for ( int i = 0 ; i < ids . size ( ) ; i + + ) {
names . put ( ids . get ( i ) , values = = null | | i > = values . size ( ) ? null : values . get ( i ) ) ;
}
return names ;
}
/**
* type≠0 行的清理后图片:按页 hardware_clean_id IN 批量查 hardware_clean_pic
* ( soft_delete=0 且 type=0 图片行),按 order_no 排序拼 OSS URL
* (老接口 :113-121 逐条查询的批量修正)。type=0 行不查图片表,用行内 picurl。
*/
private Map < Long , List < String > > afterCleanPics ( List < HardwareCleanLog > list ) {
List < Long > ids = list . stream ( )
. filter ( log - > log . getType ( ) = = null | | log . getType ( ) ! = 0 )
. map ( HardwareCleanLog : : getId )
. filter ( Objects : : nonNull ) . distinct ( ) . collect ( Collectors . toList ( ) ) ;
if ( ids . isEmpty ( ) ) {
return Map . of ( ) ;
}
List < HardwareCleanPic > pics = hardwareCleanPicMapper . selectList ( new LambdaQueryWrapper < HardwareCleanPic > ( )
. eq ( HardwareCleanPic : : getSoftDelete , 0 )
. eq ( HardwareCleanPic : : getType , 0 )
. in ( HardwareCleanPic : : getHardwareCleanId , ids )
. orderByAsc ( HardwareCleanPic : : getHardwareCleanId )
. orderByAsc ( HardwareCleanPic : : getOrderNo ) ) ;
Map < Long , List < String > > urlsByCleanId = new LinkedHashMap < > ( ) ;
for ( HardwareCleanPic pic : pics ) {
urlsByCleanId . computeIfAbsent ( pic . getHardwareCleanId ( ) , ignored - > new ArrayList < > ( ) )
. add ( ossUrl ( pic ) ) ;
}
return urlsByCleanId ;
}
/** 老接口 :118 同款 OSS URL 拼接:http://{bucket}.oss-cn-beijing.aliyuncs.com/{folder}{fileName} */
private static String ossUrl ( HardwareCleanPic pic ) {
return " http:// " + pic . getOssbucketname ( ) + " .oss-cn-beijing.aliyuncs.com/ "
+ pic . getOssfolder ( ) + pic . getFileName ( ) ;
}
private Map < String , Object > toRecord ( HardwareCleanLog log , Enrichment enrichment ,
Map < Long , List < String > > afterCleanPicsById ) {
List < String > beforeCleanPics = new ArrayList < > ( ) ;
List < String > afterCleanPics = new ArrayList < > ( ) ;
if ( log . getType ( ) ! = null & & log . getType ( ) = = 0 ) {
if ( StringUtils . hasText ( log . getBeforeCleanPicurl ( ) ) ) {
beforeCleanPics . add ( log . getBeforeCleanPicurl ( ) ) ;
}
if ( StringUtils . hasText ( log . getAfterCleanPicurl ( ) ) ) {
afterCleanPics . add ( log . getAfterCleanPicurl ( ) ) ;
}
} else {
afterCleanPics . addAll ( afterCleanPicsById . getOrDefault ( log . getId ( ) , List . of ( ) ) ) ;
}
Map < String , Object > record = new LinkedHashMap < > ( ) ;
record . put ( " id " , log . getId ( ) ) ;
record . put ( " snCode " , log . getSnCode ( ) ) ;
record . put ( " userId " , log . getUserId ( ) ) ;
record . put ( " userName " , mapGet ( enrichment . userNames , log . getUserId ( ) ) ) ;
record . put ( " userRoleType " , log . getUserRoleType ( ) ) ;
record . put ( " userRoleTypeText " , userRoleTypeText ( log . getUserRoleType ( ) ) ) ;
record . put ( " type " , log . getType ( ) ) ;
record . put ( " typeText " , typeText ( log . getType ( ) ) ) ;
record . put ( " cleanRfidCount " , log . getCleanRfidCount ( ) ) ;
record . put ( " cleanRfidDays " , log . getCleanRfidDays ( ) ) ;
record . put ( " memo " , log . getMemo ( ) ) ;
record . put ( " agentId " , log . getAgentId ( ) ) ;
record . put ( " agentName " , mapGet ( enrichment . agentNames , log . getAgentId ( ) ) ) ;
record . put ( " propertyId " , log . getPropertyId ( ) ) ;
record . put ( " propertyName " , mapGet ( enrichment . propertyNames , log . getPropertyId ( ) ) ) ;
record . put ( " districtId " , log . getDistrictId ( ) ) ;
record . put ( " districtName " , mapGet ( enrichment . districtNames , log . getDistrictId ( ) ) ) ;
record . put ( " positions " , log . getPositions ( ) ) ;
record . put ( " workNo " , log . getWorkNo ( ) ) ;
record . put ( " assignmentId " , log . getAssignmentId ( ) ) ;
record . put ( " maintenanceAgentId " , log . getMaintenanceAgentId ( ) ) ;
record . put ( " maintenanceAgentName " , log . getMaintenanceAgentName ( ) ) ;
record . put ( " maintenancePropertyId " , log . getMaintenancePropertyId ( ) ) ;
record . put ( " maintenancePropertyName " , log . getMaintenancePropertyName ( ) ) ;
record . put ( " poweredType " , log . getPoweredType ( ) ) ;
record . put ( " poweredTypeText " , poweredTypeText ( log . getPoweredType ( ) ) ) ;
record . put ( " createTime " , format ( log . getCreateTime ( ) ) ) ;
record . put ( " modifyTime " , format ( log . getModifyTime ( ) ) ) ;
record . put ( " beforeCleanPics " , beforeCleanPics ) ;
record . put ( " afterCleanPics " , afterCleanPics ) ;
return record ;
}
private static final class Enrichment {
Map < Long , String > agentNames = Map . of ( ) ;
Map < Long , String > propertyNames = Map . of ( ) ;
Map < Long , String > districtNames = Map . of ( ) ;
Map < Long , String > userNames = Map . of ( ) ;
}
private static < K , V > V mapGet ( Map < K , V > map , K key ) {
return key = = null ? null : map . get ( key ) ;
}
private static String format ( Date value ) {
return value = = null ? null : new SimpleDateFormat ( " yyyy-MM-dd HH:mm:ss " ) . format ( value ) ;
}
private static String userRoleTypeText ( Integer value ) {
if ( value = = null ) {
return null ;
}
return switch ( value ) {
case 0 - > " 代理 " ;
case 1 - > " 物业 " ;
case 2 - > " 保洁 " ;
default - > " 未知( " + value + " ) " ;
} ;
}
private static String typeText ( Integer value ) {
if ( value = = null ) {
return null ;
}
return switch ( value ) {
case 0 - > " 大清洁 " ;
case 1 - > " 小清洁 " ;
default - > " 未知( " + value + " ) " ;
} ;
}
private static String poweredTypeText ( Integer value ) {
if ( value = = null ) {
return null ;
}
return switch ( value ) {
case 0 - > " 电源 " ;
case 1 - > " 电池 " ;
default - > " 未知( " + value + " ) " ;
} ;
}
private static void validatePositive ( Long value , String name ) {
if ( value ! = null & & value < 1 ) {
throw invalid ( name + " 必须为正整数 " ) ;
}
}
private static void validateEnum ( Integer value , String name , int . . . allowed ) {
if ( value = = null ) {
return ;
}
for ( int candidate : allowed ) {
if ( value = = candidate ) {
return ;
}
}
String options = Arrays . stream ( allowed ) . mapToObj ( String : : valueOf )
. collect ( Collectors . joining ( " 、 " ) ) ;
throw invalid ( name + " 仅支持 " + options ) ;
}
private static void validateCountRange ( Integer value , String name ) {
if ( value ! = null & & value < 0 ) {
throw invalid ( name + " 必须为非负整数 " ) ;
}
}
private static LocalDateTime parseTime ( String value , String name ) {
if ( ! StringUtils . hasText ( value ) ) {
return null ;
}
try {
return LocalDateTime . parse ( value . trim ( ) , TIME_FORMAT ) ;
} catch ( DateTimeParseException e ) {
throw invalid ( name + " 格式非法,要求 yyyy-MM-dd HH:mm:ss: " + value ) ;
}
}
/** 入参类错误透出具体文案给调用方(对齐 position.detail/traffic 等新工具风格),便于 LLM 自愈 */
private static ToolCallException invalid ( String message ) {
return new ToolCallException ( McpErrorCode . INVALID_ARGUMENT , message ) ;
}
}