按手机号提取 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 拒绝)。
125 lines
5.7 KiB
Markdown
125 lines
5.7 KiB
Markdown
# 短信验证码提取工具 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 走自审批闭环。
|