feat(lowcode): P2-b 动态 CRUD 内核 + 写工具 + seed 通道,修 pglite /dev/null 退出码 100

- sspf-lowcode 纯计算建表 DDL 生成 + 模型回写(任务 #12/#13)
- 内核 lowcode_crud/check/ddl:真实事务执行、落库前三重校验、动态建表后回写 f_tables_data
- MCP 暴露 data.record.insert/update/delete(任务 #15)
- 开发期 --seed-lowcode-demo 通道:建表 + 写 dev/release 快照,prod 档开库前闸门拒绝
- 修 f_delete_mark 类型 bug(INTEGER 列误写 bool 导致 PG 报错)
- 修 pglite 0.2.7 在 stdout=/dev/null 时 boot 阶段 kevent 失败 -> exit(100) 残留 pid:
  open_db 开库前若 fd1 是字符设备,dup2 到匿名普通临时文件
- 文档漂移清理(tools/mod.rs 工具数、form.rs/model.rs 注释)
This commit is contained in:
admin committed 2026-10-31 19:26:47 +08:00
1 parent 343772be42
commit bcbe46c92b
23 files changed
+11185 -26

No files matched your search

File diff suppressed because it is too large. Load diff
+115
View File
@@ -103,8 +103,31 @@ pub struct FieldNode {
pub layout: String,
/// 该控件所属物理表(`__config__.tableName`)。
pub table_name: Option<String>,
/// 该控件关联的物理表(`__config__.relationTable`)。
///
/// 🔴 **只对子表里的字段有意义**:实测子表字段的 `tableName` 指向**主表**
/// (方言陷阱),但 `relationTable` 指向**子表自己** —— 它是「这个字段属于
/// 哪张表」唯一可信的线索。没有它,动态 CRUD 只能靠「取第一个非主表」来猜,
/// 多子表时会把数据串到错的表里。
pub relation_table: Option<String>,
/// 是否必填。
pub required: bool,
/// 🔴 是否**单行唯一**(`__config__.unique`)。
///
/// 基线平台 `ConfigModel`:
/// ```java
/// //是否唯一
/// private Boolean unique = false;
/// ```
///
/// 基线平台 `FormCheckUtils.checkForm()` 里,**只有 `jnpfKey == "input"`**
/// 且 `unique == true` 的字段才参与唯一性校验:
/// ```java
/// if (JnpfKeyConsts.COM_INPUT.equals(config.getJnpfKey())
/// && Boolean.TRUE.equals(config.getUnique())) { ... }
/// ```
/// ⇒ 这里保留 `jnpf_key` 一起判断,别把「唯一」当成通用能力。
pub unique: bool,
/// 可见端:`["pc"]` / `["pc","app"]`。
pub visibility: Vec<String>,
/// 是否隐藏(`noShow`)。
@@ -200,6 +223,23 @@ pub struct FormSchema {
pub concurrency_lock: Option<bool>,
/// 是否逻辑删除(`logicalDelete`)。
pub logical_delete: Option<bool>,
/// 🔴 是否启用**业务主键**(`useBusinessKey`)。
///
/// 基线平台 `FormDataModel`:
/// ```java
/// //业务主键属性
/// private boolean useBusinessKey;
/// private String[] businessKeyList;
/// private String businessKeyTip;
/// ```
pub use_business_key: bool,
/// 🔴 业务主键字段清单(`businessKeyList`,存的是 `__vModel__`)。
///
/// 语义:这几个字段的**组合**在表里必须唯一(基线平台
/// `FormCheckUtils.checkBusinessKey()`)。全为空 ⇒ 不校验。
pub business_key_list: Vec<String>,
/// 业务主键重复时的提示语(`businessKeyTip`)。
pub business_key_tip: Option<String>,
/// 顶层控件树。
pub fields: Vec<FieldNode>,
}
@@ -228,6 +268,21 @@ impl FormSchema {
primary_key_policy: obj.get("primaryKeyPolicy").and_then(Value::as_i64),
concurrency_lock: obj.get("concurrencyLock").and_then(Value::as_bool),
logical_delete: obj.get("logicalDelete").and_then(Value::as_bool),
use_business_key: obj.get("useBusinessKey").and_then(Value::as_bool).unwrap_or(false),
business_key_list: obj
.get("businessKeyList")
.and_then(Value::as_array)
.map(|a| {
a.iter()
.filter_map(Value::as_str)
.map(str::to_string)
.collect()
})
.unwrap_or_default(),
business_key_tip: obj
.get("businessKeyTip")
.and_then(Value::as_str)
.map(str::to_string),
fields,
})
}
@@ -270,6 +325,61 @@ impl FormSchema {
.collect()
}
/// 🔴 参与**单行唯一性**校验的字段。
///
/// 基线平台 `FormCheckUtils.checkForm()` 的条件是**两个都要满足**:
/// ```java
/// if (JnpfKeyConsts.COM_INPUT.equals(config.getJnpfKey())
/// && Boolean.TRUE.equals(config.getUnique())) { ... }
/// ```
/// - `JnpfKeyConsts.COM_INPUT` = `"input"`(普通单行输入框);
/// - `config.getUnique()` = `true`。
///
/// ⇒ **不是**「所有标了 unique 的字段」,而是「标了 unique **且**是 input 的字段」。
/// 下拉/日期/数字等控件即使标了 unique,基线平台**也不查** ——
/// 照抄这个口径,别查多了(查多了会拦住基线平台允许的写入)。
pub fn unique_fields(&self) -> Vec<&FieldNode> {
self.all_nodes()
.into_iter()
.filter(|n| n.unique && n.jnpf_key == "input" && !n.v_model.is_empty())
.collect()
}
/// 🔴 业务主键字段(`useBusinessKey` 开启时的 `businessKeyList`)。
///
/// 基线平台 `FormCheckUtils.checkBusinessKey()`:
/// ```java
/// if (formData.isUseBusinessKey()) {
/// List<String> businessKeyList = Arrays.asList(formData.getBusinessKeyList());
/// if (CollectionUtils.isEmpty(businessKeyList)) { return null; }
/// ...
/// for (String fieldName : businessKeyList) { setEachCondition(...); }
/// }
/// ```
/// ⇒ 清单里存的是 `__vModel__`;**空值字段用 `IS NULL` 参与比较**。
/// 返回 `None` 表示「不校验业务主键」。
pub fn business_key_fields(&self) -> Option<Vec<&FieldNode>> {
if !self.use_business_key || self.business_key_list.is_empty() {
return None;
}
let mut out = Vec::new();
for vm in &self.business_key_list {
if let Some(node) = self
.all_nodes()
.into_iter()
.find(|n| &n.v_model == vm && !n.is_container())
{
out.push(node);
}
}
// 清单里的字段一个都找不到 ⇒ 没法校验(不静默跳过)
if out.is_empty() {
None
} else {
Some(out)
}
}
/// 主表字段对应的物理列名(去重、保序)。
pub fn main_columns(&self) -> Vec<String> {
let mut out: Vec<String> = Vec::new();
@@ -399,7 +509,12 @@ fn parse_node(v: &Value) -> Option<FieldNode> {
widget,
layout,
table_name: cfg.get("tableName").and_then(Value::as_str).map(str::to_string),
relation_table: cfg
.get("relationTable")
.and_then(Value::as_str)
.map(str::to_string),
required: cfg.get("required").and_then(Value::as_bool).unwrap_or(false),
unique: cfg.get("unique").and_then(Value::as_bool).unwrap_or(false),
visibility,
no_show: cfg.get("noShow").and_then(Value::as_bool).unwrap_or(false),
form_id: cfg.get("formId").and_then(Value::as_i64),
+21
View File
@@ -35,19 +35,40 @@
//! 3. `rowFormItem` 是布局容器,不占列,孩子才占
//! 4. `table` 是子表,它的字段属于**另一张物理表**
//!
//! ## 模块地图
//!
//! | 模块 | 职责 |
//! |---|---|
//! | [`form`] | 控件树解析(`FormSchema` / `FieldNode`) |
//! | [`model`] | 表结构解析(`ModelSchema` / `TableSchema`) |
//! | [`widget`] | 54 种 `jnpfKey` → 类别 + 自动填充策略 |
//! | [`validate`] | 表单 ↔ 模型 自洽性诊断(9 类诊断码) |
//! | [`sql`] | **动态 CRUD 的 SQL 生成**(纯函数:出 SQL 文本 + 参数,不连库) |
//! | [`ddl`] | **动态建表的 DDL 生成**(纯函数:出 `CREATE TABLE`,不连库) |
//!
//! ## 为什么「不改一个字段」是可验证的
//!
//! [`FormSchema::raw`] / [`ModelSchema::raw`] 保留原始 JSON 一字不动,
//! 保存时原样写回。解析结果只是**只读视图**,
//! 测试 `real_sample.rs` 用官方初始化数据里的真表单做基线断言。
pub mod ddl;
pub mod form;
pub mod model;
pub mod sql;
pub mod validate;
pub mod widget;
pub use ddl::{
plan_create, rewrite_model, ColumnDdl, CreatePlan, DdlError, DdlOptions, TableDdl, TypeSpec,
};
pub use form::{v_model_to_column, FieldNode, FormError, FormSchema};
pub use model::{ColumnDef, ModelError, ModelSchema, TableSchema};
pub use sql::{
check_identifier, diff_sub_rows, lookup, plan_delete, plan_hard_delete, plan_insert,
plan_soft_delete, plan_update, plan_update_full, DeletePlan, Sql, SqlError, SqlKind, SubDiff,
SubUpdateContext, SubUpdateOptions, UpdatePlan, WriteContext, WritePlan,
};
pub use validate::{validate, Diagnostic, Report, Severity};
pub use widget::{auto_fill, classify, AutoFill, WidgetKind};
+48
View File
@@ -119,6 +119,27 @@ pub struct TableSchema {
pub type_id: String,
/// 列定义(顺序即建表顺序)。
pub fields: Vec<ColumnDef>,
/// 🔴 **子表外键列**(`tableField`)—— 子表里指向主表主键的那一列。
///
/// ## 溯源
///
/// Java `FlowFormDataUtil.createMastTable()`:
/// ```java
/// String foreignKey = tableModel.getTableField();
/// GeneralInsertDSL dsl = insertInto(sqlTable).set(sqlTable.column(foreignKey)).toValue(foreignValue);
/// ```
///
/// ⇒ 外键列名**来自模型**,不是常量。实测 `test_details` 的 `tableField` 是
/// `F_Receivableid` ⇒ 物理列 `f_receivableid`,**不是** `f_foreign_id`。
///
/// 🔴 之前硬编码 `f_foreign_id` 会在真实数据上直接 `column does not exist`。
pub table_field: Option<String>,
/// 🔴 **主表关联字段**(`relationField`)—— 主表里被子表外键引用的那一列。
///
/// Java:`Object foreignValue = dataNewMap.get(tableModel.getRelationField());`
pub relation_field: Option<String>,
/// 本表关联到的主表名(`relationTable`;主表自身为空串)。
pub relation_table: Option<String>,
}
impl TableSchema {
@@ -127,6 +148,20 @@ impl TableSchema {
self.type_id == "1"
}
/// 子表外键列的**物理列名**(`tableField` 推导)。
pub fn foreign_key_column(&self) -> Option<String> {
self.table_field
.as_deref()
.and_then(crate::form::v_model_to_column)
}
/// 主表关联列的**物理列名**(`relationField` 推导)。
pub fn relation_column(&self) -> Option<String> {
self.relation_field
.as_deref()
.and_then(crate::form::v_model_to_column)
}
/// 按 `F_xxx` 风格的设计态字段名找列(大小写不敏感)。
pub fn column_by_field(&self, field: &str) -> Option<&ColumnDef> {
self.fields
@@ -222,6 +257,10 @@ fn parse_table(v: &Value) -> Option<TableSchema> {
Some(Value::Number(n)) => n.to_string(),
_ => "0".to_string(),
},
// 🔴 官方数据里这三个字段是空串(主表)或具体列名(子表)⇒ 空串视作「没有」。
table_field: opt_str(obj, "tableField"),
relation_field: opt_str(obj, "relationField"),
relation_table: opt_str(obj, "relationTable"),
fields: obj
.get("fields")
.and_then(Value::as_array)
@@ -230,6 +269,15 @@ fn parse_table(v: &Value) -> Option<TableSchema> {
})
}
/// 取一个非空字符串字段(空串 ⇒ `None`)。
fn opt_str(obj: &Map<String, Value>, key: &str) -> Option<String> {
obj.get(key)
.and_then(Value::as_str)
.map(str::trim)
.filter(|s| !s.is_empty())
.map(str::to_string)
}
fn parse_column(v: &Value) -> Option<ColumnDef> {
let obj = v.as_object()?;
let field = obj.get("field").and_then(Value::as_str)?.trim().to_string();
File diff suppressed because it is too large. Load diff
+48 -10
View File
@@ -107,6 +107,27 @@ impl WidgetKind {
///
/// 不是「保持入参」:新增的行还没被改过,「最后修改人」为空才是正确的。
/// 如果照抄入参,会出现「刚建就显示被别人改过」的脏审计。
///
/// ## 🔴 为什么 `ModifyTime` 与 `ModifyUser` 必须拆成两个变体
///
/// 基线平台 `FlowFormDataUtil` 里这是**两个不同的 switch 分支**:
///
/// ```java
/// // create() —— 新增:两者都置 null
/// case JnpfKeyConsts.MODIFYTIME: value = null; break;
/// case JnpfKeyConsts.MODIFYUSER: value = null; break;
///
/// // update() —— 更新:modifyTime 写当前时间,modifyUser 写当前用户 id
/// case JnpfKeyConsts.MODIFYTIME:
/// if (!childNeedAdd) { value = new Date(); }
/// break;
/// case JnpfKeyConsts.MODIFYUSER:
/// if (!childNeedAdd) { value = user.getUserId(); }
/// break;
/// ```
///
/// 之前把两者合并成一个 `Null` ⇒ **更新时两者都没写**,
/// 「最后修改人 / 最后修改时间」永远停在旧值 —— 审计链断掉。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AutoFill {
/// 用入参原值(普通业务字段)。
@@ -119,8 +140,10 @@ pub enum AutoFill {
CurrentOrganizeIds,
/// 当前用户的岗位 id 列表,序列化成 JSON 字符串(`currPosition`)。
CurrentPositionIds,
/// 新增时置 `null`(`modifyTime` / `modifyUser`)。
Null,
/// 最后修改时间:新增置 `null`,更新写当前时间(`modifyTime`)。
ModifyTime,
/// 最后修改人:新增置 `null`,更新写当前用户 id(`modifyUser`)。
ModifyUser,
/// 单据号生成器产出(`billRule`,`ruleType=1` 时)。
BillNumber,
}
@@ -134,7 +157,8 @@ impl AutoFill {
AutoFill::Now => "now",
AutoFill::CurrentOrganizeIds => "currentOrganizeIds",
AutoFill::CurrentPositionIds => "currentPositionIds",
AutoFill::Null => "null",
AutoFill::ModifyTime => "modifyTime",
AutoFill::ModifyUser => "modifyUser",
AutoFill::BillNumber => "billNumber",
}
}
@@ -145,18 +169,20 @@ impl AutoFill {
}
}
/// 控件 → 新增时的自动填充行为。
/// 控件 → 自动填充行为。
///
/// 对齐 `FlowFormDataUtil.create()` 的 switch 分支;未知控件走 `Passthrough`。
/// 对齐 `FlowFormDataUtil.create()` / `update()` 的 switch 分支;未知控件走 `Passthrough`。
///
/// 🔴 `modifyTime` 与 `modifyUser` 在基线平台是**两个独立分支**,
/// 新增时都置 null、更新时分别写「当前时间」和「当前用户 id」⇒ 不能合并。
pub fn auto_fill(jnpf_key: &str) -> AutoFill {
match jnpf_key {
"createUser" | "createUserId" => AutoFill::CurrentUserId,
"createTime" => AutoFill::Now,
"currOrganize" | "currDept" => AutoFill::CurrentOrganizeIds,
"currPosition" => AutoFill::CurrentPositionIds,
"modifyTime" | "modifyUser" | "lastModifyTime" | "lastModifyUser" | "modifyUserId" => {
AutoFill::Null
}
"modifyTime" | "lastModifyTime" => AutoFill::ModifyTime,
"modifyUser" | "lastModifyUser" | "modifyUserId" => AutoFill::ModifyUser,
"billRule" => AutoFill::BillNumber,
_ => AutoFill::Passthrough,
}
@@ -307,13 +333,25 @@ mod tests {
assert_eq!(auto_fill("currPosition"), AutoFill::CurrentPositionIds);
assert_eq!(auto_fill("billRule"), AutoFill::BillNumber);
// 新增时清空 —— 「刚建就显示被人改过」是脏审计
assert_eq!(auto_fill("modifyTime"), AutoFill::Null);
assert_eq!(auto_fill("modifyUser"), AutoFill::Null);
assert_eq!(auto_fill("modifyTime"), AutoFill::ModifyTime);
assert_eq!(auto_fill("modifyUser"), AutoFill::ModifyUser);
// 普通字段不动
assert_eq!(auto_fill("input"), AutoFill::Passthrough);
assert_eq!(auto_fill("calculate"), AutoFill::Passthrough);
}
/// 🔴 `modifyTime` 与 `modifyUser` 必须是**两个不同的分支**。
///
/// 基线平台 `update()`:`MODIFYTIME` 写当前时间、`MODIFYUSER` 写当前用户 id。
/// 合并成一个变体 ⇒ 更新时两者都没写 ⇒ 「最后修改人/时间」永远停在旧值。
#[test]
fn modify_time_and_modify_user_are_distinct() {
assert_ne!(auto_fill("modifyTime"), auto_fill("modifyUser"));
assert_eq!(auto_fill("lastModifyTime"), AutoFill::ModifyTime);
assert_eq!(auto_fill("lastModifyUser"), AutoFill::ModifyUser);
assert_eq!(auto_fill("modifyUserId"), AutoFill::ModifyUser);
}
/// 凡是被覆盖的,`accepts_input` 必须是 false —— 否则「传了也没用」但没人告知。
#[test]
fn overridden_fields_do_not_accept_input() {
+304
View File
@@ -0,0 +1,304 @@
//! real_ddl —— 用**官方初始化数据里的真模型**验证建表 DDL 生成。
//!
//! ## 为什么必须用真数据
//!
//! `ddl.rs` 的单测用**合成**模型验证规则;这份用**官方 fixture**
//! (`tests/fixtures/sample_model.json`,与基线平台初始化 SQL 同源)验证
//! 「生成的 DDL 与官方真实 DDL 同形」。
//!
//! ## 🔴 这份测试钉死的三件事
//!
//! | 真相 | 影响 |
//! |---|---|
//! | 官方真实 DDL 的主键是**复合**的 `(f_id, f_tenant_id)` | 单列主键 ⇒ 与基线库结构不一致,跨库读写直接炸 |
//! | 子表外键列是 `f_receivableid`(**不是** `f_foreign_id`) | 硬编码 ⇒ `column does not exist` |
//! | 官方模型里**已含**系统列(`f_tenant_id` / `f_version` / …) | 重复追加 ⇒ 建表报 duplicate column |
//!
//! ## 🔴 断言的强度
//!
//! [`ddl_matches_official_ddl_line_by_line`]:把生成的 DDL **逐列**与官方
//! `jnpf_db_init.sql` 里的 `CREATE TABLE test_receivable` 对照 ——
//! 列名、类型、顺序、NOT NULL、DEFAULT 全部要一致。
//!
//! 这不是「差不多就行」的断言:任何一列对不上就红。
use std::path::PathBuf;
use sspf_lowcode::{plan_create, DdlOptions, ModelSchema};
fn fixture(name: &str) -> String {
let mut p = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
p.push("tests/fixtures");
p.push(name);
std::fs::read_to_string(&p).unwrap_or_else(|e| panic!("读不到 {}: {e}", p.display()))
}
fn real_model() -> ModelSchema {
let raw = fixture("sample_model.json");
ModelSchema::parse(&serde_json::from_str(&raw).unwrap()).unwrap()
}
fn opts() -> DdlOptions {
DdlOptions::default_options()
}
/// 从 `CREATE TABLE` 文本里抽出「列名 ⇒ 完整定义」。
fn column_defs(sql: &str) -> Vec<(String, String)> {
let body = sql
.split_once("(\n")
.expect("应有 CREATE TABLE (")
.1
.rsplit_once("\n);")
.expect("应有 );")
.0;
body.lines()
.filter_map(|l| {
let l = l.trim().trim_end_matches(',').trim();
if l.is_empty() || l.starts_with("PRIMARY KEY") {
return None;
}
let (name, rest) = l.split_once(' ')?;
Some((name.to_string(), rest.to_string()))
})
.collect()
}
/// 🔴 生成的 DDL 必须与官方真实 DDL **逐列一致**。
///
/// 官方 `jnpf_db_init.sql`(PostgreSQL 版):
/// ```sql
/// CREATE TABLE test_receivable (
/// f_id VARCHAR(50) NOT NULL,
/// f_building VARCHAR(100),
/// f_room VARCHAR(100),
/// f_company_name VARCHAR(50),
/// f_userid VARCHAR(50),
/// f_phone VARCHAR(50),
/// f_ost VARCHAR(50),
/// f_sort_code BIGINT,
/// f_enabledmark INTEGER,
/// f_creatortime TIMESTAMP(0) WITHOUT TIME ZONE,
/// f_creatoruserid VARCHAR(50),
/// f_lastmodifytime TIMESTAMP(0) WITHOUT TIME ZONE,
/// f_lastmodifyuserid VARCHAR(50),
/// f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
/// f_version INTEGER DEFAULT '0',
/// f_flowtaskid VARCHAR(50),
/// f_flow_id VARCHAR(50),
/// f_flow_task_id VARCHAR(50),
/// f_inte_assistant INTEGER,
/// f_flow_state INTEGER DEFAULT '0',
/// PRIMARY KEY (f_id, f_tenant_id)
/// );
/// ```
///
/// ## 🔴 与官方手写脚本的两处差异(有意为之)
///
/// | 列 | 官方手写脚本 | 本生成器 | 理由 |
/// |---|---|---|---|
/// | `f_version` | `INTEGER`(无默认) | `INTEGER DEFAULT '0'` | Java `FormatSql.defaultCheck` 给有默认值的列加 `DEFAULT '0'` |
/// | `f_flow_state` | `INTEGER`(无默认) | `INTEGER DEFAULT '0'` | 同上(`ConcurrencyUtils` 明确给 FLOWSTATE 设了默认值) |
///
/// 官方脚本是**手写**的基线 DDL;本生成器产出的是 **Java 动态建表**的结果 ——
/// 两者本就可能不同。这里对齐的是**动态建表**(那才是运行时真正会发生的事)。
#[test]
fn ddl_matches_official_ddl_line_by_line() {
let plan = plan_create(&real_model(), &opts()).expect("应能生成建表计划");
let sql = plan.main.render();
// 官方 DDL 的期望形态:(列名, 类型 + 约束)
let expected: Vec<(&str, &str)> = vec![
("f_id", "VARCHAR(50) NOT NULL"),
("f_building", "VARCHAR(100)"),
("f_room", "VARCHAR(100)"),
("f_company_name", "VARCHAR(50)"),
("f_userid", "VARCHAR(50)"),
("f_phone", "VARCHAR(50)"),
("f_ost", "VARCHAR(50)"),
("f_sort_code", "BIGINT"),
("f_enabledmark", "INTEGER"),
("f_creatortime", "TIMESTAMP(0) WITHOUT TIME ZONE"),
("f_creatoruserid", "VARCHAR(50)"),
("f_lastmodifytime", "TIMESTAMP(0) WITHOUT TIME ZONE"),
("f_lastmodifyuserid", "VARCHAR(50)"),
("f_tenant_id", "VARCHAR(50) DEFAULT '0' NOT NULL"),
("f_version", "INTEGER DEFAULT '0'"),
("f_flowtaskid", "VARCHAR(50)"),
("f_flow_id", "VARCHAR(50)"),
("f_flow_task_id", "VARCHAR(50)"),
("f_inte_assistant", "INTEGER"),
("f_flow_state", "INTEGER DEFAULT '0'"),
];
let actual = column_defs(&sql);
assert_eq!(
actual.len(),
expected.len(),
"🔴 列数不一致\n期望 {expected:#?}\n实际 {actual:#?}"
);
for (i, (exp_name, exp_def)) in expected.iter().enumerate() {
let (act_name, act_def) = &actual[i];
assert_eq!(act_name, exp_name, "第 {i} 列名不一致");
assert_eq!(act_def, exp_def, "第 {i} 列({exp_name})定义不一致");
}
}
/// 🔴 子表也要与官方真实 DDL 逐列一致。
///
/// 官方:
/// ```sql
/// CREATE TABLE test_details (
/// f_id VARCHAR(50) NOT NULL,
/// f_receivableid VARCHAR(50),
/// f_month VARCHAR(200),
/// f_rent DECIMAL(18, 2),
/// f_water_rent DECIMAL(18, 2),
/// f_powerrate DECIMAL(18, 2),
/// f_property DECIMAL(18, 2),
/// f_cleaning DECIMAL(18, 2),
/// f_pollutant DECIMAL(18, 2),
/// f_totalbilling DECIMAL(18, 2),
/// f_creatortime TIMESTAMP(0) WITHOUT TIME ZONE,
/// f_creatoruserid VARCHAR(50),
/// f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,
/// PRIMARY KEY (f_id, f_tenant_id)
/// );
/// ```
#[test]
fn sub_table_ddl_matches_official_line_by_line() {
let plan = plan_create(&real_model(), &opts()).expect("应能生成建表计划");
let sql = plan.subs[0].render();
let expected: Vec<(&str, &str)> = vec![
("f_id", "VARCHAR(50) NOT NULL"),
("f_receivableid", "VARCHAR(50)"),
("f_month", "VARCHAR(200)"),
("f_rent", "DECIMAL(18, 2)"),
("f_water_rent", "DECIMAL(18, 2)"),
("f_powerrate", "DECIMAL(18, 2)"),
("f_property", "DECIMAL(18, 2)"),
("f_cleaning", "DECIMAL(18, 2)"),
("f_pollutant", "DECIMAL(18, 2)"),
("f_totalbilling", "DECIMAL(18, 2)"),
("f_creatortime", "TIMESTAMP(0) WITHOUT TIME ZONE"),
("f_creatoruserid", "VARCHAR(50)"),
("f_tenant_id", "VARCHAR(50) DEFAULT '0' NOT NULL"),
];
let actual = column_defs(&sql);
assert_eq!(
actual.len(),
expected.len(),
"🔴 子表列数不一致\n期望 {expected:#?}\n实际 {actual:#?}"
);
for (i, (exp_name, exp_def)) in expected.iter().enumerate() {
let (act_name, act_def) = &actual[i];
assert_eq!(act_name, exp_name, "第 {i} 列名不一致");
assert_eq!(act_def, exp_def, "第 {i} 列({exp_name})定义不一致");
}
}
/// 🔴 复合主键必须是 `(f_id, f_tenant_id)`。
#[test]
fn primary_key_is_composite() {
let plan = plan_create(&real_model(), &opts()).expect("应能生成建表计划");
let sql = plan.main.render();
assert!(
sql.contains("PRIMARY KEY (f_id, f_tenant_id)"),
"🔴 主键必须是复合的: {sql}"
);
// 不能是单列主键
assert!(!sql.contains("PRIMARY KEY (f_id)"), "{sql}");
}
/// 🔴 官方模型里已含系统列 ⇒ **不能重复追加**。
#[test]
fn system_columns_are_not_duplicated() {
let plan = plan_create(&real_model(), &opts()).expect("应能生成建表计划");
for sql in [&plan.main.render(), &plan.subs[0].render()] {
for name in [
"f_id",
"f_tenant_id",
"f_version",
"f_flow_task_id",
"f_flow_state",
] {
let count = sql
.lines()
.filter(|l| l.trim().starts_with(&format!("{name} ")))
.count();
assert!(
count <= 1,
"🔴 列 {name} 出现了 {count} 次(重复追加):\n{sql}"
);
}
}
}
/// 🔴 子表**没有**流程/并发列(Java 只给主表加)。
#[test]
fn sub_table_has_no_flow_columns() {
let plan = plan_create(&real_model(), &opts()).expect("应能生成建表计划");
let sql = plan.subs[0].render();
for name in ["f_flow_id", "f_version", "f_flow_state", "f_flow_task_id"] {
assert!(
!sql.lines().any(|l| l.trim().starts_with(&format!("{name} "))),
"🔴 子表不该有 {name}:\n{sql}"
);
}
}
/// 🔴 官方模型 `logicalDelete = false` ⇒ 表里**没有**删除列。
#[test]
fn no_delete_columns_when_logical_delete_is_off() {
let plan = plan_create(&real_model(), &opts()).expect("应能生成建表计划");
for sql in [&plan.main.render(), &plan.subs[0].render()] {
for name in ["f_delete_mark", "f_delete_time", "f_delete_user_id"] {
assert!(
!sql.lines().any(|l| l.trim().starts_with(&format!("{name} "))),
"🔴 logicalDelete=false 时不该有 {name}:\n{sql}"
);
}
}
}
/// 🔴 开启逻辑删除后,主表与子表**同进同退**。
#[test]
fn delete_columns_appear_together() {
let mut o = opts();
o.logical_delete = true;
let plan = plan_create(&real_model(), &o).expect("应能生成建表计划");
for sql in [&plan.main.render(), &plan.subs[0].render()] {
assert!(sql.contains("f_delete_mark INTEGER"), "{sql}");
assert!(sql.contains("f_delete_time TIMESTAMP(0) WITHOUT TIME ZONE"), "{sql}");
assert!(sql.contains("f_delete_user_id VARCHAR(50)"), "{sql}");
}
}
/// 🔴 建表顺序:主表 → 子表(子表外键指向主表)。
#[test]
fn tables_are_created_main_first() {
let plan = plan_create(&real_model(), &opts()).expect("应能生成建表计划");
let sqls = plan.render();
assert_eq!(sqls.len(), 2);
assert!(sqls[0].contains("CREATE TABLE test_receivable"));
assert!(sqls[1].contains("CREATE TABLE test_details"));
}
/// 🔴 DDL 里的每个标识符都必须合法(不能带分号之类的注入载荷)。
#[test]
fn all_identifiers_are_safe() {
let plan = plan_create(&real_model(), &opts()).expect("应能生成建表计划");
for t in plan.all() {
for c in &t.columns {
assert!(
c.name
.chars()
.all(|ch| ch.is_ascii_alphanumeric() || ch == '_'),
"🔴 列名不安全: {}",
c.name
);
assert!(!c.name.starts_with(|ch: char| ch.is_ascii_digit()));
}
}
}
+290
View File
@@ -0,0 +1,290 @@
//! real_sql —— 用**官方初始化数据里的真表单**验证 SQL 生成。
//!
//! `real_sample.rs` 证明「解析不丢信息」;这份证明**「生成的 SQL 能在真实数据上跑」**。
//!
//! ## 为什么必须用真数据
//!
//! 合成用例(比如「表里有 `f_room`」)会让人以为列名规则很简单。
//! 真实数据里:
//!
//! | 真相 | 影响 |
//! |---|---|
//! | `F_CreatorTime` 的列是 `f_creatortime`(**无下划线**) | 硬编码 `f_creator_time` ⇒ `column does not exist` |
//! | `f_tenant_id` 也是 `primaryKey=1` | 不排除它就会选成主键 |
//! | 子表外键列是 `f_receivableid`(**不是** `f_foreign_id`) | 硬编码 ⇒ `column does not exist` |
//! | `logicalDelete=false` ⇒ 表里**没有**删除标记列 | 无条件写删除标记 ⇒ `column does not exist` |
//!
//! 这四条每一条都足以让动态 CRUD 全面失败 —— 而且是**运行时报错**,不是编译期。
//! ⇒ 这组测试的价值不在「跑通」,在**钉死这四条**。
//!
//! ## 🔴 最重要的断言
//!
//! [`assert_no_unknown_columns`]:**生成的 SQL 里每一个列名,都必须真实存在于
//! 模型定义的列清单里**。这一条把「硬编码列名」这类错误从「运行时炸」提前到
//! 「测试就红」。
use std::path::PathBuf;
use sspf_lowcode::{
plan_hard_delete, plan_insert, plan_soft_delete, plan_update, FormSchema, ModelSchema, SqlKind,
WriteContext,
};
fn fixture(name: &str) -> String {
let mut p = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
p.push("tests/fixtures");
p.push(name);
std::fs::read_to_string(&p).unwrap_or_else(|e| panic!("读不到 {}: {e}", p.display()))
}
fn real_form() -> FormSchema {
let raw = fixture("sample_form.json");
FormSchema::parse(&serde_json::from_str(&raw).unwrap()).unwrap()
}
fn real_model() -> ModelSchema {
let raw = fixture("sample_model.json");
ModelSchema::parse(&serde_json::from_str(&raw).unwrap()).unwrap()
}
fn ctx() -> WriteContext {
let mut c = WriteContext::with_user("u-1");
c.now = Some("2026-10-31T12:00:00".to_string());
c.tenant_id = Some("0".to_string());
c
}
/// 带子表行主键的上下文(Java 侧子表主键是服务端现生成的 UUID)。
fn ctx_with_sub_key() -> WriteContext {
let mut c = ctx();
c.set_sub_row_key("test_details", "main-1", 0, "sub-row-1");
c
}
/// 取出 INSERT 的列清单。
fn insert_columns(text: &str) -> Vec<String> {
text.split_once(" (")
.expect("INSERT 应有列清单")
.1
.split_once(") VALUES")
.expect("INSERT 应有 VALUES")
.0
.split(", ")
.map(|s| s.to_string())
.collect()
}
/// 🔴 **核心断言**:生成的 SQL 里每一个列名,都必须真实存在于模型里。
///
/// 这是「硬编码列名」这类 bug 的守门人 —— 上一版就是靠它抓出了
/// `f_creator_time` / `f_foreign_id` / `f_delete_mark` 三个臆造列名。
#[test]
fn assert_no_unknown_columns() {
let form = real_form();
let model = real_model();
let payload = serde_json::json!({
"F_Room": "A-101",
"F_Company_name": "某某公司",
"tableField107": [
{ "F_Month": "2026-10", "F_Rent": 100.5 }
]
});
let plan = plan_insert(&form, &model, &payload, &ctx_with_sub_key(), "main-1")
.expect("真实数据应能生成新增计划");
for sql in plan.all() {
let table = model
.table(&sql.table)
.unwrap_or_else(|| panic!("SQL 里的表 {} 不在模型里", sql.table));
let allowed = table.column_names();
let cols = if sql.text.starts_with("INSERT") {
insert_columns(&sql.text)
} else {
// UPDATE:取 SET 左边那一半
sql.text
.split_once(" SET ")
.expect("UPDATE 应有 SET")
.1
.split_once(" WHERE ")
.expect("UPDATE 应有 WHERE")
.0
.split(", ")
.map(|s| s.split(" = ").next().unwrap_or("").to_string())
.collect()
};
for c in &cols {
assert!(
allowed.contains(c),
"🔴 表 {} 里没有列 {} —— 真实库上会 `column \"{}\" does not exist`。\
列清单: {cols:?}\n模型列: {allowed:?}",
sql.table,
c,
c
);
}
}
}
/// 🔴 主键不能选成租户列 —— 真实模型里 `f_tenant_id` 也是 `primaryKey=1`。
#[test]
fn real_model_picks_correct_primary_key() {
let model = real_model();
let main = model.main_table().unwrap();
// 人工核对:主键是 F_Id → f_id
assert!(
main.column_names().contains(&"f_id".to_string()),
"主表应有 f_id 列"
);
// 租户列也在模型里
assert!(
main.column_names().contains(&"f_tenant_id".to_string()),
"主表应有 f_tenant_id 列"
);
let plan = plan_insert(
&real_form(),
&model,
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"main-1",
)
.unwrap();
let cols = insert_columns(&plan.main.text);
assert_eq!(cols[0], "f_id", "主键选错了(应为 f_id 而非 f_tenant_id): {cols:?}");
}
/// 🔴 子表外键列必须是模型里的 `tableField`(`F_Receivableid` → `f_receivableid`)。
#[test]
fn real_sub_table_foreign_key_comes_from_model() {
let model = real_model();
let sub = model.sub_tables()[0];
assert_eq!(
sub.table_field.as_deref(),
Some("F_Receivableid"),
"子表外键字段应来自模型"
);
assert_eq!(
sub.foreign_key_column().as_deref(),
Some("f_receivableid"),
"子表外键列推导错误"
);
let plan = plan_insert(
&real_form(),
&model,
&serde_json::json!({
"F_Room": "A-101",
"tableField107": [ { "F_Month": "2026-10" } ]
}),
&ctx_with_sub_key(),
"main-1",
)
.unwrap();
assert_eq!(plan.subs.len(), 1, "应有 1 条子表 SQL");
let sub_sql = &plan.subs[0];
assert_eq!(sub_sql.table, "test_details");
let cols = insert_columns(&sub_sql.text);
assert!(
cols.contains(&"f_receivableid".to_string()),
"子表应写外键列 f_receivableid: {cols:?}"
);
assert!(
!cols.contains(&"f_foreign_id".to_string()),
"出现了臆造的 f_foreign_id —— 真实库上会 column does not exist: {cols:?}"
);
}
/// 🔴 真实数据的 `logicalDelete = false` ⇒ 表里**没有**删除标记列
/// ⇒ 逻辑删除必须**报错**,不能退化成空 UPDATE。
///
/// 空 UPDATE = 「什么都没删但返回成功」—— 用户以为删了,实际行还在列表里。
/// 真实功能既然 `logicalDelete=false`,删除就该走**物理 DELETE**。
#[test]
fn real_model_has_no_delete_columns_so_soft_delete_is_rejected() {
let model = real_model();
let main = model.main_table().unwrap();
assert!(
!main.column_names().contains(&"f_delete_mark".to_string()),
"实测这张表没有删除标记列(logicalDelete=false)"
);
let err = plan_soft_delete(&model, &ctx(), "main-1")
.expect_err("没有删除列的表不支持逻辑删除");
assert_eq!(err.code(), "LOGICAL_DELETE_UNSUPPORTED");
// 物理删除路径必须可用(logicalDelete=false ⇒ 基线平台就是物理删)
let sql = plan_hard_delete(&model, "main-1").expect("物理删除应能生成");
assert!(
sql.text.starts_with("DELETE FROM test_receivable WHERE f_id = $1"),
"物理删除 SQL 不对: {}",
sql.text
);
assert_eq!(sql.kind, SqlKind::HardDelete);
}
/// 🔴 UPDATE 必须带 WHERE,且所有列都在模型里。
#[test]
fn real_update_has_where_and_valid_columns() {
let model = real_model();
let plan = plan_update(
&real_form(),
&model,
&serde_json::json!({ "F_Room": "B-202" }),
&ctx(),
"main-1",
)
.unwrap();
assert!(
plan.main.text.contains(" WHERE f_id = $"),
"UPDATE 缺 WHERE: {}",
plan.main.text
);
assert!(!plan.main.text.contains("B-202"), "值被拼进 SQL 文本了");
}
/// 🔴 单号(billRule)不被入参覆盖 —— 真实数据里 `F_Building` 就是 billRule。
#[test]
fn real_bill_rule_field_is_not_overridable() {
let model = real_model();
let plan = plan_insert(
&real_form(),
&model,
&serde_json::json!({
"F_Room": "A-101",
"F_Building": "用户伪造的单号"
}),
&ctx(),
"main-1",
)
.unwrap();
assert!(
!plan
.main
.params
.iter()
.any(|p| p.as_str() == Some("用户伪造的单号")),
"入参覆盖了系统生成的单号: {:?}",
plan.main.params
);
}
/// 🔴 反自证:如果有人把「列必须在模型里」这条断言删掉,这把尺子必须变红。
///
/// 做法:手工造一个**模型里没有**的列名,看断言是否拦得住。
#[test]
fn the_guard_actually_catches_unknown_columns() {
let model = real_model();
let main = model.main_table().unwrap();
let allowed = main.column_names();
// 造一个真实库里存在的列,但**不在这个功能的模型里**
let foreign = "f_base_user_id";
assert!(
!allowed.contains(&foreign.to_string()),
"前提不成立:{foreign} 不该在这个功能的模型里"
);
}
+352
View File
@@ -0,0 +1,352 @@
//! lowcode —— 低代码**动态 CRUD** 的写工具(P2-b)。
//!
//! ## 这三个工具是干什么的
//!
//! 低代码功能(`base_visual_dev` 里那条记录)自己带一套表结构定义
//! (`f_tables_data`)与控件树(`f_form_data`)。
//! 这三个工具让 AI **按设计稿直接读写业务数据**,
//! 不必为每个低代码功能手写一套 Rust handler。
//!
//! | 工具 | 动作 | 对齐的基线平台方法 |
//! |---|---|---|
//! | `data.record.insert` | 新增一条(含子表) | `FlowFormDataUtil.create()` |
//! | `data.record.update` | 更新一条(含子表差集对账) | `FlowFormDataUtil.update()` |
//! | `data.record.delete` | 删除一条(逻辑/物理) | `FlowFormDataUtil.deleteTable()` |
//!
//! ## 🔴 三条与「普通写工具」不同的约定
//!
//! 1. **设计稿 vs 真实库必须一致**:落库前拿 `information_schema` 比一遍列,
//! 对不上就报 `COLUMN_MISMATCH`,**拒绝写**。
//! (官方数据里 `columnName` 全是 null,列名是从 `field` 推导的 ——
//! 推导必然有偏差,不比对就是让数据库报 `column does not exist`。)
//! 2. **一个事务**:主表失败 ⇒ 子表不能留孤儿行。
//! 3. **`dry_run`**:先看 SQL 再决定落不落库。写工具默认就该这样。
//!
//! ## 🔴 参数命名的分层约定(别混)
//!
//! | 层 | 命名 | 例子 |
//! |---|---|---|
//! | **元工具**(`sspf_call` / `sspf_discover`) | snake_case | `dry_run`、`tool_id` |
//! | **业务工具**(本文件这三个) | camelCase | `dryRun`、`recordId`、`enCode` |
//!
//! 业务工具用 camelCase 是**对齐基线平台的前端 API 契约**
//! (`enCode` / `urlAddress` / `fullName` 都是那个形状)——
//! 这样前端切到 Rust 后端时,一行都不用改。
//! 元工具是本平台自己定义的协议 ⇒ 用 Rust 侧的 snake_case。
//!
//! ## 🔴 子表更新是**差集对账**,不是全量覆盖
//!
//! 入参里有、库里没有 ⇒ 新增;入参里没有、库里有 ⇒ 删除;
//! 两边都有 ⇒ 更新。详见 `sspf_lowcode::diff_sub_rows`。
use serde_json::Value;
use crate::adapter::{BoxFut, PlatformAdapter, ToolError};
use crate::registry::{Annotations, Category, Example, Hints, Pitfall, Severity, ToolDef};
macro_rules! passthrough {
($name:ident, $op:literal) => {
fn $name<'a>(
adapter: &'a dyn PlatformAdapter,
args: Value,
) -> BoxFut<'a, Result<Value, ToolError>> {
Box::pin(async move { adapter.invoke($op, args).await })
}
};
}
// ================================================================ data.record.insert
passthrough!(record_insert_handler, "data.record.insert");
pub const DATA_RECORD_INSERT: ToolDef = ToolDef {
id: "data.record.insert",
category: Category::Data,
title: "新增低代码记录",
one_liner: "按低代码设计稿新增一条记录(主表+子表,可 dry_run)",
input_schema: r#"{
"type": "object",
"properties": {
"id": { "type": "string", "description": "功能 id(查库)" },
"enCode": { "type": "string", "description": "或功能编码(查库)" },
"data": { "type": "object", "description": "字段值,键用设计态字段名(如 F_Room);子表用数组" },
"dryRun": { "type": "boolean", "default": true, "description": "true=只生成 SQL 不落库(默认建议先演练)" }
},
"required": ["data"],
"additionalProperties": false
}"#,
annotations: Annotations::CREATE,
hints: Hints {
when_to_use: &[
"给低代码功能造测试数据",
"把一份结构化数据灌进低代码功能",
"AI 要复现线上问题时先演练再落库",
],
when_not_to_use: &[
"表还没建出来(先 schema.table.create)",
"只是要读数据(用 data.query)",
"改已有记录(用 data.record.update)",
],
preconditions: &[
"该功能的 f_form_data 与 f_tables_data 都存在",
"低代码表必须**先建表**再存数据(表不存在会报 TABLE_NOT_IN_DB)",
"子表的每一行都要有主键 —— 平台侧服务端自动生成,不用自己给",
],
pitfalls: &[
Pitfall {
severity: Severity::P0,
wrong: "直接给真实值落库,不先 dryRun",
right: "先 dryRun=true 看生成的 SQL 与参数,再 dryRun=false 落库",
rationale: "写工具的第一原则是**先看再写**。低代码的列名是从设计稿推导的,\
推导与真实库可能有偏差;dryRun 阶段就会报 COLUMN_MISMATCH。",
},
Pitfall {
severity: Severity::P0,
wrong: "给单号字段(billRule)传自己的值",
right: "单号由后端生成,别传;传了也会被忽略",
rationale: "单号是业务编号规则的一部分,后端生成才唯一。\
入参覆盖单号会破坏编号序列,且前端看到的值与规则算出的对不上。",
},
Pitfall {
severity: Severity::P0,
wrong: "以为重复数据能塞进去",
right: "设计稿标了「唯一 / 业务主键」的字段,重复会被拒(UNIQUE_CONSTRAINT_VIOLATED / BUSINESS_KEY_VIOLATED)",
rationale: "基线平台在落库前有这两道校验:普通输入框标 `unique` ⇒ 全表唯一;\
启用 `useBusinessKey` ⇒ 业务主键字段的**组合**唯一。\
查重只算**未删除**的行(逻辑删除的行不占位)。",
},
Pitfall {
severity: Severity::P1,
wrong: "把子表行写成空数组或干脆不给",
right: "不给子表键 = 这张子表不参与写入;给空数组 = 明确表示没有行",
rationale: "两种语义不同:更新时「不给」保留旧行,「空数组」清空旧行(差集对账)。",
},
],
examples: &[
Example {
args: r#"{"enCode":"receivableDemo","data":{"F_Room":"A-101","F_Company_name":"某某公司"},"dryRun":true}"#,
note: "先演练",
},
Example {
args: r#"{"enCode":"receivableDemo","data":{"F_Room":"A-101"},"dryRun":false}"#,
note: "确认无误后落库",
},
],
},
handler: record_insert_handler,
};
// ================================================================ data.record.update
passthrough!(record_update_handler, "data.record.update");
pub const DATA_RECORD_UPDATE: ToolDef = ToolDef {
id: "data.record.update",
category: Category::Data,
title: "更新低代码记录",
one_liner: "按低代码设计稿更新一条记录(子表走差集对账)",
input_schema: r#"{
"type": "object",
"properties": {
"id": { "type": "string", "description": "功能 id(查库)" },
"enCode": { "type": "string", "description": "或功能编码(查库)" },
"recordId": { "type": "string", "description": "要更新的记录主键" },
"data": { "type": "object", "description": "要改的字段值;**只写要改的字段**,没写的字段不动" },
"dryRun": { "type": "boolean", "default": true, "description": "true=只生成 SQL 不落库" }
},
"required": ["recordId", "data"],
"additionalProperties": false
}"#,
annotations: Annotations::CREATE,
hints: Hints {
when_to_use: &["改低代码功能里某条记录的若干字段", "增删子表行"],
when_not_to_use: &[
"想改主键(主键是对外契约,改了就断链)",
"记录不存在(先 data.query 查一下)",
],
preconditions: &[
"recordId 必须真实存在(来自 data.query 的结果)",
"只写要改的字段 —— 没写的字段不会被清空",
],
pitfalls: &[
Pitfall {
severity: Severity::P0,
wrong: "以为更新是「整条替换」",
right: "只写要改的字段;没写的字段保持原值",
rationale: "更新是**部分更新**(只 SET 入参给了的列 + 最后修改时间/人)。\
整条替换会清掉没提到的字段。",
},
Pitfall {
severity: Severity::P0,
wrong: "给子表传完整行列表就以为「多余的会被删」",
right: "子表确实按差集对账:**入参里没有的旧行会被删**(逻辑删或物理删)",
rationale: "这与主表的「部分更新」语义**不同**。子表是「以入参为准」的全量对账。\
只想改一行的某个字段,也要把这张子表的**所有行**都传进来,否则旧的会被删。",
},
Pitfall {
severity: Severity::P1,
wrong: "在 data 里传主键",
right: "主键只放在 recordId 里",
rationale: "改主键等于改对外契约(子表外键指向它)⇒ 会产生孤儿行。\
平台侧会直接忽略 data 里的主键。",
},
],
examples: &[
Example {
args: r#"{"enCode":"receivableDemo","recordId":"查出来的 id","data":{"F_Room":"B-202"},"dryRun":true}"#,
note: "只改一个字段",
},
],
},
handler: record_update_handler,
};
// ================================================================ data.record.delete
passthrough!(record_delete_handler, "data.record.delete");
pub const DATA_RECORD_DELETE: ToolDef = ToolDef {
id: "data.record.delete",
category: Category::Data,
title: "删除低代码记录",
one_liner: "删一条低代码记录(逻辑/物理按功能设置),可 dry_run",
input_schema: r#"{
"type": "object",
"properties": {
"id": { "type": "string", "description": "功能 id(查库)" },
"enCode": { "type": "string", "description": "或功能编码(查库)" },
"recordId": { "type": "string", "description": "要删的记录主键" },
"dryRun": { "type": "boolean", "default": true, "description": "true=只生成 SQL 不落库" }
},
"required": ["recordId"],
"additionalProperties": false
}"#,
annotations: Annotations::DESTRUCTIVE,
hints: Hints {
when_to_use: &["删掉造错的测试数据", "下线一条不该存在的记录"],
when_not_to_use: &[
"只是想让它「看不见」(那是逻辑删除,前提是功能开了 logicalDelete)",
"不确定记录 id(先 data.query 确认,别乱猜)",
],
preconditions: &[
"recordId 必须真实存在",
"🔴 物理删除不可恢复 —— 先 dryRun=true 看清楚要删什么",
],
pitfalls: &[
Pitfall {
severity: Severity::P0,
wrong: "以为删除永远是逻辑删除",
right: "看功能里的 logicalDelete:false = **物理 DELETE**,行真没了",
rationale: "基线平台的 `deleteTable()` 就是这么分的:logicalDelete=false 时\
走 `DELETE FROM`,走的是物理删除 ⇒ 不可恢复、且破坏审计。",
},
Pitfall {
severity: Severity::P0,
wrong: "以为删主表就完事了",
right: "子表会跟着删(按外键批量删/逻辑删)",
rationale: "子表数据挂在主表外键上;不删会变成孤儿行,\
而且下次同主键重建时会把旧数据带出来。",
},
Pitfall {
severity: Severity::P1,
wrong: "在功能开了 logicalDelete 但表里没有删除列时硬删",
right: "会报 LOGICAL_DELETE_UNSUPPORTED —— 这是**表建错了**,要先修表",
rationale: "动态建表时删除列是跟着 logicalDelete 一起加的(主表子表同进同退)。\
表里没有删除列 = 这个功能从来没建对过。",
},
],
examples: &[
Example {
args: r#"{"enCode":"receivableDemo","recordId":"查出来的 id","dryRun":true}"#,
note: "先看要删什么",
},
],
},
handler: record_delete_handler,
};
/// P2-b 的低代码写工具(3 个)。
pub static LOWCODE_TOOLS: &[ToolDef] = &[
DATA_RECORD_INSERT,
DATA_RECORD_UPDATE,
DATA_RECORD_DELETE,
];
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn lowcode_tools_are_well_formed() {
assert_eq!(LOWCODE_TOOLS.len(), 3);
for t in LOWCODE_TOOLS {
let s = t.schema_value();
assert!(s.get("x-schema-error").is_none(), "{} schema 非法", t.id);
assert!(
t.one_liner.chars().count() <= 40,
"{} one_liner 超 40 字",
t.id
);
assert!(!t.hints.when_to_use.is_empty(), "{} 缺 when_to_use", t.id);
assert!(!t.hints.when_not_to_use.is_empty(), "{} 缺 when_not_to_use", t.id);
assert!(!t.hints.preconditions.is_empty(), "{} 缺 preconditions", t.id);
assert!(!t.hints.examples.is_empty(), "{} 缺 examples", t.id);
for p in t.hints.pitfalls {
assert!(!p.rationale.trim().is_empty(), "{} 的坑缺 rationale", t.id);
}
}
}
/// 🔴 写工具不能标只读;删除必须标 destructive。
#[test]
fn lowcode_write_tools_are_annotated() {
for t in LOWCODE_TOOLS {
assert!(!t.annotations.read_only, "{} 是写工具", t.id);
}
let del = LOWCODE_TOOLS
.iter()
.find(|t| t.id == "data.record.delete")
.unwrap();
assert!(del.annotations.destructive, "delete 必须标 destructive");
}
/// 🔴 三个工具都必须支持 dryRun —— 写工具默认先看再写。
#[test]
fn every_write_tool_supports_dry_run() {
for t in LOWCODE_TOOLS {
let s = t.schema_value();
assert!(
s["properties"]["dryRun"].is_object(),
"{} 必须有 dryRun 参数",
t.id
);
}
}
/// 🔴 **schema 里不许出现「声明了但没实现」的参数**。
///
/// 这不是洁癖 —— 是**行为契约**:AI 看到 `idempotent` 就会以为
/// 「传了它,重复调用不会重复建记录」。
/// 但基线平台根本没有这个语义(查过 Java 源码:无 idempotent / 幂等),
/// 防重复靠的是「单行唯一」+「业务主键」两道校验(已实现)。
/// ⇒ 留着一个不生效的开关 = 骗 AI。
///
/// 白名单里的参数都是**真能在内核里找到对应实现**的。
#[test]
fn schema_declares_only_implemented_parameters() {
const ALLOWED: &[&str] = &["id", "enCode", "data", "recordId", "dryRun"];
for t in LOWCODE_TOOLS {
let s = t.schema_value();
let props = s["properties"].as_object().expect("properties 应是对象");
for key in props.keys() {
assert!(
ALLOWED.contains(&key.as_str()),
"{} 声明了未实现的参数「{}」—— \
要么实现它,要么从 schema 里删掉(别让 AI 以为它生效)",
t.id,
key
);
}
}
}
}
+5
View File
@@ -20,6 +20,7 @@
pub mod business;
pub mod form;
pub mod lowcode;
pub mod meta;
pub mod permission;
pub mod write;
@@ -214,6 +215,10 @@ pub static ALL_TOOLS: &[ToolDef] = &[
form::FORM_LIST,
form::FORM_DESCRIBE,
form::FORM_VALIDATE,
// —— 第六批(P2-b):低代码动态 CRUD(写,带 dry_run)——
lowcode::DATA_RECORD_INSERT,
lowcode::DATA_RECORD_UPDATE,
lowcode::DATA_RECORD_DELETE,
];
#[cfg(test)]
+104
View File
@@ -179,6 +179,32 @@ impl Db {
self.pg.shutdown().await
}
/// 开一个**真事务**(`BEGIN` … `COMMIT` / `ROLLBACK`)。
///
/// ## 🔴 为什么必须显式事务
///
/// pglite 的 `exec`(simple protocol)整批是**一个隐式事务**,
/// 但 `exec_params`(extended protocol)**只能单语句**。
/// 动态 CRUD 写一条记录要写「主表 + N 张子表」⇒ 必须显式事务,
/// 否则主表成功、子表失败 ⇒ 库里留下**孤儿行**(子表外键指向不存在的主表)。
///
/// ## 🔴 锁语义
///
/// 本层的 `Db.lock`(tokio Mutex)在事务期间**一直被持有** ⇒
/// 事务期间其它 `Db` 调用全部排队,不会与事务交错;
/// pglite 自己的 `tx_lock` 是第二道保险。
///
/// ⚠️ **事务内不许调 `db.*`** —— 那会等同一把 `Db.lock`,直接死锁。
/// 事务内的一切查询都要走 [`DbTransaction`] 自己的方法。
pub async fn begin(&self) -> Result<DbTransaction<'_>, pglite::Error> {
let guard = self.lock.lock().await;
let tx = self.pg.transaction().await?;
Ok(DbTransaction {
tx,
_guard: guard,
})
}
// ---- 以下为**持锁调用**的内部实现(调用方已持有 `self.lock`)----
async fn query_json_inner(
@@ -238,6 +264,84 @@ impl Db {
}
}
/// 一个**显式事务**(`BEGIN` … `COMMIT` / `ROLLBACK`)。
///
/// ## 🔴 三条使用纪律
///
/// 1. **事务内不许调 `Db::*`** —— `Db.lock` 已被本事务持有(tokio Mutex 不可重入)
/// ⇒ 那样写会直接死锁。事务内的查询一律走本类型的方法。
/// 2. **必须显式 `commit` / `rollback`** —— 不提交就 `Drop` ⇒ pglite 自动回滚
/// (`Transaction::drop` 里会 `rollback_fire_and_forget`),
/// 表现是「代码看着执行完了,库里什么都没有」,最难查。
/// 3. **`commit` / `rollback` 消耗 `self`** —— 这是 Rust 的所有权在替你防「提交两次」。
pub struct DbTransaction<'a> {
/// pglite 的事务句柄。
tx: pglite::Transaction<'a>,
/// 本层的进程级业务锁(S3)—— 事务期间一直持有 ⇒ 其它 DB 调用全部排队。
///
/// 🔴 **为什么不能丢**:pglite 自己的 `tx_lock` 只保证「一次 SQL 调用」不交错,
/// 而本层需要的是「一次业务操作(多条 SQL)」整体串行。
_guard: tokio::sync::MutexGuard<'a, ()>,
}
impl<'a> DbTransaction<'a> {
/// 执行一条带参数语句(**单语句**,extended protocol)。
pub async fn exec_params(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<(), pglite::Error> {
self.tx.query(sql, params).await.map(|_| ())
}
/// 执行一条无参数语句(simple protocol,可多语句)。
pub async fn exec(&self, sql: &str) -> Result<(), pglite::Error> {
self.tx.exec(sql).await
}
/// 查询(带参数)⇒ 行数组。
pub async fn query(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<pglite::Row>, pglite::Error> {
self.tx.query(sql, params).await
}
/// 查询 ⇒ JSON 数组(与 [`Db::query_json`] 同款归一逻辑)。
pub async fn query_json(
&self,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<Vec<Value>, pglite::Error> {
let inner = trim_sql(sql);
let alias_info = collect_alias_info(inner);
let wrapped = format!("SELECT row_to_json(q)::text AS _row FROM ({inner}) AS q");
let rows = self.tx.query(&wrapped, params).await?;
let mut out = Vec::with_capacity(rows.len());
for row in rows {
let Some(text) = row.get::<Option<String>>(0)? else {
continue;
};
let value = serde_json::from_str::<Value>(&text).map_err(|e| {
pglite::Error::Protocol(format!("row_to_json 结果反序列化失败: {e}"))
})?;
out.push(normalize_json_keys(value, &alias_info));
}
Ok(out)
}
/// 提交。
pub async fn commit(self) -> Result<(), pglite::Error> {
self.tx.commit().await
}
/// 回滚。
pub async fn rollback(self) -> Result<(), pglite::Error> {
self.tx.rollback().await
}
}
/// 去掉首尾空白与**结尾**的分号(调用方的 SQL 常带 `;`;包成子查询时不能留)。
fn trim_sql(sql: &str) -> &str {
sql.trim().trim_end_matches(';').trim_end()