Merge branch 'feat/paper-trace-list-mcp-tools': 客户换纸记录 MCP 工具 (REQ-20261012-0002)

This commit is contained in:
my_local_kimi_dev2
2026-10-12 14:18:38 +08:00
12 changed files with 1097 additions and 53 deletions
@@ -0,0 +1,32 @@
package me.iiv.agent.entity.m0;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import java.io.Serializable;
import java.util.Date;
/** RFID(m0.rfid_info,极简字段:换纸明细的 isAssignment 判定用)。 */
@Getter
@Setter
@ToString
@TableName("rfid_info")
public class RfidInfo implements Serializable {
private static final long serialVersionUID = 1L;
@TableId(value = "id", type = IdType.AUTO)
private Long id;
private Long createId;
private Date createTime;
private Long modifyId;
private Date modifyTime;
private Integer softDelete;
private String rfid;
/** ≥1 表示已生成(老 getRfidTraceList 口径:assignment_flag >= 1) */
private Integer assignmentFlag;
}
@@ -1,5 +1,7 @@
package me.iiv.agent.es;
import java.util.List;
/**
* paperuselog(换纸记录)ES 查询网关。集群选择(云/本地)与索引选择(热/冷)
* 由调用方通过参数传入,本接口只做单次查询,便于单测 mock。
@@ -22,4 +24,112 @@ public interface PaperUseLogEsGateway {
*/
long countState2(String index, boolean localCluster, Long districtId, Integer gender,
Long fromMillis, Long toMillis, Integer deviceType, String positionMode);
/**
* 换纸记录分页明细:term districtId、createTime 闭区间(epoch 毫秒)、
* snCode/rfid 走 .keyword 精确匹配(text 主字段禁止 term/match 分词)、
* state(2=上纸/4=撤纸)与 deviceType 可选过滤,按 createTime ASC 排序,from+size 分页。
*
* @param index paperuselog / paperuselog_all
* @param localCluster true=本地集群,false=云集群
* @param snCode 可选,keyword 精确匹配
* @param rfid 可选,keyword 精确匹配
* @param state 可选,2=上纸、4=撤纸,null=查所有
* @param deviceType 可选,0=出纸机、1=擦手纸机,null=不过滤
* @param from from+size 分页起始偏移
* @param size 每页条数
* @return 命中总数(track_total_hits)与当页记录
*/
TraceSearchResult searchTraces(String index, boolean localCluster, Long districtId,
Long fromMillis, Long toMillis,
String snCode, String rfid, Integer state, Integer deviceType,
int from, int size);
/** 换纸明细分页查询结果。 */
class TraceSearchResult {
private final long total;
private final List<TraceRecord> records;
public TraceSearchResult(long total, List<TraceRecord> records) {
this.total = total;
this.records = records;
}
public long getTotal() {
return total;
}
public List<TraceRecord> getRecords() {
return records;
}
}
/** 单条换纸记录(_source 文本值已归一为数值、createTime 已归一为 ISO 文本)。 */
class TraceRecord {
private final String createTime;
private final Integer state;
private final String rfid;
private final String snCode;
private final Integer lengthCm;
private final Integer paperlengthCm;
private final Long positionsId;
private final Long toiletId;
private final Integer gender;
private final Integer deviceType;
public TraceRecord(String createTime, Integer state, String rfid, String snCode,
Integer lengthCm, Integer paperlengthCm,
Long positionsId, Long toiletId, Integer gender, Integer deviceType) {
this.createTime = createTime;
this.state = state;
this.rfid = rfid;
this.snCode = snCode;
this.lengthCm = lengthCm;
this.paperlengthCm = paperlengthCm;
this.positionsId = positionsId;
this.toiletId = toiletId;
this.gender = gender;
this.deviceType = deviceType;
}
public String getCreateTime() {
return createTime;
}
public Integer getState() {
return state;
}
public String getRfid() {
return rfid;
}
public String getSnCode() {
return snCode;
}
public Integer getLengthCm() {
return lengthCm;
}
public Integer getPaperlengthCm() {
return paperlengthCm;
}
public Long getPositionsId() {
return positionsId;
}
public Long getToiletId() {
return toiletId;
}
public Integer getGender() {
return gender;
}
public Integer getDeviceType() {
return deviceType;
}
}
}
@@ -12,6 +12,8 @@ import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
/**
* paperuselog ES 查询实现。
@@ -89,6 +91,118 @@ public class PaperUseLogEsGatewayImpl implements PaperUseLogEsGateway {
}
}
@Override
public TraceSearchResult searchTraces(String index, boolean localCluster, Long districtId,
Long fromMillis, Long toMillis,
String snCode, String rfid, Integer state, Integer deviceType,
int from, int size) {
ArrayNode filters = mapper.createArrayNode();
filters.addObject().putObject("term").putObject("districtId").put("value", districtId);
// createTime 为 date 类型,range 必须发 epoch 毫秒(同 distinctRfidCount)
ObjectNode range = filters.addObject().putObject("range").putObject("createTime");
range.put("gte", fromMillis).put("lte", toMillis);
if (StringUtils.hasText(snCode)) {
// rfid/snCode 主字段是 text(有 ignore_above=256 的 keyword 子字段),
// 精确匹配必须走 .keyword term;matchQuery 会被 standard analyzer 分词误配
filters.addObject().putObject("term").putObject("snCode.keyword").put("value", snCode);
}
if (StringUtils.hasText(rfid)) {
filters.addObject().putObject("term").putObject("rfid.keyword").put("value", rfid);
}
if (state != null) {
filters.addObject().putObject("term").putObject("state").put("value", state);
}
if (deviceType != null) {
// 与 baseFilters 同口径:老代码 deviceType 字符串参数走 match(数字文本分词后等价精确)
filters.addObject().putObject("match").putObject("deviceType")
.put("query", String.valueOf(deviceType));
}
try {
ObjectNode body = mapper.createObjectNode();
body.put("from", from).put("size", size);
body.put("track_total_hits", true);
ObjectNode bool = body.putObject("query").putObject("bool");
bool.set("filter", filters);
body.putArray("sort").addObject().putObject("createTime").put("order", "asc");
Request req = new Request("POST", "/" + index + "/_search");
req.setJsonEntity(mapper.writeValueAsString(body));
Response resp = client(localCluster).performRequest(req);
JsonNode root = mapper.readTree(resp.getEntity().getContent());
List<TraceRecord> records = new ArrayList<>();
for (JsonNode hit : root.at("/hits/hits")) {
JsonNode source = hit.get("_source");
if (source == null) {
continue;
}
records.add(new TraceRecord(
isoText(source.get("createTime")),
integerValue(source.get("state")),
textValue(source.get("rfid")),
textValue(source.get("snCode")),
integerValue(source.get("length")),
integerValue(source.get("paperlength")),
longValue(source.get("positionsId")),
longValue(source.get("toiletId")),
integerValue(source.get("gender")),
integerValue(source.get("deviceType"))));
}
return new TraceSearchResult(root.at("/hits/total/value").asLong(), records);
} catch (IOException | RuntimeException e) {
throw new IllegalStateException("ES 查询换纸记录明细失败: " + e.getMessage(), e);
}
}
/** createTime 在 _source 里是 ISO 文本(2026-09-21T10:00:00.000+08:00)或 epoch 毫秒数,统一归一为 ISO 文本 */
private static String isoText(JsonNode value) {
if (value == null || value.isNull()) {
return null;
}
if (value.isNumber()) {
return java.time.Instant.ofEpochMilli(value.longValue()).toString();
}
return value.isTextual() ? value.asText() : null;
}
private static String textValue(JsonNode value) {
return value == null || value.isNull() ? null : value.asText();
}
private static Long longValue(JsonNode value) {
if (value == null || value.isNull()) {
return null;
}
if (value.isNumber()) {
return value.longValue();
}
if (value.isTextual()) {
try {
return Long.valueOf(value.asText().trim());
} catch (NumberFormatException e) {
return null;
}
}
return null;
}
/** _source 里 length/paperlength/state 等数值可能是文本("150"),统一解析;非数值返回 null */
private static Integer integerValue(JsonNode value) {
if (value == null || value.isNull()) {
return null;
}
if (value.isNumber()) {
return value.intValue();
}
if (value.isTextual()) {
try {
return Integer.valueOf(value.asText().trim());
} catch (NumberFormatException e) {
return null;
}
}
return null;
}
private ArrayNode baseFilters(Long districtId, Integer gender, Long fromMillis, Long toMillis,
Integer deviceType, String positionMode) {
ArrayNode filters = mapper.createArrayNode();
@@ -0,0 +1,7 @@
package me.iiv.agent.mapper.m0;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import me.iiv.agent.entity.m0.RfidInfo;
public interface RfidInfoMapper extends BaseMapper<RfidInfo> {
}
@@ -0,0 +1,253 @@
package me.iiv.agent.mcp.tool;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import me.iiv.agent.entity.m0.DistrictDistrictStrategy;
import me.iiv.agent.entity.m0.RfidInfo;
import me.iiv.agent.entity.m0.User;
import me.iiv.agent.es.PaperUseLogEsGateway;
import me.iiv.agent.es.PaperUseLogEsPlanner;
import me.iiv.agent.mapper.m0.DistrictDistrictStrategyMapper;
import me.iiv.agent.mapper.m0.RfidInfoMapper;
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.time.LocalDate;
import java.time.ZoneId;
import java.time.temporal.ChronoUnit;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* 客户换纸记录分页查询(老 MonthlyStatisticsController.getRfidTraceList 移植):
* ES 索引 paperuselog(热)/ paperuselog_all(冷,startDate 距今 ≥90 天),
* 按用户拍板**不复刻**老系统的"轨迹展开"逻辑(scroll 全量拉取 + Java 侧隐式字段改写),
* 直接出分页明细;v1 不返回满卷标记(newPaperFlag),只返回原始 lengthCm。
* 站点可见性校验、LocalEsDate 集群分界与冷热索引路由复用 district.paper.statistics.query 同款口径。
* 设计文档:doc/paper-trace-list-mcp-design.md
*/
@Component
public class DistrictPaperTraceTools implements ToolObject {
private static final String DICTIONARY_KEY = "Dictionary";
private static final String DICT_LOCAL_ES_DATE = "LocalEsDate";
/** 日期区间硬限 31 天(一个月,2026-09-24 拍板) */
private static final int MAX_QUERY_DAYS = 31;
private static final int DEFAULT_ROWS = 20;
private static final int MAX_ROWS = 100;
private static final ZoneId SHANGHAI = ZoneId.of("Asia/Shanghai");
final DistrictDistrictStrategyMapper districtMapper;
final RfidInfoMapper rfidInfoMapper;
final PermissionService permissionService;
final PaperUseLogEsGateway paperUseLogEsGateway;
final StringRedisTemplate redisTemplate;
public DistrictPaperTraceTools(DistrictDistrictStrategyMapper districtMapper,
RfidInfoMapper rfidInfoMapper,
PermissionService permissionService,
PaperUseLogEsGateway paperUseLogEsGateway,
StringRedisTemplate redisTemplate) {
this.districtMapper = districtMapper;
this.rfidInfoMapper = rfidInfoMapper;
this.permissionService = permissionService;
this.paperUseLogEsGateway = paperUseLogEsGateway;
this.redisTemplate = redisTemplate;
}
@XqTool(category = "district", kind = "read")
@Tool(name = "district.paper.trace.list.query", description = "客户换纸记录分页查询(ES paperuselog 索引,"
+ "复刻老 /MonthlyStatistics/getRfidTraceList 的数据查询语义但出分页明细,不复刻轨迹展开逻辑)。"
+ "入参 districtId/startDate/endDate 必填;snCode/rfid 可选,keyword 精确匹配;state 可选"
+ "(2=上纸、4=撤纸,不传=查所有);deviceType 可选(0=出纸机、1=擦手纸机)。"
+ "返回 districtId/districtName/index/total/page/rows/records,record 含 createTime、state+stateText、"
+ "rfid、snCode、lengthCm(原始长度,单位厘米)、paperlengthCm、positionsId(0=厕所级)、toiletId、"
+ "gender+genderText、deviceType、isAssignment(该 rfid 在 m0 rfid_info 中 assignment_flag≥1 为 true);"
+ "按 createTime ASC 排序。日期区间最长 31 天,跨越 Redis LocalEsDate 分界会被拒绝。")
public Map<String, Object> districtPaperTraceListQuery(
@ToolParam(description = "站点 id,正整数") Long districtId,
@ToolParam(description = "开始日期,yyyy-MM-dd,含当天") String startDate,
@ToolParam(description = "结束日期,yyyy-MM-dd,含当天,不得晚于今天") String endDate,
@ToolParam(required = false, description = "设备 SN,keyword 精确匹配") String snCode,
@ToolParam(required = false, description = "rfid,keyword 精确匹配") String rfid,
@ToolParam(required = false, description = "换纸状态:2=上纸、4=撤纸,不传=查所有") Integer state,
@ToolParam(required = false, description = "设备类型:0=出纸机、1=擦手纸机,缺省不过滤") Integer deviceType,
@ToolParam(required = false, description = "页码,从 1 开始,默认 1") Integer page,
@ToolParam(required = false, description = "每页条数,默认 20,上限 100,超出截断为 100") Integer rows) {
if (districtId == null) {
throw new IllegalArgumentException("districtId 必填");
}
if (districtId < 1) {
throw new IllegalArgumentException("districtId 必须为正整数");
}
LocalDate start = parseDay(startDate, "startDate");
LocalDate end = parseDay(endDate, "endDate");
LocalDate today = LocalDate.now(SHANGHAI);
if (start.isAfter(end)) {
throw new IllegalArgumentException("startDate 不能晚于 endDate");
}
if (end.isAfter(today)) {
throw new IllegalArgumentException("endDate 不得晚于今天");
}
if (state != null && state != 2 && state != 4) {
throw new IllegalArgumentException("state 仅支持 2(上纸)、4(撤纸)");
}
if (deviceType != null && deviceType != 0 && deviceType != 1) {
throw new IllegalArgumentException("deviceType 仅支持 0、1");
}
int queryDays = (int) ChronoUnit.DAYS.between(start, end) + 1;
if (queryDays > MAX_QUERY_DAYS) {
throw new IllegalArgumentException(
"查询时间段最长 " + MAX_QUERY_DAYS + " 天(一个月),请修改日期范围");
}
User user = AuthContextHolder.get().getUser();
LambdaQueryWrapper<DistrictDistrictStrategy> districtWrapper = new LambdaQueryWrapper<DistrictDistrictStrategy>()
.eq(DistrictDistrictStrategy::getSoftDelete, 0)
.eq(DistrictDistrictStrategy::getId, districtId);
permissionService.applyDistrictRowFilter(districtWrapper, user);
DistrictDistrictStrategy district = districtMapper.selectOne(districtWrapper);
if (district == null) {
throw new IllegalStateException("站点不存在或无权访问");
}
// 与 district.paper.statistics.query 同款:LocalEsDate 集群分界,字典缺失 fail fast(老系统 NPE 被吞)
LocalDate localEsDate = parseDay(dictionaryValue(DICT_LOCAL_ES_DATE), DICT_LOCAL_ES_DATE);
PaperUseLogEsPlanner.checkNotCrossingBoundary(start, end, localEsDate);
String index = PaperUseLogEsPlanner.resolveIndex(start, today);
boolean localCluster = PaperUseLogEsPlanner.useLocalCluster(localEsDate, end);
long fromMillis = start.atStartOfDay(SHANGHAI).toInstant().toEpochMilli();
// 与 statistics 工具同款老口径:endDate=今天 → 上界取今天 00:00(当天数据未跑完),否则次日 00:00-1ms
LocalDate endExclusive = end.equals(today) ? end : end.plusDays(1);
long toMillis = endExclusive.atStartOfDay(SHANGHAI).toInstant().toEpochMilli() - 1;
int pageNo = page == null || page < 1 ? 1 : page;
boolean truncatedRows = rows != null && rows > MAX_ROWS;
int pageSize = rows == null || rows < 1 ? DEFAULT_ROWS : Math.min(rows, MAX_ROWS);
int from = (pageNo - 1) * pageSize;
PaperUseLogEsGateway.TraceSearchResult search = paperUseLogEsGateway.searchTraces(
index, localCluster, districtId, fromMillis, toMillis,
StringUtils.hasText(snCode) ? snCode.trim() : null,
StringUtils.hasText(rfid) ? rfid.trim() : null,
state, deviceType, from, pageSize);
Set<String> assignedRfids = assignedRfids(search.getRecords());
List<Map<String, Object>> records = new ArrayList<>();
for (PaperUseLogEsGateway.TraceRecord record : search.getRecords()) {
records.add(recordRow(record, assignedRfids));
}
Map<String, Object> result = new LinkedHashMap<>();
result.put("districtId", districtId);
result.put("districtName", district.getDistrictName());
result.put("index", index);
result.put("total", search.getTotal());
result.put("page", pageNo);
result.put("rows", pageSize);
if (truncatedRows) {
result.put("notice", "rows 超过上限 " + MAX_ROWS + ",已截断为 " + MAX_ROWS);
}
result.put("records", records);
return result;
}
/** 老 getRfidTraceList :735-741 口径:m0 rfid_info soft_delete=0、rfid IN (页内 rfid)、assignment_flag≥1 */
private Set<String> assignedRfids(List<PaperUseLogEsGateway.TraceRecord> records) {
Set<String> rfids = new LinkedHashSet<>();
for (PaperUseLogEsGateway.TraceRecord record : records) {
if (StringUtils.hasText(record.getRfid())) {
rfids.add(record.getRfid());
}
}
Set<String> assigned = new HashSet<>();
if (rfids.isEmpty()) {
return assigned;
}
List<RfidInfo> rfidInfos = rfidInfoMapper.selectList(new LambdaQueryWrapper<RfidInfo>()
.eq(RfidInfo::getSoftDelete, 0)
.in(RfidInfo::getRfid, rfids)
.ge(RfidInfo::getAssignmentFlag, 1));
for (RfidInfo rfidInfo : rfidInfos) {
assigned.add(rfidInfo.getRfid());
}
return assigned;
}
private Map<String, Object> recordRow(PaperUseLogEsGateway.TraceRecord record, Set<String> assignedRfids) {
Map<String, Object> row = new LinkedHashMap<>();
row.put("createTime", record.getCreateTime());
row.put("state", record.getState());
row.put("stateText", stateText(record.getState()));
row.put("rfid", record.getRfid());
row.put("snCode", record.getSnCode());
row.put("lengthCm", record.getLengthCm());
row.put("paperlengthCm", record.getPaperlengthCm());
row.put("positionsId", record.getPositionsId());
row.put("toiletId", record.getToiletId());
row.put("gender", record.getGender());
row.put("genderText", genderText(record.getGender()));
row.put("deviceType", record.getDeviceType());
row.put("isAssignment", StringUtils.hasText(record.getRfid()) && assignedRfids.contains(record.getRfid()));
return row;
}
private String dictionaryValue(String field) {
Object value = redisTemplate.opsForHash().get(DICTIONARY_KEY, field);
if (value == null) {
throw new IllegalStateException("Redis Dictionary 缺少 " + field + " 字段,拒绝查询");
}
return value.toString();
}
private static LocalDate parseDay(String value, String name) {
if (!StringUtils.hasText(value)) {
throw new IllegalArgumentException(name + " 必填,格式 yyyy-MM-dd");
}
try {
return LocalDate.parse(value.trim());
} catch (java.time.format.DateTimeParseException e) {
throw new IllegalArgumentException(name + " 格式非法,要求 yyyy-MM-dd: " + value);
}
}
private static String stateText(Integer state) {
if (state == null) {
return null;
}
switch (state) {
case 2: return "上纸";
case 4: return "撤纸";
default: return null;
}
}
/** gender 透传索引原值;0男/1女/2母婴/3残卫/4第三/5其他,未知编码 genderText 为 null */
private static String genderText(Integer gender) {
if (gender == null) {
return null;
}
switch (gender) {
case 0: return "男";
case 1: return "女";
case 2: return "母婴";
case 3: return "残卫";
case 4: return "第三";
case 5: return "其他";
default: return null;
}
}
}