feat(mcp): 新增短信验证码提取工具 sms.vercode.latest.query(REQ-20261113-0009)

按手机号提取 m0 sms_send_record 最近一条验证码(buss_type=验证码+soft_delete=0+id DESC
首条),正则提取 4-8 位数字码,send_state 不过滤并配文案,返回 ageSeconds 供判断 90s
redis 有效期。零行级权限,安全模型靠专用 scope 门禁:prod 只绑研发专用 scope 6、dev 只绑
测试专用 scope,显式排除业务 scope(全平台唯一)。王恒拍板 4 决策点全部按建议值执行。
测试:SmsToolsTest 10 例全绿;测试环境冒烟 4/4(有记录提取/无记录 notice/非法入参/
operation scope 拒绝)。
This commit is contained in:
my_local_kimi_dev2
2026-11-13 17:41:41 +08:00
parent f2eb8afcdd
commit 021cee37df
8 changed files with 503 additions and 0 deletions
@@ -0,0 +1,43 @@
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;
/** 短信发送记录(m0.sms_send_record),逐字段复制自老系统 publicbeanandmap beans/b0/SmsSendRecord。 */
@Getter
@Setter
@ToString
@TableName("sms_send_record")
public class SmsSendRecord 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;
/** 0 正常,99 停用 */
private Integer softDelete;
/** 手机号 */
private String userMobile;
/** 发送内容(验证码记录形如 "验证码=123456" 或 "【小趣智品】验证码=123456") */
private String smsContent;
/** 短信id */
private String smsid;
/** 0:成功;1:失败 */
private Integer sendState;
/** 0:成功;1:失败(验证码记录固定写 99) */
private Integer reportState;
private String reportValue;
/** 业务类型(验证码记录固定为 "验证码") */
private String bussType;
}
@@ -0,0 +1,7 @@
package me.iiv.agent.mapper.m0;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import me.iiv.agent.entity.m0.SmsSendRecord;
public interface SmsSendRecordMapper extends BaseMapper<SmsSendRecord> {
}
@@ -0,0 +1,129 @@
package me.iiv.agent.mcp.tool;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import me.iiv.agent.entity.m0.SmsSendRecord;
import me.iiv.agent.mapper.m0.SmsSendRecordMapper;
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 org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* 短信验证码提取工具(REQ-20261113-0009,设计文档 doc/sms-vercode-latest-mcp-design.md)。
* 研发/测试专用:按手机号提取 m0 sms_send_record 最近一条验证码(buss_type=验证码、soft_delete=0、
* id DESC 首条),从 sms_content 正则提取数字码。验证码 = 登录绕过原语,零行级权限,
* 访问控制完全靠专用 scope 门禁(prod 只绑研发专用 scope 6,dev 只绑测试专用 scope)。
*/
@Component
public class SmsTools implements ToolObject {
/** 验证码业务类型(老系统写入口径,SendSmsController/LoginController 等均固定写 "验证码") */
private static final String BUSS_TYPE_VERCODE = "验证码";
/** 验证码提取规则:兼容 "验证码=123456" 与 "【小趣智品】验证码=123456",4-8 位数字 */
private static final Pattern VERCODE_PATTERN = Pattern.compile("验证码\\s*[=::]\\s*(\\d{4,8})");
private static final Pattern MOBILE_PATTERN = Pattern.compile("^1\\d{10}$");
final SmsSendRecordMapper smsSendRecordMapper;
public SmsTools(SmsSendRecordMapper smsSendRecordMapper) {
this.smsSendRecordMapper = smsSendRecordMapper;
}
/**
* 提取指定手机号最近一条验证码短信。固定口径:buss_type=验证码 + soft_delete=0 + id DESC 首条;
* send_state 不过滤(发送失败的记录同样返回并标注,由调用方结合 ageSeconds 判断可用性,
* 验证码 redis 有效期 90 秒)。无记录返回 record=null + notice,不报错。
*/
@XqTool(category = "admin", kind = "read")
@Tool(name = "sms.vercode.latest.query", description = "【研发/测试专用】按手机号提取最近一条短信验证码。"
+ "查询 m0 sms_send_record 中该手机号 buss_type=验证码、soft_delete=0 的最新一条记录(id 倒序),"
+ "从发送内容中正则提取 4-8 位数字验证码(兼容 \"验证码=123456\" 与 \"【小趣智品】验证码=123456\" 格式,"
+ "内容格式不命中时 vercode 为 null 并返回原始 smsContent,不报错)。"
+ "send_state 不过滤:发送失败(sendState=1)的记录也返回并配 sendStateText 文案。"
+ "返回 ageSeconds(距发送秒数)供判断验证码 90 秒 redis 有效期,工具本身不做时间窗限制。"
+ "该手机号无验证码记录时 record 为 null 并附 notice。"
+ "注意:验证码是登录敏感原语,本工具零行级权限,仅靠专用 scope 门禁,每次调用落审计日志。")
public Map<String, Object> smsVercodeLatestQuery(
@ToolParam(description = "11 位手机号,精确匹配 user_mobile") String mobile) {
if (!StringUtils.hasText(mobile)) {
throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, "mobile 不能为空");
}
String trimmedMobile = mobile.trim();
if (!MOBILE_PATTERN.matcher(trimmedMobile).matches()) {
throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT,
"mobile 必须是 11 位手机号: " + trimmedMobile);
}
List<SmsSendRecord> rows = smsSendRecordMapper.selectList(new LambdaQueryWrapper<SmsSendRecord>()
.eq(SmsSendRecord::getUserMobile, trimmedMobile)
.eq(SmsSendRecord::getBussType, BUSS_TYPE_VERCODE)
.eq(SmsSendRecord::getSoftDelete, 0)
.orderByDesc(SmsSendRecord::getId)
.last("LIMIT 1"));
Map<String, Object> result = new LinkedHashMap<>();
if (rows.isEmpty()) {
result.put("record", null);
result.put("notice", "该手机号暂无验证码短信记录");
return result;
}
SmsSendRecord row = rows.get(0);
Map<String, Object> record = new LinkedHashMap<>();
record.put("id", row.getId());
record.put("mobile", row.getUserMobile());
record.put("vercode", extractVercode(row.getSmsContent()));
record.put("smsContent", row.getSmsContent());
record.put("sendState", row.getSendState());
record.put("sendStateText", sendStateText(row.getSendState()));
record.put("bussType", row.getBussType());
record.put("createTime", format(row.getCreateTime()));
record.put("ageSeconds", ageSeconds(row.getCreateTime()));
result.put("record", record);
result.put("notice", null);
return result;
}
/** 从短信内容提取验证码;不命中(历史脏数据/格式漂移)返回 null。 */
static String extractVercode(String smsContent) {
if (smsContent == null) {
return null;
}
Matcher matcher = VERCODE_PATTERN.matcher(smsContent);
return matcher.find() ? matcher.group(1) : null;
}
private static String sendStateText(Integer sendState) {
if (sendState == null) {
return null;
}
return switch (sendState) {
case 0 -> "发送成功";
case 1 -> "发送失败";
default -> "未知(" + sendState + ")";
};
}
private static Long ageSeconds(Date createTime) {
return createTime == null ? null : (System.currentTimeMillis() - createTime.getTime()) / 1000;
}
private static String format(Date value) {
return value == null ? null : new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(value);
}
}