Files
xiaoqu_mcp_service/xiaoqu-agent-service/doc/sms-vercode-latest-mcp-design.md
T
my_local_kimi_dev2 021cee37df 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 拒绝)。
2026-11-13 17:41:41 +08:00

125 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 短信验证码提取工具 MCP 设计(REQ-20261113-0009,已批准 2026-11-13)
> **拍板结论(2026-11-13 王恒)**:§7 四个待拍板点全部按建议值执行——
> ① buss_type 固定过滤"验证码";② send_state 不过滤、失败记录也返回并标注;
> ③ 不加时间窗、返回 ageSeconds;④ 工具名 `sms.vercode.latest.query`、category=admin。
> (实现注:kind 按平台惯例为 `read`/`write`,本工具 kind=read,设计稿中"query"为笔误。)
## 1. 背景
研发/测试场景需要"按手机号提取最近一条短信验证码"(自动化登录、联调、测试账号验证)。
老系统没有现成查询接口,目前只能人工查库。本设计新增 1 个只读 MCP 工具。
**敏感性说明**:验证码 = 登录绕过原语。本工具按运维工具口径设计——**零行级权限,
访问控制完全靠专用 scope 门禁**(同 warehouse.order.handler.update 模式),
只绑研发专用/测试专用作用域,**永不绑业务 scope(prod 1/2/3/5)**。
## 2. 数据源调研结论
表:m0 `sms_send_record`(参考库 `beans/b0/SmsSendRecord.java`,m0 mapper)。
| 列 | 说明 |
|---|---|
| user_mobile | 手机号 |
| sms_content | 发送内容,验证码记录为 `验证码=123456` 或 `【小趣智品】验证码=123456` |
| buss_type | 业务类型,验证码记录固定为 `验证码`(SendSmsController.java:84/97、LoginController.java:195/208、AccountController、ChargeController 均同) |
| send_state | 0 成功 / 1 失败(失败记录 content 里也有码,但 redis 未写入,实际不可用) |
| report_state | 验证码记录固定写 99(不过滤) |
| soft_delete | 0 正常 / 99 停用 |
| create_time | 发送时间 |
验证码本体:`RandomUtil.randomNumbers(6)`,6 位数字;redis 有效期 90 秒
(SendSmsController.java:93)。非生产/白名单环境直接返回 123456 且**不落库**,
所以测试环境查不到记录属正常现象。
## 3. 工具定义
| 项 | 值 |
|---|---|
| 工具名 | `sms.vercode.latest.query` |
| category | `admin` |
| kind | `read`(只读) |
| 工具类 | 新建 `SmsTools`(同域后续可加短信记录列表工具) |
| 数据源 | 纯 MySQL m0,无 ES、无 Redis |
| 行级权限 | 无(scope 门禁,见 §6) |
## 4. 参数契约
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mobile | string | 是 | 11 位手机号,精确匹配 `user_mobile` |
查询口径(固定,全部保老系统写入口径):
- `user_mobile = mobile`
- `buss_type = '验证码'`
- `soft_delete = 0`
- 按 `id DESC` 取第一条(自增 id 等价于 create_time 最新,避免时间精度并列)
提取规则:对 `sms_content` 跑正则 `验证码\s*[=::]\s*(\d{4,8})`,命中取第一组;
不命中(历史脏数据/格式漂移)返回 `vercode=null` + 原始 `smsContent`,不报错。
## 5. 返回契约
统一 ToolResult 结构,`record` 对象:
```json
{
"record": {
"id": 123456789,
"mobile": "13800000000",
"vercode": "483920",
"smsContent": "验证码=483920",
"sendState": 0,
"sendStateText": "发送成功",
"bussType": "验证码",
"createTime": "2026-11-13 17:20:30",
"ageSeconds": 45
},
"notice": null
}
```
- 无记录:`record=null` + `notice="该手机号暂无验证码短信记录"`
- `ageSeconds` = 当前时间 - createTime,供调用方判断 90 秒有效期(工具不做硬过期判断,
失败记录 sendState=1 也照样返回并配文案,由调用方决定可用性——**待拍板点 2**)
- 错误码:`INVALID_ARGUMENT`(手机号为空/非 11 位),`ToolCallException` 透出文案
## 6. scope 绑定(安全核心)
| 环境 | 绑定 | 说明 |
|---|---|---|
| prod | **只绑 scope 6(研发专用,code=code)** | INSERT IGNORE scope_tool(6, tool_id);严禁绑 1/2/3/5 |
| dev | seed-dev 只加「测试专用」scope 绑定 | 不加 operation 等业务 scope |
按 2026-11-07 王恒口径"所有工具默认绑研发专用 scope 6",本工具是唯一**显式排除
其他所有 scope** 的工具(其他查询工具是"默认绑 6",本工具是"只绑 6")。
服务 Token 只有 sync 作用域,天然调不到。
审计:每次调用落 svc audit_log(含调用方 token 身份、入参 mobile、request_id),
与现有工具审计链路一致。
## 7. 待拍板点(建议值)
1. **buss_type 固定过滤"验证码"**(建议)vs 不过滤取任意短信最新一条。
2. **send_state 不过滤**,最新一条即使是发送失败也返回、文案标注(建议——失败记录
同样能反映"系统生成了什么码",联调更有用)vs 只看 send_state=0。
3. **不做时间窗硬限制**,返回 ageSeconds(建议)vs 加 withinMinutes 参数只查近 N 分钟。
4. 工具名 `sms.vercode.latest.query`(建议),category=admin。
## 8. 变更文件清单
- 新增 `entity/m0/SmsSendRecord.java`(本地拷贝,全列对齐参考库——PR #31 教训)
- 新增 `mapper/m0/SmsSendRecordMapper.java`
- 新增 `mcp/tool/SmsTools.java`(1 个工具方法)
- 新增 `SmsToolsTest`(参数校验/提取正则含【小趣智品】前缀格式/空记录/sendState 文案/soft_delete 过滤)
- `sql/seed-dev.sql`:测试专用 scope 绑定
- `README.md` + `doc/agent-mcp-tools-reference.md`:登记
- 装配层零改动(ToolObject 扫描自动注册)
## 9. 测试与上线流程
按 AGENTS.md 标准流程:单测全绿 → `./deploy/test-up.sh` 测试环境冒烟
(scopeCode=test 签 Token;注意 dev 库可能无验证码记录,空记录路径也要验)→
push main → remote-deploy → 确认 ToolSyncService 新增 tool → 绑 prod scope 6 →
生产只读核验(tools/list 可见 + 真实手机号查询)。ai-proj 走自审批闭环。