From 98b93967da0ecba7e7a62885fb88180eec36800b Mon Sep 17 00:00:00 2001 From: admin Date: Tue, 3 Nov 2026 20:12:50 +0800 Subject: [PATCH] =?UTF-8?q?refactor(arch):=20M5=20=E4=BD=8E=E4=BB=A3?= =?UTF-8?q?=E7=A0=81=E6=89=A7=E8=A1=8C=E5=B1=82=E4=B8=8B=E6=B2=89=20?= =?UTF-8?q?=E2=80=94=E2=80=94=204=20=E6=A8=A1=E5=9D=97=20/=202,674=20?= =?UTF-8?q?=E8=A1=8C=E8=BF=81=E5=85=A5=20sspf-lowcode-exec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 把 src/backend/src/lowcode_{crud,ddl,check,seed}.rs 下沉到 crates/sspf-lowcode-exec/, 原路径全部变成 5 行转发壳 ⇒ CLI(--seed-lowcode-demo)与 MCP 适配器的调用路径零感知。 与 sspf-lowcode 的分工不变:前者纯计算(AR7 白名单不动),本 crate 是执行层 (连库 / 跑 SQL / 比对真实库列 / 事务 / 回写模型)。 依赖:sspf-lowcode + sspf-core + sspf-store + sspf-mcp + pglite-rs + chrono + serde_json (比原计划多三个:pglite::ToSql/Error 是直接用的、now_iso() 用 chrono::Local::now()、JSON payload) 闸门改造: - check-arch.sh 新增 AR13(两层:依赖白名单 + 源码不许 use sspf_pack_*) - check-arch.sh 反自证 7→8(两处都注入:越界依赖 axum + 业务包引用,按路径分别验) - check-boundary.sh 新增 LOWCODE_EXEC ⇒ CP1/CP2 纳入执行层真源 (反向验证:插 LEAK_PROBE ⇒ CP1 报红;还原后 11/11) - check-contract-scan.py 不用改 —— 契约里零 lowcode 端点(低代码是 MCP 工具不是 HTTP 路由) 🔴 踩坑:改写时把 use crate::lowcode_ddl; 一并改成 use crate::ddl; ⇒ 编译不过。 教训:搬 crate 只改跨 crate 的前缀(crate::platform:: → sspf_core::), 模块名一律不动;文档内链([`crate::lowcode_crud`])也不能跟着改(改了就变死链)。 数字:cargo build 零警告;cargo test 695/0(与 M1 基线完全一致); check-arch 17/17;--self-test 8/8;check-boundary 11/11;check-contract 10/10; check-module 123/123;check-citations 4/4;check-naming 3/0/1; verify.sh --smoke 14 步全绿(377.6s) --- .workbuddy/memory/2026-11-03.md | 27 + CLAUDE.md | 4 +- Cargo.lock | 14 + HANDOFF.md | 46 + crates/sspf-lowcode-exec/Cargo.toml | 45 + crates/sspf-lowcode-exec/src/lib.rs | 25 + crates/sspf-lowcode-exec/src/lowcode_check.rs | 501 +++++++ crates/sspf-lowcode-exec/src/lowcode_crud.rs | 1240 ++++++++++++++++ crates/sspf-lowcode-exec/src/lowcode_ddl.rs | 430 ++++++ crates/sspf-lowcode-exec/src/lowcode_seed.rs | 503 +++++++ docs/CRATES-MIGRATION.md | 77 +- scripts/check-arch.sh | 89 +- scripts/check-boundary.sh | 14 +- src/backend/Cargo.toml | 3 + src/backend/src/lowcode_check.rs | 504 +------ src/backend/src/lowcode_crud.rs | 1243 +---------------- src/backend/src/lowcode_ddl.rs | 433 +----- src/backend/src/lowcode_seed.rs | 506 +------ 18 files changed, 3006 insertions(+), 2698 deletions(-) create mode 100644 crates/sspf-lowcode-exec/Cargo.toml create mode 100644 crates/sspf-lowcode-exec/src/lib.rs create mode 100644 crates/sspf-lowcode-exec/src/lowcode_check.rs create mode 100644 crates/sspf-lowcode-exec/src/lowcode_crud.rs create mode 100644 crates/sspf-lowcode-exec/src/lowcode_ddl.rs create mode 100644 crates/sspf-lowcode-exec/src/lowcode_seed.rs diff --git a/.workbuddy/memory/2026-11-03.md b/.workbuddy/memory/2026-11-03.md index d7a8b32..e0841aa 100644 --- a/.workbuddy/memory/2026-11-03.md +++ b/.workbuddy/memory/2026-11-03.md @@ -131,3 +131,30 @@ ⚠️ 两处是**历史叙述**(记录当时动作),改了会失真 ⇒ 改措辞(去掉行号形式)而不是改路径。 - ⏭ **下一步 = M5(`sspf-lowcode-exec`)**:迁 `lowcode_{crud,ddl,check,seed}.rs`(2,674 行), 新 crate 依赖 sspf-lowcode + core + store + mcp。⚠️ 必须同步加 **AR13**(依赖白名单)+ 重跑全部 `--self-test`。 + +### 19:20–20:10 M5 完成:低代码执行层下沉(tag v0.1.5-m5) + +- **做法**:`src/backend/src/lowcode_{crud,ddl,check,seed}.rs`(2,674 行)下沉到 `crates/sspf-lowcode-exec/`, + 原路径全变 5 行转发壳(`pub use sspf_lowcode_exec::::*;`)⇒ **CLI(`--seed-lowcode-demo`)与 MCP 适配器零感知**。 +- **依赖**:`sspf-lowcode`(纯计算,**AR7 白名单不动**)+ `sspf-core`(Db/ids/config/registry) + + `sspf-store`(Db/pglite 真源)+ `sspf-mcp`(ToolError)+ `pglite-rs` + `chrono` + `serde_json`。 + 比原计划多三个 —— `pglite::ToSql`/`pglite::Error` 是**直接用**的、`now_iso()` 用 `chrono::Local::now()`、JSON payload 转换。 +- 🔴 **未提权任何 `pub(crate)`** —— 与 M3/M4 不同,这四个模块的对外接口**本来就是 `pub`** ⇒ 一行可见性改动都没有。 +- **闸门**:`check-arch.sh` 新增 **AR13**(两层:依赖白名单 ⊆ {lowcode,core,store,mcp,pglite-rs,chrono,serde_json} + + 源码不许 `use sspf_pack_*`);反自证 **8/8**(**两处都注入**:越界依赖 axum + 业务包引用,**按路径分别验**)。 + `check-boundary.sh` 新增 `LOWCODE_EXEC` ⇒ CP1/CP2 纳入执行层真源; + **反向验证**:插 `const LEAK_PROBE: &str = "demo_item";` ⇒ CP1 报红(10/1);还原后 11/11。 +- **`check-contract-scan.py` 不用改** —— 契约里**零 lowcode 端点**(低代码是 MCP 工具不是 HTTP 路由)⇒ 本批不影响 CC1–CC10。 +- 🔴 **本批的坑:改写规则要分清「路径前缀变了」与「模块名变了」** —— 改写时把 `use crate::lowcode_ddl;` + 一并改成 `use crate::ddl;` ⇒ 编译报 `cannot find module or crate lowcode_ddl`。 + **教训**:搬 crate 只改**跨 crate 的前缀**(`crate::platform::` → `sspf_core::`),**模块名一律不动** + (新 crate 里模块仍叫 `lowcode_crud`/`lowcode_ddl`/`lowcode_check`); + **文档内链**(``[`crate::lowcode_crud`]``)也不能跟着改(改了就变死链)⇒ 单独修回。 +- **数字**:`cargo build` 零警告;`cargo test` **695/0**(与 M1 基线完全一致);`check-arch` **17/17**; + `--self-test` **8/8**;`check-boundary` 11/11;`check-contract` 10/10(反自证 12 例全过);`check-module` 123/123; + `check-citations` 4/4(**零条引文**指向 lowcode 旧路径);`check-naming` 3/0/1;`verify --smoke` 14 步全绿(377.6s)。 +- ⏭ **下一步 = M6(`sspf-mcp-adapter`)**:迁 `mcp_adapter.rs`(2,652) + `mcp_compat.rs`(631), + 依赖 sspf-mcp + sspf-core + **所有 compat 包**(决策③)⇒ 依赖图里**唯一高扇入节点**。 + ⚠️ 必须同步做:① 新增 **AR14**(`sspf-mcp-adapter` 之外不许依赖 compat 包); + ② `check-contract-scan.py` 的 `plat_files` 必须收 `crates/sspf-mcp-adapter/src/`(守卫常量在里面,漏收 ⇒ CC6 假漂移); + ③ `check-boundary.sh` 的 CP1/CP2 纳入 MCP 适配层真源;④ 重跑全部 `--self-test`。 diff --git a/CLAUDE.md b/CLAUDE.md index f697284..373c0d3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -109,7 +109,9 @@ ssw-platform/ │ ├── sspf-compat-workflow/ # 🔴 契约面(M4):workflow + report + visualdata │ ├── sspf-compat-ext/ # 🔴 契约面(M4):extend + teamwork + ai + mobile │ ├── sspf-compat-online_dev/# 🔴 契约面(M4):online_dev(🔴 包名不能带连字符) -│ ├── sspf-lowcode/ # (P2)元数据引擎 + Rhai 沙箱 +│ ├── sspf-lowcode/ # (P2)元数据引擎 + Rhai 沙箱(**纯计算**,AR7) +│ ├── sspf-lowcode-exec/ # 🔴 低代码**执行层**(M5):连库/跑 SQL/校验/回写模型 +│ │ # `src/backend/src/lowcode_*.rs` 只是转发壳 │ ├── sspf-plugin/ # (P3)业务包加载器:静态 / dylib / wasm │ └── sspf-mcp/ # (P1)MCP 2.0 元工具层 ├── packs/ # 【业务包】整目录可搬(jnpf ⇄ sspf 双向) diff --git a/Cargo.lock b/Cargo.lock index ffa0d60..1bc221b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1218,6 +1218,19 @@ dependencies = [ "sspf-contract", ] +[[package]] +name = "sspf-lowcode-exec" +version = "0.1.0" +dependencies = [ + "chrono", + "pglite-rs", + "serde_json", + "sspf-core", + "sspf-lowcode", + "sspf-mcp", + "sspf-store", +] + [[package]] name = "sspf-mcp" version = "0.1.0" @@ -1290,6 +1303,7 @@ dependencies = [ "sspf-contract", "sspf-core", "sspf-lowcode", + "sspf-lowcode-exec", "sspf-mcp", "sspf-pack-asset", "sspf-plugin", diff --git a/HANDOFF.md b/HANDOFF.md index a114f32..f183562 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -217,6 +217,52 @@ M2/M3 搬迁后闸门都报红(正常),M4 首次跑就 10/10 ⇒ 反而是 --- +## 0-0-pre6. 2026-11-03 20:10 **M5 完成**:低代码执行层下沉(tag `v0.1.5-m5`) + +**做了什么**:`src/backend/src/lowcode_{crud,ddl,check,seed}.rs`(2,674 行)下沉到 `crates/sspf-lowcode-exec/`, +原路径全变 5 行转发壳(`pub use sspf_lowcode_exec::::*;`)⇒ **CLI(`--seed-lowcode-demo`)与 MCP 适配器零感知**。 + +| 依赖 | 为什么 | +|---|---| +| `sspf-lowcode` | 纯计算层(解析/校验/SQL 生成)—— **AR7 白名单不动** | +| `sspf-core` | `Db` / `ids::new_uuid` / `config::Profile` / `registry::MAIN_SYSTEM_ID` | +| `sspf-store` | `Db` / `pglite` 的**真源**(`sspf-core::db` 只是转发壳) | +| `sspf-mcp` | `ToolError` —— 执行失败要能变成给 AI 看懂的结构化错误 | +| `pglite-rs` + `chrono` + `serde_json` | 真实库 / `now_iso()` 时间戳 / JSON payload | + +**与原计划的差异**:计划写依赖 `{lowcode, core, store, mcp}`,实际多了 `pglite-rs` + `chrono` + `serde_json` +—— ① `pglite::ToSql` / `pglite::Error` 是**直接用**的(不只经 `Db`);② `now_iso()` 用 `chrono::Local::now()`;③ JSON payload 转换。 +另外**未提权任何 `pub(crate)`**(与 M3/M4 不同:这四个模块的对外接口**本来就是 `pub`** ⇒ 一行可见性改动都没有)。 + +**闸门改造**: +- `check-arch.sh` 新增 **AR13**(两层:依赖白名单 + 源码不许 `use sspf_pack_*`);反自证 **8/8** + (**两处都注入**:越界依赖 `axum` + 业务包引用 `use sspf_pack_asset::…`,且**按路径分别验**)。 +- `check-boundary.sh` 新增 `LOWCODE_EXEC` ⇒ **CP1**(业务标识符)/ **CP2**(`use crate::modules`)纳入执行层真源。 + **反向验证**:往 `crates/sspf-lowcode-exec/src/lowcode_check.rs` 插 `const LEAK_PROBE: &str = "demo_item";` + ⇒ CP1 报红(PASS=10/FAIL=1);还原后恢复 11/11。 +- `check-contract-scan.py` **不用改** —— 契约里**零 lowcode 端点**(低代码是 MCP 工具不是 HTTP 路由) + ⇒ 本批不影响 CC1–CC10。 + +**🔴 本批的坑(改写规则要分清两件事)**:改写时把 `use crate::lowcode_ddl;` 一并改成了 `use crate::ddl;` +⇒ 编译报 `cannot find module or crate lowcode_ddl`。 +**教训**:搬 crate 只改**跨 crate 的前缀**(`crate::platform::` → `sspf_core::`), +**模块名一律不动**(新 crate 里模块仍叫 `lowcode_crud` / `lowcode_ddl` / `lowcode_check`); +文档内链(``[`crate::lowcode_crud`]``)也不能跟着改(改了就变死链)⇒ 已单独修回。 + +**出口判据(全部达成)**: +`cargo build --workspace` 零警告;`cargo test --workspace` = **695 passed / 0 failed**(与 M1 基线完全一致); +`check-arch` **17/17**;`--self-test` **8/8**;`check-boundary` 11/11;`check-contract` 10/10(反自证 12 例全过); +`check-module` 123/123;`check-citations` 4/4(**零条引文**指向 lowcode 旧路径);`check-naming` 3/0/1; +`verify.sh --smoke` **14 步全绿**(377.6s)。 + +**⏭ 下一步 = M6(`sspf-mcp-adapter`)**:迁 `mcp_adapter.rs`(2,652) + `mcp_compat.rs`(631), +新 crate 依赖 sspf-mcp + sspf-core + **所有 compat 包**(决策③)⇒ 它是依赖图里**唯一高扇入节点**。 +⚠️ M6 必须同步做:① 新增 **AR14**(`sspf-mcp-adapter` 之外不许依赖 compat 包); +② `check-contract-scan.py` 的 `plat_files` 必须收 `crates/sspf-mcp-adapter/src/`(守卫常量在里面,漏收 ⇒ CC6 假漂移); +③ `check-boundary.sh` 的 CP1/CP2 纳入 MCP 适配层真源;④ 重跑全部 `--self-test`。 + +--- + ## 0-0. 2026-11-02 23:13 验证修复轮(官方前端 + dacli 真跑后修的) 用官方 vue 前端 + dacli + 586 条端点探针做过一轮真实系统性验证(报告: diff --git a/crates/sspf-lowcode-exec/Cargo.toml b/crates/sspf-lowcode-exec/Cargo.toml new file mode 100644 index 0000000..de7d4ed --- /dev/null +++ b/crates/sspf-lowcode-exec/Cargo.toml @@ -0,0 +1,45 @@ +[package] +name = "sspf-lowcode-exec" +version.workspace = true +edition.workspace = true +rust-version.workspace = true + +# 🔴 **低代码「执行层」**(M5 起从 `src/backend/src/lowcode_*.rs` 下沉到这里)。 +# +# 装什么:`lowcode_{crud,ddl,check,seed}.rs`(2,674 行)—— 连库、跑 SQL/DDL、回写模型、 +# 写库前的业务校验、开发期示例数据种子。 +# +# 🔴 **与 `sspf-lowcode` 的分工(不是重复)**: +# | 层 | crate | 干什么 | 依赖 | +# |---|---|---|---| +# | 纯计算 | `sspf-lowcode` | 解析 / 校验 / **SQL 文本生成** | 只认 serde(AR7) | +# | 执行 | **本 crate** | 连库、跑 SQL、**比对真实库列**、事务、回写 | 认 DB | +# ⇒ SQL 生成的正确性由 `sspf-lowcode` 的单测覆盖(38 个测试,0 依赖、毫秒级); +# 本 crate 只做「拿到 SQL 就执行」,没有分支逻辑 —— 这是刻意的分工。 +# +# 🔴 **依赖纪律**(AR13 钉住): +# - 允许:低代码元数据引擎(`sspf-lowcode`)+ 平台核心(`sspf-core`)+ 存储层(`sspf-store`) +# + MCP 工具层(`sspf-mcp`)+ pglite-rs + serde_json。 +# - 禁止:**业务包**(`sspf_pack_*`)—— 执行层不许认识任何业务。 +# - 禁止:`sspf-contract`(**不直接依赖**)—— 契约类型由 `sspf-core` / `sspf-lowcode` 转出。 +# 真需要时应先想清楚是不是该改 `sspf-lowcode` 的白名单,而不是绕过它。 +[dependencies] +# 低代码元数据引擎(纯计算:解析 / 校验 / SQL 生成) +sspf-lowcode = { path = "../sspf-lowcode" } + +# 平台核心(Db 抽象的转发 / ids / config / registry) +sspf-core = { path = "../sspf-core" } + +# 存储层(`Db` / `pglite` 的真源)—— 不认识 HTTP +sspf-store = { path = "../sspf-store" } + +# MCP 工具层(`ToolError` —— 执行失败要能变成给 AI 看懂的结构化错误) +sspf-mcp = { path = "../sspf-mcp" } + +# 真实库(执行层要连库) +pglite-rs = { workspace = true } + +# 时间戳(`now_iso()` —— 审计时间用本地时区) +chrono = { workspace = true } + +serde_json = { workspace = true } diff --git a/crates/sspf-lowcode-exec/src/lib.rs b/crates/sspf-lowcode-exec/src/lib.rs new file mode 100644 index 0000000..de1658d --- /dev/null +++ b/crates/sspf-lowcode-exec/src/lib.rs @@ -0,0 +1,25 @@ +//! sspf-lowcode-exec —— 低代码**执行层**。 +//! +//! 🔴 **它和 `sspf-lowcode` 的分工(不是重复,是两层)**: +//! +//! | 层 | crate | 干什么 | 依赖 | +//! |---|---|---|---| +//! | 纯计算 | `sspf-lowcode` | 解析 / 校验 / **SQL 文本生成** | 只认 serde(AR7) | +//! | **执行** | **本 crate** | 连库、跑 SQL、**比对真实库列**、事务、回写模型 | 认 DB | +//! +//! ⇒ SQL 生成的正确性由 `sspf-lowcode` 的单测覆盖(38 个测试,0 依赖、毫秒级); +//! 本 crate 只做「拿到 SQL 就执行」,没有分支逻辑 —— 这是刻意的分工。 +//! +//! ## 模块 +//! +//! | 模块 | 干什么 | +//! |---|---| +//! | [`lowcode_check`] | 写库**之前**的业务校验(唯一性 / 业务主键) | +//! | [`lowcode_crud`] | 动态 CRUD 执行(主表先行 / 子表随后 / 一个事务) | +//! | [`lowcode_ddl`] | 动态建表 + **回写模型**(含平台追加的系统列) | +//! | [`lowcode_seed`] | 开发期示例数据种子(CLI `--seed-lowcode-demo`) | + +pub mod lowcode_check; +pub mod lowcode_crud; +pub mod lowcode_ddl; +pub mod lowcode_seed; diff --git a/crates/sspf-lowcode-exec/src/lowcode_check.rs b/crates/sspf-lowcode-exec/src/lowcode_check.rs new file mode 100644 index 0000000..a2a4ebb --- /dev/null +++ b/crates/sspf-lowcode-exec/src/lowcode_check.rs @@ -0,0 +1,501 @@ +//! lowcode_check —— 写库**之前**的业务校验层(P2-b)。 +//! +//! ## 为什么要有这一层 +//! +//! 底层「设计稿列 vs 真实库列」的比对([`crate::lowcode_crud`])只回答 +//! 「**能不能写**」(列在不在),不回答「**该不该写**」(值合不合法)。 +//! +//! 基线平台在落库前有三道业务校验: +//! +//! | 校验 | 基线实现 | 本模块 | +//! |---|---|---| +//! | **业务主键** | `FormCheckUtils.checkBusinessKey()` | [`check_business_key`] | +//! | **必填** | `FormCheckUtils.checkForm()` 里的 `config.isRequired()` | 已在 `sspf-lowcode` 层(`MISSING_REQUIRED`) | +//! | **单行唯一** | `FormCheckUtils.checkForm()` 里的 `config.getUnique()` | [`check_unique_fields`] | +//! +//! ## 🔴 缺了会怎样 +//! +//! 不做唯一性校验 ⇒ 库里能塞进两条「房间号相同」的记录 ⇒ 列表页看到重复数据, +//! 而用户以为系统拦住了。基线平台是拦住的 ⇒ **行为不一致 = 迁移没对齐**。 +//! +//! ## 🔴 三条对齐口径(都来自 Java 源码,不是经验) +//! +//! 1. **只有 `jnpfKey == "input"` 且 `unique == true` 的字段才查唯一** +//! (Java `JnpfKeyConsts.COM_INPUT.equals(config.getJnpfKey())`)。 +//! 下拉/日期/数字控件标了 `unique` 也**不查** —— 查多了会拦住基线允许的写入。 +//! 2. **唯一性比对是「全表扫 + 排除自己」**,不是靠数据库 UNIQUE 约束。 +//! Java 是 `SELECT ... WHERE col = ? AND pk <> ?`,然后看 `count > 0`。 +//! 3. **业务主键是「组合唯一」**:清单里所有字段一起比; +//! 任一字段为空 ⇒ 该字段用 `IS NULL` 参与比较(Java `setEachCondition`)。 +//! +//! ## 🔴 逻辑删除的行算不算重复 +//! +//! 基线平台:逻辑删除的行**仍然占着**这个唯一值 —— 它只在判重时补了 +//! `delete_mark IS NULL` 条件(`FormCheckUtils` 第 259–261 行), +//! 所以逻辑删除的行**不参与**判重。 +//! ⇒ Rust 侧口径一致:查判重时带上 `delete_mark IS NULL`。 + +use serde_json::Value; + +use sspf_lowcode::{check_identifier, lookup, FieldNode, FormSchema, ModelSchema}; + +use sspf_core::db::Db; +use sspf_mcp::adapter::ToolError; + +/// 🔴 唯一性冲突的错误。 +/// +/// 基线平台的文案是 `字段名 + MsgCode.EXIST103`(≈「已存在」), +/// 这里给结构化的版本,AI 能据此自纠(改值 / 换 id)。 +pub fn unique_conflict(label: &str, column: &str, value: &Value) -> ToolError { + let shown = match value { + Value::String(s) => s.clone(), + Value::Null => "NULL".to_string(), + other => other.to_string(), + }; + ToolError::new( + "UNIQUE_CONSTRAINT_VIOLATED", + format!("字段「{label}」({column}) 的值 {shown} 已经存在了"), + ) + .field(column) + .field("value") + .hint(format!( + "这个字段被设计成「单行唯一」;换一个值,或者先 data.query 看看哪条记录占着它" + )) + .next( + "data.query", + serde_json::json!({ "enCode": "<功能编码>" }), + "查哪条记录占着这个值", + ) +} + +/// 🔴 业务主键冲突的错误。 +pub fn business_key_conflict(tip: Option<&str>, columns: &[String]) -> ToolError { + let cols = columns.join(" + "); + let message = match tip { + Some(t) if !t.trim().is_empty() => t.to_string(), + _ => format!("业务主键({cols})已经存在了"), + }; + ToolError::new("BUSINESS_KEY_VIOLATED", message) + .field("businessKey") + .hint(format!( + "这个功能启用了业务主键({cols})—— 这几个字段的组合必须唯一;\ + 换一个值,或先 data.query 查一下已有的组合" + )) + .next( + "data.query", + serde_json::json!({ "enCode": "<功能编码>" }), + "查已有的业务主键组合", + ) +} + +/// 🔴 单行唯一校验(对齐 `FormCheckUtils.checkForm()` 的 unique 分支)。 +/// +/// - 只查 `jnpfKey == "input"` **且** `unique == true` 的字段; +/// - 比对范围:整张表(子表字段在**子表**里查,主表字段在**主表**里查); +/// - 排除自己:`record_id` 存在时把该行排除(更新场景); +/// - 逻辑删除的行不参与判重(`delete_mark IS NULL`)。 +/// +/// `record_id` 为 `None` ⇒ 新增场景(不排除任何行)。 +pub async fn check_unique_fields( + db: &Db, + form: &FormSchema, + model: &ModelSchema, + payload: &Value, + record_id: Option<&str>, +) -> Result<(), ToolError> { + let fields = form.unique_fields(); + if fields.is_empty() { + return Ok(()); + } + let logical = form.logical_delete.unwrap_or(false); + + for node in fields { + // 这个字段属于哪张表? + let (table_schema, column) = resolve_table_and_column(model, node).ok_or_else(|| { + ToolError::new( + "UNIQUE_CHECK_SKIPPED", + format!( + "字段「{}」({}) 标了唯一,但模型里找不到它对应的列 —— 跳过这一项的唯一校验", + node.label, node.v_model + ), + ) + .field(&node.v_model) + .hint("先 form.describe 看这个字段到底属于哪张表;模型与表单对不上") + })?; + + let Some(raw) = lookup(payload, &node.v_model, &column) else { + // 没给值 ⇒ Java 那边 `o` 为空 ⇒ 用 `IS NULL` 判重。 + // 但基线平台的 `unique` 语义是「这个值只能有一份」—— + // 没给值时判重没意义(多数列 NOT NULL,落库时自然会报)。 + // ⇒ 这里**跳过**:交给必填校验 / 数据库 NOT NULL 去管。 + continue; + }; + + // Java `ObjectUtil.isEmpty(o) ? null : String.valueOf(o).trim()` + let value = match &raw { + Value::String(s) => { + let t = s.trim(); + if t.is_empty() { + continue; + } + Value::String(t.to_string()) + } + Value::Null => continue, + Value::Bool(b) => Value::String(b.to_string()), + Value::Number(n) => Value::String(n.to_string()), + _ => continue, + }; + + let mut params: Vec = Vec::new(); + let mut sql = format!( + "SELECT 1 FROM {} WHERE {} = $1", + table_schema.table, column + ); + params.push(match &value { + Value::String(s) => s.clone(), + other => other.to_string(), + }); + + // 逻辑删除的行不参与判重(对齐 Java 的 `delete_mark IS NULL` 条件)。 + if logical { + if let Some(dm) = delete_mark_column(table_schema) { + sql.push_str(&format!(" AND {} IS NULL", dm)); + } + } + + // 更新场景:排除自己那行。 + if let Some(rid) = record_id { + if let Some(pk) = primary_key_column(table_schema) { + sql.push_str(&format!(" AND {} <> $2", pk)); + params.push(rid.to_string()); + } + } + + sql.push_str(" LIMIT 1"); + + check_identifier("表名", &table_schema.table).map_err(ident_err)?; + check_identifier("列名", &column).map_err(ident_err)?; + + // 🔴 参数个数必须与 SQL 里的占位符**一一对应**。 + // 更新场景会多一个 `$2`(排除自己)⇒ 参数也要多一个。 + // 少传 ⇒ pglite 报 `statement takes 2 parameters, 1 given`。 + let refs: Vec<&(dyn pglite::ToSql + Sync)> = params + .iter() + .map(|s| s as &(dyn pglite::ToSql + Sync)) + .collect(); + let rows = db + .query_json_params(&sql, &refs) + .await + .map_err(|e| { + ToolError::new("DB_ERROR", format!("唯一性校验查库失败: {e}")) + .hint("先 schema.table.describe 看这张表的结构") + .retryable() + })?; + + if !rows.is_empty() { + return Err(unique_conflict(&node.label, &column, &value)); + } + } + Ok(()) +} + +/// 🔴 业务主键校验(对齐 `FormCheckUtils.checkBusinessKey()`)。 +/// +/// - 只在 `useBusinessKey == true` 且 `businessKeyList` 非空时生效; +/// - 清单里所有字段**一起**比(组合唯一); +/// - 任一字段没给值 ⇒ 该字段用 `IS NULL` 参与比较; +/// - 更新场景排除自己; +/// - 逻辑删除的行不参与判重。 +pub async fn check_business_key( + db: &Db, + form: &FormSchema, + model: &ModelSchema, + payload: &Value, + record_id: Option<&str>, +) -> Result<(), ToolError> { + let Some(nodes) = form.business_key_fields() else { + return Ok(()); + }; + let Some(main) = model.main_table() else { + return Ok(()); + }; + let logical = form.logical_delete.unwrap_or(false); + + // 把每个业务主键字段解析成「物理列 + 值」 + let mut cols: Vec = Vec::new(); + let mut values: Vec> = Vec::new(); + for node in &nodes { + let Some((tbl, col)) = resolve_table_and_column(model, node) else { + // 清单里的字段在模型里找不到 ⇒ 没法校验。 + // 静默跳过会放过重复数据 ⇒ 明确报错,让 AI 知道设计稿有问题。 + return Err(ToolError::new( + "BUSINESS_KEY_CHECK_FAILED", + format!( + "业务主键清单里的字段「{}」({}) 在模型里找不到对应的列 —— 无法校验", + node.label, node.v_model + ), + ) + .field(&node.v_model) + .hint("先 form.describe 看这个功能的字段与模型是否对得上")); + }; + if !tbl.table.eq_ignore_ascii_case(&main.table) { + // 业务主键只在**主表**上判重(Java `checkBusinessKey` 用 mainTable)。 + continue; + } + let v = lookup(payload, &node.v_model, &col) + .and_then(|v| match v { + Value::String(s) => { + let t = s.trim(); + if t.is_empty() { + None + } else { + Some(t.to_string()) + } + } + Value::Null => None, + Value::Bool(b) => Some(b.to_string()), + Value::Number(n) => Some(n.to_string()), + _ => None, + }); + cols.push(col); + values.push(v); + } + if cols.is_empty() { + return Ok(()); + } + + check_identifier("表名", &main.table).map_err(ident_err)?; + + // WHERE 条件:每个业务主键列 = ? (值为空则 IS NULL) + let mut where_parts: Vec = Vec::new(); + let mut params: Vec = Vec::new(); + for (i, (col, val)) in cols.iter().zip(values.iter()).enumerate() { + check_identifier("列名", col).map_err(ident_err)?; + match val { + Some(v) => { + params.push(v.clone()); + where_parts.push(format!("{} = ${}", col, params.len())); + } + None => { + where_parts.push(format!("{} IS NULL", col)); + } + } + let _ = i; + } + + let mut sql = format!("SELECT 1 FROM {} WHERE {}", main.table, where_parts.join(" AND ")); + + if logical { + if let Some(dm) = delete_mark_column(main) { + sql.push_str(&format!(" AND {} IS NULL", dm)); + } + } + if let Some(rid) = record_id { + if let Some(pk) = primary_key_column(main) { + params.push(rid.to_string()); + sql.push_str(&format!(" AND {} <> ${}", pk, params.len())); + } + } + sql.push_str(" LIMIT 1"); + + let refs: Vec<&(dyn pglite::ToSql + Sync)> = params + .iter() + .map(|s| s as &(dyn pglite::ToSql + Sync)) + .collect(); + let rows = db + .query_json_params(&sql, &refs) + .await + .map_err(|e| { + ToolError::new("DB_ERROR", format!("业务主键校验查库失败: {e}")) + .hint("先 schema.table.describe 看这张表的结构") + .retryable() + })?; + + if !rows.is_empty() { + return Err(business_key_conflict( + form.business_key_tip.as_deref(), + &cols, + )); + } + Ok(()) +} + +/// 🔴 标识符非法时的错误转换。 +fn ident_err(e: sspf_lowcode::SqlError) -> ToolError { + ToolError::new(e.code(), e.message()).hint("表名/列名只能含字母、数字、下划线") +} + +/// 🔴 找字段属于哪张表 + 它对应的物理列名。 +/// +/// 主表字段 → 主表;子表字段 → 子表(靠 `relationTable`)。 +fn resolve_table_and_column<'a>( + model: &'a ModelSchema, + node: &FieldNode, +) -> Option<(&'a sspf_lowcode::TableSchema, String)> { + // 子表字段:靠 `relationTable`(`tableName` 对子表字段不可信 —— 见 form.rs 注释) + if let Some(rel) = &node.relation_table { + if let Some(t) = model.table(rel) { + if let Some(col) = column_for(t, node) { + return Some((t, col)); + } + } + } + // 主表字段:靠 `tableName`;退回到主表 + if let Some(tn) = &node.table_name { + if let Some(t) = model.table(tn) { + if let Some(col) = column_for(t, node) { + return Some((t, col)); + } + } + } + let main = model.main_table()?; + let col = column_for(main, node)?; + Some((main, col)) +} + +/// 🔴 在一张表的列定义里找这个字段的物理列名。 +fn column_for(table: &sspf_lowcode::TableSchema, node: &FieldNode) -> Option { + // 先按 `__vModel__` 精确匹配 + if let Some(c) = table.column_by_field(&node.v_model) { + if let Some(col) = c.resolved_column() { + return Some(col); + } + } + // 再按「剥前缀 + 转小写」推导 + sspf_lowcode::v_model_to_column(&node.v_model) +} + +/// 🔴 主键列(排除租户列 —— Java `checkBusinessKey` 的口径)。 +fn primary_key_column(table: &sspf_lowcode::TableSchema) -> Option { + table + .primary_keys() + .into_iter() + .find(|c| !c.contains("f_tenant_id")) +} + +/// 🔴 删除标记列(逻辑删除时用来排除已删行)。 +fn delete_mark_column(table: &sspf_lowcode::TableSchema) -> Option { + table + .fields + .iter() + .find(|c| { + let f = c.field.to_lowercase(); + f.contains("f_delete_mark") || f == "delete_mark" + }) + .and_then(|c| c.resolved_column()) +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + const FORM: &str = r#"{ + "logicalDelete": true, + "useBusinessKey": true, + "businessKeyList": ["F_Code"], + "businessKeyTip": "业务编码已存在", + "fields": [ + { + "__config__": { + "jnpfKey": "input", "layout": "colFormItem", "label": "房间号", + "tableName": "biz_main", "required": true, "unique": true + }, + "__vModel__": "F_Room" + }, + { + "__config__": { + "jnpfKey": "input", "layout": "colFormItem", "label": "业务编码", + "tableName": "biz_main", "required": false + }, + "__vModel__": "F_Code" + }, + { + "__config__": { + "jnpfKey": "inputNumber", "layout": "colFormItem", "label": "数量", + "tableName": "biz_main", "unique": true + }, + "__vModel__": "F_Qty" + } + ] + }"#; + + const MODEL: &str = r#"[ + { + "table": "biz_main", "tableName": "主表", "typeId": "1", + "fields": [ + { "field": "F_Id", "fieldName": "主键", "dataType": "varchar", + "primaryKey": 1, "allowNull": false }, + { "field": "F_Tenant_Id", "fieldName": "租户", "dataType": "varchar", + "primaryKey": 1, "allowNull": false }, + { "field": "F_Room", "fieldName": "房间号", "dataType": "varchar" }, + { "field": "F_Code", "fieldName": "业务编码", "dataType": "varchar" }, + { "field": "F_Qty", "fieldName": "数量", "dataType": "int4" }, + { "field": "F_Delete_Mark", "fieldName": "删除标记", "dataType": "int4" } + ] + } + ]"#; + + fn form() -> FormSchema { + FormSchema::parse(&json!({ + "fields": serde_json::from_str::(FORM).unwrap()["fields"].clone(), + "logicalDelete": true, + "useBusinessKey": true, + "businessKeyList": ["F_Code"], + "businessKeyTip": "业务编码已存在", + })) + .unwrap() + } + + fn model() -> ModelSchema { + ModelSchema::parse(&serde_json::from_str::(MODEL).unwrap()).unwrap() + } + + /// 🔴 只有 `input` + `unique` 才参与判重 —— 数字控件标了 unique 也不查。 + #[test] + fn only_input_with_unique_is_checked() { + let f = form(); + let uniq = f.unique_fields(); + assert_eq!(uniq.len(), 1, "应该只有 F_Room 一个字段参与唯一校验"); + assert_eq!(uniq[0].v_model, "F_Room"); + } + + /// 🔴 业务主键清单能被解析成字段。 + #[test] + fn business_key_fields_are_resolved() { + let f = form(); + let bk = f.business_key_fields().expect("应该启用业务主键"); + assert_eq!(bk.len(), 1); + assert_eq!(bk[0].v_model, "F_Code"); + } + + /// 🔴 没启用业务主键 ⇒ 不校验。 + #[test] + fn business_key_disabled_returns_none() { + let f = FormSchema::parse(&json!({ + "fields": serde_json::from_str::(FORM).unwrap()["fields"].clone(), + })) + .unwrap(); + assert!(f.business_key_fields().is_none()); + } + + /// 🔴 主键列要排除租户列。 + #[test] + fn primary_key_excludes_tenant() { + let m = model(); + let main = m.main_table().unwrap(); + assert_eq!( + primary_key_column(main).as_deref(), + Some("f_id"), + "租户列也是 primaryKey=1,但不能被当成主键" + ); + } + + /// 🔴 删除标记列能被认出来。 + #[test] + fn delete_mark_column_is_found() { + let m = model(); + let main = m.main_table().unwrap(); + assert_eq!(delete_mark_column(main).as_deref(), Some("f_delete_mark")); + } +} diff --git a/crates/sspf-lowcode-exec/src/lowcode_crud.rs b/crates/sspf-lowcode-exec/src/lowcode_crud.rs new file mode 100644 index 0000000..9eb9209 --- /dev/null +++ b/crates/sspf-lowcode-exec/src/lowcode_crud.rs @@ -0,0 +1,1240 @@ +//! lowcode_crud —— 内核侧的**低代码动态 CRUD 执行层**(P2-b)。 +//! +//! ## 分工 +//! +//! | 层 | 位置 | 干什么 | +//! |---|---|---| +//! | 解析 / 校验 / **SQL 生成** | `sspf-lowcode`(纯计算,AR7) | 出 SQL 文本 + 参数 | +//! | **执行** | 本文件(内核) | 连库、跑 SQL、返回结果 | +//! +//! ⇒ SQL 生成的正确性由 `sspf-lowcode` 的单测覆盖;本文件只做「拿到 SQL 就执行」, +//! 没有分支逻辑 —— 这是刻意的分工。 +//! +//! ## 🔴 四条执行层的硬约定 +//! +//! 1. **主表先行、子表随后**:子表外键指向主表主键,顺序反了会插不进去。 +//! 2. **一个事务**:主表失败 ⇒ 子表也不能留孤儿行。 +//! pglite 有真事务 API(`transaction()` / `commit()` / `rollback()`)—— 用它。 +//! 3. **写入前先比对真实库列**:设计稿自洽 ≠ 真实库有那列。 +//! 官方数据里 `columnName` 全是 null,列名是从 `field` 推导的 —— +//! 推导必然有偏差(`F_CreatorTime` → `f_creatortime`,真实列可能是别的)。 +//! ⇒ 落库前拿 `information_schema` 对一遍,**对不上就拒绝写**, +//! 并明确告诉 AI「设计稿与真实库不一致」。 +//! 4. **子表更新走差集对账**:不是全量覆盖(详见 [`sspf_lowcode::diff_sub_rows`])。 +//! +//! ## 🔴 为什么第 3 条不能省 +//! +//! 省掉它 ⇒ 数据库报 `column "f_xxx" does not exist` —— +//! 这句话对 AI 毫无指导性(该改表单?改表?还是拼错了?)。 +//! 自己做比对 ⇒ 报「设计稿声明了 f_xxx,但真实库没有这一列」, +//! 直接指到要改的地方。 +//! +//! ## 🔴 值的类型:走 `::text` + 显式 cast +//! +//! pglite 绑参数时若不指定类型,PG 会把 `$1` **推断成目标列的类型** +//! (`timestamp` / `numeric` / `integer`),而我们绑的是 `Option` +//! ⇒ 直接报 `cannot convert between the Rust type String and the Postgres type timestamp`。 +//! ⇒ 一律 `$n::text`,再按列类型加 cast(`::numeric` / `::integer` / `::timestamp`)。 +//! +//! ## 🔴 cast 靠 `param_columns`,不靠猜 +//! +//! [`sspf_lowcode::Sql`] 自带「占位符 ↔ 列名」映射 ⇒ 执行层不需要 +//! 「理解 SQL 是怎么拼的」,也不需要「按模型字段顺序猜第 n 个参数是哪一列」 +//! (写入列顺序 ≠ 模型字段顺序 —— 系统列是运行时追加的,猜错就写脏数据)。 + +use std::collections::BTreeMap; + +use pglite::ToSql; +use serde_json::{json, Value}; + +use sspf_lowcode::{ + check_identifier, plan_delete, plan_insert, plan_update_full, sql::Sql, FieldNode, FormSchema, + ModelSchema, SqlError, SubUpdateContext, SubUpdateOptions, TableSchema, WriteContext, +}; +use sspf_mcp::adapter::ToolError; + +use sspf_core::db::Db; +use sspf_core::ids::new_uuid; + +/// 🔴 **单租户**下的默认租户值。 +/// +/// ## 溯源 +/// +/// 基线平台 `GlobalConst`: +/// ```java +/// public static final String DEFAULT_TENANT_VALUE = "0"; +/// ``` +/// +/// `TenantDataSourceUtil.getTenantColumn()`: +/// ```java +/// public static String getTenantColumn() { +/// String result = GlobalConst.DEFAULT_TENANT_VALUE; +/// if (isTenantColumn()) { // 只有「字段隔离」模式才取真实租户名 +/// result = getTenantName(); +/// } +/// return result; +/// } +/// ``` +/// +/// 本平台部署配置 `config.MultiTenancy: false` ⇒ `isTenantColumn()` 为 false +/// ⇒ **恒定返回 `"0"`**。 +/// +/// ## 🔴 为什么单租户下**仍然要写**租户列 +/// +/// `FlowFormDataUtil.addTenantId()` 是**无条件**执行的: +/// ```java +/// private void addTenantId(GeneralInsertDSL dsl, SqlTable t) { +/// dsl.set(t.column(TableFeildsEnum.TENANTID.getField())) +/// .toValue(TenantDataSourceUtil.getTenantColumn()); +/// } +/// ``` +/// ⇒ 单租户也会往 `f_tenant_id` 写 `"0"`。 +/// 不写的话,列是 NOT NULL(`TableFeildsEnum.TENANTID` 的 nullSign = "NOT NULL") +/// ⇒ 插入直接失败。 +pub const DEFAULT_TENANT_ID: &str = "0"; + +/// 动态 CRUD 的执行结果。 +#[derive(Debug, Clone)] +pub struct CrudOutcome { + /// 主键 id。 + pub id: String, + /// 实际执行的 SQL 条数(主表 + 子表)。 + pub statements: usize, + /// 诊断信息(哪些列没写、为什么)。 + pub notes: Vec, + /// 计划好的 SQL(dry-run 时返回给调用方看)。 + pub sql: Vec, + /// 是否只是演练(没落库)。 + pub dry_run: bool, +} + +/// 把 lowcode 的错误转成结构化工具错误。 +pub fn sql_err(e: SqlError) -> ToolError { + let mut t = ToolError::new(e.code(), e.message()); + match &e { + SqlError::UnknownColumn { table, column } => { + t = t + .field(column) + .hint(format!( + "表 {table} 里没有列 {column};先 form.describe 看真实字段清单" + )) + .next( + "form.describe", + json!({ "enCode": "<功能编码>" }), + "看这个功能的字段与列", + ); + } + SqlError::MissingRequired { table, column, label } => { + t = t.field(column).hint(format!( + "必填字段「{label}」({table}.{column}) 必须给值;\ + 确实要留空就先把它从「必填」里去掉" + )); + } + SqlError::UnknownTable(tbl) => { + t = t + .field("table") + .hint(format!("表 {tbl} 不在功能定义里 —— 表名白名单不通过")) + .next( + "form.validate", + json!({ "enCode": "<功能编码>" }), + "先体检这个功能", + ); + } + SqlError::NoMainTable => { + t = t.hint("模型里没有 typeId=1 的主表 —— 这个功能定义可能不完整"); + } + SqlError::NoPrimaryKey(tbl) => { + t = t.hint(format!( + "表 {tbl} 缺主键:入参没给,且调用方没生成 —— \ + 子表每行的主键需要调用方预先生成并登记" + )); + } + SqlError::TypeMismatch { column, expected } => { + t = t.field(column).hint(format!("字段 {column} 应为 {expected}")); + } + SqlError::UnsupportedValue { column } => { + t = t.field(column).hint(format!( + "字段 {column} 的值是复杂对象 —— 只能给字符串/数字/数组;\ + 对象请先序列化成 JSON 字符串" + )); + } + SqlError::IllegalIdentifier { kind, value } => { + t = t.hint(format!( + "{kind}「{value}」含非法字符,只能是字母/数字/下划线" + )); + } + SqlError::NoColumnsToUpdate(tbl) => { + t = t.hint(format!( + "表 {tbl} 没有任何列要更新 —— 入参没给可写字段,或给的都是系统字段" + )); + } + SqlError::MissingRelationValue { table, column } => { + t = t.hint(format!( + "子表 {table} 的外键指向主表的 {column},但这一列的值拿不到 —— \ + 它不是主键,需要先查出来再传进来" + )); + } + SqlError::LogicalDeleteUnsupported(tbl) => { + t = t.hint(format!( + "表 {tbl} 没有删除标记列,不支持逻辑删除 —— \ + 这个功能要么该走物理删除,要么表建错了(logicalDelete 与建表不匹配)" + )) + .next( + "form.validate", + json!({ "enCode": "<功能编码>" }), + "体检这个功能的逻辑删除设置", + ); + } + } + t +} + +/// 🔴 设计稿 vs 真实库:列名比对结果。 +#[derive(Debug, Clone, PartialEq)] +pub struct ColumnMismatch { + /// 真实库里缺的设计稿列。 + pub missing: Vec, + /// 真实库有、但设计稿没声明的列(通常是系统列,不算错,仅供参考)。 + pub extra: Vec, +} + +/// 取一张表在真实库里的列名。 +pub async fn real_columns(db: &Db, table: &str) -> Result, ToolError> { + let t = table.to_string(); + let rows = db + .query_json_params( + "SELECT column_name AS \"name\" FROM information_schema.columns \ + WHERE table_schema = 'public' AND table_name = $1 \ + ORDER BY ordinal_position", + &[&t], + ) + .await + .map_err(|e| { + ToolError::new("DB_ERROR", format!("读表结构失败: {e}")) + .hint("先 schema.table.list 确认表在不在") + .retryable() + })?; + Ok(rows + .into_iter() + .filter_map(|r| r["name"].as_str().map(str::to_string)) + .collect()) +} + +/// 比对设计稿声明的列与真实库的列。 +pub fn compare_columns(declared: &[String], actual: &[String]) -> ColumnMismatch { + let actual_lower: Vec = actual.iter().map(|c| c.to_lowercase()).collect(); + let missing: Vec = declared + .iter() + .filter(|c| !actual_lower.contains(&c.to_lowercase())) + .cloned() + .collect(); + let declared_lower: Vec = declared.iter().map(|c| c.to_lowercase()).collect(); + let extra: Vec = actual + .iter() + .filter(|c| !declared_lower.contains(&c.to_lowercase())) + .cloned() + .collect(); + ColumnMismatch { missing, extra } +} + +/// 🔴 真实库里**根本没有这张表**时的错误。 +pub fn table_missing_error(table: &str) -> ToolError { + ToolError::new("TABLE_NOT_IN_DB", format!("真实库里没有表 {table}")).field("table").hint( + "设计稿里的表还没建出来 —— 低代码功能要先「建表」再「存数据」。\ + 用 schema.table.list 看当前库有哪些表", + ) + .next( + "schema.table.list", + json!({ "prefix": table }), + "看这张表在不在", + ) +} + +/// 构造写入上下文(把内核有的东西塞进去)。 +pub fn build_context( + user_id: Option<&str>, + tenant_id: Option<&str>, + now: Option<&str>, +) -> WriteContext { + WriteContext { + user_id: user_id.map(str::to_string), + organize_ids: Vec::new(), + position_ids: Vec::new(), + tenant_id: tenant_id.map(str::to_string), + bill_numbers: Default::default(), + primary_keys: Default::default(), + now: now.map(str::to_string), + relation_values: Default::default(), + } +} + +/// 🔴 当前时间(ISO8601,秒精度)。 +/// +/// 🔴 为什么用**秒精度**而不是毫秒/纳秒: +/// 低代码表的 `f_creatortime` / `f_lastmodifytime` 在官方 DDL 里是 +/// `timestamp`(**没有时区**)⇒ 传 ISO 带 `T` 和 `Z` 的串会被 PG +/// 解析成 `timestamptz` 再转 `timestamp` ⇒ **会随时区偏移几个小时**。 +/// 统一给 `YYYY-MM-DD HH:MM:SS` 最稳(PG 直接当 timestamp 字面量)。 +pub fn now_iso() -> String { + chrono::Local::now() + .format("%Y-%m-%d %H:%M:%S") + .to_string() +} + +/// 执行一次**新增**(主表 + 子表),全部落在一个事务里。 +/// +/// `dry_run = true` ⇒ 只生成 SQL + 校验列,**不落库**。 +pub async fn insert_record( + db: &Db, + form: &FormSchema, + model: &ModelSchema, + payload: &Value, + ctx: &mut WriteContext, + dry_run: bool, +) -> Result { + let main_table = model.main_table().ok_or_else(|| { + ToolError::new("NO_MAIN_TABLE", "模型里没有主表(typeId=1)") + .hint("这个功能定义不完整") + })?; + let main_name = main_table.table.clone(); + + // 🔴 落库前先确认表在真实库里 + let real = real_columns(db, &main_name).await?; + if real.is_empty() { + return Err(table_missing_error(&main_name)); + } + + // 生成主键 + let main_id = new_uuid(); + ctx.set_primary_key(main_name.clone(), main_id.clone()); + + // 子表每行也要主键(Java 侧服务端现生成 UUID) + for sub in form.sub_tables() { + let Some(sub_model) = resolve_sub_model(model, sub) else { + continue; + }; + let rows = sub_rows(payload, &sub.v_model, &sub_model.table); + let Some(arr) = rows.as_ref().and_then(|v| v.as_array()) else { + continue; + }; + for i in 0..arr.len() { + let key = new_uuid(); + ctx.set_sub_row_key(&sub_model.table, &main_id, i, key); + } + } + + let plan = plan_insert(form, model, payload, ctx, &main_id).map_err(sql_err)?; + + // 🔴 逐条比对真实库列 —— 对不上就**拒绝写**,而不是让数据库报错 + let mut notes: Vec = Vec::new(); + let mut real_cols: Vec<(String, Vec)> = Vec::new(); + for stmt in plan.all() { + let cols = columns_of_sql(&stmt.text); + let actual = match real_cols.iter().find(|(t, _)| t == &stmt.table) { + Some((_, c)) => c.clone(), + None => { + let a = real_columns(db, &stmt.table).await?; + if a.is_empty() { + return Err(table_missing_error(&stmt.table)); + } + real_cols.push((stmt.table.clone(), a.clone())); + a + } + }; + let diff = compare_columns(&cols, &actual); + if !diff.missing.is_empty() { + return Err(column_mismatch_error(&stmt.table, &diff, &actual)); + } + if !diff.extra.is_empty() { + notes.push(format!( + "表 {} 真实库里还有设计稿没声明的列(未写入):{}", + stmt.table, + diff.extra.join(", ") + )); + } + } + + let stmts: Vec = plan.all().into_iter().cloned().collect(); + + // 🔴 **业务校验**(唯一性 / 业务主键)—— 必须在真正写库**之前**做。 + // + // 基线平台 `VisualdevModelDataServiceImpl.visualCreate()`: + // ```java + // String b = formCheckUtils.checkForm(checkFormModel); + // if (StringUtil.isNotEmpty(b)) { throw new WorkFlowException(b); } + // flowFormDataUtil.create(dataModel); + // ``` + // ⇒ 校验失败 ⇒ **一条 SQL 都不执行**。 + // + // dry-run 也要做校验:dry-run 的意义是「先看会不会被拦」。 + // 校验不过还返回 SQL,AI 会误以为「只差一步就能落库」。 + // + // 新增场景 `record_id = None` ⇒ 不排除任何行。 + crate::lowcode_check::check_unique_fields(db, form, model, payload, None).await?; + crate::lowcode_check::check_business_key(db, form, model, payload, None).await?; + + if dry_run { + return Ok(CrudOutcome { + id: main_id, + statements: stmts.len(), + notes, + sql: stmts, + dry_run: true, + }); + } + + let count = execute_plan(db, model, &stmts).await?; + + Ok(CrudOutcome { + id: main_id, + statements: count, + notes, + sql: stmts, + dry_run: false, + }) +} + +/// 🔴 记录不存在的错误(AI 据此自纠:先查再改)。 +pub fn record_missing_error(table: &str, record_id: &str) -> ToolError { + ToolError::new( + "RECORD_NOT_FOUND", + format!("表 {table} 里没有 id 为 {record_id} 的记录"), + ) + .field("recordId") + .hint("记录可能已被删除;先用 data.query 查一遍确认 id") + .next( + "data.query", + json!({ "enCode": "<功能编码>" }), + "查这条记录还在不在", + ) +} + +/// 执行一次**更新**(主表 + 子表差集对账)。 +/// +/// ## 🔴 `only_update` 的口径(对齐基线平台) +/// +/// 基线平台 `DataModel.onlyUpdate`: +/// ```java +/// // 子表仅修改 +/// private Boolean onlyUpdate = false; +/// ``` +/// ```java +/// if (CollUtil.isNotEmpty(deleteList) && !onlyUpdate) { /* 删缺失的旧行 */ } +/// ``` +/// +/// ⇒ `onlyUpdate = true` ⇒ **不删**入参里缺失的旧行(只更新/新增)。 +/// +/// 🔴 **基线的正常 HTTP 路径恒为 false**: +/// `VisualdevModelDataController` 构造 `VisualParamModel` 时**没有**设 `onlyUpdate` +/// ⇒ 只有 Excel 导入(`OnlineExcelUtil`)与流程场景才可能为 true。 +/// ⇒ 本函数默认 `false`,MCP 层**不暴露**这个开关(暴露了会让 AI 以为 +/// 「默认只更新不删除」,与基线的实际行为相反)。 +#[allow(clippy::too_many_arguments)] +pub async fn update_record( + db: &Db, + form: &FormSchema, + model: &ModelSchema, + payload: &Value, + ctx: &mut WriteContext, + record_id: &str, + dry_run: bool, +) -> Result { + update_record_with(db, form, model, payload, ctx, record_id, dry_run, false).await +} + +/// 带 `only_update` 的更新(默认路径走 [`update_record`])。 +#[allow(clippy::too_many_arguments)] +pub async fn update_record_with( + db: &Db, + form: &FormSchema, + model: &ModelSchema, + payload: &Value, + ctx: &mut WriteContext, + record_id: &str, + dry_run: bool, + only_update: bool, +) -> Result { + let main_table = model.main_table().ok_or_else(|| { + ToolError::new("NO_MAIN_TABLE", "模型里没有主表(typeId=1)") + })?; + let main_name = main_table.table.clone(); + + let real = real_columns(db, &main_name).await?; + if real.is_empty() { + return Err(table_missing_error(&main_name)); + } + + // 🔴 **先确认记录存在** —— 否则错误会一路飘到子表查询上, + // 变成一句毫无指导性的 `DB_ERROR`(AI 不知道是「记录没了」还是「库坏了」)。 + ensure_record_exists(db, model, record_id).await?; + + // 🔴 **顺序很重要**:先查主表那一行的**关联列实际值**,再收集子表上下文。 + // + // 子表外键的值 = 主表 `relationField` 指向的那一列的值 + // (基线平台:`mainMap.get(table.getRelationField())`)。 + // 当 `relationField` 就是主键时,值 = 主键,收集子表上下文时回落到 `record_id` 没问题; + // 但当它指向**别的列**(如业务编码 `F_Code`)时, + // 不先查库就拿不到值 ⇒ 外键会退化成主键 ⇒ 子表挂错父行。 + // + // 之前顺序反了(先 collect 再 fetch)⇒ 非主键 relationField 场景下 + // `collect_sub_contexts` 拿不到关联值,回落成 `main_id`。 + let relation_values = fetch_relation_values(db, form, model, record_id).await?; + for (col, val) in &relation_values { + ctx.set_relation_value(col, val.clone()); + } + + // 🔴 子表差集需要「旧行主键」—— 查库在**事务外**做(避免持锁期间再开事务死锁)。 + let logical = form.logical_delete.unwrap_or(false); + let sub_ctxs = collect_sub_contexts(db, form, model, ctx, record_id, logical, only_update).await?; + + let plan = plan_update_full(form, model, payload, ctx, record_id, &sub_ctxs).map_err(sql_err)?; + + let mut notes: Vec = Vec::new(); + let mut real_cols: Vec<(String, Vec)> = Vec::new(); + for stmt in plan.all() { + let cols = columns_of_sql(&stmt.text); + if cols.is_empty() { + continue; + } + let actual = match real_cols.iter().find(|(t, _)| t == &stmt.table) { + Some((_, c)) => c.clone(), + None => { + let a = real_columns(db, &stmt.table).await?; + if a.is_empty() { + return Err(table_missing_error(&stmt.table)); + } + real_cols.push((stmt.table.clone(), a.clone())); + a + } + }; + let diff = compare_columns(&cols, &actual); + if !diff.missing.is_empty() { + return Err(column_mismatch_error(&stmt.table, &diff, &actual)); + } + if !diff.extra.is_empty() { + notes.push(format!( + "表 {} 真实库里还有设计稿没声明的列(未写入):{}", + stmt.table, + diff.extra.join(", ") + )); + } + } + + let stmts: Vec = plan.all().into_iter().cloned().collect(); + + // 🔴 **业务校验**(唯一性 / 业务主键)—— 更新场景要**排除自己那行**。 + // + // 基线平台 `FormCheckUtils` 的唯一性 SQL: + // ```java + // if (StringUtils.isNotEmpty(id)) { + // where.and(sqlTable.column(mainKeyModel.getField()), SqlBuilder.isNotEqualTo(realId)); + // } + // ``` + // ⇒ 不排除自己 ⇒ 改一下别的字段也会被判「重复」。 + crate::lowcode_check::check_unique_fields(db, form, model, payload, Some(record_id)).await?; + crate::lowcode_check::check_business_key(db, form, model, payload, Some(record_id)).await?; + + if dry_run { + return Ok(CrudOutcome { + id: record_id.to_string(), + statements: stmts.len(), + notes, + sql: stmts, + dry_run: true, + }); + } + + let count = execute_plan(db, model, &stmts).await?; + + Ok(CrudOutcome { + id: record_id.to_string(), + statements: count, + notes, + sql: stmts, + dry_run: false, + }) +} + +/// 执行一次**删除**(逻辑 / 物理按 `form.logicalDelete`)。 +pub async fn delete_record( + db: &Db, + form: &FormSchema, + model: &ModelSchema, + ctx: &mut WriteContext, + record_id: &str, + dry_run: bool, +) -> Result { + let main_table = model.main_table().ok_or_else(|| { + ToolError::new("NO_MAIN_TABLE", "模型里没有主表(typeId=1)") + })?; + let main_name = main_table.table.clone(); + + let real = real_columns(db, &main_name).await?; + if real.is_empty() { + return Err(table_missing_error(&main_name)); + } + + // 🔴 先确认记录存在(否则错误会飘到子表查询上,变成没指导性的 DB_ERROR)。 + ensure_record_exists(db, model, record_id).await?; + + let logical = form.logical_delete.unwrap_or(false); + + // 🔴 子表外键的值可能不是主键(`relationField` 指向别的列)⇒ 先查主表那一行。 + let relation_values = fetch_relation_values(db, form, model, record_id).await?; + for (col, val) in &relation_values { + ctx.set_relation_value(col, val.clone()); + } + + // 逻辑删除但表里没有删除列 ⇒ `plan_delete` 会报 `LOGICAL_DELETE_UNSUPPORTED`。 + // 那种情况**不退化成物理删**(用户以为逻辑删了,实际物理删 ⇒ 审计链断)。 + let plan = plan_delete(form, model, ctx, record_id).map_err(sql_err)?; + + let mut notes: Vec = Vec::new(); + let mut real_cols: Vec<(String, Vec)> = Vec::new(); + for stmt in plan.all() { + let cols = columns_of_sql(&stmt.text); + if cols.is_empty() { + continue; + } + let actual = match real_cols.iter().find(|(t, _)| t == &stmt.table) { + Some((_, c)) => c.clone(), + None => { + let a = real_columns(db, &stmt.table).await?; + if a.is_empty() { + return Err(table_missing_error(&stmt.table)); + } + real_cols.push((stmt.table.clone(), a.clone())); + a + } + }; + let diff = compare_columns(&cols, &actual); + if !diff.missing.is_empty() { + return Err(column_mismatch_error(&stmt.table, &diff, &actual)); + } + if !diff.extra.is_empty() { + notes.push(format!( + "表 {} 真实库里还有设计稿没声明的列(未写入):{}", + stmt.table, + diff.extra.join(", ") + )); + } + } + + notes.push(if logical { + "逻辑删除:置删除标记,数据仍在表里".to_string() + } else { + "物理删除:行会真从表里消失(logicalDelete=false)".to_string() + }); + + let stmts: Vec = plan.all().into_iter().cloned().collect(); + + if dry_run { + return Ok(CrudOutcome { + id: record_id.to_string(), + statements: stmts.len(), + notes, + sql: stmts, + dry_run: true, + }); + } + + let count = execute_plan(db, model, &stmts).await?; + + Ok(CrudOutcome { + id: record_id.to_string(), + statements: count, + notes, + sql: stmts, + dry_run: false, + }) +} + +/// 🔴 确认主记录存在(更新 / 删除前必查)。 +/// +/// ## 为什么必须单独查一次 +/// +/// 更新流程后面会去查子表旧行、关联列值 —— 那些查询用的都是 `record_id`。 +/// 记录不存在时,错误会飘到子表查询上,变成一句 +/// `DB_ERROR: 查子表旧行失败: relation "xxx" does not exist` —— +/// AI 看到完全不知道是「记录没了」还是「库坏了」。 +/// +/// ⇒ 先明确报 `RECORD_NOT_FOUND`,并提示「先用 data.query 查一遍」。 +/// +/// ## 🔴 主键列**从模型推导**,不写死 `f_id` +/// +/// Java `getKey()`:取模型里 `primaryKey=1` 且**不是租户列**的那一列。 +/// 官方模型里 `f_tenant_id` 也是 `primaryKey=1` ⇒ 必须排除。 +async fn ensure_record_exists( + db: &Db, + model: &ModelSchema, + record_id: &str, +) -> Result<(), ToolError> { + let Some(main_table) = model.main_table() else { + return Ok(()); + }; + let table = main_table.table.clone(); + let pk_col = main_table + .primary_keys() + .into_iter() + .find(|c| !c.contains("f_tenant_id")) + .unwrap_or_else(|| "f_id".to_string()); + + // 🔴 表名/列名来自用户可编辑的模型 JSON ⇒ 进 SQL 前过标识符检查。 + check_identifier("表名", &table).map_err(sql_err)?; + check_identifier("列名", &pk_col).map_err(sql_err)?; + + let id = record_id.to_string(); + let sql = format!("SELECT {pk_col} AS \"id\" FROM {table} WHERE {pk_col} = $1 LIMIT 1"); + let rows = db + .query_json_params(&sql, &[&id]) + .await + .map_err(|e| ToolError::new("DB_ERROR", format!("查记录失败: {e}")).retryable())?; + if rows.is_empty() { + return Err(record_missing_error(&table, record_id)); + } + Ok(()) +} + +/// 🔴 收集子表更新的上下文(**旧行主键**从库里查)。 +/// +/// 差集对账的前提是知道「旧库里有哪些行」。 +/// 本函数是**纯查库**(不改数据)⇒ 放在事务外执行,避免持锁期间再开事务。 +async fn collect_sub_contexts( + db: &Db, + form: &FormSchema, + model: &ModelSchema, + ctx: &WriteContext, + main_id: &str, + logical: bool, + only_update: bool, +) -> Result, ToolError> { + let mut out: BTreeMap = BTreeMap::new(); + + for sub in form.sub_tables() { + let Some(sub_model) = resolve_sub_model(model, sub) else { + continue; + }; + let Some(fk_col) = sub_model.foreign_key_column() else { + return Err(sql_err(SqlError::UnknownColumn { + table: sub_model.table.clone(), + column: "tableField".to_string(), + })); + }; + let sub_pk = sub_model + .primary_keys() + .into_iter() + .find(|c| !c.contains("f_tenant_id")) + .unwrap_or_else(|| "f_id".to_string()); + + // 🔴 表名/列名进 SQL 之前必须过标识符检查。 + // + // 这些名字来自**用户可编辑的模型 JSON**(`f_tables_data`)。 + // 参数化只能防「值注入」,**防不住结构注入** —— + // 表名/列名是拼进 SQL 文本的,不是占位符。 + // ⇒ 规则与生成层共用同一份(`sspf_lowcode::check_identifier`), + // 避免「生成层拦了、执行层漏了」的漏洞。 + for (kind, name) in [ + ("表名", sub_model.table.as_str()), + ("列名", fk_col.as_str()), + ("列名", sub_pk.as_str()), + ] { + check_identifier(kind, name).map_err(sql_err)?; + } + + // 外键的值:主表 `relationField` 指向的那一列的实际值。 + let fk_value = ctx + .relation_value(sub_model) + .unwrap_or_else(|| main_id.to_string()); + + // 查旧行主键 + let sql = format!( + "SELECT {sub_pk} AS \"k\" FROM {table} WHERE {fk_col} = $1", + sub_pk = sub_pk, + table = sub_model.table, + fk_col = fk_col, + ); + let rows = db + .query_json_params(&sql, &[&fk_value]) + .await + .map_err(|e| { + ToolError::new("DB_ERROR", format!("查子表旧行失败: {e}")) + .hint("子表可能还没建出来") + .retryable() + })?; + let old_keys: Vec = rows + .into_iter() + .filter_map(|r| r["k"].as_str().map(str::to_string)) + .collect(); + + let mut sub_ctx = SubUpdateContext::new( + old_keys, + fk_col.clone(), + fk_value, + SubUpdateOptions { + only_update, + logical_delete: logical, + }, + ); + // 🔴 子表行主键由内核生成(Java 侧是 `RandomUtil.uuId()`)。 + sub_ctx.row_key_generator = Some(|_| new_uuid()); + out.insert(sub_model.table.clone(), sub_ctx); + } + + Ok(out) +} + +/// 🔴 查主表那一行的**关联列**实际值(子表外键要指向它)。 +/// +/// 基线平台:`Object relationFieldValue = mainMap.get(table.getRelationField());` +/// —— 读的是**主表那一行的实际值**,不是主键。 +/// +/// `relationField` 通常就是主键列 ⇒ 这次查询走的是「白名单内的表名 + 白名单内的列名」。 +async fn fetch_relation_values( + db: &Db, + form: &FormSchema, + model: &ModelSchema, + main_id: &str, +) -> Result, ToolError> { + let Some(main_table) = model.main_table() else { + return Ok(Vec::new()); + }; + let main_pk = main_table + .primary_keys() + .into_iter() + .find(|c| !c.contains("f_tenant_id")) + .unwrap_or_else(|| "f_id".to_string()); + + // 🔴 表名/主键列名进 SQL 之前必须过标识符检查(同 [`collect_sub_contexts`])。 + check_identifier("表名", &main_table.table).map_err(sql_err)?; + check_identifier("列名", &main_pk).map_err(sql_err)?; + + // 收集所有子表用到的关联列 + let mut cols: Vec = Vec::new(); + for sub in form.sub_tables() { + let Some(sub_model) = resolve_sub_model(model, sub) else { + continue; + }; + if let Some(rel) = sub_model.relation_column() { + // 🔴 关联列名同样来自用户可编辑的模型 JSON ⇒ 也要过检查。 + check_identifier("列名", &rel).map_err(sql_err)?; + if !cols.contains(&rel) { + cols.push(rel); + } + } + } + if cols.is_empty() { + return Ok(Vec::new()); + } + + // 一次查出来 + let sel: Vec = cols.iter().map(|c| format!("{c} AS \"{c}\"")).collect(); + let sql = format!( + "SELECT {} FROM {} WHERE {} = $1", + sel.join(", "), + main_table.table, + main_pk + ); + let rows = db + .query_json_params(&sql, &[&main_id.to_string()]) + .await + .map_err(|e| { + ToolError::new("DB_ERROR", format!("查主表关联列失败: {e}")).retryable() + })?; + + let Some(row) = rows.first() else { + return Ok(Vec::new()); + }; + + let mut out = Vec::new(); + for c in cols { + if let Some(v) = row.get(&c) { + let text = match v { + Value::String(s) => s.clone(), + Value::Null => continue, + other => other.to_string(), + }; + out.push((c, text)); + } + } + Ok(out) +} + +/// 🔴 在一个事务里执行整组 SQL。 +/// +/// pglite 的 `transaction()` 会拿**独占锁**(`lock_for_transaction`), +/// 所以事务期间不会有别的请求插进来 —— 不会出现「A 写了主表、B 改了子表」的交错。 +async fn execute_plan( + db: &Db, + model: &ModelSchema, + stmts: &[Sql], +) -> Result { + if stmts.is_empty() { + return Ok(0); + } + let tx = db.begin().await.map_err(|e| { + ToolError::new("DB_ERROR", format!("开事务失败: {e}")).retryable() + })?; + + for stmt in stmts { + let table = model.table(&stmt.table); + let sql_text = render_with_casts(&stmt.text, &stmt.params, &stmt.param_columns, table); + let params = params_as_text(&stmt.params); + let refs: Vec<&(dyn ToSql + Sync)> = + params.iter().map(|v| v as &(dyn ToSql + Sync)).collect(); + + if let Err(e) = tx.exec_params(&sql_text, &refs).await { + let _ = tx.rollback().await; + return Err(ToolError::new("DB_ERROR", format!("写库失败: {e}")) + .hint("多半是列名与真实表对不上;先 form.validate 再看真实表的列") + .retryable()); + } + } + + tx.commit().await.map_err(|e| { + ToolError::new("DB_ERROR", format!("提交事务失败: {e}")).retryable() + })?; + + Ok(stmts.len()) +} + +/// 🔴 列不一致时的结构化错误。 +fn column_mismatch_error( + table: &str, + diff: &ColumnMismatch, + actual: &[String], +) -> ToolError { + ToolError::new( + "COLUMN_MISMATCH", + format!( + "表 {} 缺少设计稿声明的列:{}", + table, + diff.missing.join(", ") + ), + ) + .field(diff.missing.first().map(|s| s.as_str()).unwrap_or("")) + .hint(format!( + "真实库里 {} 只有这些列:{}。\ + 设计稿的列名是从 `field` 推导的(官方数据 columnName 全是 null),\ + 推导必然有偏差 —— 要么改设计稿,要么改真实表", + table, + actual.join(", ") + )) + .next( + "form.validate", + json!({ "enCode": "<功能编码>" }), + "体检设计稿自洽性", + ) +} + +/// 把 `$n` 占位符改成 `$n::text` + 类型 cast。 +/// +/// 🔴 必须加 `::text`:pglite 绑 `Option`, +/// 若让 PG 把 `$1` 推断成 `timestamp` / `numeric`,会直接报 +/// `cannot convert between the Rust type String and the Postgres type timestamp`。 +/// +/// 🔴 占位符必须**按完整 token 扫描**:`$1` 是 `$10` 的前缀, +/// 用字符串 find 会把 `$10` 改成 `$1::text0::text`。 +/// +/// 🔴 cast 靠 `param_columns`(占位符 ↔ 列名的一一映射), +/// **不猜**「第 n 个参数是哪一列」。 +fn render_with_casts( + text: &str, + params: &[Value], + param_columns: &[String], + table: Option<&TableSchema>, +) -> String { + let mut out = String::with_capacity(text.len() + params.len() * 8); + let bytes = text.as_bytes(); + let mut i = 0usize; + + while i < bytes.len() { + if bytes[i] == b'$' { + // 读数字 + let mut j = i + 1; + while j < bytes.len() && bytes[j].is_ascii_digit() { + j += 1; + } + if j > i + 1 { + let idx: usize = text[i + 1..j].parse().unwrap_or(0); + out.push_str(&text[i..j]); + out.push_str("::text"); + if let Some(col) = param_columns.get(idx.saturating_sub(1)) { + out.push_str(cast_of_type(col, table)); + } + i = j; + continue; + } + } + let ch_len = utf8_len(bytes[i]); + out.push_str(&text[i..i + ch_len]); + i += ch_len; + } + out +} + +/// 取一个 UTF-8 字符的字节长度。 +fn utf8_len(b: u8) -> usize { + if b < 0x80 { + 1 + } else if b >> 5 == 0b110 { + 2 + } else if b >> 4 == 0b1110 { + 3 + } else if b >> 3 == 0b11110 { + 4 + } else { + 1 + } +} + +/// 按列名给出写值时的 cast。 +fn cast_of_type(column: &str, table: Option<&TableSchema>) -> &'static str { + let Some(table) = table else { + return ""; + }; + // 先看模型里声明的数据类型 + if let Some(def) = table.column_by_name(column) { + match def.data_type.to_lowercase().as_str() { + "int" | "integer" | "int2" | "int4" | "int8" | "bigint" | "smallint" => { + return "::integer" + } + "decimal" | "numeric" | "money" | "real" | "double" | "float" => return "::numeric", + "datetime" | "timestamp" | "date" | "time" => return "::timestamp", + "bool" | "boolean" => return "::boolean", + _ => {} + } + } + // 模型没说 ⇒ 按列名特征兜底 + let lower = column.to_lowercase(); + if lower.ends_with("_time") || lower.ends_with("_date") || lower.ends_with("time") { + return "::timestamp"; + } + "" +} + +/// 值 ⇒ `Option`(绑定用)。 +/// +/// 🔴 一律按**文本**传 —— 类型转换交给 SQL 里的 `::text` + cast 链。 +fn params_as_text(values: &[Value]) -> Vec> { + values + .iter() + .map(|v| match v { + Value::Null => None, + Value::String(s) => Some(s.clone()), + Value::Number(n) => Some(n.to_string()), + Value::Bool(b) => Some(b.to_string()), + other => Some(other.to_string()), + }) + .collect() +} + +/// 从一条 SQL 里取出列名。 +fn columns_of_sql(text: &str) -> Vec { + if let Some((_, rest)) = text.split_once(" (") { + if let Some((cols, _)) = rest.split_once(") VALUES") { + return cols.split(", ").map(|s| s.to_string()).collect(); + } + } + if let Some((_, rest)) = text.split_once(" SET ") { + if let Some((sets, _)) = rest.split_once(" WHERE ") { + return sets + .split(", ") + .filter_map(|s| s.split(" = ").next()) + .map(|s| s.to_string()) + .collect(); + } + } + Vec::new() +} + +/// 找出子表节点对应的模型表。 +fn resolve_sub_model<'a>( + model: &'a ModelSchema, + sub: &FieldNode, +) -> Option<&'a TableSchema> { + if let Some(name) = sub.table_name.as_deref() { + if let Some(t) = model.table(name) { + return Some(t); + } + } + for child in &sub.children { + if let Some(rt) = child.relation_table.as_deref() { + if let Some(t) = model.table(rt) { + return Some(t); + } + } + } + let subs = model.sub_tables(); + if subs.len() == 1 { + Some(subs[0]) + } else { + None + } +} + +/// 从 payload 里取子表行数组。 +fn sub_rows(payload: &Value, v_model: &str, table: &str) -> Option { + let obj = payload.as_object()?; + if let Some(v) = obj.get(v_model) { + return Some(v.clone()); + } + for (k, v) in obj { + if k.eq_ignore_ascii_case(v_model) || k.eq_ignore_ascii_case(table) { + return Some(v.clone()); + } + } + None +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 🔴 比对必须能抓出「设计稿有、真实库没有」的列。 + #[test] + fn compare_columns_finds_missing() { + let declared = vec!["f_id".to_string(), "f_room".to_string()]; + let actual = vec!["f_id".to_string()]; + let diff = compare_columns(&declared, &actual); + assert_eq!(diff.missing, vec!["f_room".to_string()]); + assert!(diff.extra.is_empty()); + } + + /// 大小写不敏感(PG 会折叠大小写)。 + #[test] + fn compare_columns_is_case_insensitive() { + let declared = vec!["F_ID".to_string()]; + let actual = vec!["f_id".to_string()]; + let diff = compare_columns(&declared, &actual); + assert!(diff.missing.is_empty(), "不该报缺列: {:?}", diff.missing); + } + + /// 🔴 占位符必须加 `::text` —— 否则 PG 推断成 timestamp/numeric 会报类型错。 + #[test] + fn placeholders_get_text_cast() { + let out = render_with_casts( + "INSERT INTO t (a, b) VALUES ($1, $2)", + &[Value::String("x".into()), Value::String("y".into())], + &["a".to_string(), "b".to_string()], + None, + ); + assert_eq!(out, "INSERT INTO t (a, b) VALUES ($1::text, $2::text)"); + } + + /// 数值列要加 `::numeric`。 + #[test] + fn numeric_column_gets_numeric_cast() { + let model = ModelSchema::from_str( + r#"[{ "table": "t", "typeId": "1", "fields": [ + { "field": "F_Id", "columnName": "f_id", "primaryKey": 1 }, + { "field": "F_Price", "columnName": "f_price", "dataType": "decimal" } + ]}]"#, + ) + .unwrap(); + let table = model.table("t").unwrap(); + let out = render_with_casts( + "INSERT INTO t (f_id, f_price) VALUES ($1, $2)", + &[Value::String("a".into()), Value::String("9.9".into())], + &["f_id".to_string(), "f_price".to_string()], + Some(table), + ); + assert!( + out.contains("$2::text::numeric"), + "数值列应带 ::numeric: {out}" + ); + } + + /// 🔴 **`$10` 不能被 `$1` 的替换误伤**。 + /// + /// 用 `str::find("$1")` 找位置会把 `$10` 当成 `$1` ⇒ 变成 `$1::text0::text` + /// ⇒ SQL 直接语法错。这是最难查的一类 bug(只在参数 ≥ 10 时出现)。 + #[test] + fn ten_placeholders_are_not_corrupted_by_one() { + // 构造:INSERT INTO t (c1, ..., c10) VALUES ($1, ..., $10) + let mut text = String::from("INSERT INTO t ("); + for i in 1..=10 { + if i > 1 { + text.push_str(", "); + } + text.push_str(&format!("c{i}")); + } + text.push_str(") VALUES ("); + for i in 1..=10 { + if i > 1 { + text.push_str(", "); + } + text.push_str(&format!("${i}")); + } + text.push(')'); + + let params: Vec = (1..=10).map(|i| Value::String(format!("v{i}"))).collect(); + let cols: Vec = (1..=10).map(|i| format!("c{i}")).collect(); + + let out = render_with_casts(&text, ¶ms, &cols, None); + assert!( + out.contains("$10::text"), + "$10 应被完整替换: {out}" + ); + assert!( + !out.contains("$1::text0"), + "$10 被 $1 的替换误伤了: {out}" + ); + assert_eq!( + out.matches("::text").count(), + 10, + "应有 10 处 ::text: {out}" + ); + } + + /// 值转 `Option`:null ⇒ None。 + #[test] + fn params_as_text_maps_null_to_none() { + let vals = params_as_text(&[ + Value::Null, + Value::String("a".into()), + Value::Number(5.into()), + Value::Bool(true), + ]); + assert_eq!(vals[0], None); + assert_eq!(vals[1].as_deref(), Some("a")); + assert_eq!(vals[2].as_deref(), Some("5")); + assert_eq!(vals[3].as_deref(), Some("true")); + } + + /// 从 SQL 文本抽列名(INSERT / UPDATE 两种形态)。 + #[test] + fn columns_of_sql_handles_both_shapes() { + let ins = "INSERT INTO t (a, b, c) VALUES ($1, $2, $3)"; + assert_eq!(columns_of_sql(ins), vec!["a", "b", "c"]); + let upd = "UPDATE t SET a = $1, b = $2 WHERE id = $3"; + assert_eq!(columns_of_sql(upd), vec!["a", "b"]); + } + + /// 🔴 cast 必须靠 **列名**,不是靠「参数序号 = 模型字段序号」。 + #[test] + fn cast_uses_param_columns_not_position() { + let model = ModelSchema::from_str( + r#"[{ "table": "t", "typeId": "1", "fields": [ + { "field": "F_Id", "columnName": "f_id", "primaryKey": 1 }, + { "field": "F_Amount", "columnName": "f_amount", "dataType": "decimal" } + ]}]"#, + ) + .unwrap(); + let table = model.table("t").unwrap(); + // 参数顺序与模型字段顺序**故意不同**:$1 是 f_amount,$2 是 f_id + let out = render_with_casts( + "INSERT INTO t (f_amount, f_id) VALUES ($1, $2)", + &[Value::String("9.9".into()), Value::String("id".into())], + &["f_amount".to_string(), "f_id".to_string()], + Some(table), + ); + assert!( + out.contains("$1::text::numeric"), + "$1 是 f_amount,应带 ::numeric: {out}" + ); + assert!( + out.contains("$2::text") && !out.contains("$2::text::numeric"), + "$2 是 f_id,不该带 ::numeric: {out}" + ); + } +} diff --git a/crates/sspf-lowcode-exec/src/lowcode_ddl.rs b/crates/sspf-lowcode-exec/src/lowcode_ddl.rs new file mode 100644 index 0000000..262cad0 --- /dev/null +++ b/crates/sspf-lowcode-exec/src/lowcode_ddl.rs @@ -0,0 +1,430 @@ +//! lowcode_ddl —— 内核侧的**动态建表执行层**(P2-b 的最后一块)。 +//! +//! ## 分工(与 [`crate::lowcode_crud`] 同款) +//! +//! | 层 | 位置 | 干什么 | +//! |---|---|---| +//! | **DDL 生成** | `sspf-lowcode::ddl`(纯计算,AR7) | 出 `CREATE TABLE` 文本 + 回写后的模型 | +//! | **执行** | 本文件(内核) | 连库、跑 DDL、回写 `f_tables_data` | +//! +//! ## 🔴 三步闭环(缺一不可) +//! +//! ```text +//! 1. plan_create() → CREATE TABLE 文本(主表在前,子表随后) +//! 2. 执行 DDL → 真实库里有表了 +//! 3. rewrite_model() → 把真实表结构回写进 f_tables_data +//! ``` +//! +//! ## 🔴 第 3 步为什么**不是可选的** +//! +//! 基线平台 `VisualDevTableCre.tableList()` 建完表后会用**建表清单**重新组装 +//! `TableModel` 再写回 `f_tables_data`: +//! +//! ```java +//! this.tableModel(tableModelList, datableList, tableName, table, true, tableField, relationField); +//! ... +//! entity.setVisualTables(JsonUtil.getObjectToString(tableModelList)); +//! ``` +//! +//! ⇒ 建表后的模型**含平台追加的系统列**(`f_tenant_id` / `f_delete_mark` …)。 +//! +//! 不回写的后果(本项目已真实踩到): +//! +//! | 现象 | 根因 | +//! |---|---| +//! | 逻辑删除报 `LOGICAL_DELETE_UNSUPPORTED` | CRUD 层在**模型**里找 `f_delete_mark`,找不到 | +//! | 「设计稿 vs 真实库」列比对永远对不上 | 模型少列、真实库多列 | +//! | `f_tenant_id` 不被写 | 租户列在模型里缺失 | +//! +//! ## 🔴 幂等 +//! +//! 基线平台 `DbTableServiceImpl.createTable()` 会先检查表是否已存在, +//! 存在则直接返回(不重复建)。本模块同理: +//! +//! - 表已存在 ⇒ **不报错**,跳过 DDL,但**仍然回写模型** +//! (回写是幂等的,且让「设计稿落后于真实库」自动修复)。 +//! - 表已存在但**列结构不同** ⇒ 报 `TABLE_ALREADY_EXISTS_DIFFERENT`, +//! 明确告诉调用方「不是同一次建表的结果」,让人去核对而不是硬改。 +//! +//! ## 🔴 只在开发期可用 +//! +//! 建表是**破坏性**操作(会改真实库结构)。本模块提供 `Profile::Dev` 闸门, +//! 生产档直接拒绝 —— 见 [`create_tables`]. + +use serde_json::{json, Value}; + +use sspf_lowcode::{ + plan_create, rewrite_model, CreatePlan, DdlError, DdlOptions, FormSchema, ModelSchema, +}; +use sspf_mcp::adapter::ToolError; + +use sspf_core::db::Db; + +/// 建表的结果。 +#[derive(Debug, Clone)] +pub struct CreateTablesOutcome { + /// 建出来的表(主表在前)。 + pub tables: Vec, + /// 哪些表是**已存在**因而跳过的。 + pub skipped: Vec, + /// 回写后的模型(`f_tables_data` 的新值)。 + pub model: Value, + /// 诊断信息。 + pub notes: Vec, + /// 实际执行的 DDL(dry-run 时给调用方看)。 + pub ddl: Vec, + /// 是否只是演练(没建表、没回写)。 + pub dry_run: bool, +} + +impl CreateTablesOutcome { + /// 一共几张表。 + pub fn table_count(&self) -> usize { + self.tables.len() + } +} + +/// 🔴 把 DDL 错误转成结构化工具错误。 +pub fn ddl_err(e: DdlError) -> ToolError { + let mut t = ToolError::new(e.code(), e.message()); + match &e { + DdlError::NoMainTable => { + t = t.hint("这个功能定义里没有主表(typeId=1)—— 设计稿不完整"); + } + DdlError::IllegalIdentifier { kind, value } => { + t = t + .field(*kind) + .hint(format!( + "{kind}「{value}」含非法字符;表名/列名只允许字母、数字、下划线,且不能以数字开头" + )) + .next("form.describe", json!({ "enCode": "<功能编码>" }), "看设计稿里的表名"); + } + DdlError::DuplicateColumn { table, column } => { + t = t + .field(column) + .hint(format!( + "表 {table} 里两列推出同一个物理列名 {column};检查模型里是不是有同义字段" + )); + } + DdlError::UnsupportedType { + table, + column, + data_type, + } => { + t = t + .field(column) + .hint(format!( + "表 {table} 的列 {column} 类型「{data_type}」还没支持;\ + 改这个字段的类型,或在 sspf-lowcode 的 map_type() 里补上" + )); + } + DdlError::InvalidLength { + table, + column, + length, + } => { + t = t + .field(column) + .hint(format!( + "表 {table} 的列 {column} 长度「{length}」不合法;\ + varchar 填数字,decimal 填「精度,标度」如 18,2" + )); + } + DdlError::NoPrimaryKey(table) => { + t = t + .hint(format!( + "表 {table} 的模型里没有 primaryKey=1 的列 —— 建不出主键,先在设计稿里标主键" + )); + } + } + t +} + +/// 🔴 表是否已存在。 +pub async fn table_exists(db: &Db, table: &str) -> Result { + let rows = db + .query_json_params( + "SELECT 1 AS \"x\" FROM information_schema.tables \ + WHERE table_name = $1 LIMIT 1", + &[&table.to_string()], + ) + .await + .map_err(db_err)?; + Ok(!rows.is_empty()) +} + +/// 🔴 真实库里某张表的列(按序)。 +pub async fn real_columns(db: &Db, table: &str) -> Result, ToolError> { + let rows = db + .query_json_params( + "SELECT column_name AS \"name\" FROM information_schema.columns \ + WHERE table_name = $1 ORDER BY ordinal_position", + &[&table.to_string()], + ) + .await + .map_err(db_err)?; + Ok(rows + .iter() + .map(|r| r["name"].as_str().unwrap_or_default().to_string()) + .collect()) +} + +/// 🔴 执行一次动态建表(**幂等**)。 +/// +/// ## 参数 +/// +/// - `db`:真实库连接; +/// - `model`:**建表前**的模型(`f_tables_data`); +/// - `form`:表单定义(决定 `logicalDelete` / `primaryKeyPolicy`); +/// - `dry_run`:只生成 DDL 与回写后的模型,**不建表、不回写**。 +/// +/// ## 🔴 幂等语义 +/// +/// 表已存在 ⇒ 跳过 DDL,但**仍回写模型**(回写是幂等的)。 +/// 列结构不一致 ⇒ 报 `TABLE_EXISTS_DIFFERENT`,让人去核对。 +pub async fn create_tables( + db: &Db, + model: &ModelSchema, + form: &FormSchema, + dry_run: bool, +) -> Result { + // 🔴 建表选项来自**表单**(基线平台同款:`VisualTableModel` 从 `FormDataModel` 取)。 + let options = DdlOptions { + logical_delete: form.logical_delete.unwrap_or(false), + with_comments: false, + primary_key_policy: form.primary_key_policy.unwrap_or(1), + }; + + let plan = plan_create(model, &options).map_err(ddl_err)?; + let ddl = plan.render(); + + // ---- 回写后的模型(纯计算,先算好;dry-run 也要给)---- + let rewritten = rewrite_model(model, &plan); + + let mut tables = Vec::new(); + let mut skipped = Vec::new(); + let mut notes = Vec::new(); + + if dry_run { + for t in plan.all() { + tables.push(t.table.clone()); + } + return Ok(CreateTablesOutcome { + tables, + skipped, + model: rewritten, + notes: vec!["dry-run:没有建表,也没有回写模型".to_string()], + ddl, + dry_run: true, + }); + } + + // ---- 逐表执行(主表在前,子表随后)---- + for t in plan.all() { + if table_exists(db, &t.table).await? { + // 🔴 已存在 ⇒ 跳过 DDL,但**核对列**。 + let actual = real_columns(db, &t.table).await?; + let expected = t.column_names(); + if actual != expected { + return Err(table_exists_different(&t.table, &expected, &actual)); + } + skipped.push(t.table.clone()); + notes.push(format!( + "表 {} 已存在且列结构一致 —— 跳过建表(幂等)", + t.table + )); + continue; + } + + let sql = t.render(); + db.exec(&sql) + .await + .map_err(|e| create_failed(&t.table, &e.to_string(), &sql))?; + tables.push(t.table.clone()); + } + + Ok(CreateTablesOutcome { + tables, + skipped, + model: rewritten, + notes, + ddl, + dry_run: false, + }) +} + +/// 🔴 表已存在但列结构不一致。 +fn table_exists_different(table: &str, expected: &[String], actual: &[String]) -> ToolError { + let missing: Vec<&str> = expected + .iter() + .filter(|c| !actual.contains(c)) + .map(|s| s.as_str()) + .collect(); + let extra: Vec<&str> = actual + .iter() + .filter(|c| !expected.contains(c)) + .map(|s| s.as_str()) + .collect(); + + let mut msg = format!("表 {table} 已存在,但列结构和设计稿对不上"); + if !missing.is_empty() { + msg.push_str(&format!(";设计稿声明但库里没有:{}", missing.join(", "))); + } + if !extra.is_empty() { + msg.push_str(&format!(";库里有但设计稿没声明:{}", extra.join(", "))); + } + + ToolError::new("TABLE_EXISTS_DIFFERENT", msg) + .field("table") + .hint( + "这张表不是当前设计稿建出来的(可能是手写的、或改过设计稿没重建表)。\ + 改设计稿请先重建表,或手动对齐库里的列 —— 别让工具替你猜", + ) + .next( + "schema.table.describe", + json!({ "table": table }), + "看这张表现在到底有哪些列", + ) +} + +/// 🔴 建表失败。 +fn create_failed(table: &str, err: &str, sql: &str) -> ToolError { + ToolError::new("CREATE_TABLE_FAILED", format!("建表 {table} 失败:{err}")) + .field("table") + .hint("看下面的 DDL 定位问题;最常见是标识符非法或类型不匹配") + .hint(format!("执行的 DDL:{}", sql)) + .next( + "form.describe", + json!({ "enCode": "<功能编码>" }), + "核对设计稿里的表名与列", + ) +} + +/// 🔴 DB 错误转工具错误。 +fn db_err(e: pglite::Error) -> ToolError { + ToolError::new("DB_ERROR", format!("数据库错误:{e}")) + .hint("先确认数据库连接正常;这个错误通常来自 SQL 或连接配置") +} + +/// 🔴 把回写后的模型写回 `base_visual_dev.f_tables_data`。 +/// +/// ## 🔴 为什么**只**写 `f_tables_data` +/// +/// 基线平台 `VisualdevServiceImpl.createTable()` 建表后写的是 +/// `entity.setVisualTables(...)` —— 也就是 `f_tables_data` 一列。 +/// `f_column_data`(列表列)与 `f_form_data`(控件树)由前端另行维护, +/// 建表不碰它们。 +pub async fn write_back_model( + db: &Db, + visualdev_id: &str, + model_json: &Value, +) -> Result<(), ToolError> { + let text = serde_json::to_string(model_json).map_err(|e| { + ToolError::new("MODEL_SERIALIZE_FAILED", format!("模型序列化失败:{e}")) + })?; + + // 🔴 先确认记录存在 —— `exec_params` 不返回影响行数 + // (pglite 0.2.7 没有这个能力),所以只能先查再写。 + let exists = db + .query_json_params( + "SELECT 1 AS \"x\" FROM base_visual_dev WHERE f_id = $1 LIMIT 1", + &[&visualdev_id.to_string()], + ) + .await + .map_err(db_err)?; + if exists.is_empty() { + return Err(ToolError::new( + "FORM_NOT_FOUND", + format!("低代码功能不存在:{visualdev_id}"), + ) + .field("id") + .hint("base_visual_dev 里没有这条记录") + .next("form.list", json!({}), "列出全部功能")); + } + + db.exec_params( + "UPDATE base_visual_dev SET f_tables_data = $1 WHERE f_id = $2", + &[&text, &visualdev_id.to_string()], + ) + .await + .map_err(db_err)?; + + Ok(()) +} + +/// 🔴 建表 + 回写的完整闭环。 +/// +/// 这是 MCP `schema.table.create` 工具背后的实现: +/// 建表 → 回写 `f_tables_data` → 返回可用的模型。 +pub async fn create_and_sync( + db: &Db, + visualdev_id: &str, + model: &ModelSchema, + form: &FormSchema, + dry_run: bool, +) -> Result { + let outcome = create_tables(db, model, form, dry_run).await?; + + if !dry_run { + write_back_model(db, visualdev_id, &outcome.model).await?; + } + + Ok(outcome) +} + +/// 🔴 一张表的 DDL 预览(只给主表,供 `schema.table.describe` 之类的诊断用)。 +pub fn preview_ddl(model: &ModelSchema, form: &FormSchema) -> Result, ToolError> { + let options = DdlOptions { + logical_delete: form.logical_delete.unwrap_or(false), + with_comments: false, + primary_key_policy: form.primary_key_policy.unwrap_or(1), + }; + let plan: CreatePlan = plan_create(model, &options).map_err(ddl_err)?; + Ok(plan.render()) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn model() -> ModelSchema { + ModelSchema::from_str( + r#"[{ "table": "t_main", "tableName": "主表", "typeId": "1", "fields": [ + { "field": "F_Id", "dataType": "varchar", "dataLength": "50", "primaryKey": 1, "allowNull": 0 }, + { "field": "F_Room", "dataType": "varchar", "dataLength": "100", "primaryKey": 0, "allowNull": 1 } + ]}]"#, + ) + .unwrap() + } + + fn form() -> FormSchema { + FormSchema::from_str( + r#"{ "formRef": "formRef", "formModel": "formData", + "primaryKeyPolicy": 1, "logicalDelete": false, "fields": [] }"#, + ) + .unwrap() + } + + /// DDL 预览应产出 `CREATE TABLE`。 + #[test] + fn preview_ddl_produces_create_table() { + let ddl = preview_ddl(&model(), &form()).unwrap(); + assert_eq!(ddl.len(), 1); + assert!(ddl[0].starts_with("CREATE TABLE t_main"), "{}", ddl[0]); + assert!(ddl[0].contains("PRIMARY KEY (f_id, f_tenant_id)"), "{}", ddl[0]); + } + + /// 🔴 DDL 错误要转成有指导性的工具错误。 + #[test] + fn ddl_error_becomes_actionable_tool_error() { + let bad = ModelSchema::from_str( + r#"[{ "table": "bad; DROP TABLE x", "typeId": "1", "fields": [ + { "field": "F_Id", "dataType": "varchar", "primaryKey": 1 } + ]}]"#, + ) + .unwrap(); + let err = preview_ddl(&bad, &form()).unwrap_err(); + assert_eq!(err.code, "ILLEGAL_IDENTIFIER"); + assert!(!err.hints.is_empty(), "非法标识符必须给出修复指引"); + } +} diff --git a/crates/sspf-lowcode-exec/src/lowcode_seed.rs b/crates/sspf-lowcode-exec/src/lowcode_seed.rs new file mode 100644 index 0000000..a39e90a --- /dev/null +++ b/crates/sspf-lowcode-exec/src/lowcode_seed.rs @@ -0,0 +1,503 @@ +//! lowcode_seed —— **开发期**低代码示例数据种子(CLI `--seed-lowcode-demo`)。 +//! +//! ## 它干什么 +//! +//! 往库里灌**一份可用的低代码功能**,让 P2-b 的动态 CRUD 能被端到端验证: +//! +//! 1. `base_visual_dev` 一行(`f_form_data` = 官方 fixture 的控件树, +//! `f_tables_data` = 官方 fixture 的表结构); +//! 2. 按设计稿**真的建出物理表**(`test_receivable` / `test_details`); +//! 3. 建表后**回写** `f_tables_data`(含平台追加的系统列)—— 与基线平台同款; +//! 4. `base_visual_release` 一行(发布快照,三段 JSON 与 dev 一致)。 +//! +//! ## 🔴 为什么要有这条通道 +//! +//! P2-b 的动态 CRUD 需要「**一个真的低代码功能**」才能验证;而手点界面造一个 +//! 功能 = 慢且不可复现 ⇒ 提供一条**命令行、可重复**的通道: +//! +//! ```text +//! ssw-platform --seed-lowcode-demo # 建表 + 灌功能定义 +//! ssw-platform --seed-lowcode-demo --dry-run # 只看要做什么,不碰库 +//! ``` +//! +//! ## 🔴 数据来源是**官方初始化数据** +//! +//! fixture 与 `crates/sspf-lowcode/tests/fixtures/` 同源(基线平台初始化 SQL 里的 +//! 「应收费用」功能)⇒ 种出来的库**就是基线平台的低代码功能在 SSPF 里的样子** +//! —— 验证才有意义(自己编的数据只能证明「自己和自己通」)。 +//! +//! ## 🔴 只在开发档可用 +//! +//! 它会**改真实库结构**(建表)⇒ 生产档直接拒绝(见 [`seed_gate`])。 +//! +//! ## 🔴 幂等 +//! +//! 固定 id + 「先查存在性再写」⇒ 重复跑不会撞复合主键,也不会留下重复行。 + +use std::path::{Path, PathBuf}; + +use serde_json::Value; + +use sspf_lowcode::{FormSchema, ModelSchema}; +use sspf_mcp::adapter::ToolError; + +use crate::lowcode_crud::now_iso; +use crate::lowcode_ddl; +use sspf_core::config::Profile; +use sspf_core::db::{pglite, Db}; +use sspf_core::registry::MAIN_SYSTEM_ID; + +/// 示例功能在 `base_visual_dev` 里的**固定 id**。 +/// +/// 🔴 用**固定 id** 而不是新生成 UUID —— 固定 id 让种子幂等: +/// 重复跑 `--seed-lowcode-demo` 是「更新同一条」而不是「插一堆重复的」。 +pub const DEMO_ID: &str = "lowcode-demo-receivable"; + +/// 示例功能的编码(`f_en_code`)—— AI 调 `data.record.insert` 时用它定位。 +/// +/// 🔴 与 MCP 工具文档里的示例(`crates/sspf-mcp/src/tools/lowcode.rs`)**逐字一致** +/// ⇒ 文档里的示例直接可跑。 +pub const DEMO_EN_CODE: &str = "receivableDemo"; + +/// 示例功能的显示名。 +pub const DEMO_FULL_NAME: &str = "应收费用(低代码示例)"; + +/// 表单 fixture(相对项目根)。 +const FORM_FIXTURE: &str = "crates/sspf-lowcode/tests/fixtures/sample_form.json"; + +/// 模型 fixture(相对项目根)。 +const MODEL_FIXTURE: &str = "crates/sspf-lowcode/tests/fixtures/sample_model.json"; + +/// 单租户口径下的租户值(与 `lowcode_crud::DEFAULT_TENANT_ID` 同源)。 +const TENANT_ID: &str = "0"; + +/// 🔴 `base_visual_dev` / `base_visual_release` 的**共同列清单**与**类型**。 +/// +/// 官方两表逐列相同(`base_visual_release` 只多一列 `f_old_content`) +/// ⇒ 用同一份清单写两张表 ⇒ 少一处漂移。 +/// +/// 🔴 每列带一个**列类型标记**(决定 SQL 里补哪层 cast): +/// +/// | 标记 | 物理类型 | 参数 cast | +/// |---|---|---| +/// | `text` | `TEXT` / `VARCHAR` | `::text` | +/// | `int` | `INTEGER` | `::text::integer` | +/// | `bigint` | `BIGINT` | `::text::bigint` | +/// | `ts` | `TIMESTAMP(0)` | `::text::timestamp` | +/// +/// 🔴 **为什么参数统一按字符串送**:pglite 的扩展查询协议里,未标注类型的参数 +/// 会被服务端当成 `text`;本仓的整型/时间戳列需要显式再转一层。 +/// 列类型标记与清单**同序** ⇒ 少一处可能对不上的地方。 +const VISUAL_COLUMNS: &[(&str, &str)] = &[ + ("f_id", "text"), + ("f_full_name", "text"), + ("f_en_code", "text"), + ("f_state", "int"), + ("f_type", "int"), + ("f_tables_data", "text"), + ("f_form_data", "text"), + ("f_column_data", "text"), + ("f_web_type", "int"), + ("f_app_column_data", "text"), + ("f_enable_flow", "int"), + ("f_description", "text"), + ("f_enabled_mark", "int"), + ("f_sort_code", "bigint"), + ("f_creator_time", "ts"), + ("f_creator_user_id", "text"), + ("f_last_modify_time", "ts"), + ("f_last_modify_user_id", "text"), + ("f_delete_mark", "int"), + ("f_tenant_id", "text"), + ("f_url_address", "text"), + ("f_web_address", "text"), + ("f_button_data", "text"), + ("f_system_id", "text"), +]; + +/// 种子结果。 +#[derive(Debug, Clone)] +pub struct SeedOutcome { + /// 功能 id(`base_visual_dev.f_id`)。 + pub form_id: String, + /// 功能编码。 + pub en_code: String, + /// 建出来的表(主表在前)。 + pub tables: Vec, + /// 已存在因而跳过的表。 + pub skipped: Vec, + /// 实际执行的 DDL。 + pub ddl: Vec, + /// 回写后的模型(`f_tables_data` 的新值)。 + pub model: Value, + /// 诊断信息。 + pub notes: Vec, + /// 是否只是演练(没建表、没写库)。 + pub dry_run: bool, +} + +/// 🔴 **档位闸门**:只在开发档允许。 +/// +/// `SSW_PROFILE=prod`(或 `production`)⇒ 拒绝。 +/// +/// 理由:这条命令会**建表**(改真实库结构)并灌入示例数据 —— +/// 生产库里既不该有示例表,也不该在启动期被一条命令改结构。 +/// +/// 纯函数 ⇒ 可单测(不依赖环境变量)。 +pub fn seed_gate(profile: Profile) -> Result<(), String> { + match profile { + Profile::Dev => Ok(()), + Profile::Prod => Err( + "--seed-lowcode-demo 只在开发档可用(SSW_PROFILE=prod/production)。\n\ + 它会往库里**建表**并灌入示例数据 —— 生产库不该有这些。\n\ + 确实要跑 ⇒ 把 SSW_PROFILE 改成 dev(或 unset),\ + 并确认 PGLITE_DIR 指向的是开发库而不是生产库。" + .to_string(), + ), + } +} + +/// fixture 的绝对路径(相对项目根)。 +pub fn fixture_path(project_dir: &Path, name: &str) -> PathBuf { + project_dir.join(name) +} + +/// 🔴 读 fixture 文件。 +fn read_fixture(project_dir: &Path, rel: &str) -> Result { + let path = fixture_path(project_dir, rel); + std::fs::read_to_string(&path).map_err(|e| { + ToolError::new( + "FIXTURE_MISSING", + format!("读不到官方 fixture:{}({e})", path.display()), + ) + .field(rel) + .hint("fixture 在 crates/sspf-lowcode/tests/fixtures/ 下,与基线平台初始化 SQL 同源") + }) +} + +/// 🔴 读官方 fixture,解析出(表单, 模型)。 +/// +/// 两个入口共用这一段 ⇒ 演练看到的与真跑执行的**一定是同一份设计稿**。 +fn load_demo_fixture( + project_dir: &Path, +) -> Result<(FormSchema, ModelSchema), ToolError> { + let form_text = read_fixture(project_dir, FORM_FIXTURE)?; + let model_text = read_fixture(project_dir, MODEL_FIXTURE)?; + + let form = FormSchema::from_str(&form_text).map_err(|e| { + ToolError::new( + e.code(), + format!("官方表单 fixture 解析失败: {}", e.message()), + ) + .field(FORM_FIXTURE) + })?; + let model = ModelSchema::from_str(&model_text).map_err(|e| { + ToolError::new( + e.code(), + format!("官方模型 fixture 解析失败: {}", e.message()), + ) + .field(MODEL_FIXTURE) + })?; + + Ok((form, model)) +} + +/// 🔴 **演练**:只看要建什么表,**不碰库**。 +/// +/// 🔴 **连数据库都不开** —— 演练的整个意义就是「什么都不发生」。 +/// 开库就意味着在数据目录里落一个临时 PG 实例(改磁盘状态)。 +pub fn preview_lowcode_demo(project_dir: &Path) -> Result { + let (form, model) = load_demo_fixture(project_dir)?; + let ddl = lowcode_ddl::preview_ddl(&model, &form)?; + + let planned: Vec = model + .tables + .iter() + .map(|t| t.table.to_lowercase()) + .collect(); + + Ok(SeedOutcome { + form_id: DEMO_ID.to_string(), + en_code: DEMO_EN_CODE.to_string(), + tables: planned, + skipped: Vec::new(), + ddl, + model: model.raw.clone(), + notes: vec!["dry-run:没有建表,也没有写库".to_string()], + dry_run: true, + }) +} + +/// 🔴 低代码示例功能种子(**开发档专用**)。 +/// +/// ## 执行顺序(顺序不能换) +/// +/// 1. 读官方 fixture(表单 + 模型); +/// 2. 先写 `base_visual_dev`(**用原始模型**)—— 因为建表后的回写要求这行已存在; +/// 3. `create_and_sync`:建表 + 回写 `f_tables_data`(含系统列); +/// 4. 写 `base_visual_release`(**用回写后的模型**)—— 发布快照与 dev 一致。 +pub async fn seed_lowcode_demo( + db: &Db, + project_dir: &Path, +) -> Result { + let (form, model) = load_demo_fixture(project_dir)?; + + // ---- DDL 预览(与真实执行用同一套生成规则)---- + let ddl = lowcode_ddl::preview_ddl(&model, &form)?; + + // ---- 1. 先写 dev 行(原始模型)---- + upsert_visual_row(db, "base_visual_dev", DEMO_ID, &form.raw.to_string(), &model.raw.to_string()) + .await?; + + // ---- 2. 建表 + 回写模型 ---- + let created = lowcode_ddl::create_and_sync(db, DEMO_ID, &model, &form, false).await?; + + // ---- 3. 写 release 行(**回写后**的模型 ⇒ 与 dev 一致)---- + let rewritten_text = serde_json::to_string(&created.model).map_err(|e| { + ToolError::new( + "MODEL_SERIALIZE_FAILED", + format!("回写后的模型序列化失败: {e}"), + ) + })?; + upsert_visual_row( + db, + "base_visual_release", + DEMO_ID, + &form.raw.to_string(), + &rewritten_text, + ) + .await?; + + let mut notes = created.notes.clone(); + notes.push(format!( + "功能定义已写入 base_visual_dev 与 base_visual_release(id={DEMO_ID}, enCode={DEMO_EN_CODE})" + )); + + Ok(SeedOutcome { + form_id: DEMO_ID.to_string(), + en_code: DEMO_EN_CODE.to_string(), + tables: created.tables, + skipped: created.skipped, + ddl, + model: created.model, + notes, + dry_run: false, + }) +} + +/// 🔴 写(插入或更新)一行低代码功能定义。 +/// +/// ## 🔴 幂等策略 +/// +/// 「先查存在性,再决定 INSERT 还是 UPDATE」—— +/// `Db::exec_params` **不返回影响行数**(pglite 0.2.7 没这个能力), +/// 所以不能用 `ON CONFLICT ... DO UPDATE`(那样也拿不到结果), +/// 只能先 `SELECT` 判存在。 +async fn upsert_visual_row( + db: &Db, + table: &str, + id: &str, + form_data: &str, + tables_data: &str, +) -> Result<(), ToolError> { + let exists = db + .query_json_params( + &format!("SELECT 1 AS \"x\" FROM {table} WHERE f_id = $1 LIMIT 1"), + &[&id.to_string()], + ) + .await + .map_err(db_err)?; + + if exists.is_empty() { + insert_visual_row(db, table, id, form_data, tables_data).await?; + } else { + update_visual_row(db, table, id, form_data, tables_data).await?; + } + Ok(()) +} + +/// 🔴 一行的**字段值**(与 [`VISUAL_COLUMNS`] 同序)。 +fn visual_row_values(id: &str, form_data: &str, tables_data: &str) -> Vec { + let now = now_iso(); + let url = format!("lowcode/{DEMO_EN_CODE}/index"); + vec![ + id.to_string(), + DEMO_FULL_NAME.to_string(), + DEMO_EN_CODE.to_string(), + "1".to_string(), // f_state:1 = 已发布 + "1".to_string(), // f_type:1 = 在线开发 + tables_data.to_string(), + form_data.to_string(), + "[]".to_string(), // f_column_data:列表列(空数组 = 不配列表页) + "2".to_string(), // f_web_type:2 = PC 端 + "[]".to_string(), // f_app_column_data + "0".to_string(), // f_enable_flow + "开发期种子生成的低代码示例功能".to_string(), + "1".to_string(), // f_enabled_mark + "0".to_string(), // f_sort_code + now.clone(), // f_creator_time + "admin".to_string(), + now.clone(), // f_last_modify_time + "admin".to_string(), + "0".to_string(), // f_delete_mark + TENANT_ID.to_string(), + url.clone(), + url, + "[]".to_string(), // f_button_data + MAIN_SYSTEM_ID.to_string(), + ] +} + +/// 🔴 插入一行低代码功能定义。 +async fn insert_visual_row( + db: &Db, + table: &str, + id: &str, + form_data: &str, + tables_data: &str, +) -> Result<(), ToolError> { + let values = visual_row_values(id, form_data, tables_data); + let cols: Vec<&str> = VISUAL_COLUMNS.iter().map(|(c, _)| *c).collect(); + let placeholders: Vec = VISUAL_COLUMNS + .iter() + .enumerate() + .map(|(i, (_, ty))| format!("${}::{}", i + 1, cast_for(ty))) + .collect(); + + let sql = format!( + "INSERT INTO {table} ({}) VALUES ({})", + cols.join(", "), + placeholders.join(", ") + ); + + let refs = build_params(&values); + db.exec_params(&sql, &refs).await.map_err(db_err)?; + Ok(()) +} + +/// 🔴 更新一行低代码功能定义(只改「这个功能真的用到」的列)。 +async fn update_visual_row( + db: &Db, + table: &str, + id: &str, + form_data: &str, + tables_data: &str, +) -> Result<(), ToolError> { + let values = visual_row_values(id, form_data, tables_data); + let now = now_iso(); + + // 🔴 列清单里除 `f_id` 外全部更新(`f_creator_*` 保持首次种下的值)。 + // 参数编号要与 `set_cols` 的顺序严格对应 ⇒ 按 `VISUAL_COLUMNS` 里的下标取。 + let mut params: Vec = Vec::new(); + let mut assignments: Vec = Vec::new(); + for (i, (col, ty)) in VISUAL_COLUMNS.iter().enumerate() { + if *col == "f_id" || *col == "f_creator_time" || *col == "f_creator_user_id" { + continue; + } + // 🔴 `f_last_modify_time` 用**当前**时间(其余值原样回填)。 + let value = if *col == "f_last_modify_time" { + now.clone() + } else { + values[i].clone() + }; + params.push(value); + assignments.push(format!("{col} = ${}::{}", params.len(), cast_for(ty))); + } + params.push(id.to_string()); + let id_pos = params.len(); + + let sql = format!( + "UPDATE {table} SET {} WHERE f_id = ${id_pos}::text", + assignments.join(", ") + ); + + let refs = build_params(¶ms); + db.exec_params(&sql, &refs).await.map_err(db_err)?; + Ok(()) +} + +/// 🔴 列类型标记 ⇒ SQL cast 片段。 +fn cast_for(kind: &str) -> &'static str { + match kind { + "int" => "text::integer", + "bigint" => "text::bigint", + "ts" => "text::timestamp", + _ => "text", + } +} + +/// 🔴 把参数向量转成可传给 `exec_params` 的引用数组。 +fn build_params(params: &[String]) -> Vec<&(dyn pglite::ToSql + Sync)> { + params + .iter() + .map(|s| s as &(dyn pglite::ToSql + Sync)) + .collect() +} + +/// 🔴 DB 错误转工具错误。 +fn db_err(e: pglite::Error) -> ToolError { + ToolError::new("DB_ERROR", format!("数据库错误:{e}")) + .hint("先确认数据库连接正常;这个错误通常来自 SQL 或连接配置") +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 🔴 **开发档放行**。 + #[test] + fn dev_profile_is_allowed() { + assert!(seed_gate(Profile::Dev).is_ok()); + } + + /// 🔴 **生产档拒绝**(且要说得清为什么、怎么办)。 + #[test] + fn prod_profile_is_rejected_with_guidance() { + let err = seed_gate(Profile::Prod).unwrap_err(); + assert!(err.contains("SSW_PROFILE"), "报错要指明用哪个环境变量:{err}"); + assert!(err.contains("PGLITE_DIR"), "报错要提醒别指到生产库:{err}"); + } + + /// 🔴 闸门**只认档位**,不读环境变量 ⇒ 纯函数、可单测。 + #[test] + fn gate_depends_only_on_profile() { + assert!(seed_gate(Profile::from_env_str("dev")).is_ok()); + assert!(seed_gate(Profile::from_env_str("")).is_ok()); + assert!(seed_gate(Profile::from_env_str("prod")).is_err()); + assert!(seed_gate(Profile::from_env_str("PRODUCTION")).is_err()); + } + + /// 🔴 **列清单与字段值必须一一对应** —— 对不上会静默写错列。 + #[test] + fn column_list_matches_value_count() { + let values = visual_row_values("id", "form", "tables"); + assert_eq!( + VISUAL_COLUMNS.len(), + values.len(), + "VISUAL_COLUMNS 的长度变了 ⇒ 同步改 visual_row_values" + ); + } + + /// 🔴 **列清单的 id 列必须是第一列** —— `UPDATE` 靠这个下标排除它。 + #[test] + fn first_column_is_id() { + assert_eq!(VISUAL_COLUMNS[0].0, "f_id"); + } + + /// 🔴 cast 片段必须与列类型对得上(写错 ⇒ PG 类型错)。 + #[test] + fn cast_for_matches_column_kinds() { + assert_eq!(cast_for("text"), "text"); + assert_eq!(cast_for("int"), "text::integer"); + assert_eq!(cast_for("bigint"), "text::bigint"); + assert_eq!(cast_for("ts"), "text::timestamp"); + } + + /// 🔴 fixture 路径拼在**项目根**下(不依赖 cwd)。 + #[test] + fn fixture_path_is_under_project_root() { + let p = fixture_path(Path::new("/tmp/proj"), FORM_FIXTURE); + assert!(p.starts_with("/tmp/proj"), "{}", p.display()); + assert!(p.ends_with("sample_form.json"), "{}", p.display()); + } +} diff --git a/docs/CRATES-MIGRATION.md b/docs/CRATES-MIGRATION.md index e0c9431..4ed0e76 100644 --- a/docs/CRATES-MIGRATION.md +++ b/docs/CRATES-MIGRATION.md @@ -2,9 +2,9 @@ > **基线锚点**:`v0.1.0`(commit `b957a11`,已推送到 `origin`) > **制定时间**:2026-11-03 -> **状态**:**M4 已完成**(tag `v0.1.4-m4`)—— 六个契约面包(14 个模块 / ~49,000 行)下沉完成; +> **状态**:**M5 已完成**(tag `v0.1.5-m5`)—— 低代码执行层(4 个模块 / 2,674 行)下沉完成; > 四个决策已拍板(§11):壳最后删 / compat 拆 6 包 / mcp_compat 放 crates / tests 跟着拆。 -> 下一步 = M5(`sspf-lowcode-exec`) +> 下一步 = M6(`sspf-mcp-adapter`) --- @@ -434,15 +434,56 @@ ssw-platform/ - [x] `check-naming.sh` = 3 通过 / 0 失败 / 1 提示 - [x] `verify.sh --smoke` 14 步全绿(300.9s) -### 批次 M5 —— 低代码执行层下沉 +### 批次 M5 —— 低代码执行层下沉 ✅ 已完成(tag v0.1.5-m5) **迁入**:`lowcode_{crud,ddl,check,seed}.rs`(2,674 行) -**新 crate**:`crates/sspf-lowcode-exec`(依赖 sspf-lowcode + sspf-core + sspf-store + sspf-mcp) +**新 crate**:`crates/sspf-lowcode-exec` + +| 依赖 | 为什么 | +|---|---| +| `sspf-lowcode` | 纯计算层(解析/校验/SQL 生成)—— **AR7 白名单不动**,它仍是纯计算 | +| `sspf-core` | `Db` / `ids::new_uuid` / `config::Profile` / `registry::MAIN_SYSTEM_ID` | +| `sspf-store` | `Db` / `pglite` 的**真源**(`sspf-core::db` 只是转发壳) | +| `sspf-mcp` | `ToolError` —— 执行失败要能变成给 AI 看懂的结构化错误 | +| `pglite-rs` + `chrono` + `serde_json` | 真实库 / 时间戳 / JSON | > `sspf-lowcode`(纯计算)**不动** —— AR7 白名单保持不变。 > 新 crate 是「执行层」,允许依赖 DB。 +**实际做法与原计划的差异**: + +| 计划 | 实际 | 为什么 | +|---|---|---| +| 依赖 `{lowcode, core, store, mcp}` | 多了 `pglite-rs` + `chrono` + `serde_json` | ① `pglite::ToSql` / `pglite::Error` 是**直接用**的(不是只经 `Db`);② `now_iso()` 用 `chrono::Local::now()`;③ JSON payload 转换 | +| — | **未提权任何 `pub(crate)`** | 与 M3/M4 不同:这四个模块的对外接口**本来就是 `pub`** ⇒ 一行可见性改动都没有 | +| — | `crate::platform::X` → `sspf_core::X`(5 处) | 独立 crate 不能用 `crate::X` 跨模块访问 | +| — | `crate::lowcode_X` **不改**(8 处) | ⚠️ 模块名在新 crate 里**没变**(仍是 `lowcode_crud` / `lowcode_ddl` / `lowcode_check`)⇒ 改了就编译不过 | + +**新增 AR13(两层判据)**: +1. `crates/sspf-lowcode-exec/Cargo.toml` 的依赖 ⊆ `{sspf-lowcode, sspf-core, sspf-store, sspf-mcp, pglite-rs, chrono, serde_json}` + —— **不许 axum**(web 框架)⇒ 这层就还能被 CLI / MCP / 离线工具复用; +2. 该 crate 源码里**不许** `use sspf_pack_*`(业务知识不许漏进平台层)。 + +**闸门改造**: +- `check-arch.sh` 新增 **AR13**(两层)+ 反自证 **8/8**(**两处都注入**:越界依赖 `axum` + 业务包引用 `use sspf_pack_asset::…`,且**按路径分别验**)。 +- `check-boundary.sh` 新增 `LOWCODE_EXEC` ⇒ **CP1**(业务标识符)/ **CP2**(`use crate::modules`)都纳入执行层真源。 + **反向验证**:往 `crates/sspf-lowcode-exec/src/lowcode_check.rs` 插 `const LEAK_PROBE: &str = "demo_item";` ⇒ CP1 报红(PASS=10/FAIL=1);还原后恢复 11/11。 + +**🔴 本批的一个坑**(比 M4 轻,但同一类): +- 改写时把 `use crate::lowcode_ddl;` 一并改成了 `use crate::ddl;` ⇒ 编译报 `cannot find module or crate lowcode_ddl`。 + **教训**:**改写规则必须区分「路径前缀变了」与「模块名变了」** —— 本次只有 `crate::platform::` → `sspf_core::` 该改,`crate::lowcode_*` 的**模块名没变**不该改。 + 同理 `[`crate::lowcode_crud`]` 这种**文档内链**也不能跟着改(改了就变成死链)⇒ 已单独修回。 + +**出口判据(全部达成)**: +- [x] `cargo build --workspace` 零警告;`cargo test --workspace` = **695 passed / 0 failed**(与 M1 基线完全一致) +- [x] `check-arch.sh` = **17/17**(新增 AR13);`--self-test` = **8/8**(新增 AR13 反自证) +- [x] `check-boundary.sh` = 11/11(CP1/CP2 已覆盖执行层) +- [x] `check-contract.sh` = 10/10(反自证 12 例全过)—— 契约里**零 lowcode 端点**(低代码是 MCP 工具不是 HTTP 路由)⇒ 本批不受影响 +- [x] `check-module.sh` = 123/123;`check-citations.sh` = 4/4(**零条引文**指向 lowcode 旧路径) +- [x] `check-naming.sh` = 3 通过 / 0 失败 / 1 提示 +- [x] `verify.sh --smoke` 14 步全绿(377.6s) + ### 批次 M6 —— MCP 适配层下沉 **迁入**:`mcp_adapter.rs`(2,652 行)+ `mcp_compat.rs`(631 行) @@ -479,7 +520,7 @@ ssw-platform/ | 🆕 AR10 | — | ✅ `crates/sspf-core` 依赖 ⊆ {contract, store, axum, tokio, serde, serde_json} | | 🆕 AR11 | — | ✅ `crates/sspf-compat-core`(底座)**不许**依赖其它契约面模块 + Cargo.toml 级判据 | | 🆕 AR12 | — | ✅ `crates/sspf-compat-*` 之间**不许**互相依赖(防环回流),白名单 3 条单向边 | -| 🆕 AR13 | — | `crates/sspf-lowcode-exec` 依赖 ⊆ {lowcode, core, store, mcp}(M5 加) | +| 🆕 AR13 | — | ✅ `crates/sspf-lowcode-exec` 依赖 ⊆ {lowcode, core, store, mcp, pglite-rs, chrono, serde_json} + 源码不许 `use sspf_pack_*` | > 🔴 **AR11/AR12 的 Cargo.toml 级判据踩过 BSD grep 的坑**:`grep -E '^\s*...'` 在 macOS 上**永远匹配不到**(BSD grep 是 POSIX ERE,不认 `\s`)⇒ 尺子永远"通过"。 > 正确写法:`[[:space:]]`。**这个坑是 AR12 反自证第一次跑就失败暴露的** —— 没有反自证,就带着一把假尺子跑完了 M4。 @@ -593,11 +634,12 @@ M3 sspf-compat-core ← ✅ v0.1.3-m3(helper/res / 1,454 行) M4 六个 compat 包 ← ✅ v0.1.4-m4(14 模块 / ~49,000 行) │ 🔴 同步改 check-contract-scan.py + check-boundary.sh + 新增 AR12 ↓ -M5 sspf-lowcode-exec ← 🔴 同步加 AR13 +M5 sspf-lowcode-exec ← ✅ v0.1.5-m5(4 模块 / 2,674 行) + │ 🔴 同步加 AR13 + check-boundary.sh 纳入执行层 ↓ M6 sspf-mcp-adapter ← 决策③:mcp_compat 放 crates ↓ -M7 壳收口 + 闸门补全 ← AR13 + 全量反自证 + 删 platform/ 转发壳 + 拆 tests/ +M7 壳收口 + 闸门补全 ← 全量反自证 + 删 platform/ 转发壳 + 拆 tests/ ``` **每一批的出口判据都相同**: @@ -654,16 +696,21 @@ bash scripts/verify.sh --smoke # 14 步全绿 ## 12. 立即可做的下一步 -**执行 M5(`sspf-lowcode-exec`)**。理由: -1. M1/M2/M3/M4 已完成并打 tag —— 地基、平台核心、契约面底座、六个契约面包都稳了 -2. M5 规模最小(2,674 行,4 个模块),是 M6/M7 前最后的低风险批次 -3. 套路成熟:M2/M3/M4 的「转发壳 + 闸门两处扫 + 反自证两处注入」直接复用 +**执行 M6(`sspf-mcp-adapter`)**。理由: +1. M1–M5 已完成并打 tag —— 地基、平台核心、契约面底座、六个契约面包、低代码执行层都稳了 +2. M6 是**决策③的落地点**(`mcp_compat.rs` 放 crates),也是**唯一高扇入节点** ⇒ 越早做越早验证依赖网 +3. 套路成熟:M2–M5 的「转发壳 + 闸门两处扫 + 反自证两处注入」直接复用 -M5 完成后打 tag `v0.1.5-m5`。 -⚠️ **M5 必须同步做**:① `check-arch.sh` 加 **AR13**(`sspf-lowcode-exec` 依赖 ⊆ {lowcode, core, store, mcp});② `check-boundary.sh` 的 CP6/软删检查若涉及 `lowcode_*.rs` 也要纳入真源;③ 重跑全部 `--self-test`。 -之后 = M6(`sspf-mcp-adapter`,决策③放 crates)→ M7(收口:删壳 + tests 拆分 + AR13)。 +M6 完成后打 tag `v0.1.6-m6`。 +⚠️ **M6 必须同步做**: +① `check-arch.sh` 加 **AR14**(`sspf-mcp-adapter` 是**唯一**允许依赖 compat 各包的 crate —— 决策③的「防回退」条款:`sspf-mcp-adapter` 之外不许依赖 compat 包); +② `check-contract-scan.py` 的 `plat_files` **必须收** `crates/sspf-mcp-adapter/src/`(MCP 适配层里有守卫常量 ⇒ 漏收 ⇒ CC6 假漂移); +③ `check-boundary.sh` 的 CP1/CP2 纳入 MCP 适配层真源; +④ 重跑全部 `--self-test`。 +之后 = M7(收口:删 `platform/` 转发壳 + 拆 `tests/` + 全量反自证)。 -> 🔴 **M4 留下的教训,M5/M6 必须继承**: +> 🔴 **M4/M5 留下的教训,M6 必须继承**: > ① **闸门判据里的正则要用反自证验证过一次**才敢信 —— `grep` 不报错 + 退出码 0 + 打印 `ok` = 三重「看起来正常」,但 BSD grep 的 `\s` 让 AR11/AR12 一直空转。 > ② **收编新目录要用 glob,不要写死路径列表** —— 写死列表必然在某次新增包时漏掉 ⇒ 尺子静默失效(M4 的 CC6 就是这么废的)。 > ③ **搬迁后第一反应不该是「全绿」而是「可疑」** —— M2/M3 搬迁后闸门都报红(正常),M4 首次跑就 10/10 ⇒ 反而是尺子坏了的信号。 +> ④ **改写规则要区分「路径前缀变了」与「模块名变了」** —— M5 把 `use crate::lowcode_ddl;` 误改成 `use crate::ddl;` ⇒ 编译不过。搬 crate 只改**跨 crate 的前缀**(`crate::platform::` → `sspf_core::`),**模块名一律不动**;文档内链(``[`crate::xxx`]``)也不能跟着改。 diff --git a/scripts/check-arch.sh b/scripts/check-arch.sh index 3d16bd5..b4793fc 100755 --- a/scripts/check-arch.sh +++ b/scripts/check-arch.sh @@ -394,6 +394,47 @@ check_ar12() { fi } +# ---------------------------------------------------------------- AR13 +# **低代码执行层的依赖白名单**(M5 把 `lowcode_*.rs` 下沉到 `sspf-lowcode-exec`)。 +# +# 🔴 **为什么需要**:`sspf-lowcode`(AR7)是**纯计算**层 —— 只认 serde,不许碰 DB/HTTP。 +# M5 新增的 `sspf-lowcode-exec` 是它的**执行层**,允许连库;但依赖面必须**锁死**: +# 一旦它拖进 `axum`(web 框架)⇒ 这层就再也用不了 CLI / MCP / 离线工具; +# 一旦它拖进 `sspf_pack_*`(业务包)⇒ 平台层开始认识业务 ⇒ 破 AR9。 +# +# 判据(两层): +# ① `crates/sspf-lowcode-exec/Cargo.toml` 的依赖 ⊆ 白名单; +# ② 该 crate 的源码里**不许**出现 `sspf_pack_`(与 AR9 同款语义,但独立钉住 +# —— AR9 只扫平台层目录,执行层是新的目录,得单独管)。 +check_ar13() { + local f="$CRATES/sspf-lowcode-exec/Cargo.toml" + if [ ! -f "$f" ]; then + skip "AR13 sspf-lowcode-exec 不存在" + return + fi + local deps; deps="$(deps_of "$f" | tr '\n' ' ')" + # 🔴 白名单:`sspf-lowcode`(纯计算)+ `sspf-core`(平台核心)+ `sspf-store`(Db 真源) + # + `sspf-mcp`(ToolError)+ `pglite-rs`(真实库)+ `chrono` + `serde_json`。 + # **不许** axum(web 框架)/ tokio(异步运行时,本层是同步函数 + 调用方 await)。 + if subset_of "$deps" "sspf-lowcode sspf-core sspf-store sspf-mcp pglite-rs chrono serde_json"; then + ok "AR13 sspf-lowcode-exec 依赖干净([$deps])" + else + bad "AR13 sspf-lowcode-exec 依赖越界:[$deps] —— 只许 {lowcode, core, store, mcp, pglite-rs, chrono, serde_json},不许 web 框架 / 业务包" + fi + # 第二层:源码不许出现业务包引用 + local src="$CRATES/sspf-lowcode-exec/src" + if [ -d "$src" ]; then + local hits + hits="$(grep -rnE '^[[:space:]]*(pub )?use[[:space:]]+sspf_pack_' "$src" 2>/dev/null || true)" + if [ -z "$hits" ]; then + ok "AR13 执行层源码没有 use sspf_pack_*(业务知识没漏进执行层)" + else + bad "AR13 执行层源码出现了业务包引用(业务知识漏进平台层):" + printf '%s\n' "$hits" | sed 's/^/ /' + fi + fi +} + # ---------------------------------------------------------------- PACK1 # **spec 单一真源**:`modules/.rs` 只许做转发,不许自己写 spec。 # @@ -527,7 +568,7 @@ PY self_test() { local rc=0 - echo "── 反自证 1/7:造一个依赖越界的假 pack,AR2 必须报 ❌ ──" + echo "── 反自证 1/8:造一个依赖越界的假 pack,AR2 必须报 ❌ ──" local tmp="$ROOT/packs/__arch_selftest__" mkdir -p "$tmp" cat > "$tmp/Cargo.toml" <<'TOML' @@ -553,7 +594,7 @@ TOML rc=1 fi - echo "── 反自证 2/7:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──" + echo "── 反自证 2/8:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──" # # 🔴 **为什么必须自证 AR9**:它的判据是 `grep 目录`。 # 目录名写错 / 路径拼错 ⇒ `grep` 永远返回空 ⇒ **永远"通过"**。 @@ -591,7 +632,7 @@ TOML rc=1 fi - echo "── 反自证 3/7:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──" + echo "── 反自证 3/8:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──" # # 🔴 造在**临时模块文件**上(不动真文件):只要它同时有 `pub use sspf_pack_` # 和 `= EntitySpec {`,PACK1 就必须红。 @@ -617,7 +658,7 @@ RS echo "⏭ 跳过 PACK1 反自证(业务模块目录不存在)" fi - echo "── 反自证 4/7:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──" + echo "── 反自证 4/8:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──" local pfile="$CRATES/sspf-plugin/Cargo.toml" if [ -f "$pfile" ]; then cp "$pfile" "$pfile.bak" @@ -638,7 +679,7 @@ RS echo "⏭ 跳过 AR8 反自证(sspf-plugin 不存在)" fi - echo "── 反自证 5/7:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──" + echo "── 反自证 5/8:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──" # # 🔴 **必须自证 AR10**:它的判据是「扫平台层目录找契约面引用」。 # 目录名写错 / 路径拼错 ⇒ 扫描永远返回空 ⇒ **永远"通过"** ⇒ 虚假安全感。 @@ -671,7 +712,7 @@ RS rc=1 fi - echo "── 反自证 6/7:往契约面底座塞 use super::system,AR11 必须报 ❌ ──" + echo "── 反自证 6/8:往契约面底座塞 use super::system,AR11 必须报 ❌ ──" # # 🔴 **M3 起底座有两处**:真源 `crates/sspf-compat-core/src/helper.rs`(实现) # + 转发壳 `src/backend/src/platform/compat/helper.rs`。**两处都注入、 @@ -698,7 +739,7 @@ RS rc=1 fi - echo "── 反自证 7/7:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──" + echo "── 反自证 7/8:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──" # # 🔴 **为什么必须自证 AR12**:它的判据是「读 Cargo.toml 找 sspf-compat-* 依赖」。 # 若 grep 模式写错(包名含连字符/下划线混用)⇒ 永远扫不到依赖 ⇒ @@ -725,6 +766,39 @@ RS rc=1 fi + echo "── 反自证 8/8:给执行层塞一个越界依赖 + 一条业务包引用,AR13 必须报 ❌ ──" + # + # 🔴 **必须自证 AR13**:它的判据是「读 Cargo.toml + grep 源码」。 + # 两种失效模式都得堵: + # ① 依赖白名单写错/漏项 ⇒ 越界依赖进得来(执行层拖进 web 框架 ⇒ CLI/MCP 报废); + # ② 源码 grep 路径写错 ⇒ 业务包引用扫不到(平台层开始认识业务 ⇒ 破 AR9)。 + # 🔴 **两处都注入、两处都被抓到**才算尺子有效(单点注入会漏判)。 + local a13ok=0 + local a13toml="$CRATES/sspf-lowcode-exec/Cargo.toml" + local a13src="$CRATES/sspf-lowcode-exec/src/__ar13_selftest.rs" + local a13need=0 a13c=0 a13out + if [ -f "$a13toml" ]; then + cp "$a13toml" "$a13toml.bak" + printf '\naxum = { workspace = true }\n' >> "$a13toml" + a13need=$((a13need+1)) + printf 'use sspf_pack_asset::DATA_RESOURCE_SPEC;\n' > "$a13src" + a13need=$((a13need+1)) + a13out="$(check_ar13 2>&1 || true)" + [ -f "$a13toml.bak" ] && mv "$a13toml.bak" "$a13toml" + rm -f "$a13src" + # ① 越界依赖(axum)必须被依赖白名单抓到 + echo "$a13out" | grep -q "依赖越界" && a13c=$((a13c+1)) + # ② 业务包引用必须被源码层抓到,且**路径明确**(不能只看到"有输出") + echo "$a13out" | grep -q "sspf-lowcode-exec/src/__ar13_selftest" && a13c=$((a13c+1)) + [ "$a13need" -gt 0 ] && [ "$a13c" -ge "$a13need" ] && a13ok=1 + fi + if [ "$a13ok" -eq 1 ]; then + echo "✅ 反自证通过:AR13 抓到了越界依赖(axum)与执行层里的业务包引用" + else + echo "❌ 反自证失败:AR13 没抓到越界依赖 / 业务包引用(或漏扫了其中一处)⇒ 尺子是假的" + rc=1 + fi + return $rc } @@ -744,6 +818,7 @@ check_ar9 check_ar10 check_ar11 check_ar12 +check_ar13 check_pack1 check_mem1 check_mem2 diff --git a/scripts/check-boundary.sh b/scripts/check-boundary.sh index 1ebdf33..8263615 100755 --- a/scripts/check-boundary.sh +++ b/scripts/check-boundary.sh @@ -49,6 +49,10 @@ COMPAT_DIRS=() for d in "$ROOT"/crates/sspf-compat-*/src; do [ -d "$d" ] && COMPAT_DIRS+=("$d") done +# 🔴 **M5 起低代码执行层真源在 `crates/sspf-lowcode-exec/src/`**—— +# 它也是「平台侧」(连库 / 跑 SQL / 校验),业务标识符泄漏同样要查。 +# ⇒ 放进 CP1/CP2 的扫描范围(与契约面同款纪律)。 +LOWCODE_EXEC="$ROOT/crates/sspf-lowcode-exec/src" MODULES="$SRC/modules" MODULES_MOD="$MODULES/mod.rs" BOOTSTRAP="$SRC/bootstrap.rs" @@ -122,7 +126,7 @@ hdr "[CP1] 平台层零业务标识符(扫字符串字面量;禁止清单从 # + `packs/*/src/lib.rs`(业务包)⇒ 两处都要进「禁止清单」, # 否则包里的业务表名会从清单里消失 ⇒ 尺子变弱。 # 🔴 **M2 起平台层真源在 `crates/sspf-core/src/`** ⇒ 它必须进扫描面(否则扫空壳)。 -SCAN_OUT="$(SSW_PACKS_DIR="${ROOT}/packs" "${PY_BIN}" "${SCAN}" "${MODULES}" "${PLATFORM_CORE}" "${PLATFORM}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} "${SRC}/routes.rs" "${SRC}/main.rs" "${BOOTSTRAP}" 2>&1)" +SCAN_OUT="$(SSW_PACKS_DIR="${ROOT}/packs" "${PY_BIN}" "${SCAN}" "${MODULES}" "${PLATFORM_CORE}" "${PLATFORM}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} ${LOWCODE_EXEC:+"${LOWCODE_EXEC}"} "${SRC}/routes.rs" "${SRC}/main.rs" "${BOOTSTRAP}" 2>&1)" if [ "$?" -eq 0 ]; then ok "平台层没有业务标识符($(printf '%s\n' "${SCAN_OUT}" | tail -1))" else @@ -131,11 +135,11 @@ else fi # ---- CP2 平台层不反向依赖业务层 ---- -hdr "[CP2] 平台层不反向依赖业务层(sspf-core/** 与 compat 包/** 不许 use crate::modules)" -# 🔴 三处都扫:平台核心真源 + 平台转发壳 + 契约面 7 个包的真源。 -CP2_HITS="$(grep -rn "use crate::modules" "${PLATFORM_CORE}" "${PLATFORM}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} 2>/dev/null)" +hdr "[CP2] 平台层不反向依赖业务层(sspf-core/** 与 compat 包/** 与 lowcode-exec/** 不许 use crate::modules)" +# 🔴 四处都扫:平台核心真源 + 平台转发壳 + 契约面 7 个包的真源 + 低代码执行层真源(M5)。 +CP2_HITS="$(grep -rn "use crate::modules" "${PLATFORM_CORE}" "${PLATFORM}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} ${LOWCODE_EXEC:+"${LOWCODE_EXEC}"} 2>/dev/null)" if [ -z "${CP2_HITS}" ]; then - ok "平台核心 / 转发壳 / 契约面各包 都没有 use crate::modules" + ok "平台核心 / 转发壳 / 契约面各包 / 低代码执行层 都没有 use crate::modules" else no "平台层引用了业务层:" printf '%s\n' "${CP2_HITS}" | sed 's/^/ /' diff --git a/src/backend/Cargo.toml b/src/backend/Cargo.toml index 927c0cd..1be99ac 100644 --- a/src/backend/Cargo.toml +++ b/src/backend/Cargo.toml @@ -62,6 +62,9 @@ sspf-compat-online_dev = { path = "../../crates/sspf-compat-online_dev" } sspf-mcp = { path = "../../crates/sspf-mcp" } # 低代码元数据引擎(纯计算:解析/校验/SQL 生成) sspf-lowcode = { path = "../../crates/sspf-lowcode" } +# 🔴 **低代码执行层**(M5)—— 连库 / 跑 SQL / 比对真实库列 / 事务 / 回写模型。 +# `src/backend/src/lowcode_*.rs` 现在只是转发壳 ⇒ CLI 与 MCP 适配器的调用路径零感知。 +sspf-lowcode-exec = { path = "../../crates/sspf-lowcode-exec" } # 业务包装载器(L2 静态:读清单 / 校验 / 收集声明)—— 不认识 axum sspf-plugin = { path = "../../crates/sspf-plugin" } diff --git a/src/backend/src/lowcode_check.rs b/src/backend/src/lowcode_check.rs index fcb24db..fa0266a 100644 --- a/src/backend/src/lowcode_check.rs +++ b/src/backend/src/lowcode_check.rs @@ -1,501 +1,5 @@ -//! lowcode_check —— 写库**之前**的业务校验层(P2-b)。 -//! -//! ## 为什么要有这一层 -//! -//! 底层「设计稿列 vs 真实库列」的比对([`crate::lowcode_crud`])只回答 -//! 「**能不能写**」(列在不在),不回答「**该不该写**」(值合不合法)。 -//! -//! 基线平台在落库前有三道业务校验: -//! -//! | 校验 | 基线实现 | 本模块 | -//! |---|---|---| -//! | **业务主键** | `FormCheckUtils.checkBusinessKey()` | [`check_business_key`] | -//! | **必填** | `FormCheckUtils.checkForm()` 里的 `config.isRequired()` | 已在 `sspf-lowcode` 层(`MISSING_REQUIRED`) | -//! | **单行唯一** | `FormCheckUtils.checkForm()` 里的 `config.getUnique()` | [`check_unique_fields`] | -//! -//! ## 🔴 缺了会怎样 -//! -//! 不做唯一性校验 ⇒ 库里能塞进两条「房间号相同」的记录 ⇒ 列表页看到重复数据, -//! 而用户以为系统拦住了。基线平台是拦住的 ⇒ **行为不一致 = 迁移没对齐**。 -//! -//! ## 🔴 三条对齐口径(都来自 Java 源码,不是经验) -//! -//! 1. **只有 `jnpfKey == "input"` 且 `unique == true` 的字段才查唯一** -//! (Java `JnpfKeyConsts.COM_INPUT.equals(config.getJnpfKey())`)。 -//! 下拉/日期/数字控件标了 `unique` 也**不查** —— 查多了会拦住基线允许的写入。 -//! 2. **唯一性比对是「全表扫 + 排除自己」**,不是靠数据库 UNIQUE 约束。 -//! Java 是 `SELECT ... WHERE col = ? AND pk <> ?`,然后看 `count > 0`。 -//! 3. **业务主键是「组合唯一」**:清单里所有字段一起比; -//! 任一字段为空 ⇒ 该字段用 `IS NULL` 参与比较(Java `setEachCondition`)。 -//! -//! ## 🔴 逻辑删除的行算不算重复 -//! -//! 基线平台:逻辑删除的行**仍然占着**这个唯一值 —— 它只在判重时补了 -//! `delete_mark IS NULL` 条件(`FormCheckUtils` 第 259–261 行), -//! 所以逻辑删除的行**不参与**判重。 -//! ⇒ Rust 侧口径一致:查判重时带上 `delete_mark IS NULL`。 +//! lowcode_check —— **转发壳**:真源在 [`sspf_lowcode_exec::lowcode_check`](M5 低代码执行层下沉)。 +//! 🔴 只做转发、不含实现;CLI(`--seed-lowcode-demo`)与 MCP 适配器的调用路径不用改。 +//! 为什么留壳、闸门怎么改:见 `docs/CRATES-MIGRATION.md` §4 M5。 -use serde_json::Value; - -use sspf_lowcode::{check_identifier, lookup, FieldNode, FormSchema, ModelSchema}; - -use crate::platform::db::Db; -use sspf_mcp::adapter::ToolError; - -/// 🔴 唯一性冲突的错误。 -/// -/// 基线平台的文案是 `字段名 + MsgCode.EXIST103`(≈「已存在」), -/// 这里给结构化的版本,AI 能据此自纠(改值 / 换 id)。 -pub fn unique_conflict(label: &str, column: &str, value: &Value) -> ToolError { - let shown = match value { - Value::String(s) => s.clone(), - Value::Null => "NULL".to_string(), - other => other.to_string(), - }; - ToolError::new( - "UNIQUE_CONSTRAINT_VIOLATED", - format!("字段「{label}」({column}) 的值 {shown} 已经存在了"), - ) - .field(column) - .field("value") - .hint(format!( - "这个字段被设计成「单行唯一」;换一个值,或者先 data.query 看看哪条记录占着它" - )) - .next( - "data.query", - serde_json::json!({ "enCode": "<功能编码>" }), - "查哪条记录占着这个值", - ) -} - -/// 🔴 业务主键冲突的错误。 -pub fn business_key_conflict(tip: Option<&str>, columns: &[String]) -> ToolError { - let cols = columns.join(" + "); - let message = match tip { - Some(t) if !t.trim().is_empty() => t.to_string(), - _ => format!("业务主键({cols})已经存在了"), - }; - ToolError::new("BUSINESS_KEY_VIOLATED", message) - .field("businessKey") - .hint(format!( - "这个功能启用了业务主键({cols})—— 这几个字段的组合必须唯一;\ - 换一个值,或先 data.query 查一下已有的组合" - )) - .next( - "data.query", - serde_json::json!({ "enCode": "<功能编码>" }), - "查已有的业务主键组合", - ) -} - -/// 🔴 单行唯一校验(对齐 `FormCheckUtils.checkForm()` 的 unique 分支)。 -/// -/// - 只查 `jnpfKey == "input"` **且** `unique == true` 的字段; -/// - 比对范围:整张表(子表字段在**子表**里查,主表字段在**主表**里查); -/// - 排除自己:`record_id` 存在时把该行排除(更新场景); -/// - 逻辑删除的行不参与判重(`delete_mark IS NULL`)。 -/// -/// `record_id` 为 `None` ⇒ 新增场景(不排除任何行)。 -pub async fn check_unique_fields( - db: &Db, - form: &FormSchema, - model: &ModelSchema, - payload: &Value, - record_id: Option<&str>, -) -> Result<(), ToolError> { - let fields = form.unique_fields(); - if fields.is_empty() { - return Ok(()); - } - let logical = form.logical_delete.unwrap_or(false); - - for node in fields { - // 这个字段属于哪张表? - let (table_schema, column) = resolve_table_and_column(model, node).ok_or_else(|| { - ToolError::new( - "UNIQUE_CHECK_SKIPPED", - format!( - "字段「{}」({}) 标了唯一,但模型里找不到它对应的列 —— 跳过这一项的唯一校验", - node.label, node.v_model - ), - ) - .field(&node.v_model) - .hint("先 form.describe 看这个字段到底属于哪张表;模型与表单对不上") - })?; - - let Some(raw) = lookup(payload, &node.v_model, &column) else { - // 没给值 ⇒ Java 那边 `o` 为空 ⇒ 用 `IS NULL` 判重。 - // 但基线平台的 `unique` 语义是「这个值只能有一份」—— - // 没给值时判重没意义(多数列 NOT NULL,落库时自然会报)。 - // ⇒ 这里**跳过**:交给必填校验 / 数据库 NOT NULL 去管。 - continue; - }; - - // Java `ObjectUtil.isEmpty(o) ? null : String.valueOf(o).trim()` - let value = match &raw { - Value::String(s) => { - let t = s.trim(); - if t.is_empty() { - continue; - } - Value::String(t.to_string()) - } - Value::Null => continue, - Value::Bool(b) => Value::String(b.to_string()), - Value::Number(n) => Value::String(n.to_string()), - _ => continue, - }; - - let mut params: Vec = Vec::new(); - let mut sql = format!( - "SELECT 1 FROM {} WHERE {} = $1", - table_schema.table, column - ); - params.push(match &value { - Value::String(s) => s.clone(), - other => other.to_string(), - }); - - // 逻辑删除的行不参与判重(对齐 Java 的 `delete_mark IS NULL` 条件)。 - if logical { - if let Some(dm) = delete_mark_column(table_schema) { - sql.push_str(&format!(" AND {} IS NULL", dm)); - } - } - - // 更新场景:排除自己那行。 - if let Some(rid) = record_id { - if let Some(pk) = primary_key_column(table_schema) { - sql.push_str(&format!(" AND {} <> $2", pk)); - params.push(rid.to_string()); - } - } - - sql.push_str(" LIMIT 1"); - - check_identifier("表名", &table_schema.table).map_err(ident_err)?; - check_identifier("列名", &column).map_err(ident_err)?; - - // 🔴 参数个数必须与 SQL 里的占位符**一一对应**。 - // 更新场景会多一个 `$2`(排除自己)⇒ 参数也要多一个。 - // 少传 ⇒ pglite 报 `statement takes 2 parameters, 1 given`。 - let refs: Vec<&(dyn pglite::ToSql + Sync)> = params - .iter() - .map(|s| s as &(dyn pglite::ToSql + Sync)) - .collect(); - let rows = db - .query_json_params(&sql, &refs) - .await - .map_err(|e| { - ToolError::new("DB_ERROR", format!("唯一性校验查库失败: {e}")) - .hint("先 schema.table.describe 看这张表的结构") - .retryable() - })?; - - if !rows.is_empty() { - return Err(unique_conflict(&node.label, &column, &value)); - } - } - Ok(()) -} - -/// 🔴 业务主键校验(对齐 `FormCheckUtils.checkBusinessKey()`)。 -/// -/// - 只在 `useBusinessKey == true` 且 `businessKeyList` 非空时生效; -/// - 清单里所有字段**一起**比(组合唯一); -/// - 任一字段没给值 ⇒ 该字段用 `IS NULL` 参与比较; -/// - 更新场景排除自己; -/// - 逻辑删除的行不参与判重。 -pub async fn check_business_key( - db: &Db, - form: &FormSchema, - model: &ModelSchema, - payload: &Value, - record_id: Option<&str>, -) -> Result<(), ToolError> { - let Some(nodes) = form.business_key_fields() else { - return Ok(()); - }; - let Some(main) = model.main_table() else { - return Ok(()); - }; - let logical = form.logical_delete.unwrap_or(false); - - // 把每个业务主键字段解析成「物理列 + 值」 - let mut cols: Vec = Vec::new(); - let mut values: Vec> = Vec::new(); - for node in &nodes { - let Some((tbl, col)) = resolve_table_and_column(model, node) else { - // 清单里的字段在模型里找不到 ⇒ 没法校验。 - // 静默跳过会放过重复数据 ⇒ 明确报错,让 AI 知道设计稿有问题。 - return Err(ToolError::new( - "BUSINESS_KEY_CHECK_FAILED", - format!( - "业务主键清单里的字段「{}」({}) 在模型里找不到对应的列 —— 无法校验", - node.label, node.v_model - ), - ) - .field(&node.v_model) - .hint("先 form.describe 看这个功能的字段与模型是否对得上")); - }; - if !tbl.table.eq_ignore_ascii_case(&main.table) { - // 业务主键只在**主表**上判重(Java `checkBusinessKey` 用 mainTable)。 - continue; - } - let v = lookup(payload, &node.v_model, &col) - .and_then(|v| match v { - Value::String(s) => { - let t = s.trim(); - if t.is_empty() { - None - } else { - Some(t.to_string()) - } - } - Value::Null => None, - Value::Bool(b) => Some(b.to_string()), - Value::Number(n) => Some(n.to_string()), - _ => None, - }); - cols.push(col); - values.push(v); - } - if cols.is_empty() { - return Ok(()); - } - - check_identifier("表名", &main.table).map_err(ident_err)?; - - // WHERE 条件:每个业务主键列 = ? (值为空则 IS NULL) - let mut where_parts: Vec = Vec::new(); - let mut params: Vec = Vec::new(); - for (i, (col, val)) in cols.iter().zip(values.iter()).enumerate() { - check_identifier("列名", col).map_err(ident_err)?; - match val { - Some(v) => { - params.push(v.clone()); - where_parts.push(format!("{} = ${}", col, params.len())); - } - None => { - where_parts.push(format!("{} IS NULL", col)); - } - } - let _ = i; - } - - let mut sql = format!("SELECT 1 FROM {} WHERE {}", main.table, where_parts.join(" AND ")); - - if logical { - if let Some(dm) = delete_mark_column(main) { - sql.push_str(&format!(" AND {} IS NULL", dm)); - } - } - if let Some(rid) = record_id { - if let Some(pk) = primary_key_column(main) { - params.push(rid.to_string()); - sql.push_str(&format!(" AND {} <> ${}", pk, params.len())); - } - } - sql.push_str(" LIMIT 1"); - - let refs: Vec<&(dyn pglite::ToSql + Sync)> = params - .iter() - .map(|s| s as &(dyn pglite::ToSql + Sync)) - .collect(); - let rows = db - .query_json_params(&sql, &refs) - .await - .map_err(|e| { - ToolError::new("DB_ERROR", format!("业务主键校验查库失败: {e}")) - .hint("先 schema.table.describe 看这张表的结构") - .retryable() - })?; - - if !rows.is_empty() { - return Err(business_key_conflict( - form.business_key_tip.as_deref(), - &cols, - )); - } - Ok(()) -} - -/// 🔴 标识符非法时的错误转换。 -fn ident_err(e: sspf_lowcode::SqlError) -> ToolError { - ToolError::new(e.code(), e.message()).hint("表名/列名只能含字母、数字、下划线") -} - -/// 🔴 找字段属于哪张表 + 它对应的物理列名。 -/// -/// 主表字段 → 主表;子表字段 → 子表(靠 `relationTable`)。 -fn resolve_table_and_column<'a>( - model: &'a ModelSchema, - node: &FieldNode, -) -> Option<(&'a sspf_lowcode::TableSchema, String)> { - // 子表字段:靠 `relationTable`(`tableName` 对子表字段不可信 —— 见 form.rs 注释) - if let Some(rel) = &node.relation_table { - if let Some(t) = model.table(rel) { - if let Some(col) = column_for(t, node) { - return Some((t, col)); - } - } - } - // 主表字段:靠 `tableName`;退回到主表 - if let Some(tn) = &node.table_name { - if let Some(t) = model.table(tn) { - if let Some(col) = column_for(t, node) { - return Some((t, col)); - } - } - } - let main = model.main_table()?; - let col = column_for(main, node)?; - Some((main, col)) -} - -/// 🔴 在一张表的列定义里找这个字段的物理列名。 -fn column_for(table: &sspf_lowcode::TableSchema, node: &FieldNode) -> Option { - // 先按 `__vModel__` 精确匹配 - if let Some(c) = table.column_by_field(&node.v_model) { - if let Some(col) = c.resolved_column() { - return Some(col); - } - } - // 再按「剥前缀 + 转小写」推导 - sspf_lowcode::v_model_to_column(&node.v_model) -} - -/// 🔴 主键列(排除租户列 —— Java `checkBusinessKey` 的口径)。 -fn primary_key_column(table: &sspf_lowcode::TableSchema) -> Option { - table - .primary_keys() - .into_iter() - .find(|c| !c.contains("f_tenant_id")) -} - -/// 🔴 删除标记列(逻辑删除时用来排除已删行)。 -fn delete_mark_column(table: &sspf_lowcode::TableSchema) -> Option { - table - .fields - .iter() - .find(|c| { - let f = c.field.to_lowercase(); - f.contains("f_delete_mark") || f == "delete_mark" - }) - .and_then(|c| c.resolved_column()) -} - -#[cfg(test)] -mod tests { - use super::*; - use serde_json::json; - - const FORM: &str = r#"{ - "logicalDelete": true, - "useBusinessKey": true, - "businessKeyList": ["F_Code"], - "businessKeyTip": "业务编码已存在", - "fields": [ - { - "__config__": { - "jnpfKey": "input", "layout": "colFormItem", "label": "房间号", - "tableName": "biz_main", "required": true, "unique": true - }, - "__vModel__": "F_Room" - }, - { - "__config__": { - "jnpfKey": "input", "layout": "colFormItem", "label": "业务编码", - "tableName": "biz_main", "required": false - }, - "__vModel__": "F_Code" - }, - { - "__config__": { - "jnpfKey": "inputNumber", "layout": "colFormItem", "label": "数量", - "tableName": "biz_main", "unique": true - }, - "__vModel__": "F_Qty" - } - ] - }"#; - - const MODEL: &str = r#"[ - { - "table": "biz_main", "tableName": "主表", "typeId": "1", - "fields": [ - { "field": "F_Id", "fieldName": "主键", "dataType": "varchar", - "primaryKey": 1, "allowNull": false }, - { "field": "F_Tenant_Id", "fieldName": "租户", "dataType": "varchar", - "primaryKey": 1, "allowNull": false }, - { "field": "F_Room", "fieldName": "房间号", "dataType": "varchar" }, - { "field": "F_Code", "fieldName": "业务编码", "dataType": "varchar" }, - { "field": "F_Qty", "fieldName": "数量", "dataType": "int4" }, - { "field": "F_Delete_Mark", "fieldName": "删除标记", "dataType": "int4" } - ] - } - ]"#; - - fn form() -> FormSchema { - FormSchema::parse(&json!({ - "fields": serde_json::from_str::(FORM).unwrap()["fields"].clone(), - "logicalDelete": true, - "useBusinessKey": true, - "businessKeyList": ["F_Code"], - "businessKeyTip": "业务编码已存在", - })) - .unwrap() - } - - fn model() -> ModelSchema { - ModelSchema::parse(&serde_json::from_str::(MODEL).unwrap()).unwrap() - } - - /// 🔴 只有 `input` + `unique` 才参与判重 —— 数字控件标了 unique 也不查。 - #[test] - fn only_input_with_unique_is_checked() { - let f = form(); - let uniq = f.unique_fields(); - assert_eq!(uniq.len(), 1, "应该只有 F_Room 一个字段参与唯一校验"); - assert_eq!(uniq[0].v_model, "F_Room"); - } - - /// 🔴 业务主键清单能被解析成字段。 - #[test] - fn business_key_fields_are_resolved() { - let f = form(); - let bk = f.business_key_fields().expect("应该启用业务主键"); - assert_eq!(bk.len(), 1); - assert_eq!(bk[0].v_model, "F_Code"); - } - - /// 🔴 没启用业务主键 ⇒ 不校验。 - #[test] - fn business_key_disabled_returns_none() { - let f = FormSchema::parse(&json!({ - "fields": serde_json::from_str::(FORM).unwrap()["fields"].clone(), - })) - .unwrap(); - assert!(f.business_key_fields().is_none()); - } - - /// 🔴 主键列要排除租户列。 - #[test] - fn primary_key_excludes_tenant() { - let m = model(); - let main = m.main_table().unwrap(); - assert_eq!( - primary_key_column(main).as_deref(), - Some("f_id"), - "租户列也是 primaryKey=1,但不能被当成主键" - ); - } - - /// 🔴 删除标记列能被认出来。 - #[test] - fn delete_mark_column_is_found() { - let m = model(); - let main = m.main_table().unwrap(); - assert_eq!(delete_mark_column(main).as_deref(), Some("f_delete_mark")); - } -} +pub use sspf_lowcode_exec::lowcode_check::*; diff --git a/src/backend/src/lowcode_crud.rs b/src/backend/src/lowcode_crud.rs index a11dc86..aa0a4d0 100644 --- a/src/backend/src/lowcode_crud.rs +++ b/src/backend/src/lowcode_crud.rs @@ -1,1240 +1,5 @@ -//! lowcode_crud —— 内核侧的**低代码动态 CRUD 执行层**(P2-b)。 -//! -//! ## 分工 -//! -//! | 层 | 位置 | 干什么 | -//! |---|---|---| -//! | 解析 / 校验 / **SQL 生成** | `sspf-lowcode`(纯计算,AR7) | 出 SQL 文本 + 参数 | -//! | **执行** | 本文件(内核) | 连库、跑 SQL、返回结果 | -//! -//! ⇒ SQL 生成的正确性由 `sspf-lowcode` 的单测覆盖;本文件只做「拿到 SQL 就执行」, -//! 没有分支逻辑 —— 这是刻意的分工。 -//! -//! ## 🔴 四条执行层的硬约定 -//! -//! 1. **主表先行、子表随后**:子表外键指向主表主键,顺序反了会插不进去。 -//! 2. **一个事务**:主表失败 ⇒ 子表也不能留孤儿行。 -//! pglite 有真事务 API(`transaction()` / `commit()` / `rollback()`)—— 用它。 -//! 3. **写入前先比对真实库列**:设计稿自洽 ≠ 真实库有那列。 -//! 官方数据里 `columnName` 全是 null,列名是从 `field` 推导的 —— -//! 推导必然有偏差(`F_CreatorTime` → `f_creatortime`,真实列可能是别的)。 -//! ⇒ 落库前拿 `information_schema` 对一遍,**对不上就拒绝写**, -//! 并明确告诉 AI「设计稿与真实库不一致」。 -//! 4. **子表更新走差集对账**:不是全量覆盖(详见 [`sspf_lowcode::diff_sub_rows`])。 -//! -//! ## 🔴 为什么第 3 条不能省 -//! -//! 省掉它 ⇒ 数据库报 `column "f_xxx" does not exist` —— -//! 这句话对 AI 毫无指导性(该改表单?改表?还是拼错了?)。 -//! 自己做比对 ⇒ 报「设计稿声明了 f_xxx,但真实库没有这一列」, -//! 直接指到要改的地方。 -//! -//! ## 🔴 值的类型:走 `::text` + 显式 cast -//! -//! pglite 绑参数时若不指定类型,PG 会把 `$1` **推断成目标列的类型** -//! (`timestamp` / `numeric` / `integer`),而我们绑的是 `Option` -//! ⇒ 直接报 `cannot convert between the Rust type String and the Postgres type timestamp`。 -//! ⇒ 一律 `$n::text`,再按列类型加 cast(`::numeric` / `::integer` / `::timestamp`)。 -//! -//! ## 🔴 cast 靠 `param_columns`,不靠猜 -//! -//! [`sspf_lowcode::Sql`] 自带「占位符 ↔ 列名」映射 ⇒ 执行层不需要 -//! 「理解 SQL 是怎么拼的」,也不需要「按模型字段顺序猜第 n 个参数是哪一列」 -//! (写入列顺序 ≠ 模型字段顺序 —— 系统列是运行时追加的,猜错就写脏数据)。 +//! lowcode_crud —— **转发壳**:真源在 [`sspf_lowcode_exec::lowcode_crud`](M5 低代码执行层下沉)。 +//! 🔴 只做转发、不含实现;CLI(`--seed-lowcode-demo`)与 MCP 适配器的调用路径不用改。 +//! 为什么留壳、闸门怎么改:见 `docs/CRATES-MIGRATION.md` §4 M5。 -use std::collections::BTreeMap; - -use pglite::ToSql; -use serde_json::{json, Value}; - -use sspf_lowcode::{ - check_identifier, plan_delete, plan_insert, plan_update_full, sql::Sql, FieldNode, FormSchema, - ModelSchema, SqlError, SubUpdateContext, SubUpdateOptions, TableSchema, WriteContext, -}; -use sspf_mcp::adapter::ToolError; - -use crate::platform::db::Db; -use crate::platform::ids::new_uuid; - -/// 🔴 **单租户**下的默认租户值。 -/// -/// ## 溯源 -/// -/// 基线平台 `GlobalConst`: -/// ```java -/// public static final String DEFAULT_TENANT_VALUE = "0"; -/// ``` -/// -/// `TenantDataSourceUtil.getTenantColumn()`: -/// ```java -/// public static String getTenantColumn() { -/// String result = GlobalConst.DEFAULT_TENANT_VALUE; -/// if (isTenantColumn()) { // 只有「字段隔离」模式才取真实租户名 -/// result = getTenantName(); -/// } -/// return result; -/// } -/// ``` -/// -/// 本平台部署配置 `config.MultiTenancy: false` ⇒ `isTenantColumn()` 为 false -/// ⇒ **恒定返回 `"0"`**。 -/// -/// ## 🔴 为什么单租户下**仍然要写**租户列 -/// -/// `FlowFormDataUtil.addTenantId()` 是**无条件**执行的: -/// ```java -/// private void addTenantId(GeneralInsertDSL dsl, SqlTable t) { -/// dsl.set(t.column(TableFeildsEnum.TENANTID.getField())) -/// .toValue(TenantDataSourceUtil.getTenantColumn()); -/// } -/// ``` -/// ⇒ 单租户也会往 `f_tenant_id` 写 `"0"`。 -/// 不写的话,列是 NOT NULL(`TableFeildsEnum.TENANTID` 的 nullSign = "NOT NULL") -/// ⇒ 插入直接失败。 -pub const DEFAULT_TENANT_ID: &str = "0"; - -/// 动态 CRUD 的执行结果。 -#[derive(Debug, Clone)] -pub struct CrudOutcome { - /// 主键 id。 - pub id: String, - /// 实际执行的 SQL 条数(主表 + 子表)。 - pub statements: usize, - /// 诊断信息(哪些列没写、为什么)。 - pub notes: Vec, - /// 计划好的 SQL(dry-run 时返回给调用方看)。 - pub sql: Vec, - /// 是否只是演练(没落库)。 - pub dry_run: bool, -} - -/// 把 lowcode 的错误转成结构化工具错误。 -pub fn sql_err(e: SqlError) -> ToolError { - let mut t = ToolError::new(e.code(), e.message()); - match &e { - SqlError::UnknownColumn { table, column } => { - t = t - .field(column) - .hint(format!( - "表 {table} 里没有列 {column};先 form.describe 看真实字段清单" - )) - .next( - "form.describe", - json!({ "enCode": "<功能编码>" }), - "看这个功能的字段与列", - ); - } - SqlError::MissingRequired { table, column, label } => { - t = t.field(column).hint(format!( - "必填字段「{label}」({table}.{column}) 必须给值;\ - 确实要留空就先把它从「必填」里去掉" - )); - } - SqlError::UnknownTable(tbl) => { - t = t - .field("table") - .hint(format!("表 {tbl} 不在功能定义里 —— 表名白名单不通过")) - .next( - "form.validate", - json!({ "enCode": "<功能编码>" }), - "先体检这个功能", - ); - } - SqlError::NoMainTable => { - t = t.hint("模型里没有 typeId=1 的主表 —— 这个功能定义可能不完整"); - } - SqlError::NoPrimaryKey(tbl) => { - t = t.hint(format!( - "表 {tbl} 缺主键:入参没给,且调用方没生成 —— \ - 子表每行的主键需要调用方预先生成并登记" - )); - } - SqlError::TypeMismatch { column, expected } => { - t = t.field(column).hint(format!("字段 {column} 应为 {expected}")); - } - SqlError::UnsupportedValue { column } => { - t = t.field(column).hint(format!( - "字段 {column} 的值是复杂对象 —— 只能给字符串/数字/数组;\ - 对象请先序列化成 JSON 字符串" - )); - } - SqlError::IllegalIdentifier { kind, value } => { - t = t.hint(format!( - "{kind}「{value}」含非法字符,只能是字母/数字/下划线" - )); - } - SqlError::NoColumnsToUpdate(tbl) => { - t = t.hint(format!( - "表 {tbl} 没有任何列要更新 —— 入参没给可写字段,或给的都是系统字段" - )); - } - SqlError::MissingRelationValue { table, column } => { - t = t.hint(format!( - "子表 {table} 的外键指向主表的 {column},但这一列的值拿不到 —— \ - 它不是主键,需要先查出来再传进来" - )); - } - SqlError::LogicalDeleteUnsupported(tbl) => { - t = t.hint(format!( - "表 {tbl} 没有删除标记列,不支持逻辑删除 —— \ - 这个功能要么该走物理删除,要么表建错了(logicalDelete 与建表不匹配)" - )) - .next( - "form.validate", - json!({ "enCode": "<功能编码>" }), - "体检这个功能的逻辑删除设置", - ); - } - } - t -} - -/// 🔴 设计稿 vs 真实库:列名比对结果。 -#[derive(Debug, Clone, PartialEq)] -pub struct ColumnMismatch { - /// 真实库里缺的设计稿列。 - pub missing: Vec, - /// 真实库有、但设计稿没声明的列(通常是系统列,不算错,仅供参考)。 - pub extra: Vec, -} - -/// 取一张表在真实库里的列名。 -pub async fn real_columns(db: &Db, table: &str) -> Result, ToolError> { - let t = table.to_string(); - let rows = db - .query_json_params( - "SELECT column_name AS \"name\" FROM information_schema.columns \ - WHERE table_schema = 'public' AND table_name = $1 \ - ORDER BY ordinal_position", - &[&t], - ) - .await - .map_err(|e| { - ToolError::new("DB_ERROR", format!("读表结构失败: {e}")) - .hint("先 schema.table.list 确认表在不在") - .retryable() - })?; - Ok(rows - .into_iter() - .filter_map(|r| r["name"].as_str().map(str::to_string)) - .collect()) -} - -/// 比对设计稿声明的列与真实库的列。 -pub fn compare_columns(declared: &[String], actual: &[String]) -> ColumnMismatch { - let actual_lower: Vec = actual.iter().map(|c| c.to_lowercase()).collect(); - let missing: Vec = declared - .iter() - .filter(|c| !actual_lower.contains(&c.to_lowercase())) - .cloned() - .collect(); - let declared_lower: Vec = declared.iter().map(|c| c.to_lowercase()).collect(); - let extra: Vec = actual - .iter() - .filter(|c| !declared_lower.contains(&c.to_lowercase())) - .cloned() - .collect(); - ColumnMismatch { missing, extra } -} - -/// 🔴 真实库里**根本没有这张表**时的错误。 -pub fn table_missing_error(table: &str) -> ToolError { - ToolError::new("TABLE_NOT_IN_DB", format!("真实库里没有表 {table}")).field("table").hint( - "设计稿里的表还没建出来 —— 低代码功能要先「建表」再「存数据」。\ - 用 schema.table.list 看当前库有哪些表", - ) - .next( - "schema.table.list", - json!({ "prefix": table }), - "看这张表在不在", - ) -} - -/// 构造写入上下文(把内核有的东西塞进去)。 -pub fn build_context( - user_id: Option<&str>, - tenant_id: Option<&str>, - now: Option<&str>, -) -> WriteContext { - WriteContext { - user_id: user_id.map(str::to_string), - organize_ids: Vec::new(), - position_ids: Vec::new(), - tenant_id: tenant_id.map(str::to_string), - bill_numbers: Default::default(), - primary_keys: Default::default(), - now: now.map(str::to_string), - relation_values: Default::default(), - } -} - -/// 🔴 当前时间(ISO8601,秒精度)。 -/// -/// 🔴 为什么用**秒精度**而不是毫秒/纳秒: -/// 低代码表的 `f_creatortime` / `f_lastmodifytime` 在官方 DDL 里是 -/// `timestamp`(**没有时区**)⇒ 传 ISO 带 `T` 和 `Z` 的串会被 PG -/// 解析成 `timestamptz` 再转 `timestamp` ⇒ **会随时区偏移几个小时**。 -/// 统一给 `YYYY-MM-DD HH:MM:SS` 最稳(PG 直接当 timestamp 字面量)。 -pub fn now_iso() -> String { - chrono::Local::now() - .format("%Y-%m-%d %H:%M:%S") - .to_string() -} - -/// 执行一次**新增**(主表 + 子表),全部落在一个事务里。 -/// -/// `dry_run = true` ⇒ 只生成 SQL + 校验列,**不落库**。 -pub async fn insert_record( - db: &Db, - form: &FormSchema, - model: &ModelSchema, - payload: &Value, - ctx: &mut WriteContext, - dry_run: bool, -) -> Result { - let main_table = model.main_table().ok_or_else(|| { - ToolError::new("NO_MAIN_TABLE", "模型里没有主表(typeId=1)") - .hint("这个功能定义不完整") - })?; - let main_name = main_table.table.clone(); - - // 🔴 落库前先确认表在真实库里 - let real = real_columns(db, &main_name).await?; - if real.is_empty() { - return Err(table_missing_error(&main_name)); - } - - // 生成主键 - let main_id = new_uuid(); - ctx.set_primary_key(main_name.clone(), main_id.clone()); - - // 子表每行也要主键(Java 侧服务端现生成 UUID) - for sub in form.sub_tables() { - let Some(sub_model) = resolve_sub_model(model, sub) else { - continue; - }; - let rows = sub_rows(payload, &sub.v_model, &sub_model.table); - let Some(arr) = rows.as_ref().and_then(|v| v.as_array()) else { - continue; - }; - for i in 0..arr.len() { - let key = new_uuid(); - ctx.set_sub_row_key(&sub_model.table, &main_id, i, key); - } - } - - let plan = plan_insert(form, model, payload, ctx, &main_id).map_err(sql_err)?; - - // 🔴 逐条比对真实库列 —— 对不上就**拒绝写**,而不是让数据库报错 - let mut notes: Vec = Vec::new(); - let mut real_cols: Vec<(String, Vec)> = Vec::new(); - for stmt in plan.all() { - let cols = columns_of_sql(&stmt.text); - let actual = match real_cols.iter().find(|(t, _)| t == &stmt.table) { - Some((_, c)) => c.clone(), - None => { - let a = real_columns(db, &stmt.table).await?; - if a.is_empty() { - return Err(table_missing_error(&stmt.table)); - } - real_cols.push((stmt.table.clone(), a.clone())); - a - } - }; - let diff = compare_columns(&cols, &actual); - if !diff.missing.is_empty() { - return Err(column_mismatch_error(&stmt.table, &diff, &actual)); - } - if !diff.extra.is_empty() { - notes.push(format!( - "表 {} 真实库里还有设计稿没声明的列(未写入):{}", - stmt.table, - diff.extra.join(", ") - )); - } - } - - let stmts: Vec = plan.all().into_iter().cloned().collect(); - - // 🔴 **业务校验**(唯一性 / 业务主键)—— 必须在真正写库**之前**做。 - // - // 基线平台 `VisualdevModelDataServiceImpl.visualCreate()`: - // ```java - // String b = formCheckUtils.checkForm(checkFormModel); - // if (StringUtil.isNotEmpty(b)) { throw new WorkFlowException(b); } - // flowFormDataUtil.create(dataModel); - // ``` - // ⇒ 校验失败 ⇒ **一条 SQL 都不执行**。 - // - // dry-run 也要做校验:dry-run 的意义是「先看会不会被拦」。 - // 校验不过还返回 SQL,AI 会误以为「只差一步就能落库」。 - // - // 新增场景 `record_id = None` ⇒ 不排除任何行。 - crate::lowcode_check::check_unique_fields(db, form, model, payload, None).await?; - crate::lowcode_check::check_business_key(db, form, model, payload, None).await?; - - if dry_run { - return Ok(CrudOutcome { - id: main_id, - statements: stmts.len(), - notes, - sql: stmts, - dry_run: true, - }); - } - - let count = execute_plan(db, model, &stmts).await?; - - Ok(CrudOutcome { - id: main_id, - statements: count, - notes, - sql: stmts, - dry_run: false, - }) -} - -/// 🔴 记录不存在的错误(AI 据此自纠:先查再改)。 -pub fn record_missing_error(table: &str, record_id: &str) -> ToolError { - ToolError::new( - "RECORD_NOT_FOUND", - format!("表 {table} 里没有 id 为 {record_id} 的记录"), - ) - .field("recordId") - .hint("记录可能已被删除;先用 data.query 查一遍确认 id") - .next( - "data.query", - json!({ "enCode": "<功能编码>" }), - "查这条记录还在不在", - ) -} - -/// 执行一次**更新**(主表 + 子表差集对账)。 -/// -/// ## 🔴 `only_update` 的口径(对齐基线平台) -/// -/// 基线平台 `DataModel.onlyUpdate`: -/// ```java -/// // 子表仅修改 -/// private Boolean onlyUpdate = false; -/// ``` -/// ```java -/// if (CollUtil.isNotEmpty(deleteList) && !onlyUpdate) { /* 删缺失的旧行 */ } -/// ``` -/// -/// ⇒ `onlyUpdate = true` ⇒ **不删**入参里缺失的旧行(只更新/新增)。 -/// -/// 🔴 **基线的正常 HTTP 路径恒为 false**: -/// `VisualdevModelDataController` 构造 `VisualParamModel` 时**没有**设 `onlyUpdate` -/// ⇒ 只有 Excel 导入(`OnlineExcelUtil`)与流程场景才可能为 true。 -/// ⇒ 本函数默认 `false`,MCP 层**不暴露**这个开关(暴露了会让 AI 以为 -/// 「默认只更新不删除」,与基线的实际行为相反)。 -#[allow(clippy::too_many_arguments)] -pub async fn update_record( - db: &Db, - form: &FormSchema, - model: &ModelSchema, - payload: &Value, - ctx: &mut WriteContext, - record_id: &str, - dry_run: bool, -) -> Result { - update_record_with(db, form, model, payload, ctx, record_id, dry_run, false).await -} - -/// 带 `only_update` 的更新(默认路径走 [`update_record`])。 -#[allow(clippy::too_many_arguments)] -pub async fn update_record_with( - db: &Db, - form: &FormSchema, - model: &ModelSchema, - payload: &Value, - ctx: &mut WriteContext, - record_id: &str, - dry_run: bool, - only_update: bool, -) -> Result { - let main_table = model.main_table().ok_or_else(|| { - ToolError::new("NO_MAIN_TABLE", "模型里没有主表(typeId=1)") - })?; - let main_name = main_table.table.clone(); - - let real = real_columns(db, &main_name).await?; - if real.is_empty() { - return Err(table_missing_error(&main_name)); - } - - // 🔴 **先确认记录存在** —— 否则错误会一路飘到子表查询上, - // 变成一句毫无指导性的 `DB_ERROR`(AI 不知道是「记录没了」还是「库坏了」)。 - ensure_record_exists(db, model, record_id).await?; - - // 🔴 **顺序很重要**:先查主表那一行的**关联列实际值**,再收集子表上下文。 - // - // 子表外键的值 = 主表 `relationField` 指向的那一列的值 - // (基线平台:`mainMap.get(table.getRelationField())`)。 - // 当 `relationField` 就是主键时,值 = 主键,收集子表上下文时回落到 `record_id` 没问题; - // 但当它指向**别的列**(如业务编码 `F_Code`)时, - // 不先查库就拿不到值 ⇒ 外键会退化成主键 ⇒ 子表挂错父行。 - // - // 之前顺序反了(先 collect 再 fetch)⇒ 非主键 relationField 场景下 - // `collect_sub_contexts` 拿不到关联值,回落成 `main_id`。 - let relation_values = fetch_relation_values(db, form, model, record_id).await?; - for (col, val) in &relation_values { - ctx.set_relation_value(col, val.clone()); - } - - // 🔴 子表差集需要「旧行主键」—— 查库在**事务外**做(避免持锁期间再开事务死锁)。 - let logical = form.logical_delete.unwrap_or(false); - let sub_ctxs = collect_sub_contexts(db, form, model, ctx, record_id, logical, only_update).await?; - - let plan = plan_update_full(form, model, payload, ctx, record_id, &sub_ctxs).map_err(sql_err)?; - - let mut notes: Vec = Vec::new(); - let mut real_cols: Vec<(String, Vec)> = Vec::new(); - for stmt in plan.all() { - let cols = columns_of_sql(&stmt.text); - if cols.is_empty() { - continue; - } - let actual = match real_cols.iter().find(|(t, _)| t == &stmt.table) { - Some((_, c)) => c.clone(), - None => { - let a = real_columns(db, &stmt.table).await?; - if a.is_empty() { - return Err(table_missing_error(&stmt.table)); - } - real_cols.push((stmt.table.clone(), a.clone())); - a - } - }; - let diff = compare_columns(&cols, &actual); - if !diff.missing.is_empty() { - return Err(column_mismatch_error(&stmt.table, &diff, &actual)); - } - if !diff.extra.is_empty() { - notes.push(format!( - "表 {} 真实库里还有设计稿没声明的列(未写入):{}", - stmt.table, - diff.extra.join(", ") - )); - } - } - - let stmts: Vec = plan.all().into_iter().cloned().collect(); - - // 🔴 **业务校验**(唯一性 / 业务主键)—— 更新场景要**排除自己那行**。 - // - // 基线平台 `FormCheckUtils` 的唯一性 SQL: - // ```java - // if (StringUtils.isNotEmpty(id)) { - // where.and(sqlTable.column(mainKeyModel.getField()), SqlBuilder.isNotEqualTo(realId)); - // } - // ``` - // ⇒ 不排除自己 ⇒ 改一下别的字段也会被判「重复」。 - crate::lowcode_check::check_unique_fields(db, form, model, payload, Some(record_id)).await?; - crate::lowcode_check::check_business_key(db, form, model, payload, Some(record_id)).await?; - - if dry_run { - return Ok(CrudOutcome { - id: record_id.to_string(), - statements: stmts.len(), - notes, - sql: stmts, - dry_run: true, - }); - } - - let count = execute_plan(db, model, &stmts).await?; - - Ok(CrudOutcome { - id: record_id.to_string(), - statements: count, - notes, - sql: stmts, - dry_run: false, - }) -} - -/// 执行一次**删除**(逻辑 / 物理按 `form.logicalDelete`)。 -pub async fn delete_record( - db: &Db, - form: &FormSchema, - model: &ModelSchema, - ctx: &mut WriteContext, - record_id: &str, - dry_run: bool, -) -> Result { - let main_table = model.main_table().ok_or_else(|| { - ToolError::new("NO_MAIN_TABLE", "模型里没有主表(typeId=1)") - })?; - let main_name = main_table.table.clone(); - - let real = real_columns(db, &main_name).await?; - if real.is_empty() { - return Err(table_missing_error(&main_name)); - } - - // 🔴 先确认记录存在(否则错误会飘到子表查询上,变成没指导性的 DB_ERROR)。 - ensure_record_exists(db, model, record_id).await?; - - let logical = form.logical_delete.unwrap_or(false); - - // 🔴 子表外键的值可能不是主键(`relationField` 指向别的列)⇒ 先查主表那一行。 - let relation_values = fetch_relation_values(db, form, model, record_id).await?; - for (col, val) in &relation_values { - ctx.set_relation_value(col, val.clone()); - } - - // 逻辑删除但表里没有删除列 ⇒ `plan_delete` 会报 `LOGICAL_DELETE_UNSUPPORTED`。 - // 那种情况**不退化成物理删**(用户以为逻辑删了,实际物理删 ⇒ 审计链断)。 - let plan = plan_delete(form, model, ctx, record_id).map_err(sql_err)?; - - let mut notes: Vec = Vec::new(); - let mut real_cols: Vec<(String, Vec)> = Vec::new(); - for stmt in plan.all() { - let cols = columns_of_sql(&stmt.text); - if cols.is_empty() { - continue; - } - let actual = match real_cols.iter().find(|(t, _)| t == &stmt.table) { - Some((_, c)) => c.clone(), - None => { - let a = real_columns(db, &stmt.table).await?; - if a.is_empty() { - return Err(table_missing_error(&stmt.table)); - } - real_cols.push((stmt.table.clone(), a.clone())); - a - } - }; - let diff = compare_columns(&cols, &actual); - if !diff.missing.is_empty() { - return Err(column_mismatch_error(&stmt.table, &diff, &actual)); - } - if !diff.extra.is_empty() { - notes.push(format!( - "表 {} 真实库里还有设计稿没声明的列(未写入):{}", - stmt.table, - diff.extra.join(", ") - )); - } - } - - notes.push(if logical { - "逻辑删除:置删除标记,数据仍在表里".to_string() - } else { - "物理删除:行会真从表里消失(logicalDelete=false)".to_string() - }); - - let stmts: Vec = plan.all().into_iter().cloned().collect(); - - if dry_run { - return Ok(CrudOutcome { - id: record_id.to_string(), - statements: stmts.len(), - notes, - sql: stmts, - dry_run: true, - }); - } - - let count = execute_plan(db, model, &stmts).await?; - - Ok(CrudOutcome { - id: record_id.to_string(), - statements: count, - notes, - sql: stmts, - dry_run: false, - }) -} - -/// 🔴 确认主记录存在(更新 / 删除前必查)。 -/// -/// ## 为什么必须单独查一次 -/// -/// 更新流程后面会去查子表旧行、关联列值 —— 那些查询用的都是 `record_id`。 -/// 记录不存在时,错误会飘到子表查询上,变成一句 -/// `DB_ERROR: 查子表旧行失败: relation "xxx" does not exist` —— -/// AI 看到完全不知道是「记录没了」还是「库坏了」。 -/// -/// ⇒ 先明确报 `RECORD_NOT_FOUND`,并提示「先用 data.query 查一遍」。 -/// -/// ## 🔴 主键列**从模型推导**,不写死 `f_id` -/// -/// Java `getKey()`:取模型里 `primaryKey=1` 且**不是租户列**的那一列。 -/// 官方模型里 `f_tenant_id` 也是 `primaryKey=1` ⇒ 必须排除。 -async fn ensure_record_exists( - db: &Db, - model: &ModelSchema, - record_id: &str, -) -> Result<(), ToolError> { - let Some(main_table) = model.main_table() else { - return Ok(()); - }; - let table = main_table.table.clone(); - let pk_col = main_table - .primary_keys() - .into_iter() - .find(|c| !c.contains("f_tenant_id")) - .unwrap_or_else(|| "f_id".to_string()); - - // 🔴 表名/列名来自用户可编辑的模型 JSON ⇒ 进 SQL 前过标识符检查。 - check_identifier("表名", &table).map_err(sql_err)?; - check_identifier("列名", &pk_col).map_err(sql_err)?; - - let id = record_id.to_string(); - let sql = format!("SELECT {pk_col} AS \"id\" FROM {table} WHERE {pk_col} = $1 LIMIT 1"); - let rows = db - .query_json_params(&sql, &[&id]) - .await - .map_err(|e| ToolError::new("DB_ERROR", format!("查记录失败: {e}")).retryable())?; - if rows.is_empty() { - return Err(record_missing_error(&table, record_id)); - } - Ok(()) -} - -/// 🔴 收集子表更新的上下文(**旧行主键**从库里查)。 -/// -/// 差集对账的前提是知道「旧库里有哪些行」。 -/// 本函数是**纯查库**(不改数据)⇒ 放在事务外执行,避免持锁期间再开事务。 -async fn collect_sub_contexts( - db: &Db, - form: &FormSchema, - model: &ModelSchema, - ctx: &WriteContext, - main_id: &str, - logical: bool, - only_update: bool, -) -> Result, ToolError> { - let mut out: BTreeMap = BTreeMap::new(); - - for sub in form.sub_tables() { - let Some(sub_model) = resolve_sub_model(model, sub) else { - continue; - }; - let Some(fk_col) = sub_model.foreign_key_column() else { - return Err(sql_err(SqlError::UnknownColumn { - table: sub_model.table.clone(), - column: "tableField".to_string(), - })); - }; - let sub_pk = sub_model - .primary_keys() - .into_iter() - .find(|c| !c.contains("f_tenant_id")) - .unwrap_or_else(|| "f_id".to_string()); - - // 🔴 表名/列名进 SQL 之前必须过标识符检查。 - // - // 这些名字来自**用户可编辑的模型 JSON**(`f_tables_data`)。 - // 参数化只能防「值注入」,**防不住结构注入** —— - // 表名/列名是拼进 SQL 文本的,不是占位符。 - // ⇒ 规则与生成层共用同一份(`sspf_lowcode::check_identifier`), - // 避免「生成层拦了、执行层漏了」的漏洞。 - for (kind, name) in [ - ("表名", sub_model.table.as_str()), - ("列名", fk_col.as_str()), - ("列名", sub_pk.as_str()), - ] { - check_identifier(kind, name).map_err(sql_err)?; - } - - // 外键的值:主表 `relationField` 指向的那一列的实际值。 - let fk_value = ctx - .relation_value(sub_model) - .unwrap_or_else(|| main_id.to_string()); - - // 查旧行主键 - let sql = format!( - "SELECT {sub_pk} AS \"k\" FROM {table} WHERE {fk_col} = $1", - sub_pk = sub_pk, - table = sub_model.table, - fk_col = fk_col, - ); - let rows = db - .query_json_params(&sql, &[&fk_value]) - .await - .map_err(|e| { - ToolError::new("DB_ERROR", format!("查子表旧行失败: {e}")) - .hint("子表可能还没建出来") - .retryable() - })?; - let old_keys: Vec = rows - .into_iter() - .filter_map(|r| r["k"].as_str().map(str::to_string)) - .collect(); - - let mut sub_ctx = SubUpdateContext::new( - old_keys, - fk_col.clone(), - fk_value, - SubUpdateOptions { - only_update, - logical_delete: logical, - }, - ); - // 🔴 子表行主键由内核生成(Java 侧是 `RandomUtil.uuId()`)。 - sub_ctx.row_key_generator = Some(|_| new_uuid()); - out.insert(sub_model.table.clone(), sub_ctx); - } - - Ok(out) -} - -/// 🔴 查主表那一行的**关联列**实际值(子表外键要指向它)。 -/// -/// 基线平台:`Object relationFieldValue = mainMap.get(table.getRelationField());` -/// —— 读的是**主表那一行的实际值**,不是主键。 -/// -/// `relationField` 通常就是主键列 ⇒ 这次查询走的是「白名单内的表名 + 白名单内的列名」。 -async fn fetch_relation_values( - db: &Db, - form: &FormSchema, - model: &ModelSchema, - main_id: &str, -) -> Result, ToolError> { - let Some(main_table) = model.main_table() else { - return Ok(Vec::new()); - }; - let main_pk = main_table - .primary_keys() - .into_iter() - .find(|c| !c.contains("f_tenant_id")) - .unwrap_or_else(|| "f_id".to_string()); - - // 🔴 表名/主键列名进 SQL 之前必须过标识符检查(同 [`collect_sub_contexts`])。 - check_identifier("表名", &main_table.table).map_err(sql_err)?; - check_identifier("列名", &main_pk).map_err(sql_err)?; - - // 收集所有子表用到的关联列 - let mut cols: Vec = Vec::new(); - for sub in form.sub_tables() { - let Some(sub_model) = resolve_sub_model(model, sub) else { - continue; - }; - if let Some(rel) = sub_model.relation_column() { - // 🔴 关联列名同样来自用户可编辑的模型 JSON ⇒ 也要过检查。 - check_identifier("列名", &rel).map_err(sql_err)?; - if !cols.contains(&rel) { - cols.push(rel); - } - } - } - if cols.is_empty() { - return Ok(Vec::new()); - } - - // 一次查出来 - let sel: Vec = cols.iter().map(|c| format!("{c} AS \"{c}\"")).collect(); - let sql = format!( - "SELECT {} FROM {} WHERE {} = $1", - sel.join(", "), - main_table.table, - main_pk - ); - let rows = db - .query_json_params(&sql, &[&main_id.to_string()]) - .await - .map_err(|e| { - ToolError::new("DB_ERROR", format!("查主表关联列失败: {e}")).retryable() - })?; - - let Some(row) = rows.first() else { - return Ok(Vec::new()); - }; - - let mut out = Vec::new(); - for c in cols { - if let Some(v) = row.get(&c) { - let text = match v { - Value::String(s) => s.clone(), - Value::Null => continue, - other => other.to_string(), - }; - out.push((c, text)); - } - } - Ok(out) -} - -/// 🔴 在一个事务里执行整组 SQL。 -/// -/// pglite 的 `transaction()` 会拿**独占锁**(`lock_for_transaction`), -/// 所以事务期间不会有别的请求插进来 —— 不会出现「A 写了主表、B 改了子表」的交错。 -async fn execute_plan( - db: &Db, - model: &ModelSchema, - stmts: &[Sql], -) -> Result { - if stmts.is_empty() { - return Ok(0); - } - let tx = db.begin().await.map_err(|e| { - ToolError::new("DB_ERROR", format!("开事务失败: {e}")).retryable() - })?; - - for stmt in stmts { - let table = model.table(&stmt.table); - let sql_text = render_with_casts(&stmt.text, &stmt.params, &stmt.param_columns, table); - let params = params_as_text(&stmt.params); - let refs: Vec<&(dyn ToSql + Sync)> = - params.iter().map(|v| v as &(dyn ToSql + Sync)).collect(); - - if let Err(e) = tx.exec_params(&sql_text, &refs).await { - let _ = tx.rollback().await; - return Err(ToolError::new("DB_ERROR", format!("写库失败: {e}")) - .hint("多半是列名与真实表对不上;先 form.validate 再看真实表的列") - .retryable()); - } - } - - tx.commit().await.map_err(|e| { - ToolError::new("DB_ERROR", format!("提交事务失败: {e}")).retryable() - })?; - - Ok(stmts.len()) -} - -/// 🔴 列不一致时的结构化错误。 -fn column_mismatch_error( - table: &str, - diff: &ColumnMismatch, - actual: &[String], -) -> ToolError { - ToolError::new( - "COLUMN_MISMATCH", - format!( - "表 {} 缺少设计稿声明的列:{}", - table, - diff.missing.join(", ") - ), - ) - .field(diff.missing.first().map(|s| s.as_str()).unwrap_or("")) - .hint(format!( - "真实库里 {} 只有这些列:{}。\ - 设计稿的列名是从 `field` 推导的(官方数据 columnName 全是 null),\ - 推导必然有偏差 —— 要么改设计稿,要么改真实表", - table, - actual.join(", ") - )) - .next( - "form.validate", - json!({ "enCode": "<功能编码>" }), - "体检设计稿自洽性", - ) -} - -/// 把 `$n` 占位符改成 `$n::text` + 类型 cast。 -/// -/// 🔴 必须加 `::text`:pglite 绑 `Option`, -/// 若让 PG 把 `$1` 推断成 `timestamp` / `numeric`,会直接报 -/// `cannot convert between the Rust type String and the Postgres type timestamp`。 -/// -/// 🔴 占位符必须**按完整 token 扫描**:`$1` 是 `$10` 的前缀, -/// 用字符串 find 会把 `$10` 改成 `$1::text0::text`。 -/// -/// 🔴 cast 靠 `param_columns`(占位符 ↔ 列名的一一映射), -/// **不猜**「第 n 个参数是哪一列」。 -fn render_with_casts( - text: &str, - params: &[Value], - param_columns: &[String], - table: Option<&TableSchema>, -) -> String { - let mut out = String::with_capacity(text.len() + params.len() * 8); - let bytes = text.as_bytes(); - let mut i = 0usize; - - while i < bytes.len() { - if bytes[i] == b'$' { - // 读数字 - let mut j = i + 1; - while j < bytes.len() && bytes[j].is_ascii_digit() { - j += 1; - } - if j > i + 1 { - let idx: usize = text[i + 1..j].parse().unwrap_or(0); - out.push_str(&text[i..j]); - out.push_str("::text"); - if let Some(col) = param_columns.get(idx.saturating_sub(1)) { - out.push_str(cast_of_type(col, table)); - } - i = j; - continue; - } - } - let ch_len = utf8_len(bytes[i]); - out.push_str(&text[i..i + ch_len]); - i += ch_len; - } - out -} - -/// 取一个 UTF-8 字符的字节长度。 -fn utf8_len(b: u8) -> usize { - if b < 0x80 { - 1 - } else if b >> 5 == 0b110 { - 2 - } else if b >> 4 == 0b1110 { - 3 - } else if b >> 3 == 0b11110 { - 4 - } else { - 1 - } -} - -/// 按列名给出写值时的 cast。 -fn cast_of_type(column: &str, table: Option<&TableSchema>) -> &'static str { - let Some(table) = table else { - return ""; - }; - // 先看模型里声明的数据类型 - if let Some(def) = table.column_by_name(column) { - match def.data_type.to_lowercase().as_str() { - "int" | "integer" | "int2" | "int4" | "int8" | "bigint" | "smallint" => { - return "::integer" - } - "decimal" | "numeric" | "money" | "real" | "double" | "float" => return "::numeric", - "datetime" | "timestamp" | "date" | "time" => return "::timestamp", - "bool" | "boolean" => return "::boolean", - _ => {} - } - } - // 模型没说 ⇒ 按列名特征兜底 - let lower = column.to_lowercase(); - if lower.ends_with("_time") || lower.ends_with("_date") || lower.ends_with("time") { - return "::timestamp"; - } - "" -} - -/// 值 ⇒ `Option`(绑定用)。 -/// -/// 🔴 一律按**文本**传 —— 类型转换交给 SQL 里的 `::text` + cast 链。 -fn params_as_text(values: &[Value]) -> Vec> { - values - .iter() - .map(|v| match v { - Value::Null => None, - Value::String(s) => Some(s.clone()), - Value::Number(n) => Some(n.to_string()), - Value::Bool(b) => Some(b.to_string()), - other => Some(other.to_string()), - }) - .collect() -} - -/// 从一条 SQL 里取出列名。 -fn columns_of_sql(text: &str) -> Vec { - if let Some((_, rest)) = text.split_once(" (") { - if let Some((cols, _)) = rest.split_once(") VALUES") { - return cols.split(", ").map(|s| s.to_string()).collect(); - } - } - if let Some((_, rest)) = text.split_once(" SET ") { - if let Some((sets, _)) = rest.split_once(" WHERE ") { - return sets - .split(", ") - .filter_map(|s| s.split(" = ").next()) - .map(|s| s.to_string()) - .collect(); - } - } - Vec::new() -} - -/// 找出子表节点对应的模型表。 -fn resolve_sub_model<'a>( - model: &'a ModelSchema, - sub: &FieldNode, -) -> Option<&'a TableSchema> { - if let Some(name) = sub.table_name.as_deref() { - if let Some(t) = model.table(name) { - return Some(t); - } - } - for child in &sub.children { - if let Some(rt) = child.relation_table.as_deref() { - if let Some(t) = model.table(rt) { - return Some(t); - } - } - } - let subs = model.sub_tables(); - if subs.len() == 1 { - Some(subs[0]) - } else { - None - } -} - -/// 从 payload 里取子表行数组。 -fn sub_rows(payload: &Value, v_model: &str, table: &str) -> Option { - let obj = payload.as_object()?; - if let Some(v) = obj.get(v_model) { - return Some(v.clone()); - } - for (k, v) in obj { - if k.eq_ignore_ascii_case(v_model) || k.eq_ignore_ascii_case(table) { - return Some(v.clone()); - } - } - None -} - -#[cfg(test)] -mod tests { - use super::*; - - /// 🔴 比对必须能抓出「设计稿有、真实库没有」的列。 - #[test] - fn compare_columns_finds_missing() { - let declared = vec!["f_id".to_string(), "f_room".to_string()]; - let actual = vec!["f_id".to_string()]; - let diff = compare_columns(&declared, &actual); - assert_eq!(diff.missing, vec!["f_room".to_string()]); - assert!(diff.extra.is_empty()); - } - - /// 大小写不敏感(PG 会折叠大小写)。 - #[test] - fn compare_columns_is_case_insensitive() { - let declared = vec!["F_ID".to_string()]; - let actual = vec!["f_id".to_string()]; - let diff = compare_columns(&declared, &actual); - assert!(diff.missing.is_empty(), "不该报缺列: {:?}", diff.missing); - } - - /// 🔴 占位符必须加 `::text` —— 否则 PG 推断成 timestamp/numeric 会报类型错。 - #[test] - fn placeholders_get_text_cast() { - let out = render_with_casts( - "INSERT INTO t (a, b) VALUES ($1, $2)", - &[Value::String("x".into()), Value::String("y".into())], - &["a".to_string(), "b".to_string()], - None, - ); - assert_eq!(out, "INSERT INTO t (a, b) VALUES ($1::text, $2::text)"); - } - - /// 数值列要加 `::numeric`。 - #[test] - fn numeric_column_gets_numeric_cast() { - let model = ModelSchema::from_str( - r#"[{ "table": "t", "typeId": "1", "fields": [ - { "field": "F_Id", "columnName": "f_id", "primaryKey": 1 }, - { "field": "F_Price", "columnName": "f_price", "dataType": "decimal" } - ]}]"#, - ) - .unwrap(); - let table = model.table("t").unwrap(); - let out = render_with_casts( - "INSERT INTO t (f_id, f_price) VALUES ($1, $2)", - &[Value::String("a".into()), Value::String("9.9".into())], - &["f_id".to_string(), "f_price".to_string()], - Some(table), - ); - assert!( - out.contains("$2::text::numeric"), - "数值列应带 ::numeric: {out}" - ); - } - - /// 🔴 **`$10` 不能被 `$1` 的替换误伤**。 - /// - /// 用 `str::find("$1")` 找位置会把 `$10` 当成 `$1` ⇒ 变成 `$1::text0::text` - /// ⇒ SQL 直接语法错。这是最难查的一类 bug(只在参数 ≥ 10 时出现)。 - #[test] - fn ten_placeholders_are_not_corrupted_by_one() { - // 构造:INSERT INTO t (c1, ..., c10) VALUES ($1, ..., $10) - let mut text = String::from("INSERT INTO t ("); - for i in 1..=10 { - if i > 1 { - text.push_str(", "); - } - text.push_str(&format!("c{i}")); - } - text.push_str(") VALUES ("); - for i in 1..=10 { - if i > 1 { - text.push_str(", "); - } - text.push_str(&format!("${i}")); - } - text.push(')'); - - let params: Vec = (1..=10).map(|i| Value::String(format!("v{i}"))).collect(); - let cols: Vec = (1..=10).map(|i| format!("c{i}")).collect(); - - let out = render_with_casts(&text, ¶ms, &cols, None); - assert!( - out.contains("$10::text"), - "$10 应被完整替换: {out}" - ); - assert!( - !out.contains("$1::text0"), - "$10 被 $1 的替换误伤了: {out}" - ); - assert_eq!( - out.matches("::text").count(), - 10, - "应有 10 处 ::text: {out}" - ); - } - - /// 值转 `Option`:null ⇒ None。 - #[test] - fn params_as_text_maps_null_to_none() { - let vals = params_as_text(&[ - Value::Null, - Value::String("a".into()), - Value::Number(5.into()), - Value::Bool(true), - ]); - assert_eq!(vals[0], None); - assert_eq!(vals[1].as_deref(), Some("a")); - assert_eq!(vals[2].as_deref(), Some("5")); - assert_eq!(vals[3].as_deref(), Some("true")); - } - - /// 从 SQL 文本抽列名(INSERT / UPDATE 两种形态)。 - #[test] - fn columns_of_sql_handles_both_shapes() { - let ins = "INSERT INTO t (a, b, c) VALUES ($1, $2, $3)"; - assert_eq!(columns_of_sql(ins), vec!["a", "b", "c"]); - let upd = "UPDATE t SET a = $1, b = $2 WHERE id = $3"; - assert_eq!(columns_of_sql(upd), vec!["a", "b"]); - } - - /// 🔴 cast 必须靠 **列名**,不是靠「参数序号 = 模型字段序号」。 - #[test] - fn cast_uses_param_columns_not_position() { - let model = ModelSchema::from_str( - r#"[{ "table": "t", "typeId": "1", "fields": [ - { "field": "F_Id", "columnName": "f_id", "primaryKey": 1 }, - { "field": "F_Amount", "columnName": "f_amount", "dataType": "decimal" } - ]}]"#, - ) - .unwrap(); - let table = model.table("t").unwrap(); - // 参数顺序与模型字段顺序**故意不同**:$1 是 f_amount,$2 是 f_id - let out = render_with_casts( - "INSERT INTO t (f_amount, f_id) VALUES ($1, $2)", - &[Value::String("9.9".into()), Value::String("id".into())], - &["f_amount".to_string(), "f_id".to_string()], - Some(table), - ); - assert!( - out.contains("$1::text::numeric"), - "$1 是 f_amount,应带 ::numeric: {out}" - ); - assert!( - out.contains("$2::text") && !out.contains("$2::text::numeric"), - "$2 是 f_id,不该带 ::numeric: {out}" - ); - } -} +pub use sspf_lowcode_exec::lowcode_crud::*; diff --git a/src/backend/src/lowcode_ddl.rs b/src/backend/src/lowcode_ddl.rs index da623ee..2bff8c6 100644 --- a/src/backend/src/lowcode_ddl.rs +++ b/src/backend/src/lowcode_ddl.rs @@ -1,430 +1,5 @@ -//! lowcode_ddl —— 内核侧的**动态建表执行层**(P2-b 的最后一块)。 -//! -//! ## 分工(与 [`crate::lowcode_crud`] 同款) -//! -//! | 层 | 位置 | 干什么 | -//! |---|---|---| -//! | **DDL 生成** | `sspf-lowcode::ddl`(纯计算,AR7) | 出 `CREATE TABLE` 文本 + 回写后的模型 | -//! | **执行** | 本文件(内核) | 连库、跑 DDL、回写 `f_tables_data` | -//! -//! ## 🔴 三步闭环(缺一不可) -//! -//! ```text -//! 1. plan_create() → CREATE TABLE 文本(主表在前,子表随后) -//! 2. 执行 DDL → 真实库里有表了 -//! 3. rewrite_model() → 把真实表结构回写进 f_tables_data -//! ``` -//! -//! ## 🔴 第 3 步为什么**不是可选的** -//! -//! 基线平台 `VisualDevTableCre.tableList()` 建完表后会用**建表清单**重新组装 -//! `TableModel` 再写回 `f_tables_data`: -//! -//! ```java -//! this.tableModel(tableModelList, datableList, tableName, table, true, tableField, relationField); -//! ... -//! entity.setVisualTables(JsonUtil.getObjectToString(tableModelList)); -//! ``` -//! -//! ⇒ 建表后的模型**含平台追加的系统列**(`f_tenant_id` / `f_delete_mark` …)。 -//! -//! 不回写的后果(本项目已真实踩到): -//! -//! | 现象 | 根因 | -//! |---|---| -//! | 逻辑删除报 `LOGICAL_DELETE_UNSUPPORTED` | CRUD 层在**模型**里找 `f_delete_mark`,找不到 | -//! | 「设计稿 vs 真实库」列比对永远对不上 | 模型少列、真实库多列 | -//! | `f_tenant_id` 不被写 | 租户列在模型里缺失 | -//! -//! ## 🔴 幂等 -//! -//! 基线平台 `DbTableServiceImpl.createTable()` 会先检查表是否已存在, -//! 存在则直接返回(不重复建)。本模块同理: -//! -//! - 表已存在 ⇒ **不报错**,跳过 DDL,但**仍然回写模型** -//! (回写是幂等的,且让「设计稿落后于真实库」自动修复)。 -//! - 表已存在但**列结构不同** ⇒ 报 `TABLE_ALREADY_EXISTS_DIFFERENT`, -//! 明确告诉调用方「不是同一次建表的结果」,让人去核对而不是硬改。 -//! -//! ## 🔴 只在开发期可用 -//! -//! 建表是**破坏性**操作(会改真实库结构)。本模块提供 `Profile::Dev` 闸门, -//! 生产档直接拒绝 —— 见 [`create_tables`]. +//! lowcode_ddl —— **转发壳**:真源在 [`sspf_lowcode_exec::lowcode_ddl`](M5 低代码执行层下沉)。 +//! 🔴 只做转发、不含实现;CLI(`--seed-lowcode-demo`)与 MCP 适配器的调用路径不用改。 +//! 为什么留壳、闸门怎么改:见 `docs/CRATES-MIGRATION.md` §4 M5。 -use serde_json::{json, Value}; - -use sspf_lowcode::{ - plan_create, rewrite_model, CreatePlan, DdlError, DdlOptions, FormSchema, ModelSchema, -}; -use sspf_mcp::adapter::ToolError; - -use crate::platform::db::Db; - -/// 建表的结果。 -#[derive(Debug, Clone)] -pub struct CreateTablesOutcome { - /// 建出来的表(主表在前)。 - pub tables: Vec, - /// 哪些表是**已存在**因而跳过的。 - pub skipped: Vec, - /// 回写后的模型(`f_tables_data` 的新值)。 - pub model: Value, - /// 诊断信息。 - pub notes: Vec, - /// 实际执行的 DDL(dry-run 时给调用方看)。 - pub ddl: Vec, - /// 是否只是演练(没建表、没回写)。 - pub dry_run: bool, -} - -impl CreateTablesOutcome { - /// 一共几张表。 - pub fn table_count(&self) -> usize { - self.tables.len() - } -} - -/// 🔴 把 DDL 错误转成结构化工具错误。 -pub fn ddl_err(e: DdlError) -> ToolError { - let mut t = ToolError::new(e.code(), e.message()); - match &e { - DdlError::NoMainTable => { - t = t.hint("这个功能定义里没有主表(typeId=1)—— 设计稿不完整"); - } - DdlError::IllegalIdentifier { kind, value } => { - t = t - .field(*kind) - .hint(format!( - "{kind}「{value}」含非法字符;表名/列名只允许字母、数字、下划线,且不能以数字开头" - )) - .next("form.describe", json!({ "enCode": "<功能编码>" }), "看设计稿里的表名"); - } - DdlError::DuplicateColumn { table, column } => { - t = t - .field(column) - .hint(format!( - "表 {table} 里两列推出同一个物理列名 {column};检查模型里是不是有同义字段" - )); - } - DdlError::UnsupportedType { - table, - column, - data_type, - } => { - t = t - .field(column) - .hint(format!( - "表 {table} 的列 {column} 类型「{data_type}」还没支持;\ - 改这个字段的类型,或在 sspf-lowcode 的 map_type() 里补上" - )); - } - DdlError::InvalidLength { - table, - column, - length, - } => { - t = t - .field(column) - .hint(format!( - "表 {table} 的列 {column} 长度「{length}」不合法;\ - varchar 填数字,decimal 填「精度,标度」如 18,2" - )); - } - DdlError::NoPrimaryKey(table) => { - t = t - .hint(format!( - "表 {table} 的模型里没有 primaryKey=1 的列 —— 建不出主键,先在设计稿里标主键" - )); - } - } - t -} - -/// 🔴 表是否已存在。 -pub async fn table_exists(db: &Db, table: &str) -> Result { - let rows = db - .query_json_params( - "SELECT 1 AS \"x\" FROM information_schema.tables \ - WHERE table_name = $1 LIMIT 1", - &[&table.to_string()], - ) - .await - .map_err(db_err)?; - Ok(!rows.is_empty()) -} - -/// 🔴 真实库里某张表的列(按序)。 -pub async fn real_columns(db: &Db, table: &str) -> Result, ToolError> { - let rows = db - .query_json_params( - "SELECT column_name AS \"name\" FROM information_schema.columns \ - WHERE table_name = $1 ORDER BY ordinal_position", - &[&table.to_string()], - ) - .await - .map_err(db_err)?; - Ok(rows - .iter() - .map(|r| r["name"].as_str().unwrap_or_default().to_string()) - .collect()) -} - -/// 🔴 执行一次动态建表(**幂等**)。 -/// -/// ## 参数 -/// -/// - `db`:真实库连接; -/// - `model`:**建表前**的模型(`f_tables_data`); -/// - `form`:表单定义(决定 `logicalDelete` / `primaryKeyPolicy`); -/// - `dry_run`:只生成 DDL 与回写后的模型,**不建表、不回写**。 -/// -/// ## 🔴 幂等语义 -/// -/// 表已存在 ⇒ 跳过 DDL,但**仍回写模型**(回写是幂等的)。 -/// 列结构不一致 ⇒ 报 `TABLE_EXISTS_DIFFERENT`,让人去核对。 -pub async fn create_tables( - db: &Db, - model: &ModelSchema, - form: &FormSchema, - dry_run: bool, -) -> Result { - // 🔴 建表选项来自**表单**(基线平台同款:`VisualTableModel` 从 `FormDataModel` 取)。 - let options = DdlOptions { - logical_delete: form.logical_delete.unwrap_or(false), - with_comments: false, - primary_key_policy: form.primary_key_policy.unwrap_or(1), - }; - - let plan = plan_create(model, &options).map_err(ddl_err)?; - let ddl = plan.render(); - - // ---- 回写后的模型(纯计算,先算好;dry-run 也要给)---- - let rewritten = rewrite_model(model, &plan); - - let mut tables = Vec::new(); - let mut skipped = Vec::new(); - let mut notes = Vec::new(); - - if dry_run { - for t in plan.all() { - tables.push(t.table.clone()); - } - return Ok(CreateTablesOutcome { - tables, - skipped, - model: rewritten, - notes: vec!["dry-run:没有建表,也没有回写模型".to_string()], - ddl, - dry_run: true, - }); - } - - // ---- 逐表执行(主表在前,子表随后)---- - for t in plan.all() { - if table_exists(db, &t.table).await? { - // 🔴 已存在 ⇒ 跳过 DDL,但**核对列**。 - let actual = real_columns(db, &t.table).await?; - let expected = t.column_names(); - if actual != expected { - return Err(table_exists_different(&t.table, &expected, &actual)); - } - skipped.push(t.table.clone()); - notes.push(format!( - "表 {} 已存在且列结构一致 —— 跳过建表(幂等)", - t.table - )); - continue; - } - - let sql = t.render(); - db.exec(&sql) - .await - .map_err(|e| create_failed(&t.table, &e.to_string(), &sql))?; - tables.push(t.table.clone()); - } - - Ok(CreateTablesOutcome { - tables, - skipped, - model: rewritten, - notes, - ddl, - dry_run: false, - }) -} - -/// 🔴 表已存在但列结构不一致。 -fn table_exists_different(table: &str, expected: &[String], actual: &[String]) -> ToolError { - let missing: Vec<&str> = expected - .iter() - .filter(|c| !actual.contains(c)) - .map(|s| s.as_str()) - .collect(); - let extra: Vec<&str> = actual - .iter() - .filter(|c| !expected.contains(c)) - .map(|s| s.as_str()) - .collect(); - - let mut msg = format!("表 {table} 已存在,但列结构和设计稿对不上"); - if !missing.is_empty() { - msg.push_str(&format!(";设计稿声明但库里没有:{}", missing.join(", "))); - } - if !extra.is_empty() { - msg.push_str(&format!(";库里有但设计稿没声明:{}", extra.join(", "))); - } - - ToolError::new("TABLE_EXISTS_DIFFERENT", msg) - .field("table") - .hint( - "这张表不是当前设计稿建出来的(可能是手写的、或改过设计稿没重建表)。\ - 改设计稿请先重建表,或手动对齐库里的列 —— 别让工具替你猜", - ) - .next( - "schema.table.describe", - json!({ "table": table }), - "看这张表现在到底有哪些列", - ) -} - -/// 🔴 建表失败。 -fn create_failed(table: &str, err: &str, sql: &str) -> ToolError { - ToolError::new("CREATE_TABLE_FAILED", format!("建表 {table} 失败:{err}")) - .field("table") - .hint("看下面的 DDL 定位问题;最常见是标识符非法或类型不匹配") - .hint(format!("执行的 DDL:{}", sql)) - .next( - "form.describe", - json!({ "enCode": "<功能编码>" }), - "核对设计稿里的表名与列", - ) -} - -/// 🔴 DB 错误转工具错误。 -fn db_err(e: pglite::Error) -> ToolError { - ToolError::new("DB_ERROR", format!("数据库错误:{e}")) - .hint("先确认数据库连接正常;这个错误通常来自 SQL 或连接配置") -} - -/// 🔴 把回写后的模型写回 `base_visual_dev.f_tables_data`。 -/// -/// ## 🔴 为什么**只**写 `f_tables_data` -/// -/// 基线平台 `VisualdevServiceImpl.createTable()` 建表后写的是 -/// `entity.setVisualTables(...)` —— 也就是 `f_tables_data` 一列。 -/// `f_column_data`(列表列)与 `f_form_data`(控件树)由前端另行维护, -/// 建表不碰它们。 -pub async fn write_back_model( - db: &Db, - visualdev_id: &str, - model_json: &Value, -) -> Result<(), ToolError> { - let text = serde_json::to_string(model_json).map_err(|e| { - ToolError::new("MODEL_SERIALIZE_FAILED", format!("模型序列化失败:{e}")) - })?; - - // 🔴 先确认记录存在 —— `exec_params` 不返回影响行数 - // (pglite 0.2.7 没有这个能力),所以只能先查再写。 - let exists = db - .query_json_params( - "SELECT 1 AS \"x\" FROM base_visual_dev WHERE f_id = $1 LIMIT 1", - &[&visualdev_id.to_string()], - ) - .await - .map_err(db_err)?; - if exists.is_empty() { - return Err(ToolError::new( - "FORM_NOT_FOUND", - format!("低代码功能不存在:{visualdev_id}"), - ) - .field("id") - .hint("base_visual_dev 里没有这条记录") - .next("form.list", json!({}), "列出全部功能")); - } - - db.exec_params( - "UPDATE base_visual_dev SET f_tables_data = $1 WHERE f_id = $2", - &[&text, &visualdev_id.to_string()], - ) - .await - .map_err(db_err)?; - - Ok(()) -} - -/// 🔴 建表 + 回写的完整闭环。 -/// -/// 这是 MCP `schema.table.create` 工具背后的实现: -/// 建表 → 回写 `f_tables_data` → 返回可用的模型。 -pub async fn create_and_sync( - db: &Db, - visualdev_id: &str, - model: &ModelSchema, - form: &FormSchema, - dry_run: bool, -) -> Result { - let outcome = create_tables(db, model, form, dry_run).await?; - - if !dry_run { - write_back_model(db, visualdev_id, &outcome.model).await?; - } - - Ok(outcome) -} - -/// 🔴 一张表的 DDL 预览(只给主表,供 `schema.table.describe` 之类的诊断用)。 -pub fn preview_ddl(model: &ModelSchema, form: &FormSchema) -> Result, ToolError> { - let options = DdlOptions { - logical_delete: form.logical_delete.unwrap_or(false), - with_comments: false, - primary_key_policy: form.primary_key_policy.unwrap_or(1), - }; - let plan: CreatePlan = plan_create(model, &options).map_err(ddl_err)?; - Ok(plan.render()) -} - -#[cfg(test)] -mod tests { - use super::*; - - fn model() -> ModelSchema { - ModelSchema::from_str( - r#"[{ "table": "t_main", "tableName": "主表", "typeId": "1", "fields": [ - { "field": "F_Id", "dataType": "varchar", "dataLength": "50", "primaryKey": 1, "allowNull": 0 }, - { "field": "F_Room", "dataType": "varchar", "dataLength": "100", "primaryKey": 0, "allowNull": 1 } - ]}]"#, - ) - .unwrap() - } - - fn form() -> FormSchema { - FormSchema::from_str( - r#"{ "formRef": "formRef", "formModel": "formData", - "primaryKeyPolicy": 1, "logicalDelete": false, "fields": [] }"#, - ) - .unwrap() - } - - /// DDL 预览应产出 `CREATE TABLE`。 - #[test] - fn preview_ddl_produces_create_table() { - let ddl = preview_ddl(&model(), &form()).unwrap(); - assert_eq!(ddl.len(), 1); - assert!(ddl[0].starts_with("CREATE TABLE t_main"), "{}", ddl[0]); - assert!(ddl[0].contains("PRIMARY KEY (f_id, f_tenant_id)"), "{}", ddl[0]); - } - - /// 🔴 DDL 错误要转成有指导性的工具错误。 - #[test] - fn ddl_error_becomes_actionable_tool_error() { - let bad = ModelSchema::from_str( - r#"[{ "table": "bad; DROP TABLE x", "typeId": "1", "fields": [ - { "field": "F_Id", "dataType": "varchar", "primaryKey": 1 } - ]}]"#, - ) - .unwrap(); - let err = preview_ddl(&bad, &form()).unwrap_err(); - assert_eq!(err.code, "ILLEGAL_IDENTIFIER"); - assert!(!err.hints.is_empty(), "非法标识符必须给出修复指引"); - } -} +pub use sspf_lowcode_exec::lowcode_ddl::*; diff --git a/src/backend/src/lowcode_seed.rs b/src/backend/src/lowcode_seed.rs index 7fa2b7b..a89f425 100644 --- a/src/backend/src/lowcode_seed.rs +++ b/src/backend/src/lowcode_seed.rs @@ -1,503 +1,5 @@ -//! lowcode_seed —— **开发期**低代码示例数据种子(CLI `--seed-lowcode-demo`)。 -//! -//! ## 它干什么 -//! -//! 往库里灌**一份可用的低代码功能**,让 P2-b 的动态 CRUD 能被端到端验证: -//! -//! 1. `base_visual_dev` 一行(`f_form_data` = 官方 fixture 的控件树, -//! `f_tables_data` = 官方 fixture 的表结构); -//! 2. 按设计稿**真的建出物理表**(`test_receivable` / `test_details`); -//! 3. 建表后**回写** `f_tables_data`(含平台追加的系统列)—— 与基线平台同款; -//! 4. `base_visual_release` 一行(发布快照,三段 JSON 与 dev 一致)。 -//! -//! ## 🔴 为什么要有这条通道 -//! -//! P2-b 的动态 CRUD 需要「**一个真的低代码功能**」才能验证;而手点界面造一个 -//! 功能 = 慢且不可复现 ⇒ 提供一条**命令行、可重复**的通道: -//! -//! ```text -//! ssw-platform --seed-lowcode-demo # 建表 + 灌功能定义 -//! ssw-platform --seed-lowcode-demo --dry-run # 只看要做什么,不碰库 -//! ``` -//! -//! ## 🔴 数据来源是**官方初始化数据** -//! -//! fixture 与 `crates/sspf-lowcode/tests/fixtures/` 同源(基线平台初始化 SQL 里的 -//! 「应收费用」功能)⇒ 种出来的库**就是基线平台的低代码功能在 SSPF 里的样子** -//! —— 验证才有意义(自己编的数据只能证明「自己和自己通」)。 -//! -//! ## 🔴 只在开发档可用 -//! -//! 它会**改真实库结构**(建表)⇒ 生产档直接拒绝(见 [`seed_gate`])。 -//! -//! ## 🔴 幂等 -//! -//! 固定 id + 「先查存在性再写」⇒ 重复跑不会撞复合主键,也不会留下重复行。 +//! lowcode_seed —— **转发壳**:真源在 [`sspf_lowcode_exec::lowcode_seed`](M5 低代码执行层下沉)。 +//! 🔴 只做转发、不含实现;CLI(`--seed-lowcode-demo`)与 MCP 适配器的调用路径不用改。 +//! 为什么留壳、闸门怎么改:见 `docs/CRATES-MIGRATION.md` §4 M5。 -use std::path::{Path, PathBuf}; - -use serde_json::Value; - -use sspf_lowcode::{FormSchema, ModelSchema}; -use sspf_mcp::adapter::ToolError; - -use crate::lowcode_crud::now_iso; -use crate::lowcode_ddl; -use crate::platform::config::Profile; -use crate::platform::db::{pglite, Db}; -use crate::platform::registry::MAIN_SYSTEM_ID; - -/// 示例功能在 `base_visual_dev` 里的**固定 id**。 -/// -/// 🔴 用**固定 id** 而不是新生成 UUID —— 固定 id 让种子幂等: -/// 重复跑 `--seed-lowcode-demo` 是「更新同一条」而不是「插一堆重复的」。 -pub const DEMO_ID: &str = "lowcode-demo-receivable"; - -/// 示例功能的编码(`f_en_code`)—— AI 调 `data.record.insert` 时用它定位。 -/// -/// 🔴 与 MCP 工具文档里的示例(`crates/sspf-mcp/src/tools/lowcode.rs`)**逐字一致** -/// ⇒ 文档里的示例直接可跑。 -pub const DEMO_EN_CODE: &str = "receivableDemo"; - -/// 示例功能的显示名。 -pub const DEMO_FULL_NAME: &str = "应收费用(低代码示例)"; - -/// 表单 fixture(相对项目根)。 -const FORM_FIXTURE: &str = "crates/sspf-lowcode/tests/fixtures/sample_form.json"; - -/// 模型 fixture(相对项目根)。 -const MODEL_FIXTURE: &str = "crates/sspf-lowcode/tests/fixtures/sample_model.json"; - -/// 单租户口径下的租户值(与 `lowcode_crud::DEFAULT_TENANT_ID` 同源)。 -const TENANT_ID: &str = "0"; - -/// 🔴 `base_visual_dev` / `base_visual_release` 的**共同列清单**与**类型**。 -/// -/// 官方两表逐列相同(`base_visual_release` 只多一列 `f_old_content`) -/// ⇒ 用同一份清单写两张表 ⇒ 少一处漂移。 -/// -/// 🔴 每列带一个**列类型标记**(决定 SQL 里补哪层 cast): -/// -/// | 标记 | 物理类型 | 参数 cast | -/// |---|---|---| -/// | `text` | `TEXT` / `VARCHAR` | `::text` | -/// | `int` | `INTEGER` | `::text::integer` | -/// | `bigint` | `BIGINT` | `::text::bigint` | -/// | `ts` | `TIMESTAMP(0)` | `::text::timestamp` | -/// -/// 🔴 **为什么参数统一按字符串送**:pglite 的扩展查询协议里,未标注类型的参数 -/// 会被服务端当成 `text`;本仓的整型/时间戳列需要显式再转一层。 -/// 列类型标记与清单**同序** ⇒ 少一处可能对不上的地方。 -const VISUAL_COLUMNS: &[(&str, &str)] = &[ - ("f_id", "text"), - ("f_full_name", "text"), - ("f_en_code", "text"), - ("f_state", "int"), - ("f_type", "int"), - ("f_tables_data", "text"), - ("f_form_data", "text"), - ("f_column_data", "text"), - ("f_web_type", "int"), - ("f_app_column_data", "text"), - ("f_enable_flow", "int"), - ("f_description", "text"), - ("f_enabled_mark", "int"), - ("f_sort_code", "bigint"), - ("f_creator_time", "ts"), - ("f_creator_user_id", "text"), - ("f_last_modify_time", "ts"), - ("f_last_modify_user_id", "text"), - ("f_delete_mark", "int"), - ("f_tenant_id", "text"), - ("f_url_address", "text"), - ("f_web_address", "text"), - ("f_button_data", "text"), - ("f_system_id", "text"), -]; - -/// 种子结果。 -#[derive(Debug, Clone)] -pub struct SeedOutcome { - /// 功能 id(`base_visual_dev.f_id`)。 - pub form_id: String, - /// 功能编码。 - pub en_code: String, - /// 建出来的表(主表在前)。 - pub tables: Vec, - /// 已存在因而跳过的表。 - pub skipped: Vec, - /// 实际执行的 DDL。 - pub ddl: Vec, - /// 回写后的模型(`f_tables_data` 的新值)。 - pub model: Value, - /// 诊断信息。 - pub notes: Vec, - /// 是否只是演练(没建表、没写库)。 - pub dry_run: bool, -} - -/// 🔴 **档位闸门**:只在开发档允许。 -/// -/// `SSW_PROFILE=prod`(或 `production`)⇒ 拒绝。 -/// -/// 理由:这条命令会**建表**(改真实库结构)并灌入示例数据 —— -/// 生产库里既不该有示例表,也不该在启动期被一条命令改结构。 -/// -/// 纯函数 ⇒ 可单测(不依赖环境变量)。 -pub fn seed_gate(profile: Profile) -> Result<(), String> { - match profile { - Profile::Dev => Ok(()), - Profile::Prod => Err( - "--seed-lowcode-demo 只在开发档可用(SSW_PROFILE=prod/production)。\n\ - 它会往库里**建表**并灌入示例数据 —— 生产库不该有这些。\n\ - 确实要跑 ⇒ 把 SSW_PROFILE 改成 dev(或 unset),\ - 并确认 PGLITE_DIR 指向的是开发库而不是生产库。" - .to_string(), - ), - } -} - -/// fixture 的绝对路径(相对项目根)。 -pub fn fixture_path(project_dir: &Path, name: &str) -> PathBuf { - project_dir.join(name) -} - -/// 🔴 读 fixture 文件。 -fn read_fixture(project_dir: &Path, rel: &str) -> Result { - let path = fixture_path(project_dir, rel); - std::fs::read_to_string(&path).map_err(|e| { - ToolError::new( - "FIXTURE_MISSING", - format!("读不到官方 fixture:{}({e})", path.display()), - ) - .field(rel) - .hint("fixture 在 crates/sspf-lowcode/tests/fixtures/ 下,与基线平台初始化 SQL 同源") - }) -} - -/// 🔴 读官方 fixture,解析出(表单, 模型)。 -/// -/// 两个入口共用这一段 ⇒ 演练看到的与真跑执行的**一定是同一份设计稿**。 -fn load_demo_fixture( - project_dir: &Path, -) -> Result<(FormSchema, ModelSchema), ToolError> { - let form_text = read_fixture(project_dir, FORM_FIXTURE)?; - let model_text = read_fixture(project_dir, MODEL_FIXTURE)?; - - let form = FormSchema::from_str(&form_text).map_err(|e| { - ToolError::new( - e.code(), - format!("官方表单 fixture 解析失败: {}", e.message()), - ) - .field(FORM_FIXTURE) - })?; - let model = ModelSchema::from_str(&model_text).map_err(|e| { - ToolError::new( - e.code(), - format!("官方模型 fixture 解析失败: {}", e.message()), - ) - .field(MODEL_FIXTURE) - })?; - - Ok((form, model)) -} - -/// 🔴 **演练**:只看要建什么表,**不碰库**。 -/// -/// 🔴 **连数据库都不开** —— 演练的整个意义就是「什么都不发生」。 -/// 开库就意味着在数据目录里落一个临时 PG 实例(改磁盘状态)。 -pub fn preview_lowcode_demo(project_dir: &Path) -> Result { - let (form, model) = load_demo_fixture(project_dir)?; - let ddl = lowcode_ddl::preview_ddl(&model, &form)?; - - let planned: Vec = model - .tables - .iter() - .map(|t| t.table.to_lowercase()) - .collect(); - - Ok(SeedOutcome { - form_id: DEMO_ID.to_string(), - en_code: DEMO_EN_CODE.to_string(), - tables: planned, - skipped: Vec::new(), - ddl, - model: model.raw.clone(), - notes: vec!["dry-run:没有建表,也没有写库".to_string()], - dry_run: true, - }) -} - -/// 🔴 低代码示例功能种子(**开发档专用**)。 -/// -/// ## 执行顺序(顺序不能换) -/// -/// 1. 读官方 fixture(表单 + 模型); -/// 2. 先写 `base_visual_dev`(**用原始模型**)—— 因为建表后的回写要求这行已存在; -/// 3. `create_and_sync`:建表 + 回写 `f_tables_data`(含系统列); -/// 4. 写 `base_visual_release`(**用回写后的模型**)—— 发布快照与 dev 一致。 -pub async fn seed_lowcode_demo( - db: &Db, - project_dir: &Path, -) -> Result { - let (form, model) = load_demo_fixture(project_dir)?; - - // ---- DDL 预览(与真实执行用同一套生成规则)---- - let ddl = lowcode_ddl::preview_ddl(&model, &form)?; - - // ---- 1. 先写 dev 行(原始模型)---- - upsert_visual_row(db, "base_visual_dev", DEMO_ID, &form.raw.to_string(), &model.raw.to_string()) - .await?; - - // ---- 2. 建表 + 回写模型 ---- - let created = lowcode_ddl::create_and_sync(db, DEMO_ID, &model, &form, false).await?; - - // ---- 3. 写 release 行(**回写后**的模型 ⇒ 与 dev 一致)---- - let rewritten_text = serde_json::to_string(&created.model).map_err(|e| { - ToolError::new( - "MODEL_SERIALIZE_FAILED", - format!("回写后的模型序列化失败: {e}"), - ) - })?; - upsert_visual_row( - db, - "base_visual_release", - DEMO_ID, - &form.raw.to_string(), - &rewritten_text, - ) - .await?; - - let mut notes = created.notes.clone(); - notes.push(format!( - "功能定义已写入 base_visual_dev 与 base_visual_release(id={DEMO_ID}, enCode={DEMO_EN_CODE})" - )); - - Ok(SeedOutcome { - form_id: DEMO_ID.to_string(), - en_code: DEMO_EN_CODE.to_string(), - tables: created.tables, - skipped: created.skipped, - ddl, - model: created.model, - notes, - dry_run: false, - }) -} - -/// 🔴 写(插入或更新)一行低代码功能定义。 -/// -/// ## 🔴 幂等策略 -/// -/// 「先查存在性,再决定 INSERT 还是 UPDATE」—— -/// `Db::exec_params` **不返回影响行数**(pglite 0.2.7 没这个能力), -/// 所以不能用 `ON CONFLICT ... DO UPDATE`(那样也拿不到结果), -/// 只能先 `SELECT` 判存在。 -async fn upsert_visual_row( - db: &Db, - table: &str, - id: &str, - form_data: &str, - tables_data: &str, -) -> Result<(), ToolError> { - let exists = db - .query_json_params( - &format!("SELECT 1 AS \"x\" FROM {table} WHERE f_id = $1 LIMIT 1"), - &[&id.to_string()], - ) - .await - .map_err(db_err)?; - - if exists.is_empty() { - insert_visual_row(db, table, id, form_data, tables_data).await?; - } else { - update_visual_row(db, table, id, form_data, tables_data).await?; - } - Ok(()) -} - -/// 🔴 一行的**字段值**(与 [`VISUAL_COLUMNS`] 同序)。 -fn visual_row_values(id: &str, form_data: &str, tables_data: &str) -> Vec { - let now = now_iso(); - let url = format!("lowcode/{DEMO_EN_CODE}/index"); - vec![ - id.to_string(), - DEMO_FULL_NAME.to_string(), - DEMO_EN_CODE.to_string(), - "1".to_string(), // f_state:1 = 已发布 - "1".to_string(), // f_type:1 = 在线开发 - tables_data.to_string(), - form_data.to_string(), - "[]".to_string(), // f_column_data:列表列(空数组 = 不配列表页) - "2".to_string(), // f_web_type:2 = PC 端 - "[]".to_string(), // f_app_column_data - "0".to_string(), // f_enable_flow - "开发期种子生成的低代码示例功能".to_string(), - "1".to_string(), // f_enabled_mark - "0".to_string(), // f_sort_code - now.clone(), // f_creator_time - "admin".to_string(), - now.clone(), // f_last_modify_time - "admin".to_string(), - "0".to_string(), // f_delete_mark - TENANT_ID.to_string(), - url.clone(), - url, - "[]".to_string(), // f_button_data - MAIN_SYSTEM_ID.to_string(), - ] -} - -/// 🔴 插入一行低代码功能定义。 -async fn insert_visual_row( - db: &Db, - table: &str, - id: &str, - form_data: &str, - tables_data: &str, -) -> Result<(), ToolError> { - let values = visual_row_values(id, form_data, tables_data); - let cols: Vec<&str> = VISUAL_COLUMNS.iter().map(|(c, _)| *c).collect(); - let placeholders: Vec = VISUAL_COLUMNS - .iter() - .enumerate() - .map(|(i, (_, ty))| format!("${}::{}", i + 1, cast_for(ty))) - .collect(); - - let sql = format!( - "INSERT INTO {table} ({}) VALUES ({})", - cols.join(", "), - placeholders.join(", ") - ); - - let refs = build_params(&values); - db.exec_params(&sql, &refs).await.map_err(db_err)?; - Ok(()) -} - -/// 🔴 更新一行低代码功能定义(只改「这个功能真的用到」的列)。 -async fn update_visual_row( - db: &Db, - table: &str, - id: &str, - form_data: &str, - tables_data: &str, -) -> Result<(), ToolError> { - let values = visual_row_values(id, form_data, tables_data); - let now = now_iso(); - - // 🔴 列清单里除 `f_id` 外全部更新(`f_creator_*` 保持首次种下的值)。 - // 参数编号要与 `set_cols` 的顺序严格对应 ⇒ 按 `VISUAL_COLUMNS` 里的下标取。 - let mut params: Vec = Vec::new(); - let mut assignments: Vec = Vec::new(); - for (i, (col, ty)) in VISUAL_COLUMNS.iter().enumerate() { - if *col == "f_id" || *col == "f_creator_time" || *col == "f_creator_user_id" { - continue; - } - // 🔴 `f_last_modify_time` 用**当前**时间(其余值原样回填)。 - let value = if *col == "f_last_modify_time" { - now.clone() - } else { - values[i].clone() - }; - params.push(value); - assignments.push(format!("{col} = ${}::{}", params.len(), cast_for(ty))); - } - params.push(id.to_string()); - let id_pos = params.len(); - - let sql = format!( - "UPDATE {table} SET {} WHERE f_id = ${id_pos}::text", - assignments.join(", ") - ); - - let refs = build_params(¶ms); - db.exec_params(&sql, &refs).await.map_err(db_err)?; - Ok(()) -} - -/// 🔴 列类型标记 ⇒ SQL cast 片段。 -fn cast_for(kind: &str) -> &'static str { - match kind { - "int" => "text::integer", - "bigint" => "text::bigint", - "ts" => "text::timestamp", - _ => "text", - } -} - -/// 🔴 把参数向量转成可传给 `exec_params` 的引用数组。 -fn build_params(params: &[String]) -> Vec<&(dyn pglite::ToSql + Sync)> { - params - .iter() - .map(|s| s as &(dyn pglite::ToSql + Sync)) - .collect() -} - -/// 🔴 DB 错误转工具错误。 -fn db_err(e: pglite::Error) -> ToolError { - ToolError::new("DB_ERROR", format!("数据库错误:{e}")) - .hint("先确认数据库连接正常;这个错误通常来自 SQL 或连接配置") -} - -#[cfg(test)] -mod tests { - use super::*; - - /// 🔴 **开发档放行**。 - #[test] - fn dev_profile_is_allowed() { - assert!(seed_gate(Profile::Dev).is_ok()); - } - - /// 🔴 **生产档拒绝**(且要说得清为什么、怎么办)。 - #[test] - fn prod_profile_is_rejected_with_guidance() { - let err = seed_gate(Profile::Prod).unwrap_err(); - assert!(err.contains("SSW_PROFILE"), "报错要指明用哪个环境变量:{err}"); - assert!(err.contains("PGLITE_DIR"), "报错要提醒别指到生产库:{err}"); - } - - /// 🔴 闸门**只认档位**,不读环境变量 ⇒ 纯函数、可单测。 - #[test] - fn gate_depends_only_on_profile() { - assert!(seed_gate(Profile::from_env_str("dev")).is_ok()); - assert!(seed_gate(Profile::from_env_str("")).is_ok()); - assert!(seed_gate(Profile::from_env_str("prod")).is_err()); - assert!(seed_gate(Profile::from_env_str("PRODUCTION")).is_err()); - } - - /// 🔴 **列清单与字段值必须一一对应** —— 对不上会静默写错列。 - #[test] - fn column_list_matches_value_count() { - let values = visual_row_values("id", "form", "tables"); - assert_eq!( - VISUAL_COLUMNS.len(), - values.len(), - "VISUAL_COLUMNS 的长度变了 ⇒ 同步改 visual_row_values" - ); - } - - /// 🔴 **列清单的 id 列必须是第一列** —— `UPDATE` 靠这个下标排除它。 - #[test] - fn first_column_is_id() { - assert_eq!(VISUAL_COLUMNS[0].0, "f_id"); - } - - /// 🔴 cast 片段必须与列类型对得上(写错 ⇒ PG 类型错)。 - #[test] - fn cast_for_matches_column_kinds() { - assert_eq!(cast_for("text"), "text"); - assert_eq!(cast_for("int"), "text::integer"); - assert_eq!(cast_for("bigint"), "text::bigint"); - assert_eq!(cast_for("ts"), "text::timestamp"); - } - - /// 🔴 fixture 路径拼在**项目根**下(不依赖 cwd)。 - #[test] - fn fixture_path_is_under_project_root() { - let p = fixture_path(Path::new("/tmp/proj"), FORM_FIXTURE); - assert!(p.starts_with("/tmp/proj"), "{}", p.display()); - assert!(p.ends_with("sample_form.json"), "{}", p.display()); - } -} +pub use sspf_lowcode_exec::lowcode_seed::*;