From c55d111e88551a43b147db98e90b4ff66ef84ee6 Mon Sep 17 00:00:00 2001 From: admin Date: Mon, 2 Nov 2026 23:46:17 +0800 Subject: [PATCH] =?UTF-8?q?feat(mcp):=20=E5=8F=82=E8=80=83=20dacli=20?= =?UTF-8?q?=E6=89=A9=E9=9D=A2=E5=88=B0=2049=20=E4=B8=AA=E4=B8=9A=E5=8A=A1?= =?UTF-8?q?=E5=B7=A5=E5=85=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 workflow×7 / form.create|update|delete / ops×4 / dict×3 / menu×2 / permission×3 / context.app.list - 实现方式:mcp_compat 进程内直调契约面 handler(与 HTTP 同一函数),不重写 SQL - 自动把 formData 等对象字段序列化为 TEXT,避免 value_to_text 静默丢弃 - 管理员头缓存按 SessionStore 实例缓存并设上界(防地址复用 602 与无界内存) - 新增 tests/mcp_tools_it.rs 6 条;全量 667 passed,verify.sh --smoke 14 步全绿 --- .workbuddy/memory/2026-11-02.md | 9 + HANDOFF.md | 29 +- PLAN.md | 2 +- crates/sspf-mcp/src/tools/admin.rs | 384 +++++++++++++++++ crates/sspf-mcp/src/tools/form.rs | 142 +++++++ crates/sspf-mcp/src/tools/mod.rs | 34 +- crates/sspf-mcp/src/tools/ops.rs | 156 +++++++ crates/sspf-mcp/src/tools/workflow.rs | 302 ++++++++++++++ docs/mcp.md | 30 +- src/backend/src/lib.rs | 1 + src/backend/src/mcp_adapter.rs | 56 +++ src/backend/src/mcp_compat.rs | 565 ++++++++++++++++++++++++++ src/backend/tests/mcp_tools_it.rs | 228 +++++++++++ 13 files changed, 1931 insertions(+), 7 deletions(-) create mode 100644 crates/sspf-mcp/src/tools/admin.rs create mode 100644 crates/sspf-mcp/src/tools/ops.rs create mode 100644 crates/sspf-mcp/src/tools/workflow.rs create mode 100644 src/backend/src/mcp_compat.rs create mode 100644 src/backend/tests/mcp_tools_it.rs diff --git a/.workbuddy/memory/2026-11-02.md b/.workbuddy/memory/2026-11-02.md index 008e7be..466fdcd 100644 --- a/.workbuddy/memory/2026-11-02.md +++ b/.workbuddy/memory/2026-11-02.md @@ -453,3 +453,12 @@ - 未修(有意):WS 推送(要真通道)、官方 vue 的四个死链菜单(React MVP 需要)。 - 复验:`cargo test --workspace` 661 passed;`verify.sh --smoke` 14 步全绿;586 探针 0 个 404/405/500;OPTIONS 765 全 405;浏览器 pageerror/404 资源清零。 - 🔴 探针教训:写探针必须用**不存在的 id**;本次因复用真实 admin id 又软删了一次,已恢复。脚本已改为非 GET 一律 DUMMY。 + +### 23:25–23:50 MCP 扩面:26 → 49 个业务工具(参考 dacli 命令面) +- 新增域:workflow×7、form.create/update/delete、ops×4、dict×3、menu×2、permission×3、context.app.list。 +- 实现方式:`src/backend/src/mcp_compat.rs` **进程内直调契约面 handler**(与 HTTP 同一函数),只造管理员头 + 转 ToolError;不重写 SQL。 +- 🔴 踩坑:handler 的 `value_to_text` 只收 string/number/bool ⇒ `formData` 传对象会被静默丢弃;mcp_compat 里统一把对象序列化成字符串。 +- 🔴 踩坑:管理员头缓存若只按 `Arc::as_ptr` 存,地址复用会让新 AppState 命中旧 token ⇒ 随机 602;必须连 `Arc` 一起存,并设上界(check-arch 的 MEM2 会拦无界缓存)。 +- `form.release` 本仓 handler 恒「不支持」,**刻意不注册**(不做假工具);同理未加 model/verify 死工具。 +- 测试:新增 `tests/mcp_tools_it.rs` 6 条;全量 667 passed;`verify.sh --smoke` 14 步全绿;mcp-smoke 34+14 全过。 +- 文档:docs/mcp.md 工具表 49 个;PLAN/HANDOFF 数字同步。 diff --git a/HANDOFF.md b/HANDOFF.md index 6e42233..1ebee6f 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -25,11 +25,34 @@ **有意没修**:① WebSocket `/api/message/websocket/{token}`(要真推送通道,静默挂起=假装连上); ② 四个业务菜单在官方 vue 里仍是死链(缺 views,属集成阶段;React MVP 需要这些菜单)。 -⇒ 复验:`cargo test --workspace` **661 passed / 0 failed**;`verify.sh --smoke` **14 步全绿**; +⇒ 复验:`cargo test --workspace` **667 passed / 0 failed**;`verify.sh --smoke` **14 步全绿**; 586 探针 **0 个 404/405/500**;OPTIONS 765 条全 405。 --- +## 0-0-bis. 2026-11-02 23:40 MCP 扩面:26 → 49 个业务工具 + +参考 dacli 的命令面,把 MCP 从「26 个工具」扩到 **49 个**(4 元工具不变,仍是分层加载): + +| 域 | 新增 | +|---|---| +| workflow | `template.list/info/create/update/delete/selector` + `task.list`(7) | +| form | `form.create / update / delete`(写定义;**release 本仓未支持,刻意不注册**) | +| ops | `ops.health / logs / online / schedule.list`(4) | +| dict | `type.update / type.delete / data.create`(3) | +| menu | `menu.info / menu.update`(2) | +| permission | `role.create / role.delete / user.delete`(3) | +| context | `context.app.list`(1) | + +🔴 **实现方式**:不重写 SQL,`src/backend/src/mcp_compat.rs` **进程内直调契约面 handler** +(与 HTTP 注册同一个函数),只负责造管理员请求头 + 把 `ActionResult` 转成 `ToolError`。 +⇒ 校验/默认值/软删语义只有一份。代价:MCP 适配器构造 `admin` 会话,**只适用于本地开发**。 + +🔴 新增 `src/backend/tests/mcp_tools_it.rs`(6 条)覆盖 CRUD 闭环与结构化失败; +`scripts/mcp-smoke.sh` 仍全绿(4 元工具 + 分层加载未被破坏)。 + +--- + ## 0. ⚠️ 修正上一版口径(很重要) 上一版说「跑 pnpm 必须 `dangerouslyDisableSandbox`」。**这条不完整**:真正拦住 fs 的是 @@ -381,8 +404,8 @@ React 模板的加模块成本 = **改/加 8 个文件、15~20 分钟**(`HOWTO - 契约端点 **765 条**(面 A 28 + 面 B **735** + 两面共用 2);`tables` → **153** (`schema.sql` **152** 张 + 业务包 1 张;平台表 `BASE_TABLES` **123** + `WORKFLOW_TABLES` **24** + `REPORT_TABLES` **2** + 内嵌业务表 3)。 -- `cargo test --offline --workspace` = **全绿 0 failed**(**661 passed**;主 lib 105; - `batch19_it` **7 passed**、`batch20_it` **6 passed**、`verify_fixes_it` **7 passed**)。 +- `cargo test --offline --workspace` = **全绿 0 failed**(**667 passed**;主 lib 105; + `batch19_it` **7**、`batch20_it` **6**、`verify_fixes_it` **7**、`mcp_tools_it` **6**)。 - 十二道闸门全绿;`check-contract` `PASS=10 FAIL=0`,官方端点覆盖 **751/757** (implemented 581 / partial 170 / absent 6;oos 4 单列)。 - `python3 scripts/fe-gap.py`:合计 **717 / 900(79.7%)**、**`msgCenter` 50/50(100%)**、 diff --git a/PLAN.md b/PLAN.md index 93d1020..4bc043e 100644 --- a/PLAN.md +++ b/PLAN.md @@ -256,7 +256,7 @@ ssw-platform/ | 平台/业务分层 | ✅ `check-boundary.sh` 钉住 | 升级为 crate 级隔离 | **P0 已拆 contract / store / sdk;asset 包可独立编译;`jnpf.rs`→`face_b.rs`** | | 低代码元数据引擎 | ✅ **P2-b 完成**:解析 + 校验 + 建表 + 动态 CRUD(6 个工具) | visualdev 同构 + 动态 CRUD + 发布 | 读 release / 单据号 / 乐观锁 → P2-c | | 业务包格式 | 🟡 `pack.toml` 已定稿、`packs/asset` 已有样板 | 导入导出工具 | **P3** | -| MCP 工具面 | 🟡 **P1 主体完成**:4 元工具 + registry + 分层加载 + 双适配器 + 26 个业务工具 + 3 个流程模板 | 约 55 个业务工具(补 model/workflow/release) | P1 收尾 | +| MCP 工具面 | 🟡 **P1 主体完成**:4 元工具 + registry + 分层加载 + 双适配器 + 49 个业务工具 + 3 个流程模板 | 约 55 个业务工具(补 model / verify / 发布) | P1 收尾 | | 影子对账 | ❌ 无 | 语料库 + 归一化比对 | **全新,P4** | | 部署形态 | 🟡 pglite 单二进制 | 单二进制 + 可选真实 PG | P5 收口 | diff --git a/crates/sspf-mcp/src/tools/admin.rs b/crates/sspf-mcp/src/tools/admin.rs new file mode 100644 index 0000000..e15af34 --- /dev/null +++ b/crates/sspf-mcp/src/tools/admin.rs @@ -0,0 +1,384 @@ +//! admin —— 字典 / 菜单 / 角色 / 用户 / 应用的**管理面**(对齐 dacli 的写命令)。 +//! +//! 全部直调契约面 handler(`platform/compat/*`),与 HTTP 同一套校验: +//! 编码唯一、父节点存在、系统内置角色不可删、管理员不可删 —— 这些规则不在 MCP 重写。 +//! +//! 🔴 删除一律**软删**;`permission.role.delete` / `permission.user.delete` +//! 会被后端按官方语义拦(系统角色、管理员、自己)。 + +use serde_json::Value; + +use crate::adapter::{BoxFut, PlatformAdapter, ToolError}; +use crate::registry::{Annotations, Category, Example, Hints, Pitfall, Severity, ToolDef}; + +macro_rules! passthrough { + ($name:ident, $op:literal) => { + fn $name<'a>( + adapter: &'a dyn PlatformAdapter, + args: Value, + ) -> BoxFut<'a, Result> { + Box::pin(async move { adapter.invoke($op, args).await }) + } + }; +} + +passthrough!(dict_type_update_handler, "dict.type.update"); +passthrough!(dict_type_delete_handler, "dict.type.delete"); +passthrough!(dict_data_create_handler, "dict.data.create"); +passthrough!(menu_info_handler, "menu.info"); +passthrough!(menu_update_handler, "menu.update"); +passthrough!(role_create_handler, "permission.role.create"); +passthrough!(role_delete_handler, "permission.role.delete"); +passthrough!(user_delete_handler, "permission.user.delete"); +passthrough!(app_list_handler, "context.app.list"); + +// ================================================================ dict.type.update + +pub const DICT_TYPE_UPDATE: ToolDef = ToolDef { + id: "dict.type.update", + category: Category::Dict, + title: "改字典分类", + one_liner: "按 id 改字典分类(只 SET 传了的键)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "分类 id(必填)" }, + "fullName": { "type": "string" }, + "enCode": { "type": "string" }, + "type": { "type": "integer", "description": "0=业务 1=系统" }, + "isTree": { "type": "integer", "enum": [0, 1] }, + "enabledMark": { "type": "integer", "enum": [0, 1] }, + "sortCode": { "type": "integer" }, + "description": { "type": "string" } + }, + "required": ["id"], + "additionalProperties": false + }"#, + annotations: Annotations::UPSERT, + hints: Hints { + when_to_use: &["改名 / 改分类 / 停用字典"], + when_not_to_use: &["改字典项(用 dict.data.create;改项暂未开放 MCP)"], + preconditions: &["先 dict.type.list 拿 id 并确认 enCode 不冲突"], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "改 enCode 后不同步前端引用", + right: "enCode 是前端取值键,改名要同步所有引用它的表单/代码", + rationale: "字典项按 enCode 被 `select` 控件引用;改编码后旧引用取不到值,\ + 下拉会静默变空。", + }], + examples: &[Example { + args: r#"{"id":"","fullName":"业务分类(新)"}"#, + note: "只改名", + }], + }, + handler: dict_type_update_handler, +}; + +// ================================================================ dict.type.delete + +pub const DICT_TYPE_DELETE: ToolDef = ToolDef { + id: "dict.type.delete", + category: Category::Dict, + title: "删字典分类", + one_liner: "软删字典分类(**不级联**字典项)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "分类 id(必填)" } + }, + "required": ["id"], + "additionalProperties": false + }"#, + annotations: Annotations::DESTRUCTIVE, + hints: Hints { + when_to_use: &["清理验证时建的临时字典"], + when_not_to_use: &["生产里被表单引用的字典(先确认没有引用)"], + preconditions: &["先 dict.data.list --typeId 确认项也要清"], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "以为删分类会把字典项一起删", + right: "本仓**不级联**;字典项会留在 base_dictionary_data 里成为孤儿", + rationale: "官方 DictionaryTypeController.delete 也只删分类。残留项不会被列举,\ + 但按 id 仍能查到 —— 排障时容易误判「删不掉」。", + }], + examples: &[Example { + args: r#"{"id":""}"#, + note: "确认无引用再删", + }], + }, + handler: dict_type_delete_handler, +}; + +// ================================================================ dict.data.create + +pub const DICT_DATA_CREATE: ToolDef = ToolDef { + id: "dict.data.create", + category: Category::Dict, + title: "加字典项", + one_liner: "往已有分类追加一个字典项", + input_schema: r#"{ + "type": "object", + "properties": { + "dictionaryTypeId": { "type": "string", "description": "分类 id(必填)" }, + "enCode": { "type": "string", "description": "项编码(必填)" }, + "fullName": { "type": "string", "description": "显示名(必填)" }, + "parentId": { "type": "string", "default": "0" }, + "sortCode": { "type": "integer", "default": 0 }, + "isDefault": { "type": "integer", "enum": [0, 1], "default": 0 }, + "enabledMark": { "type": "integer", "enum": [0, 1], "default": 1 } + }, + "required": ["dictionaryTypeId", "enCode", "fullName"], + "additionalProperties": false + }"#, + annotations: Annotations::CREATE, + hints: Hints { + when_to_use: &["给已有字典加选项", "造测试数据"], + when_not_to_use: &["建新分类(用 dict.type.create)"], + preconditions: &["dictionaryTypeId 必须存在;先 dict.type.list"], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "同一分类下重复 enCode", + right: "先 dict.data.list 查重;重复会被后端拒", + rationale: "官方按 (typeId, enCode) 做唯一性校验,但报错只说「已存在」,\ + 不告诉你是哪一条。", + }], + examples: &[Example { + args: r#"{"dictionaryTypeId":"","enCode":"draft","fullName":"草稿"}"#, + note: "最小可用", + }], + }, + handler: dict_data_create_handler, +}; + +// ================================================================ menu.info + +pub const MENU_INFO: ToolDef = ToolDef { + id: "menu.info", + category: Category::Menu, + title: "看菜单详情", + one_liner: "取菜单完整字段(改之前先看)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "菜单 id(必填)" } + }, + "required": ["id"], + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["改菜单前拿现状", "排查「菜单建了但不显示」"], + when_not_to_use: &["看整棵树(用 menu.tree)"], + preconditions: &["id 来自 menu.tree"], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "只看 urlAddress 就改", + right: "同时看 enCode / systemId / type / parentId", + rationale: "面 B 的权限判据是 enCode,多应用隔离靠 systemId;只改 urlAddress 可能\ + 页面能开但按钮全 403。", + }], + examples: &[Example { + args: r#"{"id":""}"#, + note: "先 tree 拿 id", + }], + }, + handler: menu_info_handler, +}; + +// ================================================================ menu.update + +pub const MENU_UPDATE: ToolDef = ToolDef { + id: "menu.update", + category: Category::Menu, + title: "改菜单", + one_liner: "按 id 改菜单(名称/地址/图标/排序/状态)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "菜单 id(必填)" }, + "fullName": { "type": "string" }, + "enCode": { "type": "string", "description": "权限编码(改了会改判据)" }, + "urlAddress": { "type": "string" }, + "icon": { "type": "string" }, + "sortCode": { "type": "integer" }, + "enabledMark": { "type": "integer", "enum": [0, 1] } + }, + "required": ["id"], + "additionalProperties": true + }"#, + annotations: Annotations::UPSERT, + hints: Hints { + when_to_use: &["改菜单名称/图标/排序", "修菜单地址错误"], + when_not_to_use: &["换父节点(本仓未开放 move;别硬改 parentId)"], + preconditions: &["先 menu.info 确认现状与 enCode"], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "随手改 enCode", + right: "enCode 是权限判据;改完所有授权记录都对不上,按钮/页面会 403", + rationale: "`base_authorize.f_item_id` 存的是菜单 id,但接口守卫按 enCode 判;\ + 两者不一致时表现为「授权了还是无权限」。", + }], + examples: &[Example { + args: r#"{"id":"","fullName":"用户管理(新)"}"#, + note: "只改名", + }], + }, + handler: menu_update_handler, +}; + +// ================================================================ role.create + +pub const ROLE_CREATE: ToolDef = ToolDef { + id: "permission.role.create", + category: Category::Permission, + title: "建角色", + one_liner: "建角色(enCode 全平台唯一)", + input_schema: r#"{ + "type": "object", + "properties": { + "fullName": { "type": "string", "description": "角色名(必填)" }, + "enCode": { "type": "string", "description": "角色编码(必填)" }, + "type": { "type": "string", "description": "0=全局 1=业务(默认 0)" }, + "enabledMark": { "type": "integer", "enum": [0, 1], "default": 1 }, + "sortCode": { "type": "integer", "default": 0 }, + "description": { "type": "string" } + }, + "required": ["fullName", "enCode"], + "additionalProperties": false + }"#, + annotations: Annotations::CREATE, + hints: Hints { + when_to_use: &["建新角色再做授权(推荐:先角色后授权)"], + when_not_to_use: &["只给一个人临时开权限(直接授给用户)"], + preconditions: &["enCode 全平台唯一;先 permission.role.list 查重"], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "建完角色就以为有权限", + right: "还要 permission.authorize.grant 授菜单", + rationale: "角色只是权限载体;没有授权记录时,用户登录后菜单是空的。", + }], + examples: &[Example { + args: r#"{"fullName":"运营","enCode":"ops_role"}"#, + note: "最小可用", + }], + }, + handler: role_create_handler, +}; + +// ================================================================ role.delete + +pub const ROLE_DELETE: ToolDef = ToolDef { + id: "permission.role.delete", + category: Category::Permission, + title: "删角色", + one_liner: "软删角色(系统内置角色删不掉)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "角色 id(必填)" } + }, + "required": ["id"], + "additionalProperties": false + }"#, + annotations: Annotations::DESTRUCTIVE, + hints: Hints { + when_to_use: &["清理验证角色"], + when_not_to_use: &["`isSystem=1` 的内置角色(必失败)"], + preconditions: &["先 permission.role.list 确认不是系统角色"], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "删还在被用户绑定的角色", + right: "先 permission.role.list 看用户数,必要时改绑", + rationale: "角色软删后用户↔角色关系仍在,但判权时角色已失效 ⇒ 用户突然少一批菜单,\ + 而且是静默的。", + }], + examples: &[Example { + args: r#"{"id":""}"#, + note: "确认后删", + }], + }, + handler: role_delete_handler, +}; + +// ================================================================ user.delete + +pub const USER_DELETE: ToolDef = ToolDef { + id: "permission.user.delete", + category: Category::Permission, + title: "删用户", + one_liner: "软删用户(管理员不可删)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "用户 id(必填)" } + }, + "required": ["id"], + "additionalProperties": false + }"#, + annotations: Annotations::DESTRUCTIVE, + hints: Hints { + when_to_use: &["清理验证账号"], + when_not_to_use: &["要保留审计的用户(改为停用 enabledMark=0)"], + preconditions: &["先 permission.user.list 拿 id"], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "删了用户再登录,看到「账号或密码错误」以为密码坏了", + right: "软删后 f_delete_mark<>0,登录查询直接不命中", + rationale: "登录 SQL 只查未软删行;被删账号与「密码错」返回**同一条**文案,\ + 现场极易误判。", + }], + examples: &[Example { + args: r#"{"id":""}"#, + note: "确认后删", + }], + }, + handler: user_delete_handler, +}; + +// ================================================================ context.app.list + +pub const APP_LIST: ToolDef = ToolDef { + id: "context.app.list", + category: Category::Context, + title: "列应用", + one_liner: "列多应用(base_system,默认不含主系统)", + input_schema: r#"{ + "type": "object", + "properties": { + "keyword": { "type": "string" }, + "type": { "type": "integer", "enum": [1, 2, 3], "description": "1=全部 2=我建的 3=授权给我的" }, + "currentPage": { "type": "integer", "default": 1 }, + "pageSize": { "type": "integer", "default": 20 } + }, + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["确认多应用环境有哪些 appCode", "切 appCode 前先看清单"], + when_not_to_use: &["看当前应用(用 context.get)"], + preconditions: &[], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "以为列表里应该有 mainSystem", + right: "默认 filterMain=true ⇒ 主系统被排除;看主系统用 context.get", + rationale: "官方 SystemController.list 默认过滤主系统;这是接口默认值,不是数据丢了。", + }], + examples: &[Example { + args: r#"{}"#, + note: "默认第一页", + }], + }, + handler: app_list_handler, +}; + +pub const ADMIN_TOOLS: &[ToolDef] = &[ + DICT_TYPE_UPDATE, + DICT_TYPE_DELETE, + DICT_DATA_CREATE, + MENU_INFO, + MENU_UPDATE, + ROLE_CREATE, + ROLE_DELETE, + USER_DELETE, + APP_LIST, +]; diff --git a/crates/sspf-mcp/src/tools/form.rs b/crates/sspf-mcp/src/tools/form.rs index 0d4f7ef..efd3135 100644 --- a/crates/sspf-mcp/src/tools/form.rs +++ b/crates/sspf-mcp/src/tools/form.rs @@ -220,3 +220,145 @@ pub const FORM_VALIDATE: ToolDef = ToolDef { }, handler: validate_handler, }; + +// ================================================================ form.create +// +// 写表单定义(P2-c):直接复用契约面 `visual_dev_create` 的校验与落库逻辑 +// (名称/编码查重、系统隔离、state 默认 0),MCP 只负责把 JSON 递进去。 + +passthrough!(create_handler, "form.create"); + +pub const FORM_CREATE: ToolDef = ToolDef { + id: "form.create", + category: Category::Form, + title: "建低代码功能", + one_liner: "建表单定义(草稿态;formData 可直接传对象)", + input_schema: r#"{ + "type": "object", + "properties": { + "fullName": { "type": "string", "description": "功能名称(必填)" }, + "enCode": { "type": "string", "description": "功能编码(建议填,全平台唯一)" }, + "type": { "type": "integer", "enum": [1, 2, 3, 4], "description": "1=在线开发 2=流程表单(默认 1)" }, + "category": { "type": "string", "description": "分类 id(可选)" }, + "formData": { "type": ["object", "string"], "description": "表单 JSON(控件树);对象会自动序列化" }, + "columnData": { "type": ["object", "string"], "description": "列配置 JSON" }, + "tablesData": { "type": ["object", "string"], "description": "子表 JSON" }, + "dbLinkId": { "type": "string", "description": "业务库 id(默认 0=主库)" }, + "enableFlow": { "type": "integer", "enum": [0, 1] }, + "description": { "type": "string" }, + "sortCode": { "type": "integer" } + }, + "required": ["fullName"], + "additionalProperties": true + }"#, + annotations: Annotations::CREATE, + hints: Hints { + when_to_use: &["要把一份设计稿落成低代码功能"], + when_not_to_use: &["只想建物理表(用 schema.table.create)", "想建菜单(用 menu.create)"], + preconditions: &[ + "enCode 建议必填且全平台唯一;不填后续绑定/发布都没有稳定键", + "formData 传对象即可(工具会序列化);不要自己再 JSON.stringify 一层", + ], + pitfalls: &[ + Pitfall { + severity: Severity::P0, + wrong: "把 formData 传成「字符串包字符串」", + right: "直接传对象,或传一次序列化后的字符串", + rationale: "handler 对 TEXT 列只收 string/number/bool;对象会被 value_to_text 丢掉,\ + 双重字符串则会存进带转义的垃圾(前端渲染空白)。工具已对对象自动序列化。", + }, + Pitfall { + severity: Severity::P1, + wrong: "建完不发布就期待前端菜单能打开", + right: "form.create 只建草稿(state=0);要调 form.release", + rationale: "运行时读 base_visual_release;草稿只在设计器里可见。", + }, + ], + examples: &[ + Example { + args: r#"{"fullName":"验证表单","enCode":"demo_verify_form"}"#, + note: "最小可用(空表单)", + }, + ], + }, + handler: create_handler, +}; + +// ================================================================ form.update + +passthrough!(update_handler, "form.update"); + +pub const FORM_UPDATE: ToolDef = ToolDef { + id: "form.update", + category: Category::Form, + title: "改低代码功能", + one_liner: "按 id 改表单定义(只 SET 传了的键)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "功能 id(必填)" }, + "fullName": { "type": "string" }, + "enCode": { "type": "string" }, + "formData": { "type": ["object", "string"] }, + "columnData": { "type": ["object", "string"] }, + "tablesData": { "type": ["object", "string"] }, + "enableFlow": { "type": "integer", "enum": [0, 1] }, + "description": { "type": "string" } + }, + "required": ["id"], + "additionalProperties": true + }"#, + annotations: Annotations::UPSERT, + hints: Hints { + when_to_use: &["改字段 / 改列配置 / 换绑流程"], + when_not_to_use: &["只改发布态(用 form.release)"], + preconditions: &["先 form.describe 拿现状;改完要 form.release 才生效"], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "改完 formData 不 release 就以为生效", + right: "update 只改草稿;运行时仍读旧 release 快照", + rationale: "base_visual_dev 与 base_visual_release 是两份数据,发布才复制。", + }], + examples: &[Example { + args: r#"{"id":"","fullName":"验证表单 v2"}"#, + note: "只改名", + }], + }, + handler: update_handler, +}; + +// ================================================================ form.delete + +passthrough!(delete_handler, "form.delete"); + +pub const FORM_DELETE: ToolDef = ToolDef { + id: "form.delete", + category: Category::Form, + title: "删低代码功能", + one_liner: "软删功能(菜单需另行清理)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "功能 id(必填)" } + }, + "required": ["id"], + "additionalProperties": false + }"#, + annotations: Annotations::DESTRUCTIVE, + hints: Hints { + when_to_use: &["清理验证功能"], + when_not_to_use: &["还在被菜单引用的功能(先删菜单)"], + preconditions: &["先 form.list 确认 state 与引用"], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "删功能后以为菜单会一起消失", + right: "菜单在 base_module,另有一套生命周期;用 menu.delete / menu.tree 处理", + rationale: "官方 VisualDevController.delete 只删功能与发布快照,不碰菜单。", + }], + examples: &[Example { + args: r#"{"id":""}"#, + note: "确认后删", + }], + }, + handler: delete_handler, +}; diff --git a/crates/sspf-mcp/src/tools/mod.rs b/crates/sspf-mcp/src/tools/mod.rs index 6ee9613..8fca151 100644 --- a/crates/sspf-mcp/src/tools/mod.rs +++ b/crates/sspf-mcp/src/tools/mod.rs @@ -18,11 +18,14 @@ //! //! 🔴 **不需要改 `META_TOOLS`,也不需要改协议层** —— 这是加工具的正常成本。 +pub mod admin; pub mod business; pub mod form; pub mod lowcode; pub mod meta; +pub mod ops; pub mod permission; +pub mod workflow; pub mod write; use serde_json::Value; @@ -192,8 +195,10 @@ const MENU_TREE_TOOL: ToolDef = ToolDef { /// | P1-d 授权闭环 | 4 | grant / revoke / effective / user.create | /// | P2-a 低代码读 | 3 | form.list / describe / validate | /// | P2-b 低代码写 | 4 | schema.table.create + data.record.insert / update / delete | +/// | P2-c 表单定义 | 3 | form.create / update / delete(release 本仓未支持,不注册) | +/// | P3 dacli 对齐 | 24 | workflow ×7 / ops ×4 / dict+menu+role+user+app ×9 | /// -/// 合计 **26 个**。后续按 `PLAN.md` §6.3 的 12 域补齐到约 55 个。 +/// 合计 **49 个**(`PLAN.md` §6.3 目标约 55,剩 model / verify / 其它 release 工具)。 /// /// 🔴 改这个数组就要同步改这一行数字 —— `tool_count_matches_doc` 会钉住它。 pub static ALL_TOOLS: &[ToolDef] = &[ @@ -229,6 +234,31 @@ pub static ALL_TOOLS: &[ToolDef] = &[ lowcode::DATA_RECORD_INSERT, lowcode::DATA_RECORD_UPDATE, lowcode::DATA_RECORD_DELETE, + // —— 第七批(P2-c):表单定义写入 + 发布(直调契约面 handler)—— + form::FORM_CREATE, + form::FORM_UPDATE, + form::FORM_DELETE, + // —— 第八批(P3):流程元数据 / 运维 / 管理面(对齐 dacli 命令面)—— + workflow::TEMPLATE_LIST, + workflow::TEMPLATE_INFO, + workflow::TEMPLATE_CREATE, + workflow::TEMPLATE_UPDATE, + workflow::TEMPLATE_DELETE, + workflow::TEMPLATE_SELECTOR, + workflow::TASK_LIST, + ops::HEALTH, + ops::LOGS, + ops::ONLINE, + ops::SCHEDULE_LIST, + admin::DICT_TYPE_UPDATE, + admin::DICT_TYPE_DELETE, + admin::DICT_DATA_CREATE, + admin::MENU_INFO, + admin::MENU_UPDATE, + admin::ROLE_CREATE, + admin::ROLE_DELETE, + admin::USER_DELETE, + admin::APP_LIST, ]; #[cfg(test)] @@ -270,7 +300,7 @@ mod tests { fn tool_count_matches_doc() { assert_eq!( ALL_TOOLS.len(), - 26, + 49, "ALL_TOOLS 数量变了:同步改 `ALL_TOOLS` 的文档表、PLAN.md 与 docs/mcp.md" ); } diff --git a/crates/sspf-mcp/src/tools/ops.rs b/crates/sspf-mcp/src/tools/ops.rs new file mode 100644 index 0000000..6f7af77 --- /dev/null +++ b/crates/sspf-mcp/src/tools/ops.rs @@ -0,0 +1,156 @@ +//! ops —— 运维视角(健康 / 日志 / 在线会话 / 定时任务)。 +//! +//! 对齐 dacli 的 `app status` / `log *` / `monitor online` / `schedule list`。 +//! 四个工具**全只读**:排障时先看这里,别一上来就改数据。 + +use serde_json::Value; + +use crate::adapter::{BoxFut, PlatformAdapter, ToolError}; +use crate::registry::{Annotations, Category, Example, Hints, Pitfall, Severity, ToolDef}; + +macro_rules! passthrough { + ($name:ident, $op:literal) => { + fn $name<'a>( + adapter: &'a dyn PlatformAdapter, + args: Value, + ) -> BoxFut<'a, Result> { + Box::pin(async move { adapter.invoke($op, args).await }) + } + }; +} + +passthrough!(health_handler, "ops.health"); +passthrough!(logs_handler, "ops.logs"); +passthrough!(online_handler, "ops.online"); +passthrough!(schedule_handler, "ops.schedule.list"); + +// ================================================================ health + +pub const HEALTH: ToolDef = ToolDef { + id: "ops.health", + category: Category::Ops, + title: "健康检查", + one_liner: "表数 / 会话数 / admin 是否就绪(不走 HTTP)", + input_schema: r#"{"type":"object","properties":{},"additionalProperties":false}"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["开工第一步确认库连上了", "写库前确认表已建(tables 数)"], + when_not_to_use: &["要看具体表结构(用 schema.table.list)"], + preconditions: &[], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "把 `tables` 当成「业务表数量」", + right: "它是当前 schema 的全部 BASE TABLE(含 base_* 平台表)", + rationale: "平台表 120+ 张;业务表只有个位数。看业务表用 schema.table.list + 前缀过滤。", + }], + examples: &[Example { + args: r#"{}"#, + note: "无参数", + }], + }, + handler: health_handler, +}; + +// ================================================================ logs + +pub const LOGS: ToolDef = ToolDef { + id: "ops.logs", + category: Category::Ops, + title: "查系统日志", + one_liner: "按分类分页查 base_sys_log(登录/操作/异常/请求)", + input_schema: r#"{ + "type": "object", + "properties": { + "category": { "type": "integer", "enum": [1, 3, 4, 5], "description": "1=登录 3=操作 4=异常 5=请求(必填)" }, + "keyword": { "type": "string", "description": "按内容模糊搜" }, + "startTime": { "type": "string", "description": "起始时间(YYYY-MM-DD HH:mm:ss)" }, + "endTime": { "type": "string", "description": "结束时间" }, + "currentPage": { "type": "integer", "default": 1 }, + "pageSize": { "type": "integer", "default": 20 } + }, + "required": ["category"], + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["登录失败 / 接口 500 后找现场", "确认某操作有没有被记录"], + when_not_to_use: &["找业务数据(用 data.query)"], + preconditions: &["category 只接受 1/3/4/5;其它值会明确报「获取失败」"], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "传 category=2 或 category=login", + right: "用数字 1(登录)/3(操作)/4(异常)/5(请求)", + rationale: "后端按整数分支查不同的投影;字符串会被 parse 成 0 ⇒ 直接拒。", + }], + examples: &[Example { + args: r#"{"category":1,"pageSize":5}"#, + note: "最近 5 条登录日志", + }], + }, + handler: logs_handler, +}; + +// ================================================================ online + +pub const ONLINE: ToolDef = ToolDef { + id: "ops.online", + category: Category::Ops, + title: "在线会话", + one_liner: "按账号聚合的在线会话(不返回 token)", + input_schema: r#"{"type":"object","properties":{},"additionalProperties":false}"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["确认自己刚登录的 token 在不在", "排查「为什么我 602」"], + when_not_to_use: &["要看在线用户业务资料(用 permission.user.list)"], + preconditions: &[], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "用 token 数量判断在线人数", + right: "按 account 聚合;一个人可以有多个会话(多标签页/多设备)", + rationale: "SessionStore 以 token 为键;同账号多次登录会留下多条。工具已按账号聚合。", + }], + examples: &[Example { + args: r#"{}"#, + note: "无参数", + }], + }, + handler: online_handler, +}; + +// ================================================================ schedule + +pub const SCHEDULE_LIST: ToolDef = ToolDef { + id: "ops.schedule.list", + category: Category::Ops, + title: "列定时任务", + one_liner: "列 Quartz 定时任务(本仓只存定义,不跑调度)", + input_schema: r#"{ + "type": "object", + "properties": { + "keyword": { "type": "string" }, + "currentPage": { "type": "integer", "default": 1 }, + "pageSize": { "type": "integer", "default": 20 } + }, + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["看有哪些定时任务定义"], + when_not_to_use: &["期待任务真的会按 cron 跑(本仓没有 Quartz 执行器)"], + preconditions: &[], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "建了定时任务就以为它会自己执行", + right: "本仓只落 base_time_task 定义,没有调度进程", + rationale: "官方用 Quartz + 独立调度线程;本仓是单二进制、无后台任务框架,\ + 触发端点也明确返回「不支持」。", + }], + examples: &[Example { + args: r#"{"pageSize":10}"#, + note: "通常为空", + }], + }, + handler: schedule_handler, +}; + +pub const OPS_TOOLS: &[ToolDef] = &[HEALTH, LOGS, ONLINE, SCHEDULE_LIST]; diff --git a/crates/sspf-mcp/src/tools/workflow.rs b/crates/sspf-mcp/src/tools/workflow.rs new file mode 100644 index 0000000..a85b042 --- /dev/null +++ b/crates/sspf-mcp/src/tools/workflow.rs @@ -0,0 +1,302 @@ +//! workflow —— 流程模板与任务的**元数据面**(MCP 直调契约面 handler)。 +//! +//! 与 dacli 的 `workflow list/info/create/update/delete/selector/tasks` 对齐。 +//! +//! 🔴 **只覆盖元数据**:官方流程引擎是独立 HTTP 服务(`FlowAbleUrl`), +//! 发起 / 审批 / 转审这些「动作」本仓没有引擎,MCP 也不假装能做 —— +//! 它们会返回 `code=400 + 人话`,AI 应从 `form.list` / `workflow.template.list` +//! 确认「模板在、引擎不在」。 + +use serde_json::Value; + +use crate::adapter::{BoxFut, PlatformAdapter, ToolError}; +use crate::registry::{Annotations, Category, Example, Hints, Pitfall, Severity, ToolDef}; + +macro_rules! passthrough { + ($name:ident, $op:literal) => { + fn $name<'a>( + adapter: &'a dyn PlatformAdapter, + args: Value, + ) -> BoxFut<'a, Result> { + Box::pin(async move { adapter.invoke($op, args).await }) + } + }; +} + +passthrough!(list_handler, "workflow.template.list"); +passthrough!(info_handler, "workflow.template.info"); +passthrough!(create_handler, "workflow.template.create"); +passthrough!(update_handler, "workflow.template.update"); +passthrough!(delete_handler, "workflow.template.delete"); +passthrough!(selector_handler, "workflow.template.selector"); +passthrough!(tasks_handler, "workflow.task.list"); + +// ================================================================ list + +pub const TEMPLATE_LIST: ToolDef = ToolDef { + id: "workflow.template.list", + category: Category::Workflow, + title: "列流程模板", + one_liner: "列出流程模板(元数据;引擎动作本仓没有)", + input_schema: r#"{ + "type": "object", + "properties": { + "keyword": { "type": "string", "description": "按名称/编码模糊搜" }, + "category": { "type": "string", "description": "流程分类 id(可选)" }, + "type": { "type": "integer", "description": "模板类型(可选)" }, + "state": { "type": "integer", "description": "状态(可选)" }, + "currentPage": { "type": "integer", "default": 1 }, + "pageSize": { "type": "integer", "default": 20 } + }, + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["建表单前看有没有可绑的流程", "排查「流程管理页空白」"], + when_not_to_use: &["要发起/审批流程(本仓没有 Flowable 引擎,调了会明确失败)"], + preconditions: &["流程模板与表单是两套东西:模板在 workflow_template,表单在 base_visual_dev"], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "看到模板列表有数据,就认为「流程能发起」", + right: "模板只是元数据;发起/审批要 Flowable 独立服务,本仓恒 code=400", + rationale: "批次 19 只导入了 workflow_* 元数据表,没有导入 Flowable 的 act_* 引擎表,\ + 也没有接 FlowAbleUrl。列表能看不等于能跑。", + }], + examples: &[Example { + args: r#"{"keyword":"报销","pageSize":10}"#, + note: "按名字找流程模板", + }], + }, + handler: list_handler, +}; + +// ================================================================ info + +pub const TEMPLATE_INFO: ToolDef = ToolDef { + id: "workflow.template.info", + category: Category::Workflow, + title: "看流程模板", + one_liner: "取一个流程模板的完整元数据(节点/版本)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "workflow_template.f_id" } + }, + "required": ["id"], + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["改模板前先看现状", "确认表单绑的是哪个流程"], + when_not_to_use: &["只要列表(用 workflow.template.list)"], + preconditions: &["id 来自 workflow.template.list"], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "把模板 id 和版本 id 混用", + right: "模板 id 在 workflow_template;版本 id 在 workflow_version", + rationale: "两者都是 32/36 位串,长度接近;传错只会得到「流程不存在」,看不出是层级错了。", + }], + examples: &[Example { + args: r#"{"id":""}"#, + note: "先 list 拿 id", + }], + }, + handler: info_handler, +}; + +// ================================================================ create + +pub const TEMPLATE_CREATE: ToolDef = ToolDef { + id: "workflow.template.create", + category: Category::Workflow, + title: "新建流程模板", + one_liner: "建流程模板(只写元数据,不含引擎流程 XML)", + input_schema: r#"{ + "type": "object", + "properties": { + "fullName": { "type": "string", "description": "流程名称(必填)" }, + "enCode": { "type": "string", "description": "流程编码(必填,英文)" }, + "type": { "type": "integer", "description": "模板类型(可选)" }, + "category": { "type": "string", "description": "分类 id(可选)" }, + "formId": { "type": "string", "description": "绑定的表单 id(可选)" }, + "sortCode": { "type": "integer" }, + "description": { "type": "string" } + }, + "required": ["fullName", "enCode"], + "additionalProperties": true + }"#, + annotations: Annotations::CREATE, + hints: Hints { + when_to_use: &["要在流程管理里出现一个新模板"], + when_not_to_use: &["想跑审批(先确认已接 Flowable;本仓没有)"], + preconditions: &["enCode 全局唯一;建议 _ 前缀"], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "以为建了模板就能审批", + right: "模板只是定义;发起/审批仍会 code=400(无引擎)", + rationale: "引擎动作在 OperatorController/TaskController,本仓 27 条全部「诚实失败」。", + }], + examples: &[Example { + args: r#"{"fullName":"报销审批","enCode":"demo_expense_flow"}"#, + note: "最小可用", + }], + }, + handler: create_handler, +}; + +// ================================================================ update + +pub const TEMPLATE_UPDATE: ToolDef = ToolDef { + id: "workflow.template.update", + category: Category::Workflow, + title: "改流程模板", + one_liner: "按 id 改模板元数据(只 SET 传了的键)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "模板 id(必填)" }, + "fullName": { "type": "string" }, + "enCode": { "type": "string" }, + "formId": { "type": "string" }, + "sortCode": { "type": "integer" }, + "description": { "type": "string" } + }, + "required": ["id"], + "additionalProperties": true + }"#, + annotations: Annotations::UPSERT, + hints: Hints { + when_to_use: &["改名 / 换绑表单 / 改排序"], + when_not_to_use: &["改流程节点连线(那是引擎侧的 flowXml,本仓不落)"], + preconditions: &["先 workflow.template.info 确认现状"], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "只传 id 期望「清空」字段", + right: "PUT 语义是「只改传了的键」,没传的保持原值", + rationale: "与官方 Mybatis 非 null 更新一致;传空对象等于什么都不改。", + }], + examples: &[Example { + args: r#"{"id":"","fullName":"报销审批 v2"}"#, + note: "只改名字", + }], + }, + handler: update_handler, +}; + +// ================================================================ delete + +pub const TEMPLATE_DELETE: ToolDef = ToolDef { + id: "workflow.template.delete", + category: Category::Workflow, + title: "删流程模板", + one_liner: "软删模板(引用它的表单会失效)", + input_schema: r#"{ + "type": "object", + "properties": { + "id": { "type": "string", "description": "模板 id(必填)" } + }, + "required": ["id"], + "additionalProperties": false + }"#, + annotations: Annotations::DESTRUCTIVE, + hints: Hints { + when_to_use: &["清理验证用的临时模板"], + when_not_to_use: &["生产里被表单引用的模板(先解绑)"], + preconditions: &["先 workflow.template.info 确认不是在用模板"], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "直接删还在被 form.flowId 引用的模板", + right: "先改表单解绑,再删模板", + rationale: "流程模板删除后,引用它的表单在运行时会找不到流程定义,页面不报错但发起按钮失效。", + }], + examples: &[Example { + args: r#"{"id":""}"#, + note: "确认后再删", + }], + }, + handler: delete_handler, +}; + +// ================================================================ selector + +pub const TEMPLATE_SELECTOR: ToolDef = ToolDef { + id: "workflow.template.selector", + category: Category::Workflow, + title: "流程下拉", + one_liner: "给表单/菜单选流程用(精简列表)", + input_schema: r#"{ + "type": "object", + "properties": { + "keyword": { "type": "string" }, + "category": { "type": "string" }, + "currentPage": { "type": "integer", "default": 1 }, + "pageSize": { "type": "integer", "default": 20 } + }, + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["建菜单挂流程前拿 id", "给表单绑流程"], + when_not_to_use: &["要看模板详情(用 info)"], + preconditions: &[], + pitfalls: &[Pitfall { + severity: Severity::P2, + wrong: "拿下拉里的名字当唯一键", + right: "始终用 id 关联", + rationale: "模板允许同名不同编码;名字不是唯一键。", + }], + examples: &[Example { + args: r#"{"pageSize":10}"#, + note: "拿前 10 个", + }], + }, + handler: selector_handler, +}; + +// ================================================================ tasks + +pub const TASK_LIST: ToolDef = ToolDef { + id: "workflow.task.list", + category: Category::Workflow, + title: "列流程任务", + one_liner: "列任务元数据(本仓无引擎 ⇒ 通常为空)", + input_schema: r#"{ + "type": "object", + "properties": { + "keyword": { "type": "string" }, + "type": { "type": "integer" }, + "category": { "type": "integer" }, + "currentPage": { "type": "integer", "default": 1 }, + "pageSize": { "type": "integer", "default": 20 } + }, + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["确认某个流程有没有产生过任务记录"], + when_not_to_use: &["想看「我的待办」(那是引擎侧查询,本仓没有)"], + preconditions: &[], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "把空列表当成「查询条件写错了」", + right: "本仓没有引擎,任务表本来就不会新增行", + rationale: "批次 19 只导了元数据;没有发起动作就不会有任务。空是正确结果。", + }], + examples: &[Example { + args: r#"{"pageSize":10}"#, + note: "通常返回空", + }], + }, + handler: tasks_handler, +}; + +/// 本域全部工具(供 `tools/mod.rs` 汇总)。 +pub const WORKFLOW_TOOLS: &[ToolDef] = &[ + TEMPLATE_LIST, + TEMPLATE_INFO, + TEMPLATE_CREATE, + TEMPLATE_UPDATE, + TEMPLATE_DELETE, + TEMPLATE_SELECTOR, + TASK_LIST, +]; diff --git a/docs/mcp.md b/docs/mcp.md index 6c155b7..724eeff 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -80,21 +80,27 @@ sspf_context # 1. 先确认环境 → 失败则读 error.hints / next_actions 自纠 ``` -### 当前业务工具(26 个) +### 当前业务工具(49 个) | 域 | 工具 | 一句话 | 写 | |---|---|---|---| | context | `context.get` | 取后端/应用/表数 | | +| context | `context.app.list` | 列多应用(`base_system`,默认不含主系统) | | | schema | `schema.table.list` | 列出物理表 | | | schema | `schema.table.describe` | 看表的列与类型 | | | schema | `schema.index.list` | 索引与唯一约束 | | | schema | `schema.table.create` | 按低代码设计稿建表 + 回写模型 | ✅ | | menu | `menu.tree` | 菜单树(按应用隔离) | | +| menu | `menu.info` | 菜单详情(改之前先看) | | | menu | `menu.create` | 建菜单(写全 enCode + systemId) | ✅ | +| menu | `menu.update` | 改菜单(名称/地址/图标/排序) | ✅ | | menu | `menu.delete` | 软删菜单 | ✅ | | permission | `permission.user.list` | 用户(**不含口令字段**) | | | permission | `permission.user.create` | 建普通用户(可同时绑角色) | ✅ | +| permission | `permission.user.delete` | 软删用户(管理员不可删) | ✅ | | permission | `permission.role.list` | 角色 | | +| permission | `permission.role.create` | 建角色(enCode 全平台唯一) | ✅ | +| permission | `permission.role.delete` | 软删角色(系统角色不可删) | ✅ | | permission | `permission.authorize.list` | 查某对象的直授 | | | permission | `permission.authorize.grant` | 给用户/角色/组织/岗位授菜单(幂等) | ✅ | | permission | `permission.authorize.revoke` | 撤权(软删,撤不存在会报错) | ✅ | @@ -102,6 +108,9 @@ sspf_context # 1. 先确认环境 | dict | `dict.type.list` | 字典分类 | | | dict | `dict.data.list` | 字典项 | | | dict | `dict.type.create` | 建字典分类 | ✅ | +| dict | `dict.type.update` | 改字典分类 | ✅ | +| dict | `dict.type.delete` | 软删分类(**不级联**字典项) | ✅ | +| dict | `dict.data.create` | 往分类追加字典项 | ✅ | | data | `data.query` | 按表名查数据(结构化条件) | | | data | `data.count` | 按表名计数 | | | data | `data.record.insert` | 按设计稿新增记录(主表 + 子表) | ✅ | @@ -110,6 +119,25 @@ sspf_context # 1. 先确认环境 | form | `form.list` | 列低代码功能(`base_visual_dev`) | | | form | `form.describe` | 解析表单:主表字段/子表/控件类型 | | | form | `form.validate` | 校验表单声明的字段在表里是否真有列 | | +| form | `form.create` | 建表单定义(草稿态;`formData` 可传对象) | ✅ | +| form | `form.update` | 改表单定义(只 SET 传了的键) | ✅ | +| form | `form.delete` | 软删功能(菜单需另行清理) | ✅ | +| workflow | `workflow.template.list` | 流程模板列表(元数据) | | +| workflow | `workflow.template.info` | 模板详情 | | +| workflow | `workflow.template.create` | 建模板(只写元数据) | ✅ | +| workflow | `workflow.template.update` | 改模板 | ✅ | +| workflow | `workflow.template.delete` | 软删模板 | ✅ | +| workflow | `workflow.template.selector` | 流程下拉(绑表单/菜单用) | | +| workflow | `workflow.task.list` | 任务元数据(无引擎 ⇒ 通常为空) | | +| ops | `ops.health` | 表数 / 会话数 / admin 就绪 | | +| ops | `ops.logs` | 按分类查系统日志 | | +| ops | `ops.online` | 按账号聚合的在线会话(不含 token) | | +| ops | `ops.schedule.list` | 定时任务定义(不跑调度) | | + +**P3 这批(23 个)怎么实现的**:不重写 SQL,而是**进程内直调契约面 handler** +(`src/backend/src/mcp_compat.rs`),与 HTTP 路由注册的是同一个函数 ⇒ 校验、默认值、 +软删语义只有一份。代价是 MCP 适配器必须构造管理员请求头(`SessionStore::issue` 一个 +`admin` 会话),所以**它只适用于本地开发**;对外暴露要走 `BaselineHttpAdapter` 带真实 token。 **写工具为什么少而严**:读工具错了只是「看到错的数据」,写工具错了是「把库改坏」。 所以写工具都在写库**之前**做完校验(必填/格式/父节点存在/编码唯一), diff --git a/src/backend/src/lib.rs b/src/backend/src/lib.rs index c5c254f..3d69cda 100644 --- a/src/backend/src/lib.rs +++ b/src/backend/src/lib.rs @@ -18,6 +18,7 @@ pub mod lowcode_crud; pub mod lowcode_ddl; pub mod lowcode_seed; pub mod mcp_adapter; +pub mod mcp_compat; pub mod modules; // 🔴 **本文件是 `scripts/pack-sync.py` 生成的**(业务包清单 + `pack.toml` 快照) // ⇒ 不要手改;加包跑 `bash scripts/new-pack.sh`。 diff --git a/src/backend/src/mcp_adapter.rs b/src/backend/src/mcp_adapter.rs index 5a6ac15..6ceb704 100644 --- a/src/backend/src/mcp_adapter.rs +++ b/src/backend/src/mcp_adapter.rs @@ -2538,6 +2538,62 @@ impl PlatformAdapter for NativeAdapter { "data.record.update" => self.data_record_update(&args).await, "data.record.delete" => self.data_record_delete(&args).await, + // ------------------------------------------------ 流程(直调契约面 handler) + "workflow.template.list" => { + crate::mcp_compat::workflow_template_list(&self.state, args).await + } + "workflow.template.info" => { + crate::mcp_compat::workflow_template_info(&self.state, args).await + } + "workflow.template.create" => { + crate::mcp_compat::workflow_template_create(&self.state, args).await + } + "workflow.template.update" => { + crate::mcp_compat::workflow_template_update(&self.state, args).await + } + "workflow.template.delete" => { + crate::mcp_compat::workflow_template_delete(&self.state, args).await + } + "workflow.template.selector" => { + crate::mcp_compat::workflow_template_selector(&self.state, args).await + } + "workflow.task.list" => { + crate::mcp_compat::workflow_task_list(&self.state, args).await + } + + // ------------------------------------------------ 字典 / 菜单(写) + "dict.type.update" => crate::mcp_compat::dict_type_update(&self.state, args).await, + "dict.type.delete" => crate::mcp_compat::dict_type_delete(&self.state, args).await, + "dict.data.create" => crate::mcp_compat::dict_data_create(&self.state, args).await, + "menu.info" => crate::mcp_compat::menu_info(&self.state, args).await, + "menu.update" => crate::mcp_compat::menu_update(&self.state, args).await, + + // ------------------------------------------------ 权限(角色 / 用户) + "permission.role.create" => { + crate::mcp_compat::role_create(&self.state, args).await + } + "permission.role.delete" => { + crate::mcp_compat::role_delete(&self.state, args).await + } + "permission.user.delete" => { + crate::mcp_compat::user_delete(&self.state, args).await + } + + // ------------------------------------------------ 低代码表单(写 / 发布) + "form.create" => crate::mcp_compat::form_create(&self.state, args).await, + "form.update" => crate::mcp_compat::form_update(&self.state, args).await, + "form.delete" => crate::mcp_compat::form_delete(&self.state, args).await, + "form.release" => crate::mcp_compat::form_release(&self.state, args).await, + + // ------------------------------------------------ 应用 / 运维 + "context.app.list" => crate::mcp_compat::app_list(&self.state, args).await, + "ops.health" => crate::mcp_compat::ops_health(&self.state, args).await, + "ops.logs" => crate::mcp_compat::ops_logs(&self.state, args).await, + "ops.online" => crate::mcp_compat::ops_online(&self.state, args).await, + "ops.schedule.list" => { + crate::mcp_compat::ops_schedule_list(&self.state, args).await + } + other => Err(ToolError::new( "OP_NOT_IMPLEMENTED", format!("原生适配器还没实现 op: {other}"), diff --git a/src/backend/src/mcp_compat.rs b/src/backend/src/mcp_compat.rs new file mode 100644 index 0000000..f5d0b4d --- /dev/null +++ b/src/backend/src/mcp_compat.rs @@ -0,0 +1,565 @@ +//! mcp_compat —— MCP 工具对**契约面 handler** 的进程内直调。 +//! +//! ## 为什么直调 handler,而不是重写一遍 SQL +//! +//! MCP 与 HTTP 是同一套能力的两个入口。若 MCP 自己拼 SQL,两边会**双份实现**: +//! 校验规则、默认值、软删语义、审计列都会各写一遍 ⇒ 必然漂移(dacli 踩过: +//! 50+ 处漂移修了 6 周)。这里直接调 `platform::compat::*` 的 handler +//! (与 HTTP 路由注册的是同一个函数),语义天然一致。 +//! +//! ## 身份从哪来 +//! +//! 进程内没有 HTTP 登录态。这里给 handler 造一套**管理员请求头**: +//! 用 `SessionStore::issue` 签发一个 `admin` 会话(与 HTTP 登录同一个表), +//! 再把 token 塞进 `Authorization`。`App-Code` 默认 `mainSystem`,可由工具入参覆盖。 +//! +//! 🔴 **等价于「本地 AI 就是管理员」** —— 与 `mcp_adapter.rs` 顶部的安全前提一致: +//! 该适配器只用于本地开发;对外暴露必须走 `BaselineHttpAdapter` 带真实 token。 +//! +//! ## 失败怎么报 +//! +//! handler 返回 `ActionResult{code,msg,data}`: +//! - `code=200` ⇒ 透传 `data`;`data` 为 null 时回 `{ok:true,msg}`(保留官方提示语) +//! - 其它 ⇒ `ToolError`(`BUSINESS_FAILED` / `NO_PERMISSION` / `NOT_LOGGED_IN`), +//! 带 `hints + next_actions`,让 AI 自己改参数而不是原样重试。 + +use std::collections::HashMap; +use std::sync::{Arc, Mutex, OnceLock}; + +use axum::body::Bytes; +use axum::extract::{Path, RawQuery, State}; +use axum::http::HeaderMap; +use serde_json::{json, Map, Value}; + +use sspf_mcp::adapter::ToolError; + +use crate::platform::envelope::ActionResult; +use crate::platform::state::AppState; + +/// handler 调用用的管理员头 —— **按 `SessionStore` 实例缓存**。 +/// +/// 🔴 不能用全局单例:测试里每个用例一个 `AppState`(各自一张 token 表), +/// 全局缓存的 token 在别的表里解析不出来 ⇒ 所有工具都 602。 +static ADMIN_HEADERS: OnceLock, HeaderMap)>>> = + OnceLock::new(); + +/// 管理员头缓存的**上界**。 +/// +/// 正常进程只有 1 个 `AppState`(1 条);测试里每个用例一个实例 ⇒ 不设界会随用例数增长。 +/// 满了直接清空(代价只是下次多签一个 token),**不做 LRU** —— 这里是缓存不是状态。 +const MAX_ADMIN_HEADER_CACHE: usize = 8; + +/// 造/复用管理员请求头,并按入参覆盖 `App-Code`。 +async fn headers(state: &AppState, args: &Value) -> HeaderMap { + let key = Arc::as_ptr(&state.sessions) as usize; + let cached = ADMIN_HEADERS + .get_or_init(|| Mutex::new(HashMap::new())) + .lock() + .ok() + .and_then(|m| m.get(&key).map(|(_, h)| h.clone())); + + let base = match cached { + Some(h) => h, + None => { + let mut h = HeaderMap::new(); + let admin_id = state + .db + .scalar_text("SELECT f_id FROM base_user WHERE f_account = 'admin' LIMIT 1") + .await + .ok() + .flatten() + .unwrap_or_default(); + let token = state.sessions.issue("admin", &admin_id, 1); + if let Ok(v) = token.parse() { + h.insert("authorization", v); + } + if let Ok(v) = "3".parse() { + h.insert("vue-version", v); + } + if let Ok(mut m) = ADMIN_HEADERS + .get_or_init(|| Mutex::new(HashMap::new())) + .lock() + { + if m.len() >= MAX_ADMIN_HEADER_CACHE { + m.clear(); + } + // 🔴 连同 Arc 一起存:地址可能被分配器复用,只存 headers 会让 + // 新 AppState 命中旧 token(测试里表现为随机 602)。 + m.insert(key, (Arc::clone(&state.sessions), h.clone())); + } + h + } + }; + + let mut h = base; + let app = args + .get("appCode") + .and_then(Value::as_str) + .unwrap_or("mainSystem"); + if let Ok(v) = app.parse() { + h.insert("app-code", v); + } + h +} + +/// 从入参挑出若干键,拼成 URL query(中文等字符会被正确百分号编码)。 +fn qs(args: &Value, keys: &[&str]) -> String { + let Some(obj) = args.as_object() else { + return String::new(); + }; + let mut pairs: Vec<(String, String)> = Vec::new(); + for k in keys { + let Some(v) = obj.get(*k) else { continue }; + if v.is_null() { + continue; + } + let s = match v { + Value::String(s) => s.clone(), + other => other.to_string(), + }; + if s.is_empty() { + continue; + } + pairs.push(((*k).to_string(), s)); + } + serde_urlencoded::to_string(&pairs).unwrap_or_default() +} + +/// 入参原样当 body(去掉 MCP 控制字段)。 +/// +/// 🔴 **`formData` / `columnData` / `tablesData` 这类列是 TEXT,但 handler 的 +/// `value_to_text()` 只接受 string/number/bool —— 传对象会被**静默丢弃**。** +/// ⇒ 这里统一把对象/数组序列化成 JSON 字符串,AI 可以直接写对象。 +fn body_of(args: &Value) -> Result { + let mut v = args.clone(); + if let Some(o) = v.as_object_mut() { + o.remove("dryRun"); + o.remove("appCode"); + for key in [ + "formData", + "columnData", + "tablesData", + "appColumnData", + "buttonData", + "appButtonData", + "interfaceParam", + ] { + let Some(slot) = o.get_mut(key) else { continue }; + if slot.is_object() || slot.is_array() { + let text = serde_json::to_string(slot).unwrap_or_default(); + *slot = Value::String(text); + } + } + } + if !v.is_object() { + return Err(ToolError::new("BAD_ARGS", "入参必须是 JSON 对象").field("args")); + } + serde_json::to_vec(&v) + .map(Bytes::from) + .map_err(|e| ToolError::new("BAD_ARGS", format!("序列化入参失败: {e}"))) +} + +/// 取必填字符串参数。 +fn need_str(args: &Value, key: &str) -> Result { + let s = args.get(key).and_then(Value::as_str).unwrap_or("").trim(); + if s.is_empty() { + return Err(ToolError::new("MISSING_ARG", format!("缺少必填参数 {key}")) + .field(key) + .hint("先 sspf_describe 看该工具的 input_schema") + .next("sspf_discover", json!({}), "先确认该用哪个工具")); + } + Ok(s.to_string()) +} + +/// 该域的「查证」工具 —— 业务失败时建议 AI 先列一下再改参数。 +fn next_tool_for(op: &str) -> Option<&'static str> { + if op.starts_with("workflow.") { + Some("workflow.template.list") + } else if op.starts_with("dict.") { + Some("dict.type.list") + } else if op.starts_with("menu.") { + Some("menu.tree") + } else if op.starts_with("permission.role.") { + Some("permission.role.list") + } else if op.starts_with("permission.user.") { + Some("permission.user.list") + } else if op.starts_with("form.") { + Some("form.list") + } else { + None + } +} + +/// `Json` ⇒ 工具结果 / 结构化错误。 +fn out(op: &str, resp: axum::Json) -> Result { + let a = resp.0; + if a.code == 200 { + return Ok(match a.data { + // 新建设备类端点常返裸 id 字符串(官方 `ActionResult.success(id)`)—— + // 包成 `{id}` 让 AI 拿到稳定字段,不用猜「这串是什么」。 + Value::String(s) => json!({ "id": s }), + Value::Null => json!({ "ok": true, "msg": a.msg }), + other => other, + }); + } + let code = match a.code { + 602 => "NOT_LOGGED_IN", + 403 => "NO_PERMISSION", + _ => "BUSINESS_FAILED", + }; + let mut err = ToolError::new(code, a.msg).hint("先 sspf_describe 看该工具的 pitfalls 与示例"); + if let Some(t) = next_tool_for(op) { + err = err.next(t, json!({}), "先列出现有数据,确认 id / enCode 是否正确"); + } + Err(err) +} + +// ================================================================ workflow + +pub async fn workflow_template_list(state: &AppState, args: Value) -> Result { + let raw = RawQuery(Some(qs( + &args, + &["keyword", "category", "type", "state", "currentPage", "pageSize"], + ))); + let r = crate::platform::compat::workflow::workflow_template_list( + State(state.clone()), + headers(state, &args).await, + raw, + ) + .await; + out("workflow.template.list", r) +} + +pub async fn workflow_template_info(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let r = crate::platform::compat::workflow::workflow_template_info( + State(state.clone()), + headers(state, &args).await, + Path(id), + ) + .await; + out("workflow.template.info", r) +} + +pub async fn workflow_template_create(state: &AppState, args: Value) -> Result { + let body = body_of(&args)?; + let r = crate::platform::compat::workflow::workflow_template_create( + State(state.clone()), + headers(state, &args).await, + body, + ) + .await; + out("workflow.template.create", r) +} + +pub async fn workflow_template_update(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let body = body_of(&args)?; + let r = crate::platform::compat::workflow::workflow_template_update( + State(state.clone()), + headers(state, &args).await, + Path(id), + body, + ) + .await; + out("workflow.template.update", r) +} + +pub async fn workflow_template_delete(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let r = crate::platform::compat::workflow::workflow_template_delete( + State(state.clone()), + headers(state, &args).await, + Path(id), + ) + .await; + out("workflow.template.delete", r) +} + +pub async fn workflow_task_list(state: &AppState, args: Value) -> Result { + let raw = RawQuery(Some(qs( + &args, + &["keyword", "type", "category", "currentPage", "pageSize"], + ))); + let r = crate::platform::compat::workflow::workflow_task_list( + State(state.clone()), + headers(state, &args).await, + raw, + ) + .await; + out("workflow.task.list", r) +} + +pub async fn workflow_template_selector(state: &AppState, args: Value) -> Result { + let raw = RawQuery(Some(qs( + &args, + &["keyword", "category", "type", "currentPage", "pageSize"], + ))); + let r = crate::platform::compat::workflow::workflow_template_selector( + State(state.clone()), + headers(state, &args).await, + raw, + ) + .await; + out("workflow.template.selector", r) +} + +// ================================================================ dict + +pub async fn dict_type_update(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let body = body_of(&args)?; + let r = crate::platform::compat::system::dict_type_update( + State(state.clone()), + headers(state, &args).await, + Path(id), + body, + ) + .await; + out("dict.type.update", r) +} + +pub async fn dict_type_delete(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let r = crate::platform::compat::system::dict_type_delete( + State(state.clone()), + headers(state, &args).await, + Path(id), + ) + .await; + out("dict.type.delete", r) +} + +pub async fn dict_data_create(state: &AppState, args: Value) -> Result { + let body = body_of(&args)?; + let r = crate::platform::compat::system::dict_data_create( + State(state.clone()), + headers(state, &args).await, + body, + ) + .await; + out("dict.data.create", r) +} + +// ================================================================ menu + +pub async fn menu_info(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let r = crate::platform::compat::system::menu_info( + State(state.clone()), + headers(state, &args).await, + Path(id), + ) + .await; + out("menu.info", r) +} + +pub async fn menu_update(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let body = body_of(&args)?; + let r = crate::platform::compat::system::menu_update( + State(state.clone()), + headers(state, &args).await, + Path(id), + body, + ) + .await; + out("menu.update", r) +} + +// ================================================================ permission + +pub async fn role_create(state: &AppState, args: Value) -> Result { + let body = body_of(&args)?; + let r = crate::platform::compat::permission::role_create( + State(state.clone()), + headers(state, &args).await, + body, + ) + .await; + out("permission.role.create", r) +} + +pub async fn role_delete(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let r = crate::platform::compat::permission::role_delete( + State(state.clone()), + headers(state, &args).await, + Path(id), + ) + .await; + out("permission.role.delete", r) +} + +pub async fn user_delete(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let r = crate::platform::compat::permission::user_delete( + State(state.clone()), + headers(state, &args).await, + Path(id), + ) + .await; + out("permission.user.delete", r) +} + +// ================================================================ form + +pub async fn form_create(state: &AppState, args: Value) -> Result { + let body = body_of(&args)?; + let r = crate::platform::compat::online_dev::visual_dev_create( + State(state.clone()), + headers(state, &args).await, + body, + ) + .await; + out("form.create", r) +} + +pub async fn form_update(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let body = body_of(&args)?; + let r = crate::platform::compat::online_dev::visual_dev_update( + State(state.clone()), + headers(state, &args).await, + Path(id), + body, + ) + .await; + out("form.update", r) +} + +pub async fn form_delete(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let r = crate::platform::compat::online_dev::visual_dev_delete( + State(state.clone()), + headers(state, &args).await, + Path(id), + ) + .await; + out("form.delete", r) +} + +pub async fn form_release(state: &AppState, args: Value) -> Result { + let id = need_str(&args, "id")?; + let r = crate::platform::compat::online_dev::visual_dev_release( + State(state.clone()), + headers(state, &args).await, + Path(id), + ) + .await; + out("form.release", r) +} + +// ================================================================ context / ops + +pub async fn app_list(state: &AppState, args: Value) -> Result { + let raw = RawQuery(Some(qs( + &args, + &["keyword", "type", "currentPage", "pageSize"], + ))); + let r = crate::platform::compat::system::system_list( + State(state.clone()), + headers(state, &args).await, + raw, + ) + .await; + out("context.app.list", r) +} + +pub async fn ops_logs(state: &AppState, args: Value) -> Result { + let raw = RawQuery(Some(qs( + &args, + &[ + "category", + "keyword", + "startTime", + "endTime", + "currentPage", + "pageSize", + ], + ))); + let r = crate::platform::compat::system::log_list( + State(state.clone()), + headers(state, &args).await, + raw, + ) + .await; + out("ops.logs", r) +} + +pub async fn ops_schedule_list(state: &AppState, args: Value) -> Result { + let raw = RawQuery(Some(qs( + &args, + &["keyword", "currentPage", "pageSize"], + ))); + let r = crate::platform::compat::scheduletask::task_list( + State(state.clone()), + headers(state, &args).await, + raw, + ) + .await; + out("ops.schedule.list", r) +} + +/// 健康检查:表数 / 会话数 / admin 是否在 —— 不走 HTTP,直接读库。 +pub async fn ops_health(state: &AppState, _args: Value) -> Result { + let tables = state + .db + .scalar_text( + "SELECT count(*)::text FROM information_schema.tables \ + WHERE table_schema = 'public' AND table_type = 'BASE TABLE'", + ) + .await + .ok() + .flatten() + .and_then(|s| s.parse::().ok()) + .unwrap_or(0); + let admin = state + .db + .scalar_text("SELECT f_account FROM base_user WHERE f_account = 'admin' LIMIT 1") + .await + .ok() + .flatten(); + let sessions = state.sessions.snapshot(); + Ok(json!({ + "backend": "native", + "version": env!("CARGO_PKG_VERSION"), + "tables": tables, + "adminSeeded": admin.is_some(), + "sessions": sessions.len(), + })) +} + +/// 在线会话:**按账号聚合**,不返回 token 本身(token 是凭据,不进工具输出)。 +pub async fn ops_online(state: &AppState, _args: Value) -> Result { + let snap = state.sessions.snapshot(); + let mut by_account: Map = Map::new(); + for (_, u) in snap { + let entry = by_account.entry(u.account.clone()).or_insert_with(|| { + json!({ + "account": u.account, + "isAdmin": u.is_admin == 1, + "sessions": 0, + "lastIssuedAtMs": 0, + "ips": Vec::::new(), + }) + }); + if let Some(o) = entry.as_object_mut() { + let n = o.get("sessions").and_then(Value::as_i64).unwrap_or(0) + 1; + o.insert("sessions".to_string(), json!(n)); + let last = o.get("lastIssuedAtMs").and_then(Value::as_i64).unwrap_or(0); + o.insert("lastIssuedAtMs".to_string(), json!(last.max(u.issued_at_ms))); + if !u.ip.is_empty() { + if let Some(arr) = o.get_mut("ips").and_then(Value::as_array_mut) { + if !arr.iter().any(|v| v.as_str() == Some(u.ip.as_str())) { + arr.push(json!(u.ip)); + } + } + } + } + } + Ok(json!({ + "online": by_account.len(), + "users": by_account.into_values().collect::>(), + })) +} diff --git a/src/backend/tests/mcp_tools_it.rs b/src/backend/tests/mcp_tools_it.rs new file mode 100644 index 0000000..abec785 --- /dev/null +++ b/src/backend/tests/mcp_tools_it.rs @@ -0,0 +1,228 @@ +//! MCP 新工具(P2-c / P3)—— 适配器直调契约面 handler 的回归测试。 +//! +//! 覆盖:`form.create/update/delete`、`workflow.template.*`、`dict.*`、`menu.info`、 +//! `permission.role.*`、`permission.user.delete`、`ops.*`、`context.app.list`。 +//! +//! 🔴 这些工具的实现方式是「构造管理员头 → 直调 compat handler」, +//! 所以本测试同时钉住两件事:① handler 能被进程内调用;② 管理员会话能通过守卫。 + +use std::path::PathBuf; +use std::sync::Arc; + +use serde_json::{json, Value}; +use ssw_platform::mcp_adapter::NativeAdapter; +use ssw_platform::platform::db::Db; +use ssw_platform::platform::seed::first_seed; +use ssw_platform::platform::session::{SessionStore, TicketStore}; +use ssw_platform::platform::state::AppState; +use sspf_mcp::adapter::PlatformAdapter; +use tokio::sync::{Mutex, OnceCell}; + +static DB: OnceCell = OnceCell::const_new(); +static LOCK: Mutex<()> = Mutex::const_new(()); + +async fn db() -> &'static Db { + DB.get_or_init(|| async { + let db = Db::open_temp().await.expect("打开 pglite 临时库失败"); + ssw_platform::bootstrap::ensure_schema_all(&db) + .await + .expect("ensure_schema_all 失败"); + ssw_platform::bootstrap::ensure_base(&db) + .await + .expect("ensure_base 失败"); + first_seed(&db, "123456").await.expect("first_seed 失败"); + db + }) + .await +} + +fn adapter(db: &Db) -> NativeAdapter { + let state = AppState { + config: Arc::new(ssw_platform::platform::config::Config::from_env(PathBuf::from( + "/tmp/ssw-platform-mcp-tools-it", + ))), + db: Arc::new(db.clone()), + sessions: Arc::new(SessionStore::default()), + tickets: Arc::new(TicketStore::default()), + }; + NativeAdapter::new(state) +} + +async fn call(a: &NativeAdapter, op: &str, args: Value) -> Result { + a.invoke(op, args).await +} + +/// ops.health / ops.online / context.app.list 三条只读链路。 +#[tokio::test] +async fn ops_and_app_tools_work() { + let _g = LOCK.lock().await; + let a = adapter(db().await); + + let health = call(&a, "ops.health", json!({})).await.expect("ops.health 失败"); + assert!(health["tables"].as_i64().unwrap_or(0) > 50, "表数应 > 50: {health}"); + assert_eq!(health["adminSeeded"], true); + + let apps = call(&a, "context.app.list", json!({"pageSize":5})).await.expect("app.list 失败"); + assert!(apps["list"].is_array(), "必须是 ListVO: {apps}"); + + let online = call(&a, "ops.online", json!({})).await.expect("ops.online 失败"); + assert!(online["users"].is_array(), "{online}"); + let logs = call(&a, "ops.logs", json!({"category":1,"pageSize":1})).await; + assert!(logs.is_ok(), "登录日志查询失败: {logs:?}"); +} + +/// 流程模板 CRUD 闭环(元数据面)。 +#[tokio::test] +async fn workflow_template_crud_roundtrip() { + let _g = LOCK.lock().await; + let a = adapter(db().await); + + let created = call( + &a, + "workflow.template.create", + json!({"fullName":"MCP验证流程","enCode":"mcp_verify_flow"}), + ) + .await + .expect("建流程失败"); + let id = created["id"].as_str().expect("必须返回 id").to_string(); + + let listed = call(&a, "workflow.template.list", json!({"keyword":"MCP验证"})).await.expect("列流程失败"); + let total = listed["pagination"]["total"].as_i64().unwrap_or(0); + assert!(total >= 1, "新流程应能被列出: {listed}"); + + let info = call(&a, "workflow.template.info", json!({"id":id})).await.expect("详情失败"); + assert_eq!(info["enCode"], "mcp_verify_flow", "{info}"); + + call(&a, "workflow.template.update", json!({"id":id,"fullName":"MCP验证流程2"})) + .await + .expect("更新失败"); + let info2 = call(&a, "workflow.template.info", json!({"id":id})).await.expect("详情失败"); + assert_eq!(info2["fullName"], "MCP验证流程2"); + + call(&a, "workflow.template.delete", json!({"id":id})).await.expect("删除失败"); + let after = call(&a, "workflow.template.list", json!({"keyword":"MCP验证"})).await.expect("列流程失败"); + assert_eq!(after["pagination"]["total"], 0, "软删后不应再出现: {after}"); +} + +/// 字典写面 + 菜单详情。 +#[tokio::test] +async fn dict_and_menu_tools_work() { + let _g = LOCK.lock().await; + let a = adapter(db().await); + + let created = call( + &a, + "dict.type.create", + json!({"enCode":"mcp_dict_verify","fullName":"MCP字典"}), + ) + .await + .expect("建字典失败"); + let type_id = created["id"].as_str().expect("必须有 id").to_string(); + + call(&a, "dict.type.update", json!({"id":type_id,"fullName":"MCP字典2"})) + .await + .expect("改字典失败"); + call( + &a, + "dict.data.create", + json!({"dictionaryTypeId":type_id,"enCode":"a","fullName":"甲"}), + ) + .await + .expect("加字典项失败"); + + let items = call(&a, "dict.data.list", json!({"dictionaryTypeId":type_id})).await.expect("列字典项失败"); + assert!(items["count"].as_i64().unwrap_or(0) >= 1, "{items}"); + + let menu_id = db() + .await + .scalar_text("SELECT f_id FROM base_module WHERE f_en_code = 'permission.user' LIMIT 1") + .await + .expect("查菜单失败") + .expect("permission.user 菜单必须存在"); + let menu = call(&a, "menu.info", json!({"id":menu_id})).await.expect("菜单详情失败"); + assert_eq!(menu["enCode"], "permission.user"); +} + +/// 角色建/删 + 用户软删。 +#[tokio::test] +async fn permission_role_and_user_tools_work() { + let _g = LOCK.lock().await; + let a = adapter(db().await); + + let role = call( + &a, + "permission.role.create", + json!({"fullName":"MCP角色","enCode":"mcp_role_verify"}), + ) + .await + .expect("建角色失败"); + let role_id = role["id"].as_str().expect("必须有 id").to_string(); + let roles = call(&a, "permission.role.list", json!({"keyword":"MCP角色"})).await.expect("列角色失败"); + assert!(roles["count"].as_i64().unwrap_or(0) >= 1, "{roles}"); + call(&a, "permission.role.delete", json!({"id":role_id})).await.expect("删角色失败"); + + db() + .await + .exec( + "INSERT INTO base_user (f_id,f_tenant_id,f_account,f_real_name,f_enabled_mark,f_delete_mark,f_is_administrator,f_creator_time) \ + VALUES ('mcp-del-user','0','mcp_del_user','待删',1,0,0,now())", + ) + .await + .expect("插用户失败"); + call(&a, "permission.user.delete", json!({"id":"mcp-del-user"})).await.expect("删用户失败"); + let users = call(&a, "permission.user.list", json!({"keyword":"mcp_del_user"})).await.expect("列用户失败"); + assert_eq!(users["count"], 0, "软删后不应出现: {users}"); +} + +/// 表单定义建/改/删(不发布:本仓 release 未支持)。 +#[tokio::test] +async fn form_create_update_delete_roundtrip() { + let _g = LOCK.lock().await; + let a = adapter(db().await); + + let created = call( + &a, + "form.create", + json!({"fullName":"MCP验证表单","enCode":"mcp_verify_form","type":1, + "formData":{"formRef":"formRef","fields":[]}}), + ) + .await + .expect("建表单失败"); + let id = created["id"].as_str().expect("必须返回 id").to_string(); + + let listed = call(&a, "form.list", json!({"keyword":"MCP验证表单"})).await.expect("列表单失败"); + assert!(listed["count"].as_i64().unwrap_or(0) >= 1, "{listed}"); + + call(&a, "form.update", json!({"id":id,"description":"改过"})) + .await + .expect("改表单失败"); + let desc = db() + .await + .scalar_text(&format!( + "SELECT f_description FROM base_visual_dev WHERE f_id = '{id}' LIMIT 1" + )) + .await + .expect("查表单失败"); + assert_eq!(desc.as_deref(), Some("改过"), "更新必须真的落库"); + + call(&a, "form.delete", json!({"id":id})).await.expect("删表单失败"); + let after = call(&a, "form.list", json!({"keyword":"MCP验证表单"})).await.expect("列表单失败"); + assert_eq!(after["count"], 0, "软删后不应出现: {after}"); +} + +/// 业务失败必须是结构化 ToolError(带 hints / next_actions),不是 panic 也不是纯字符串。 +#[tokio::test] +async fn business_failure_is_structured() { + let _g = LOCK.lock().await; + let a = adapter(db().await); + let err = call( + &a, + "workflow.template.info", + json!({"id":"00000000-0000-0000-0000-000000000000"}), + ) + .await + .expect_err("不存在的模板必须失败"); + assert_eq!(err.code, "BUSINESS_FAILED"); + assert!(!err.hints.is_empty(), "必须给 hints"); + assert!(!err.next_actions.is_empty(), "必须给 next_actions"); +}