Files
ssw-platform/crates/sspf-lowcode/src/sql.rs
T
admin 1d1a3b1ef9 feat(mcp): schema.table.create 落地 + P2-b 冒烟闭环,修 data.query 泄漏口令列
- MCP:新增 schema.table.create(第 26 个业务工具)—— 库内功能按设计稿建表并回写
  f_tables_data;内联 formData/tablesData 只能演练(INLINE_REQUIRES_DRY_RUN);
  写且幂等(表已存在跳 DDL,列不同报 TABLE_EXISTS_DIFFERENT),默认 dryRun=true
- mcp-smoke 32 → 48 条:先 --seed-lowcode-demo 造 receivableDemo,再用同一 PGLITE_DIR
  起 --mcp,python 动态驱动(主键是服务端 UUID)跑通「默认演练不落库 → 真写 → 查证 →
  子表差集三类 → 删除 → 建表演练/幂等」;M4 回复数改为按请求文件计算,不再写死 29
- lowcode-smoke 8 → 15 条:用内联演练钉建表规则(类型映射+dataLength / 复合主键 /
  逻辑删除三列 / 系统列视图类型),外加两条反自证(不开逻辑删除就不加删除列;
  inline 不许落库)
- fix:data.query 不再投影 f_password / f_secretkey(实测能拖走全库口令哈希);
  缺省滤掉并返回 hiddenColumns,显式 columns/where/orderBy 要用 ⇒ SENSITIVE_COLUMN
- docs:PLAN / CLAUDE / docs/mcp / docs/visualdev-mechanism 补 P2-b 结论;
  业务工具数 21 → 26 由 tool_count_matches_doc 钉死;清 f_foreign_id 文档漂移
  (子表外键列来自模型 tableField);补单租户口径的三条交叉证据(K8s 配置 / Java 常量 /
  官方 DDL);记 UNIQUE_CONSTRAINT_VIOLATED / BUSINESS_KEY_VIOLATED
2026-10-31 21:34:37 +08:00

2563 lines
97 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 动态 CRUD 的 SQL 生成(**纯函数**:只产出 SQL 文本 + 参数,不连库)。
//!
//! ## 为什么 SQL 生成要放在本 crate(而不是内核)
//!
//! 内核连库执行;SQL 生成的**正确性**(列白名单、系统字段、类型转换、父子表顺序)
//! 才是最该被单测覆盖的部分。放在这里 ⇒
//! - 不用起数据库就能测(毫秒级)
//! - CLI / 离线工具 / 迁移脚本都能复用同一套生成逻辑
//! - 内核那边只剩「拿到 SQL 就执行」,没有分支逻辑
//!
//! ## 对齐基线平台的机制
//!
//! 逐条对齐 `FlowFormDataUtil`(`jnpf-visualdev-base-biz`):
//!
//! | 规则 | 溯源 |
//! |---|---|
//! | 列名 = `lower(vModel)` | `VisualDevTableCre.fieldList()` + PG `toLowerCase()` |
//! | 空串 → NULL | `getInsertDSL()`:`data == null \|\| isEmpty(data.toString())` → `toNull()` |
//! | 空数组 → NULL | `valueToNull()`:空 List → null |
//! | 主表 `f_flow_task_id` = 主键 | `createMast()`:`set(flowTaskId).toValue(mainId.toString())` |
//! | 主键列名取模型里 `primaryKey=1` 的列,否则 `f_id` | `getKey()` |
//! | 子表外键列 = 模型的 `tableField`(**不是** `f_foreign_id`) | `createMastTable()` |
//! | 列表值 → JSON 字符串 | `createMast()`:`data instanceof List ? JsonUtil.getObjectToString(data)` |
//! | 系统字段不被入参覆盖 | `create()` 的 switch 分支 |
//!
//! ## 🔴 值一律参数化
//!
//! 本模块**只输出 SQL 文本与参数数组**,绝不把值拼进 SQL。
//! 列名与表名走白名单(来自模型定义),值走 `$n` 占位符。
//! —— 参数化只能防「值注入」,**结构注入必须靠列白名单**,两者都要。
//!
//! ## 🔴 表名/列名也不是「拼进去就没事」
//!
//! 表名来自 `f_tables_data`(用户可编辑的 JSON)⇒ 拼进 SQL 前必须过白名单。
//! 本模块用两道防线:
//! 1. 表名必须**出现在模型定义里**(`UnknownTable` 错误);
//! 2. 列名必须**出现在该表的列定义里**(`UnknownColumn` 错误)。
//! 两道都过不了的,一律**报错而不是跳过** —— 跳过会让「传错了字段」静默丢数据。
use std::collections::BTreeMap;
use serde_json::Value;
use crate::form::{FieldNode, FormSchema};
use crate::model::{ModelSchema, TableSchema};
use crate::widget::{auto_fill, AutoFill};
/// 系统字段的**识别特征**(不是列名!)。
///
/// ## 🔴 为什么这里写的是「特征」而不是列名
///
/// 上一版这里硬编码了 `f_creator_time` / `f_foreign_id` / `f_delete_mark` …,
/// 看起来很规整,但**在真实数据上会直接撞 `column does not exist`**。
///
/// 原因(已核实 jnpf Java 源码 + 官方初始化数据):
///
/// | 事实 | 证据 |
/// |---|---|
/// | 建表追加的系统列,名字来自**模型里的字段** | `VisualDevTableCre.fieldList()`:`fieldForm.setField(fieLdsModel.getVModel())` |
/// | 主键列 = 模型里 `primaryKey=1` 的字段 | `FlowFormDataUtil.getKey()` |
/// | 流程任务 id 列 = 模型里字段名**含** `f_flow_task_id` 的那个 | `FlowFormDataUtil.getFlowTaskId()` |
/// | 子表外键列 = 模型的 `tableField` | `FlowFormDataUtil.createMastTable()` |
///
/// 实测 `test_receivable` 的模型里,`F_CreatorTime` 推出的列是 `f_creatortime`
/// (**没有下划线**),而 `f_creator_time` 是平台表 `base_*` 的手写 DDL 风格。
/// ⇒ 硬编码列名 = 猜 = 静默写错列。
///
/// ## 🔴 特征常量取自 Java 源码,**不许自行简化**
///
/// `TableFieldsNameConst`(`jnpf-common-core`)的真实字面量:
/// ```java
/// F_ID = "f_id"; F_TENANT_ID = "f_tenant_id";
/// F_VERSION = "f_version"; F_FLOW_TASK_ID = "f_flow_task_id";
/// F_FLOW_ID = "f_flow_id"; F_DELETE_MARK = "f_delete_mark";
/// F_DELETE_TIME = "f_delete_time"; F_DELETE_USER_ID = "f_delete_user_id";
/// F_FOREIGN_ID = "f_foreign_id"; F_FLOW_STATE = "f_flow_state";
/// ```
///
/// Java 的识别用的是 `field.toLowerCase().contains(<常量>)` ——
/// 例如 `getKey()` 过滤 `contains("f_tenant_id")`、
/// `getFlowTaskId()` 找 `contains("f_flow_task_id")`。
/// 写成 `"tenantid"` 会**匹配不上** `f_tenant_id`(多了下划线)⇒ 主键会选错列。
pub mod sys {
/// 主键列的**兜底**名(模型没标主键时用;Java `TableFeildsEnum.FID`)。
pub const F_ID: &str = "f_id";
/// 租户列的**识别特征**(Java `TableFeildsEnum.TENANTID`)。
pub const TENANTID: &str = "f_tenant_id";
/// 流程任务 id 列的**识别特征**(Java `TableFeildsEnum.FLOWTASKID`)。
///
/// 🔴 Java 侧是 `contains`(包含),不是相等。
pub const FLOWTASKID: &str = "f_flow_task_id";
/// 版本列的**识别特征**(并发锁开启时写它;Java `TableFeildsEnum.VERSION`)。
pub const VERSION: &str = "f_version";
/// 逻辑删除标记列的**识别特征**(Java `TableFeildsEnum.DELETEMARK`)。
pub const DELETE_MARK: &str = "f_delete_mark";
/// 逻辑删除时间列的**识别特征**(Java `TableFeildsEnum.DELETETIME`)。
pub const DELETE_TIME: &str = "f_delete_time";
/// 逻辑删除人列的**识别特征**(Java `TableFeildsEnum.DELETEUSERID`)。
pub const DELETE_USER_ID: &str = "f_delete_user_id";
/// 最后修改时间列的**识别特征**(Java `TableFeildsEnum.LASTMODIFYTIME`)。
pub const LAST_MODIFY_TIME: &str = "f_last_modify_time";
/// 最后修改人列的**识别特征**(Java `TableFeildsEnum.LASTMODIFYUSERID`)。
pub const LAST_MODIFY_USER_ID: &str = "f_last_modify_user_id";
}
/// 一条待执行的 SQL(文本 + 参数)。
#[derive(Debug, Clone, PartialEq)]
pub struct Sql {
/// SQL 文本(值全部是 `$1`/`$2` 占位符)。
pub text: String,
/// 参数值(按占位符顺序)。
pub params: Vec<Value>,
/// 🔴 **占位符 ↔ 列名的一一映射**(`params[i]` 写的是 `param_columns[i]`)。
///
/// ## 为什么必须显式带这个
///
/// 执行层要给参数加类型 cast(`$n::text::numeric`),
/// 而 cast 取决于**目标列的数据类型** ⇒ 必须知道「`$n` 是哪一列」。
///
/// 之前的做法是「按模型里的字段顺序猜」——
/// `INSERT INTO t (f_id, f_room) ...` 里 `$1` 未必是 `f_id`,
/// 因为**模型字段顺序 ≠ 实际写入列顺序**(系统列、租户列、
/// 流程任务列都是运行时追加的)。猜错 ⇒ 数值列被当字符串写、
/// 时间列 cast 不对 ⇒ 静默写脏数据。
///
/// ⇒ 列名跟着参数一起生成,执行层不再需要「理解 SQL 怎么拼的」。
pub param_columns: Vec<String>,
/// 这条 SQL 作用于哪张表(诊断用)。
pub table: String,
/// 这条 SQL 属于哪一步(诊断 / 日志用)。
pub kind: SqlKind,
}
impl Sql {
/// 稳定字符串(诊断输出用)。
pub fn kind_str(&self) -> &'static str {
self.kind.as_str()
}
/// 取某个占位符对应的列名(`$1` ⇒ 第 0 个)。
pub fn column_of(&self, index: usize) -> Option<&str> {
self.param_columns.get(index).map(String::as_str)
}
}
/// SQL 的语义类别。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SqlKind {
/// 主表新增。
InsertMain,
/// 子表新增。
InsertSub,
/// 主表更新。
UpdateMain,
/// 子表更新。
UpdateSub,
/// 逻辑删除(置删除标记)。
SoftDelete,
/// 物理删除(`logicalDelete=false` 时基线平台的行为)。
HardDelete,
}
impl SqlKind {
/// 稳定字符串(诊断输出用)。
pub fn as_str(self) -> &'static str {
match self {
SqlKind::InsertMain => "insertMain",
SqlKind::InsertSub => "insertSub",
SqlKind::UpdateMain => "updateMain",
SqlKind::UpdateSub => "updateSub",
SqlKind::SoftDelete => "softDelete",
SqlKind::HardDelete => "hardDelete",
}
}
}
/// 生成 SQL 时的错误。
#[derive(Debug, Clone, PartialEq)]
pub enum SqlError {
/// 表不在模型定义里(⇒ 表名白名单不通过)。
UnknownTable(String),
/// 列不在模型定义里(⇒ 列名白名单不通过)。
UnknownColumn { table: String, column: String },
/// 必填字段没给值。
MissingRequired { table: String, column: String, label: String },
/// 主表缺失(模型里没有 `typeId=1` 的表)。
NoMainTable,
/// 主键缺失且无法自动生成。
NoPrimaryKey(String),
/// 入参类型不对(该字段要数组却给了标量)。
TypeMismatch { column: String, expected: &'static str },
/// 值里含非法类型(对象/数组不能直接入库,除已知可序列化的)。
UnsupportedValue { column: String },
/// 表名非法(不是合法 SQL 标识符)。
IllegalIdentifier { kind: &'static str, value: String },
/// 更新/删除时**一列都没改** —— 静默执行一条空 UPDATE 等于骗人。
NoColumnsToUpdate(String),
/// 子表外键指向的主表列,值拿不到。
///
/// 🔴 为什么会有这个错:`relationField` 指向的**不一定是主键**
/// (官方 fixture 里恰好是 `F_Id`)。若它指向别的列(如 `F_Code`),
/// 那个值只能来自数据库或入参 —— 本 crate 是纯计算层,查不了库。
MissingRelationValue { table: String, column: String },
/// 这张表**不支持逻辑删除**(模型里没有删除标记列)。
///
/// ## 🔴 为什么必须报错,而不是「退化成物理删除」
///
/// 动态建表时(`VisualDevTableCre`)删除列是**跟着 `logicalDelete` 一起加的** ——
/// 主表和子表要么都有,要么都没有。
/// ⇒ 「表里没有删除列」只可能是两种情况:
/// 1. 这个功能的 `logicalDelete = false` ⇒ 本来就该物理删(调用方会走物理删路径);
/// 2. 设计稿与真实库不一致(表建错了)⇒ **必须报出来**。
///
/// 退化成空 UPDATE = 「什么都没删,但返回成功」—— 比删不掉更糟:
/// 用户以为删了,实际行还在,列表里还查得到。
LogicalDeleteUnsupported(String),
}
impl SqlError {
/// 错误码(稳定字符串,便于 AI 自纠)。
pub fn code(&self) -> &'static str {
match self {
SqlError::UnknownTable(_) => "UNKNOWN_TABLE",
SqlError::UnknownColumn { .. } => "UNKNOWN_COLUMN",
SqlError::MissingRequired { .. } => "MISSING_REQUIRED",
SqlError::NoMainTable => "NO_MAIN_TABLE",
SqlError::NoPrimaryKey(_) => "NO_PRIMARY_KEY",
SqlError::TypeMismatch { .. } => "TYPE_MISMATCH",
SqlError::UnsupportedValue { .. } => "UNSUPPORTED_VALUE",
SqlError::IllegalIdentifier { .. } => "ILLEGAL_IDENTIFIER",
SqlError::NoColumnsToUpdate(_) => "NO_COLUMNS_TO_UPDATE",
SqlError::MissingRelationValue { .. } => "MISSING_RELATION_VALUE",
SqlError::LogicalDeleteUnsupported(_) => "LOGICAL_DELETE_UNSUPPORTED",
}
}
/// 人话描述。
pub fn message(&self) -> String {
match self {
SqlError::UnknownTable(t) => {
format!("表 {t} 不在功能定义里(表名白名单不通过)")
}
SqlError::UnknownColumn { table, column } => {
format!("表 {table} 没有列 {column}(列名白名单不通过)")
}
SqlError::MissingRequired { table, column, label } => {
format!("必填字段「{label}」({table}.{column})没给值")
}
SqlError::NoMainTable => "模型里没有主表(typeId=1)".to_string(),
SqlError::NoPrimaryKey(t) => format!("表 {t} 既没标主键,也没给主键值"),
SqlError::TypeMismatch { column, expected } => {
format!("字段 {column} 应为 {expected}")
}
SqlError::UnsupportedValue { column } => {
format!("字段 {column} 的值是复杂对象,无法直接入库")
}
SqlError::IllegalIdentifier { kind, value } => {
format!("{kind}「{value}」不是合法标识符")
}
SqlError::NoColumnsToUpdate(t) => {
format!("表 {t} 没有任何列要更新(入参没给可写字段,或全是系统字段)")
}
SqlError::MissingRelationValue { table, column } => {
format!(
"子表 {table} 的外键指向主表的 {column},但拿不到这一列的值 —— \
它不是主键,只能由调用方查出来再传进来"
)
}
SqlError::LogicalDeleteUnsupported(t) => {
format!(
"表 {t} 没有删除标记列,不支持逻辑删除 —— \
这个功能要么该走物理删除,要么表建错了"
)
}
}
}
}
/// 写入操作所需的运行时上下文。
#[derive(Debug, Clone, Default)]
pub struct WriteContext {
/// 当前用户 id(写 `f_creator_user_id` / `f_last_modify_user_id`)。
pub user_id: Option<String>,
/// 当前用户组织 id 列表(写 `f_curr_organize` 类字段,序列化成 JSON)。
pub organize_ids: Vec<String>,
/// 当前用户岗位 id 列表。
pub position_ids: Vec<String>,
/// 租户 id(写 `f_tenant_id`)。
pub tenant_id: Option<String>,
/// 单据号生成器已产出的值(字段名 → 值)。
pub bill_numbers: BTreeMap<String, Value>,
/// 主键生成器已产出的值。
///
/// ## 🔴 键的约定(唯一,别再猜)
///
/// | 键 | 含义 |
/// |---|---|
/// | `<表名>` | 该表**主表行**的主键值 |
/// | `<表名>#<主键>` | 该表**首行**的主键值(子表用) |
/// | `<表名>#<主键>#<行号>` | 该表**第 n 行**的主键值(子表多行用,行号从 0 起) |
///
/// 查键顺序:`<表名>#<主键>#<行号>` → `<表名>#<主键>` → 入参里显式给的值。
///
/// Java 侧子表主键是**服务端现生成**的(`RandomUtil.uuId()`),
/// 所以调用方必须先把子表每行的主键备齐 —— 本 crate 不生成 id
///(AR7:纯计算,不引 uuid 库)。备不齐 ⇒ 报 `NO_PRIMARY_KEY`,
/// **绝不写空主键**(空主键 = 多行挤成一行)。
pub primary_keys: BTreeMap<String, String>,
/// 当前时间(ISO8601,如 `2026-10-31T12:00:00`)。
///
/// 🔴 由调用方传入(内核有 chrono),本 crate 不引时间库(AR7)。
/// `None` ⇒ **不写时间列**,交给数据库的 DEFAULT —— 这比编一个假时间安全。
pub now: Option<String>,
/// 主表**关联列**的实际值(列名 → 值)。
///
/// ## 🔴 为什么需要它
///
/// 子表外键的值 = 主表 `relationField` 指向的那一列的值
/// (基线平台:`mainMap.get(table.getRelationField())`)。
/// 当 `relationField` **就是主键**时,值 = 主键,调用方可以不登记;
/// 当它指向别的列(如业务编码 `F_Code`)时,
/// 那个值只能从数据库里查出来 ⇒ 由调用方(执行层)查完登记进来。
///
/// 本 crate 是**纯计算**层(AR7)⇒ 它不查库,只消费这里登记的值。
pub relation_values: BTreeMap<String, String>,
}
impl WriteContext {
/// 构造一个带用户 id 的上下文。
pub fn with_user(user_id: impl Into<String>) -> Self {
Self {
user_id: Some(user_id.into()),
..Default::default()
}
}
/// 登记一个主键值。
///
/// `key` 的形态见 [`WriteContext::primary_keys`]。
pub fn set_primary_key(&mut self, key: impl Into<String>, value: impl Into<String>) {
self.primary_keys.insert(key.into(), value.into());
}
/// 登记子表某一行的主键。
pub fn set_sub_row_key(
&mut self,
table: &str,
main_id: &str,
row_index: usize,
value: impl Into<String>,
) {
self.primary_keys.insert(
format!("{table}#{main_id}#{row_index}"),
value.into(),
);
}
/// 登记主表某个关联列的实际值(子表外键要指向它)。
pub fn set_relation_value(&mut self, column: &str, value: impl Into<String>) {
self.relation_values
.insert(column.to_lowercase(), value.into());
}
/// 取主表关联列的值。
///
/// ## 🔴 参数是**子表模型**,不是主表模型
///
/// `relationField` 定义在**子表**上(`TableModel.relationField`),
/// 它说的是「本子表的外键指向主表的**哪一列**」。
/// 之前传主表模型 ⇒ 主表的 `relationField` 是空串 ⇒ 永远查不到值。
///
/// 查不到 ⇒ `None`(调用方应回落到主键)。
pub fn relation_value(&self, sub_table: &TableSchema) -> Option<String> {
let rel_col = sub_table.relation_column()?;
self.relation_values.get(&rel_col.to_lowercase()).cloned()
}
}
/// 一次写入计划:主表 SQL + 子表 SQL(按依赖顺序)。
#[derive(Debug, Clone, PartialEq)]
pub struct WritePlan {
/// 主表新增。
pub main: Sql,
/// 子表新增(每条对应一行子表数据)。
pub subs: Vec<Sql>,
}
impl WritePlan {
/// 全部 SQL(主表在前)。
pub fn all(&self) -> Vec<&Sql> {
let mut v: Vec<&Sql> = vec![&self.main];
v.extend(self.subs.iter());
v
}
/// 一共几条 SQL(诊断 / 日志用)。
pub fn len(&self) -> usize {
1 + self.subs.len()
}
/// 一条都没有(理论不会发生 —— 主表 SQL 恒存在)。
pub fn is_empty(&self) -> bool {
false
}
}
/// 一次更新的计划。
#[derive(Debug, Clone, PartialEq)]
pub struct UpdatePlan {
/// 主表更新。
pub main: Sql,
/// 子表更新 / 新增 / 删除(差集对账的产物)。
pub subs: Vec<Sql>,
}
impl UpdatePlan {
/// 全部 SQL(主表在前)。
pub fn all(&self) -> Vec<&Sql> {
let mut v: Vec<&Sql> = vec![&self.main];
v.extend(self.subs.iter());
v
}
/// 一共几条 SQL。
pub fn len(&self) -> usize {
1 + self.subs.len()
}
/// 恒不为空(主表 SQL 恒存在)。
pub fn is_empty(&self) -> bool {
false
}
}
/// 子表更新的**差集对账**结果。
///
/// ## 🔴 为什么必须做差集,而不是「全量覆盖」
///
/// 基线平台 `FlowFormDataUtil.updateTable()` 的语义:
///
/// | 旧库里的行 | 入参里的行 | 动作 |
/// |---|---|---|
/// | 有 | 有(主键相同) | **UPDATE** |
/// | 无 | 有(主键是新的) | **INSERT** |
/// | 有 | 无(入参没这行) | **DELETE**(逻辑/物理按 `logicalDelete`) |
///
/// 全量覆盖(先 DELETE 全部再 INSERT 全部)会产生两个后果:
/// 1. 行的主键变了 ⇒ 子表主键是**对外契约**(前端可能存着它),一变就断链;
/// 2. 没在 `logicalDelete` 语义下的「删除」变成了物理删,破坏审计。
#[derive(Debug, Clone, Default, PartialEq)]
pub struct SubDiff {
/// 要更新的行(入参里主键与旧行相同的)。
pub updates: Vec<Value>,
/// 要新增的行(入参里主键是新的,或没给主键)。
pub inserts: Vec<Value>,
/// 要删除的行主键(旧库里有、入参里没有的)。
pub deletes: Vec<String>,
}
impl SubDiff {
/// 差集是否为空(没旧行、没新行 ⇒ 子表不用动)。
pub fn is_empty(&self) -> bool {
self.updates.is_empty() && self.inserts.is_empty() && self.deletes.is_empty()
}
/// 一共会产生几条子表 SQL(更新 + 新增 + 删除)。
pub fn statement_count(&self) -> usize {
self.updates.len() + self.inserts.len() + self.deletes.len()
}
}
/// 子表更新的**行为开关**(对齐基线平台的 `DataModel` 开关)。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SubUpdateOptions {
/// 只更新,不删除缺失的旧行(基线平台 `dataModel.getOnlyUpdate()`)。
///
/// 🔴 这是一个**危险**的开关:入参只给了一部分子表行时,
/// 旧行会被保留 —— 但如果调用方本意是「整表替换」,
/// 就会留下幽灵行。默认 `false`(对齐基线默认行为)。
pub only_update: bool,
/// 逻辑删除(基线平台 `dataModel.getLogicalDelete()`)。
///
/// `true` ⇒ 缺失的旧行**逻辑删除**(置删除标记);
/// `false` ⇒ **物理删除**。
pub logical_delete: bool,
}
impl Default for SubUpdateOptions {
fn default() -> Self {
Self {
only_update: false,
logical_delete: false,
}
}
}
/// 子表更新的**上下文**(差集对账需要的信息)。
#[derive(Debug, Clone)]
pub struct SubUpdateContext {
/// 旧库里的行主键(按外键查出来的)。
///
/// 🔴 本 crate 是纯计算层(AR7)⇒ **查库由调用方做**,
/// 这里只消费结果。空 ⇒ 子表没有旧行(全部视为新增)。
pub old_row_keys: Vec<String>,
/// 子表外键列(模型 `tableField`)。
pub foreign_key_column: String,
/// 外键的**值**(主表 `relationField` 指向的那一列的实际值)。
pub foreign_key_value: String,
/// 子表行主键生成器:入参没给主键时,用它生成一个。
///
/// 🔴 Java 侧子表主键是**服务端现生成**的(`RandomUtil.uuId()`),
/// 但本 crate 不引 uuid 库(AR7)⇒ 由调用方注入生成器。
/// 传 `None` ⇒ 入参没给主键的行**报错**(绝不写空主键)。
pub row_key_generator: Option<fn(usize) -> String>,
/// 选项(`only_update` / `logical_delete`)。
pub options: SubUpdateOptions,
}
impl SubUpdateContext {
/// 构造一个上下文(无主键生成器)。
pub fn new(
old_row_keys: Vec<String>,
foreign_key_column: impl Into<String>,
foreign_key_value: impl Into<String>,
options: SubUpdateOptions,
) -> Self {
Self {
old_row_keys,
foreign_key_column: foreign_key_column.into(),
foreign_key_value: foreign_key_value.into(),
row_key_generator: None,
options,
}
}
}
/// 计算子表的**差集**(对齐基线平台 `updateTable()`)。
///
/// ## 语义(逐条对齐 Java)
///
/// ```java
/// List<Object> childIdList = 旧库里的行主键;
/// List<Object> formDataIdList = 入参里带了主键的行主键;
/// List<Object> deleteList = childIdList 中不在 formDataIdList 的;
/// // 再逐行看:主键在 childIdList 里 ⇒ UPDATE,否则 ⇒ INSERT
/// ```
///
/// ⇒ 三种结果:
/// - `updates`:入参行主键在旧库里 ⇒ 更新;
/// - `inserts`:入参行主键不在旧库里(或没给主键)⇒ 新增;
/// - `deletes`:旧库行主键不在入参里 ⇒ 删除。
///
/// ## 🔴 大小写与类型
///
/// Java 用 `String.valueOf(t).contains(...)` 比较 ⇒ **字符串化后比较**。
/// 这里沿用:主键统一转字符串再比,避免 `123` vs `"123"` 判成两行。
pub fn diff_sub_rows(
rows: &[Value],
pk_col: &str,
ctx: &SubUpdateContext,
) -> SubDiff {
let old: Vec<String> = ctx.old_row_keys.iter().map(|s| s.to_string()).collect();
let mut diff = SubDiff::default();
for (idx, row) in rows.iter().enumerate() {
let given_key = row_key_of(row, pk_col);
match given_key {
Some(k) if old.iter().any(|o| o == &k) => {
// 旧库里有这行 ⇒ 更新
diff.updates.push(row.clone());
}
Some(k) => {
// 主键是新的 ⇒ 新增
let mut r = row.clone();
set_row_key(&mut r, pk_col, &k);
diff.inserts.push(r);
}
None => {
// 没给主键 ⇒ 新增,且主键由调用方生成(或报错)
let key = match ctx.row_key_generator {
Some(f) => f(idx),
None => {
// 没有生成器 ⇒ 这行没法落库,记下来由上层报错
// (用空串占位,调用方会因缺主键而拒绝)
String::new()
}
};
let mut r = row.clone();
set_row_key(&mut r, pk_col, &key);
diff.inserts.push(r);
}
}
}
// 旧库有、入参没有 ⇒ 删除(`only_update` 时不删)
if !ctx.options.only_update {
for o in &old {
let still_there = rows.iter().any(|r| {
row_key_of(r, pk_col).is_some_and(|k| k == *o)
});
if !still_there {
diff.deletes.push(o.clone());
}
}
}
diff
}
/// 取一行里的主键值(字符串化)。
fn row_key_of(row: &Value, pk_col: &str) -> Option<String> {
let obj = row.as_object()?;
for (k, v) in obj {
if k.eq_ignore_ascii_case(pk_col) {
return match v {
Value::String(s) if !s.is_empty() => Some(s.clone()),
Value::Number(n) => Some(n.to_string()),
Value::Null => None,
_ => None,
};
}
}
None
}
/// 往一行里写主键(兼容 `F_Id` / `f_id` 两种键名)。
fn set_row_key(row: &mut Value, pk_col: &str, key: &str) {
let Some(obj) = row.as_object_mut() else {
return;
};
// 已有的键(可能是 `F_Id`)直接覆盖
let existing = obj
.keys()
.find(|k| k.eq_ignore_ascii_case(pk_col))
.cloned();
match existing {
Some(k) => {
obj.insert(k, Value::String(key.to_string()));
}
None => {
obj.insert(pk_col.to_string(), Value::String(key.to_string()));
}
}
}
/// 列白名单:某张表允许写入的列(来自模型定义)。
#[derive(Debug, Clone)]
struct ColumnGuard {
/// 允许的物理列名(小写)。
allowed: Vec<String>,
/// 主键列名(模型标了 primaryKey 的那个;**排除租户列**)。
///
/// 🔴 排除租户列是 Java 的规则:`getKey()` 过滤掉
/// `field.toLowerCase().contains("tenantid")` 的字段 ——
/// 官方模型里 `f_tenant_id` 也是 `primaryKey=1`,若不排除会选错主键。
primary_key: Option<String>,
/// 流程任务 id 列名(模型里字段名含 `flowtaskid` 的那个)。
flow_task_id: Option<String>,
/// 租户列名(模型里字段名含 `tenantid` 的那个)。
tenant_id: Option<String>,
}
impl ColumnGuard {
fn allows(&self, column: &str) -> bool {
self.allowed.iter().any(|c| c == column)
}
}
/// 构造某张表的列白名单 + 系统列定位。
fn guard_for(table: &TableSchema) -> Result<ColumnGuard, SqlError> {
let allowed: Vec<String> = table
.fields
.iter()
.filter_map(|c| c.resolved_column())
.collect();
if allowed.is_empty() {
return Err(SqlError::UnknownTable(table.table.clone()));
}
// 主键:primaryKey=1 且**不是租户列**(Java `getKey()` 的规则)
let primary_key = table
.fields
.iter()
.filter(|c| c.primary_key)
.filter(|c| !c.field.to_lowercase().contains(sys::TENANTID))
.find_map(|c| c.resolved_column());
// 流程任务 id:字段名**包含** flowtaskid(Java `getFlowTaskId()` 的规则)
let flow_task_id = table
.fields
.iter()
.filter(|c| c.field.to_lowercase().contains(sys::FLOWTASKID))
.find_map(|c| c.resolved_column());
// 租户列:字段名包含 tenantid
let tenant_id = table
.fields
.iter()
.filter(|c| c.field.to_lowercase().contains(sys::TENANTID))
.find_map(|c| c.resolved_column());
Ok(ColumnGuard {
allowed,
primary_key,
flow_task_id,
tenant_id,
})
}
/// 生成一次**新增**的 SQL 计划。
///
/// `payload` 的键是**设计态字段名**(`F_Room`)或**物理列名**(`f_room`)——
/// 两种都接受,与前端提交时用的 `F_Room` 一致。
///
/// `main_id` 由调用方生成(用平台统一的 UUID 生成器),这里不生成。
pub fn plan_insert(
form: &FormSchema,
model: &ModelSchema,
payload: &Value,
ctx: &WriteContext,
main_id: &str,
) -> Result<WritePlan, SqlError> {
let main_table = model.main_table().ok_or(SqlError::NoMainTable)?;
let main_guard = guard_for(main_table)?;
// 主键列名:模型标了 primaryKey 就用它,否则 f_id
let pk_col = main_guard
.primary_key
.clone()
.unwrap_or_else(|| sys::F_ID.to_string());
let pk_val = ctx
.primary_keys
.get(&main_table.table)
.cloned()
.unwrap_or_else(|| main_id.to_string());
let mut cols: Vec<(String, Value)> = Vec::new();
let add = |cols: &mut Vec<(String, Value)>, col: &str, v: Value| {
if cols.iter().any(|(c, _)| c == col) {
return;
}
cols.push((col.to_string(), v));
};
// ① 主键
add(&mut cols, &pk_col, Value::String(pk_val.clone()));
// ② 业务字段(按表单定义顺序,列白名单过滤)
for field in form.main_fields() {
let Some(col) = field.column_name() else { continue };
if !main_guard.allows(&col) {
// 表单引用了模型里没有的列 ⇒ 跳过(form.validate 会报出来)
continue;
}
let raw = lookup(payload, &field.v_model, &col);
let value = match auto_fill(&field.jnpf_key) {
AutoFill::Passthrough => match raw {
Some(v) => normalize_value(v, &col)?,
None => {
// 没给值:必填则报错,否则写 NULL
if field.required {
return Err(SqlError::MissingRequired {
table: main_table.table.clone(),
column: col.clone(),
label: field.label.clone(),
});
}
Value::Null
}
},
AutoFill::CurrentUserId => Value::String(ctx.user_id.clone().unwrap_or_default()),
AutoFill::Now => match &ctx.now {
Some(t) => Value::String(t.clone()),
None => Value::Null,
},
AutoFill::CurrentOrganizeIds => Value::String(json_array(&ctx.organize_ids)),
AutoFill::CurrentPositionIds => Value::String(json_array(&ctx.position_ids)),
// 🔴 新增时「最后修改人/时间」置 null(Java `create()` 两个分支都是 null)
AutoFill::ModifyTime | AutoFill::ModifyUser => Value::Null,
AutoFill::BillNumber => ctx
.bill_numbers
.get(&field.v_model)
.cloned()
.or_else(|| ctx.bill_numbers.get(&col).cloned())
.unwrap_or(Value::Null),
};
add(&mut cols, &col, value);
}
// ③ 系统字段
// 🔴 列名**全部来自模型**(Java 同款规则),不硬编码 ——
// 实测模型里 `F_CreatorTime` 的列是 `f_creatortime`,硬编码 `f_creator_time` 会炸。
//
// 流程任务 id:Java `createMast()` 无条件写,值 = 主键(**非流程功能也写**)。
if let Some(flow_col) = &main_guard.flow_task_id {
add(
&mut cols,
flow_col,
Value::String(pk_val.clone()),
);
}
// 租户:Java `addTenantId()` 无条件写。
if let Some(tenant_col) = &main_guard.tenant_id {
if let Some(tid) = &ctx.tenant_id {
add(
&mut cols,
tenant_col,
Value::String(tid.clone()),
);
}
}
// 并发锁:Java 只在 `concurrencyLock` 开启时写 `f_version`。
if form.concurrency_lock.unwrap_or(false) {
if let Some(ver_col) = find_column(main_table, sys::VERSION) {
add(&mut cols, &ver_col, Value::from(0));
}
}
// ④ 渲染 SQL
let main_sql = render_insert(
&main_table.table,
&cols,
SqlKind::InsertMain,
)?;
// ⑤ 子表
let mut subs = Vec::new();
for sub in form.sub_tables() {
let sub_model = resolve_sub_table(model, sub)?;
let sub_guard = guard_for(sub_model)?;
let sub_pk = sub_guard
.primary_key
.clone()
.unwrap_or_else(|| sys::F_ID.to_string());
// 子表行数据:payload 里以子表 vModel 或表名为键
let rows = lookup_sub_rows(payload, &sub.v_model, &sub_model.table);
let Some(rows) = rows else { continue };
let arr = rows.as_array().ok_or_else(|| SqlError::TypeMismatch {
column: sub.v_model.clone(),
expected: "数组",
})?;
for (idx, row) in arr.iter().enumerate() {
let mut ccols: Vec<(String, Value)> = Vec::new();
let cadd = |cols: &mut Vec<(String, Value)>, c: &str, v: Value| {
if cols.iter().any(|(x, _)| x == c) {
return;
}
cols.push((c.to_string(), v));
};
// 子表行主键:入参给了就用;否则由调用方按 `表名#主键#行号` 提供,
// 再兜底用 `表名#主键#行号` 形态查一次 —— 都拿不到就**报错**,
// 绝不写空主键(空主键 = 多行挤成一行)。
let row_pk = lookup(row, &sub_pk, &sub_pk)
.and_then(|v| v.as_str().map(str::to_string))
.or_else(|| {
ctx.primary_keys
.get(&format!("{}#{}#{}", sub_model.table, pk_val, idx))
.cloned()
})
.or_else(|| {
ctx.primary_keys
.get(&format!("{}#{}", sub_model.table, pk_val))
.cloned()
})
.ok_or_else(|| SqlError::NoPrimaryKey(sub_model.table.clone()))?;
cadd(&mut ccols, &sub_pk, Value::String(row_pk));
// 子表字段:从子节点的 children 取
for child in &sub.children {
let Some(col) = child.column_name() else { continue };
if !sub_guard.allows(&col) {
continue;
}
let raw = lookup(row, &child.v_model, &col);
let value = match auto_fill(&child.jnpf_key) {
AutoFill::Passthrough => match raw {
Some(v) => normalize_value(v, &col)?,
None => {
if child.required {
return Err(SqlError::MissingRequired {
table: sub_model.table.clone(),
column: col.clone(),
label: child.label.clone(),
});
}
Value::Null
}
},
AutoFill::CurrentUserId => {
Value::String(ctx.user_id.clone().unwrap_or_default())
}
AutoFill::Now => match &ctx.now {
Some(t) => Value::String(t.clone()),
None => Value::Null,
},
AutoFill::CurrentOrganizeIds => {
Value::String(json_array(&ctx.organize_ids))
}
AutoFill::CurrentPositionIds => {
Value::String(json_array(&ctx.position_ids))
}
// 🔴 新增时「最后修改人/时间」置 null
AutoFill::ModifyTime | AutoFill::ModifyUser => Value::Null,
AutoFill::BillNumber => ctx
.bill_numbers
.get(&child.v_model)
.cloned()
.unwrap_or(Value::Null),
};
cadd(&mut ccols, &col, value);
}
// 🔴 外键:子表指向主表的**关联列**。
// 列名来自模型的 `tableField`(Java `createMastTable()` 同款)——
// 实测 `test_details` 的外键列是 `f_receivableid`,**不是** `f_foreign_id`。
// 值取主表 `relationField` 指向的那一列的值(基线平台同款:
// `dataNewMap.get(tableModel.getRelationField())`),
// 默认回落到主表主键(官方 fixture 的 relationField 就是主键列)。
//
// 🔴 `relationField` 定义在**子表模型**上 —— 查子表,不是主表。
if let Some(fk_col) = sub_model.foreign_key_column() {
let fk_value = ctx
.relation_value(sub_model)
.unwrap_or_else(|| pk_val.clone());
cadd(
&mut ccols,
&fk_col,
Value::String(fk_value),
);
}
// 租户(子表也有)
if let Some(tenant_col) = &sub_guard.tenant_id {
if let Some(tid) = &ctx.tenant_id {
cadd(
&mut ccols,
tenant_col,
Value::String(tid.clone()),
);
}
}
subs.push(render_insert(
&sub_model.table,
&ccols,
SqlKind::InsertSub,
)?);
}
}
Ok(WritePlan { main: main_sql, subs })
}
/// 生成一次**更新**的 SQL 计划。
///
/// 与基线平台的差异(刻意):基线平台更新时把**所有系统字段重置**,
/// 这里只更新「入参明确给了的列」+ 最后修改时间/人 —— 更安全,
/// 且避免覆盖并发修改。
pub fn plan_update(
form: &FormSchema,
model: &ModelSchema,
payload: &Value,
ctx: &WriteContext,
main_id: &str,
) -> Result<UpdatePlan, SqlError> {
let main_table = model.main_table().ok_or(SqlError::NoMainTable)?;
let main_guard = guard_for(main_table)?;
let pk_col = main_guard
.primary_key
.clone()
.unwrap_or_else(|| sys::F_ID.to_string());
let mut cols: Vec<(String, Value)> = Vec::new();
let add = |cols: &mut Vec<(String, Value)>, c: &str, v: Value| {
if cols.iter().any(|(x, _)| x == c) {
return;
}
cols.push((c.to_string(), v));
};
for field in form.main_fields() {
let Some(col) = field.column_name() else { continue };
if !main_guard.allows(&col) {
continue;
}
let Some(raw) = lookup(payload, &field.v_model, &col) else {
continue;
};
// 🔴 被系统覆盖的字段在更新时**直接跳过**,不写回入参值
if auto_fill(&field.jnpf_key).overrides_input() {
continue;
}
let value = normalize_value(raw, &col)?;
add(&mut cols, &col, value);
}
// 🔴 最后修改时间/人:列名**从模型推导**,不硬编码。
// 实测模型里是 `f_lastmodifytime` / `f_lastmodifyuserid`(无下划线)。
if let Some(t) = &ctx.now {
if let Some(c) = find_column(main_table, sys::LAST_MODIFY_TIME) {
add(&mut cols, &c, Value::String(t.clone()));
} else if let Some(c) = find_column(main_table, "lastmodifytime") {
add(&mut cols, &c, Value::String(t.clone()));
}
}
if let Some(uid) = &ctx.user_id {
if let Some(c) = find_column(main_table, sys::LAST_MODIFY_USER_ID) {
add(&mut cols, &c, Value::String(uid.clone()));
} else if let Some(c) = find_column(main_table, "lastmodifyuserid") {
add(&mut cols, &c, Value::String(uid.clone()));
}
}
let main = render_update(
&main_table.table,
&cols,
&pk_col,
main_id,
SqlKind::UpdateMain,
)?;
Ok(UpdatePlan { main, subs: Vec::new() })
}
/// 生成一次**更新**的 SQL 计划(**含子表差集对账**)。
///
/// 与 [`plan_update`] 的差别:**多了子表**。
/// - [`plan_update`]:只更新主表(子表完全不动);
/// - [`plan_update_full`]:主表 + 子表的 UPDATE / INSERT / DELETE(差集对账)。
///
/// ## 🔴 子表差集必须由调用方提供「旧行主键」
///
/// 本 crate 是纯计算层(AR7)⇒ 查不了库。
/// 调用方(内核执行层)要先按外键查旧行主键,塞进
/// [`SubUpdateContext::old_row_keys`]。
///
/// ## 🔴 与基线平台的差异(刻意)
///
/// 基线平台更新时把**所有系统字段重置**,这里只更新「入参明确给了的列」
/// + 最后修改时间/人 —— 更安全,且避免覆盖并发修改。
///
/// 另:基线平台 `updateTable()` 查旧行用的是**旧值** `oldForeignValue`
/// (主表改之前的关联列值),这里用**新值** —— 因为更新场景下
/// 关联列一般就是主键,不受影响;若关联列真的变了,
/// 那是「把子表搬到另一个父行」的语义,基线平台也不支持。
pub fn plan_update_full(
form: &FormSchema,
model: &ModelSchema,
payload: &Value,
ctx: &WriteContext,
main_id: &str,
sub_ctxs: &BTreeMap<String, SubUpdateContext>,
) -> Result<UpdatePlan, SqlError> {
let mut plan = plan_update(form, model, payload, ctx, main_id)?;
let mut subs: Vec<Sql> = Vec::new();
for sub in form.sub_tables() {
let sub_model = resolve_sub_table(model, sub)?;
let sub_guard = guard_for(sub_model)?;
let sub_pk = sub_guard
.primary_key
.clone()
.unwrap_or_else(|| sys::F_ID.to_string());
let Some(sub_ctx) = sub_ctxs.get(&sub_model.table) else {
// 没给子表上下文 ⇒ 子表不动(调用方明确表示「这张子表不参与更新」)
continue;
};
// 入参里的子表行
let rows = lookup_sub_rows(payload, &sub.v_model, &sub_model.table);
let arr: Vec<Value> = match rows {
Some(v) => v.as_array().cloned().unwrap_or_default(),
None => Vec::new(),
};
let diff = diff_sub_rows(&arr, &sub_pk, sub_ctx);
// ---- 删除缺失的旧行 ----
if !diff.deletes.is_empty() {
for key in &diff.deletes {
let sql = if sub_ctx.options.logical_delete {
soft_delete_row(sub_model, &sub_pk, key, ctx)?
} else {
render_delete(
&sub_model.table,
&sub_pk,
key,
SqlKind::HardDelete,
)?
};
subs.push(sql);
}
}
// ---- 更新已有行 ----
for row in &diff.updates {
let key = row_key_of(row, &sub_pk).unwrap_or_default();
let cols = sub_row_columns(sub, sub_model, &sub_guard, row, ctx, true)?;
if cols.is_empty() {
// 没有可写列 ⇒ 这行不用动(Java 那边也是空 UPDATE 跳过)
continue;
}
subs.push(render_update(
&sub_model.table,
&cols,
&sub_pk,
&key,
SqlKind::UpdateSub,
)?);
}
// ---- 新增行 ----
for row in diff.inserts.iter() {
let key = row_key_of(row, &sub_pk).unwrap_or_default();
if key.is_empty() {
return Err(SqlError::NoPrimaryKey(sub_model.table.clone()));
}
let mut cols = sub_row_columns(sub, sub_model, &sub_guard, row, ctx, false)?;
// 🔴 主键:子表行主键由调用方(内核)生成 —— Java 侧是 `RandomUtil.uuId()`。
// `diff_sub_rows` 已经把生成的主键写回行对象了 ⇒ 这里取出来写进列。
if !cols.iter().any(|(c, _)| c.eq_ignore_ascii_case(&sub_pk)) {
cols.insert(
0,
(sub_pk.clone(), Value::String(key.clone())),
);
}
// 🔴 外键:子表指向主表的关联列。
// Java `updateTable()`:`generalInsertDSL.set(foreignKey).toValue(foreignValue)`。
if !sub_ctx.foreign_key_column.is_empty()
&& !cols
.iter()
.any(|(c, _)| c.eq_ignore_ascii_case(&sub_ctx.foreign_key_column))
{
cols.push((
sub_ctx.foreign_key_column.clone(),
Value::String(sub_ctx.foreign_key_value.clone()),
));
}
// 🔴 租户:Java `addTenantId()` 对子表也写。
if let Some(tenant_col) = &sub_guard.tenant_id {
if let Some(tid) = &ctx.tenant_id {
if !cols.iter().any(|(c, _)| c.eq_ignore_ascii_case(tenant_col)) {
cols.push((tenant_col.clone(), Value::String(tid.clone())));
}
}
}
subs.push(render_insert(
&sub_model.table,
&cols,
SqlKind::InsertSub,
)?);
}
}
plan.subs = subs;
Ok(plan)
}
/// 取子表一行的可写列(列名 + 值)。
///
/// `is_update` ⇒ 更新语义(不写外键、不写创建人/创建时间);
/// `false` ⇒ 新增语义。
///
/// 🔴 返回**单一** `Vec<(列名, 值)>` —— 不再返回平行的 `params` 数组。
/// 两个平行数组靠下标对齐,少 push 一次就会「列数 ≠ 参数数」,
/// 而且不会报错,只会把值错位写到别的列上(静默写坏数据)。
fn sub_row_columns(
sub: &FieldNode,
sub_model: &TableSchema,
sub_guard: &ColumnGuard,
row: &Value,
ctx: &WriteContext,
is_update: bool,
) -> Result<Vec<(String, Value)>, SqlError> {
let mut cols: Vec<(String, Value)> = Vec::new();
for child in &sub.children {
let Some(col) = child.column_name() else { continue };
if !sub_guard.allows(&col) {
continue;
}
let raw = lookup(row, &child.v_model, &col);
let fill = auto_fill(&child.jnpf_key);
// 🔴 更新语义:Java 在 `isUpdate` 时**跳过**创建人/创建时间/组织/岗位
// (`updateTable()` 的 `isUpdate && (CURRORGANIZE || CURRPOSITION ||
// CREATETIME || CREATEUSER)` 分支)—— 更新时不能改「谁创建的」。
// 新增语义下反过来:修改人/修改时间在新增时应置空。
if is_update
&& matches!(
fill,
AutoFill::CurrentOrganizeIds | AutoFill::CurrentPositionIds | AutoFill::Now
| AutoFill::CurrentUserId
)
{
continue;
}
if !is_update && matches!(fill, AutoFill::ModifyTime | AutoFill::ModifyUser) {
// 新增时「最后修改人/时间」置空(Java `create()` 的两个分支都是 null)
cols.push((col, Value::Null));
continue;
}
if fill.overrides_input() && !is_update {
// 新增:系统字段由后端填
let value = match fill {
AutoFill::CurrentUserId => Value::String(ctx.user_id.clone().unwrap_or_default()),
AutoFill::Now => match &ctx.now {
Some(t) => Value::String(t.clone()),
None => Value::Null,
},
AutoFill::CurrentOrganizeIds => Value::String(json_array(&ctx.organize_ids)),
AutoFill::CurrentPositionIds => Value::String(json_array(&ctx.position_ids)),
AutoFill::BillNumber => ctx
.bill_numbers
.get(&child.v_model)
.cloned()
.or_else(|| ctx.bill_numbers.get(&col).cloned())
.unwrap_or(Value::Null),
_ => Value::Null,
};
if !cols.iter().any(|(c, _)| c == &col) {
cols.push((col, value));
}
continue;
}
if fill.overrides_input() && is_update {
// 🔴 更新:最后修改时间/人由后端填,其余系统字段跳过。
// Java `update()`:`MODIFYTIME` 写当前时间、`MODIFYUSER` 写当前用户 id。
// (之前两者都归到 `Null`,更新时被整段跳过 ⇒ 审计链断掉。)
let value = match fill {
AutoFill::ModifyTime => match &ctx.now {
Some(t) => Value::String(t.clone()),
None => Value::Null,
},
AutoFill::ModifyUser => match &ctx.user_id {
Some(u) => Value::String(u.clone()),
None => Value::Null,
},
_ => continue,
};
if !cols.iter().any(|(c, _)| c == &col) {
cols.push((col, value));
}
continue;
}
let value = match raw {
Some(v) => normalize_value(v, &col)?,
None => {
if child.required {
return Err(SqlError::MissingRequired {
table: sub_model.table.clone(),
column: col.clone(),
label: child.label.clone(),
});
}
continue;
}
};
if !cols.iter().any(|(c, _)| c == &col) {
cols.push((col, value));
}
}
Ok(cols)
}
/// 逻辑删除子表的一行(置删除标记)。
///
/// 🔴 表里没有删除标记列 ⇒ **报错**(`LogicalDeleteUnsupported`),
/// 不退化成物理删 —— 动态建表时主表与子表的删除列同进同退,
/// 子表缺删除列说明表建错了,静默物理删会毁掉审计链。
fn soft_delete_row(
sub_model: &TableSchema,
pk_col: &str,
pk_value: &str,
ctx: &WriteContext,
) -> Result<Sql, SqlError> {
let mut cols: Vec<(String, Value)> = Vec::new();
let mark_col = find_column(sub_model, sys::DELETE_MARK).ok_or_else(|| {
SqlError::LogicalDeleteUnsupported(sub_model.table.clone())
})?;
// 🔴 写 **1**,不是 `true`。
// 官方真实 DDL:`f_delete_mark INTEGER`;Java `TableFeildsEnum.DELETEMARK`
// 的 dataType 也是 `"int"`;基线平台 `FlowFormDataUtil` 写的是 `equalTo(1)`。
// 写 boolean ⇒ 执行层转成字符串 `"true"` ⇒ PG 报
// `invalid input syntax for type integer: "true"`。
cols.push((mark_col, Value::from(1)));
if let Some(t) = &ctx.now {
if let Some(c) = find_column(sub_model, sys::DELETE_TIME) {
cols.push((c, Value::String(t.clone())));
}
}
if let Some(uid) = &ctx.user_id {
if let Some(c) = find_column(sub_model, sys::DELETE_USER_ID) {
cols.push((c, Value::String(uid.clone())));
}
}
render_update(
&sub_model.table,
&cols,
pk_col,
pk_value,
SqlKind::SoftDelete,
)
}
/// 生成**逻辑删除**的 SQL。
///
/// 对齐基线平台:只置逻辑删除标记 + 删除时间/人,**不物理删除**。
///
/// ## 🔴 逻辑删除的列**只在表里有这些列时**才写 ——
/// 实测 `test_receivable` 的 `logicalDelete = false`,表里根本没有删除标记列。
///
/// ## 🔴 一列都没有 ⇒ **报错**,不生成空 UPDATE
///
/// 动态建表时删除列是跟着 `logicalDelete` 一起加的(主表 + 子表同进同退)。
/// ⇒ 表里没有删除列 = 「这张表不支持逻辑删除」。
/// 生成空 UPDATE 等于「什么都没删,但返回成功」—— 用户以为删了,实际行还在。
pub fn plan_soft_delete(
model: &ModelSchema,
ctx: &WriteContext,
main_id: &str,
) -> Result<Sql, SqlError> {
let main_table = model.main_table().ok_or(SqlError::NoMainTable)?;
let guard = guard_for(main_table)?;
let pk_col = guard
.primary_key
.clone()
.unwrap_or_else(|| sys::F_ID.to_string());
// 🔴 逻辑删除标记列必须有 —— 没有就是「这张表不支持逻辑删除」。
let mark_col = find_column(main_table, sys::DELETE_MARK).ok_or_else(|| {
SqlError::LogicalDeleteUnsupported(main_table.table.clone())
})?;
let mut cols: Vec<(String, Value)> = Vec::new();
// 🔴 写 **1**,不是 `true`。
// 官方真实 DDL:`f_delete_mark INTEGER`;Java `TableFeildsEnum.DELETEMARK`
// 的 dataType 也是 `"int"`;基线平台 `FlowFormDataUtil` 写的是 `equalTo(1)`。
// 写 boolean ⇒ 执行层转成字符串 `"true"` ⇒ PG 报
// `invalid input syntax for type integer: "true"`。
cols.push((mark_col, Value::from(1)));
if let Some(t) = &ctx.now {
if let Some(c) = find_column(main_table, sys::DELETE_TIME) {
cols.push((c, Value::String(t.clone())));
}
}
if let Some(uid) = &ctx.user_id {
if let Some(c) = find_column(main_table, sys::DELETE_USER_ID) {
cols.push((c, Value::String(uid.clone())));
}
}
if let Some(t) = &ctx.now {
if let Some(c) = find_column(main_table, sys::LAST_MODIFY_TIME) {
cols.push((c, Value::String(t.clone())));
} else if let Some(c) = find_column(main_table, "lastmodifytime") {
cols.push((c, Value::String(t.clone())));
}
}
Ok(render_update(
&main_table.table,
&cols,
&pk_col,
main_id,
SqlKind::SoftDelete,
)?)
}
/// 生成**物理删除**的 SQL。
///
/// ## 🔴 为什么需要这条路径
///
/// 基线平台 `FlowFormDataUtil.deleteTable()`:
/// ```java
/// if (logicalDelete) { UPDATE ... SET delete_mark = 1 ... }
/// else { DELETE FROM ... WHERE pk = ?; }
/// ```
///
/// ⇒ `logicalDelete = false` 的表**必须物理 DELETE**。
/// 退化成「空 UPDATE」会留下一行永远还在的数据(列表里还查得到),
/// 比删不掉更糟 —— 用户以为删了,实际没删。
pub fn plan_hard_delete(
model: &ModelSchema,
main_id: &str,
) -> Result<Sql, SqlError> {
let main_table = model.main_table().ok_or(SqlError::NoMainTable)?;
let guard = guard_for(main_table)?;
let pk_col = guard
.primary_key
.clone()
.unwrap_or_else(|| sys::F_ID.to_string());
render_delete(&main_table.table, &pk_col, main_id, SqlKind::HardDelete)
}
/// 一次删除的计划(主表 + 子表)。
#[derive(Debug, Clone, PartialEq)]
pub struct DeletePlan {
/// 主表删除语句(逻辑或物理)。
pub main: Sql,
/// 子表删除语句(按外键批量删)。
pub subs: Vec<Sql>,
}
impl DeletePlan {
/// 全部 SQL(主表在前 —— 顺序与基线平台相反,见下)。
///
/// 🔴 **顺序**:基线平台是「先删主表、再删子表」;
/// 这里**必须反过来**(先子表后主表),否则主表删完、
/// 子表那批 `DELETE ... WHERE fk = ?` 仍能执行(FK 约束在 PG 里默认不级联、
/// 且我们不建 FK 约束),但如果将来建了 FK 约束就会**违反外键约束**。
/// 先删子表 ⇒ 主表还在时子表已清空 ⇒ 任何时刻都不违反约束。
pub fn all(&self) -> Vec<&Sql> {
let mut v: Vec<&Sql> = self.subs.iter().collect();
v.push(&self.main);
v
}
/// 一共几条 SQL。
pub fn len(&self) -> usize {
1 + self.subs.len()
}
/// 恒不为空(主表 SQL 恒存在)。
pub fn is_empty(&self) -> bool {
false
}
}
/// 生成一次**删除**的完整计划(主表 + 子表级联)。
///
/// ## 🔴 语义严格对齐 `FlowFormDataUtil.deleteTable()`
///
/// 1. `logicalDelete = true` ⇒ 主表置删除标记,子表也置删除标记;
/// 2. `logicalDelete = false` ⇒ 主表**物理 DELETE**,子表**物理 DELETE**;
/// 3. 子表删除条件用**外键列 = 主表关联列的值**,
/// 不是「子表主键 = 主表主键」—— 外键列来自模型 `tableField`,
/// 关联值来自模型 `relationField` 指向的主表列。
///
/// ## 🔴 子表外键的值从哪来
///
/// 基线平台:`Object relationFieldValue = mainMap.get(table.getRelationField());`
/// —— 读的是**主表那一行的实际值**,不是主键。
/// 例:主表 `relationField = F_Code`(业务编码),
/// 子表 `tableField = F_Code_Ref` ⇒ 子表外键值 = 主表的业务编码。
/// 这与「子表外键 = 主表主键」不是一回事 —— 官方 fixture 里两者恰好都指向 `f_id`,
/// 但那是巧合,不能当规则。
pub fn plan_delete(
form: &FormSchema,
model: &ModelSchema,
ctx: &WriteContext,
main_id: &str,
) -> Result<DeletePlan, SqlError> {
let logical = form.logical_delete.unwrap_or(false);
// 主表必须存在(没有主表谈不上删除一条记录)。
model.main_table().ok_or(SqlError::NoMainTable)?;
// 🔴 子表外键的值**按子表各算**(`relationField` 定义在子表模型上)——
// 不同子表可能指向不同的主表列,不能在主表层面统一取。
// ---- 子表:按外键批量删 ----
let mut subs = Vec::new();
for sub in form.sub_tables() {
let Some(sub_model) = resolve_sub_table(model, sub).ok() else {
continue;
};
let Some(fk_col) = sub_model.foreign_key_column() else {
// 基线平台:`foreignField == null` ⇒ 抛 SQL 异常(不是跳过)。
return Err(SqlError::UnknownColumn {
table: sub_model.table.clone(),
column: "tableField".to_string(),
});
};
// 🔴 子表没有删除标记列时,逻辑删除会退化成物理删 ——
// 先确认这张表真的在模型里(guard_for 会校验列白名单非空)。
let _sub_guard = guard_for(sub_model)?;
// 🔴 外键的值:子表 `relationField` 指向的主表列的实际值。
// `relationField` 定义在**子表模型**上(基线平台:
// `mainMap.get(table.getRelationField())` —— `table` 是子表的 TableModel)。
// 若它指向的不是主键 ⇒ 值只能由调用方查库后登记进 `ctx.relation_values`;
// 拿不到就**报错**,绝不猜(猜错 = 删错行的子表数据)。
let relation_value = ctx
.relation_value(sub_model)
.unwrap_or_else(|| main_id.to_string());
let sql = if logical {
// 逻辑删除:置删除标记。
// 🔴 子表没有删除标记列 ⇒ **报错**,不静默物理删
// (动态建表时主表与子表的删除列同进同退)。
let mark_col = find_column(sub_model, sys::DELETE_MARK).ok_or_else(|| {
SqlError::LogicalDeleteUnsupported(sub_model.table.clone())
})?;
let mut cols: Vec<(String, Value)> = Vec::new();
// 🔴 写 **1**,不是 `true`(`f_delete_mark` 是 INTEGER —— 见上)。
cols.push((mark_col, Value::from(1)));
if let Some(t) = &ctx.now {
if let Some(c) = find_column(sub_model, sys::DELETE_TIME) {
cols.push((c, Value::String(t.clone())));
}
}
if let Some(uid) = &ctx.user_id {
if let Some(c) = find_column(sub_model, sys::DELETE_USER_ID) {
cols.push((c, Value::String(uid.clone())));
}
}
render_update(
&sub_model.table,
&cols,
&fk_col,
&relation_value,
SqlKind::SoftDelete,
)?
} else {
// 物理删除:按**外键列**删(不是按子表主键)
render_delete_by_column(
&sub_model.table,
&fk_col,
&relation_value,
SqlKind::HardDelete,
)?
};
subs.push(sql);
}
// ---- 主表 ----
let main = if logical {
plan_soft_delete(model, ctx, main_id)?
} else {
plan_hard_delete(model, main_id)?
};
Ok(DeletePlan { main, subs })
}
/// 渲染「按任意列删」(`DELETE FROM t WHERE <col> = $1`)。
fn render_delete_by_column(
table: &str,
col: &str,
value: &str,
kind: SqlKind,
) -> Result<Sql, SqlError> {
check_identifier("表名", table)?;
check_identifier("列名", col)?;
Ok(Sql {
text: format!("DELETE FROM {} WHERE {} = $1", table, col),
params: vec![Value::String(value.to_string())],
param_columns: vec![col.to_string()],
table: table.to_string(),
kind,
})
}
/// 在表定义里按**列名特征**找一个列(大小写不敏感,`contains`)。
///
/// 这是「系统列名从模型推导」的核心工具:只认**特征**,不认具体名字 ——
/// `f_creatortime` 与 `f_creator_time` 都含 `creatortime`/`creator_time`,
/// 具体用哪个由模型说了算。
fn find_column(table: &TableSchema, feature: &str) -> Option<String> {
table
.fields
.iter()
.filter_map(|c| c.resolved_column())
.find(|c| c.to_lowercase().contains(&feature.to_lowercase()))
}
/// 🔴 找出子表节点对应的**物理表**。
///
/// ## 为什么不能「取第一个非主表」
///
/// 官方数据里一张功能可能带**多个子表**。按顺序取第一个 ⇒
/// 第二个子表的数据会被写进第一个子表的表里 —— 静默串表,最难查。
///
/// ## 解析顺序(从强到弱)
/// 1. `__config__.relationTable`(子表字段的 `relationTable` 明确指向子表)—— 最可信
/// 2. 子表节点的 `__config__.tableName`
/// 3. 都没有 ⇒ 只有一个子表时用它;有多个 ⇒ **报错**(不猜)
fn resolve_sub_table<'a>(
model: &'a ModelSchema,
sub: &FieldNode,
) -> Result<&'a TableSchema, SqlError> {
// ① 子表节点的 tableName
if let Some(name) = sub.table_name.as_deref() {
if let Some(t) = model.table(name) {
return Ok(t);
}
}
// ② 子表字段的 relationTable(子节点的 __config__ 里)
for child in &sub.children {
if let Some(rt) = child.relation_table.as_deref() {
if let Some(t) = model.table(rt) {
return Ok(t);
}
}
}
// ③ 兜底:只有一个子表就用它
let subs = model.sub_tables();
match subs.len() {
0 => Err(SqlError::UnknownTable(sub.v_model.clone())),
1 => Ok(subs[0]),
_ => Err(SqlError::UnknownTable(sub.v_model.clone())),
}
}
/// 渲染 INSERT。
///
/// 🔴 **列与值必须同源** —— 这里只收 `cols: &[(String, Value)]`,
/// 参数由函数自己从 `cols` 生成。
/// 之前是「`cols` 数组 + 平行的 `params` 数组」两个独立入参,
/// 靠下标对齐 —— 少 push 一次就会**列数 ≠ 参数数**,
/// 而且不报错,只是把值错位写到别的列上(静默写坏数据)。
/// 从类型上收口,两个数组就不可能不一致。
fn render_insert(
table: &str,
cols: &[(String, Value)],
kind: SqlKind,
) -> Result<Sql, SqlError> {
check_identifier("表名", table)?;
for (c, _) in cols {
check_identifier("列名", c)?;
}
let names: Vec<&str> = cols.iter().map(|(c, _)| c.as_str()).collect();
let marks: Vec<String> = (1..=cols.len()).map(|i| format!("${i}")).collect();
let text = format!(
"INSERT INTO {} ({}) VALUES ({})",
table,
names.join(", "),
marks.join(", ")
);
Ok(Sql {
text,
params: cols.iter().map(|(_, v)| v.clone()).collect(),
param_columns: cols.iter().map(|(c, _)| c.clone()).collect(),
table: table.to_string(),
kind,
})
}
/// 渲染 UPDATE。
///
/// 🔴 **必须有 WHERE** —— 没有 WHERE 的 UPDATE 会把整张表改成同一个值。
/// 这是本模块最危险的一处,故由 `render_update` 统一收口,不给调用方绕过的机会。
///
/// 🔴 **主键只出现在 WHERE,不出现在 SET** —— 写主键等于「改主键」,
/// 而主键是对外契约(子表外键指向它)⇒ 改了就产生孤儿行。
///
/// 🔴 **列与值同源** —— 同 [`render_insert`]:只收 `cols`,
/// 参数自己生成,杜绝「列数 ≠ 参数数」把值错位写到别的列。
fn render_update(
table: &str,
cols: &[(String, Value)],
pk_col: &str,
pk_value: &str,
kind: SqlKind,
) -> Result<Sql, SqlError> {
check_identifier("表名", table)?;
check_identifier("列名", pk_col)?;
for (c, _) in cols {
check_identifier("列名", c)?;
}
if pk_value.is_empty() {
return Err(SqlError::NoPrimaryKey(table.to_string()));
}
// 🔴 主键不能被写进 SET(哪怕值相同,改主键 = 改对外契约)
let mut all_params: Vec<Value> = Vec::new();
let mut param_columns: Vec<String> = Vec::new();
let mut sets: Vec<String> = Vec::new();
for (c, v) in cols {
if c.eq_ignore_ascii_case(pk_col) {
continue;
}
sets.push(format!("{c} = ${}", all_params.len() + 1));
all_params.push(v.clone());
param_columns.push(c.clone());
}
if sets.is_empty() {
return Err(SqlError::NoColumnsToUpdate(table.to_string()));
}
let pk_index = all_params.len() + 1;
all_params.push(Value::String(pk_value.to_string()));
// WHERE 里的主键占位符也带上列名 —— 执行层要按它 cast(主键常是 uuid 文本)
param_columns.push(pk_col.to_string());
let text = format!(
"UPDATE {} SET {} WHERE {} = ${}",
table,
sets.join(", "),
pk_col,
pk_index
);
Ok(Sql {
text,
params: all_params,
param_columns,
table: table.to_string(),
kind,
})
}
/// 渲染 DELETE。
///
/// 🔴 **必须有 WHERE** —— 没有 WHERE 的 DELETE 会清空整张表。
fn render_delete(
table: &str,
pk_col: &str,
pk_value: &str,
kind: SqlKind,
) -> Result<Sql, SqlError> {
check_identifier("表名", table)?;
check_identifier("列名", pk_col)?;
if pk_value.is_empty() {
return Err(SqlError::NoPrimaryKey(table.to_string()));
}
Ok(Sql {
text: format!("DELETE FROM {} WHERE {} = $1", table, pk_col),
params: vec![Value::String(pk_value.to_string())],
param_columns: vec![pk_col.to_string()],
table: table.to_string(),
kind,
})
}
/// 标识符合法性检查(只允许字母/数字/下划线,且不以数字开头)。
///
/// 🔴 表名与列名来自**用户可编辑的 JSON**(`f_tables_data`),
/// 即使过了「在模型里」的白名单,也要再过一道字符检查 ——
/// 防止模型定义里被人塞了 `"t; DROP TABLE x"`。
///
/// ## 🔴 为什么是 `pub`
///
/// 执行层(内核)也要**动态拼查询 SQL**(查子表旧行、查主表关联列)——
/// 那里的表名列名同样来自模型定义,同样必须过这道检查。
/// 规则只有一份(在这里),两边复用 ⇒ 不会出现「生成层拦了、执行层没拦」的漏洞。
pub fn check_identifier(kind: &'static str, value: &str) -> Result<(), SqlError> {
let ok = !value.is_empty()
&& value
.chars()
.all(|c| c.is_ascii_alphanumeric() || c == '_')
&& !value.starts_with(|c: char| c.is_ascii_digit());
if ok {
Ok(())
} else {
Err(SqlError::IllegalIdentifier {
kind,
value: value.to_string(),
})
}
}
/// 在 payload 里找值:先按设计态字段名,再按物理列名(大小写不敏感)。
///
/// 🔴 **pub 是有意的**:内核侧的唯一性 / 业务主键校验必须用**同一份**取值规则
/// —— 若校验层另写一份「按列名找值」,就会与 SQL 生成层对同一个字段
/// 得出不同结论(一个认为给了值、另一个认为没给)⇒ 校验通过但写进去是 NULL。
pub fn lookup(payload: &Value, v_model: &str, column: &str) -> Option<Value> {
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(column) {
return Some(v.clone());
}
}
None
}
/// 在 payload 里找子表行数组。
fn lookup_sub_rows(payload: &Value, v_model: &str, table: &str) -> Option<Value> {
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
}
/// 值归一化:空串 → NULL、空数组 → NULL、列表 → JSON 字符串。
///
/// 对齐基线平台的 `getInsertDSL()` + `valueToNull()`:
/// - `data == null || StringUtils.isEmpty(data.toString())` → `toNull()`
/// - 空 List → null
/// - 非空 List → `JsonUtil.getObjectToString(data)`(JSON 字符串)
fn normalize_value(v: Value, column: &str) -> Result<Value, SqlError> {
match v {
Value::Null => Ok(Value::Null),
Value::String(s) => {
if s.is_empty() {
Ok(Value::Null)
} else {
Ok(Value::String(s))
}
}
Value::Array(a) => {
if a.is_empty() {
Ok(Value::Null)
} else {
// 🔴 数组一律序列化成 JSON 字符串(前端多选/子表就是这么存的)
Ok(Value::String(
serde_json::to_string(&Value::Array(a)).unwrap_or_default(),
))
}
}
Value::Object(_) => Err(SqlError::UnsupportedValue {
column: column.to_string(),
}),
other => Ok(other),
}
}
/// id 列表 → JSON 数组字符串。
fn json_array(ids: &[String]) -> String {
serde_json::to_string(&ids).unwrap_or_else(|_| "[]".to_string())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::form::FormSchema;
use crate::model::ModelSchema;
/// 最小表单:一个 billRule + 一个必填 input。
const FORM: &str = r#"{
"formRef": "formRef", "formModel": "formData",
"fields": [
{ "__vModel__": "F_Code", "__config__": { "jnpfKey": "billRule", "label": "单号", "layout": "colFormItem", "tableName": "biz_main" } },
{ "__vModel__": "F_Room", "__config__": { "jnpfKey": "input", "label": "房间", "layout": "colFormItem", "tableName": "biz_main", "required": true } }
]
}"#;
/// 最小模型:一张主表。
///
/// 🔴 列名**刻意模仿官方数据的真实形态**:
/// - `F_Id` → `f_id`(主键)
/// - `F_CreatorTime` → `f_creatortime`(**没有下划线** —— 官方就是这样)
/// - `f_tenant_id` → 租户列(**也是 primaryKey=1** ⇒ 不能选成主键)
const MODEL: &str = r#"[
{ "table": "biz_main", "tableName": "主表", "typeId": "1", "fields": [
{ "field": "F_Id", "columnName": null, "dataType": "varchar", "primaryKey": 1 },
{ "field": "F_Code", "columnName": null, "dataType": "varchar" },
{ "field": "F_Room", "columnName": null, "dataType": "varchar" },
{ "field": "F_CreatorTime", "columnName": null, "dataType": "datetime" },
{ "field": "f_tenant_id", "columnName": null, "dataType": "varchar", "primaryKey": 1 }
]}
]"#;
fn form() -> FormSchema {
FormSchema::from_str(FORM).expect("表单应可解析")
}
fn model() -> ModelSchema {
ModelSchema::from_str(MODEL).expect("模型应可解析")
}
/// 🔴 带「最后修改时间/人」列的模型(列名形态照官方:`f_lastmodifytime`)。
const MODEL_WITH_MODIFY: &str = r#"[
{ "table": "biz_main", "tableName": "主表", "typeId": "1", "fields": [
{ "field": "F_Id", "columnName": null, "dataType": "varchar", "primaryKey": 1 },
{ "field": "F_Room", "columnName": null, "dataType": "varchar" },
{ "field": "F_LastModifyTime", "columnName": null, "dataType": "datetime" },
{ "field": "F_LastModifyUserId", "columnName": null, "dataType": "varchar" },
{ "field": "f_tenant_id", "columnName": null, "dataType": "varchar", "primaryKey": 1 }
]}
]"#;
fn model_with_modify() -> ModelSchema {
ModelSchema::from_str(MODEL_WITH_MODIFY).expect("模型应可解析")
}
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
}
/// 从 INSERT 语句里取出列清单(按顺序)。
fn insert_columns(sql: &Sql) -> Vec<String> {
sql.text
.split_once(" (")
.expect("INSERT 应有列清单")
.1
.split_once(") VALUES")
.expect("INSERT 应有 VALUES")
.0
.split(", ")
.map(|s| s.to_string())
.collect()
}
/// 🔴 UPDATE 必须带 WHERE —— 没有 WHERE 的 UPDATE 会改全表。
#[test]
fn update_always_has_where_clause() {
let plan = plan_update(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"main-1",
)
.expect("应能生成更新计划");
assert!(
plan.main.text.contains("WHERE f_id = $"),
"UPDATE 缺 WHERE 子句: {}",
plan.main.text
);
assert!(!plan.main.text.contains("A-101"), "值被拼进 SQL 文本了");
}
/// 🔴 空主键必须报错 —— 否则会退化成 UPDATE 全表。
#[test]
fn update_rejects_empty_primary_key() {
let err = plan_update(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"",
)
.expect_err("空主键必须被拒");
assert_eq!(err.code(), "NO_PRIMARY_KEY");
}
/// INSERT 的值必须全部走占位符。
#[test]
fn insert_uses_placeholders_only() {
let plan = plan_insert(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"main-1",
)
.expect("应能生成新增计划");
assert!(plan.main.text.contains("VALUES ($1"), "应有占位符: {}", plan.main.text);
assert!(!plan.main.text.contains("A-101"));
assert_eq!(plan.main.params.len(), plan.main.text.matches('$').count());
}
/// 🔴 必填字段没给值 ⇒ 报错(而不是写 NULL)。
#[test]
fn missing_required_field_is_rejected() {
let err = plan_insert(
&form(),
&model(),
&serde_json::json!({}),
&ctx(),
"main-1",
)
.expect_err("必填缺失必须被拒");
assert_eq!(err.code(), "MISSING_REQUIRED");
}
/// 🔴 系统生成字段不被入参覆盖。
#[test]
fn system_generated_field_ignores_payload() {
let plan = plan_insert(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101", "F_Code": "用户伪造的单号" }),
&ctx(),
"main-1",
)
.expect("应能生成新增计划");
assert!(
!plan
.main
.params
.iter()
.any(|p| p.as_str() == Some("用户伪造的单号")),
"入参覆盖了系统生成的单号: {:?}",
plan.main.params
);
}
/// 🔴 主键**不能**选成租户列(官方模型里 `f_tenant_id` 也是 primaryKey=1)。
#[test]
fn tenant_column_is_never_used_as_primary_key() {
let plan = plan_insert(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"main-1",
)
.unwrap();
let cols = insert_columns(&plan.main);
// 主键列应是 f_id(第一个)
assert_eq!(cols[0], "f_id", "主键选错了: {cols:?}");
// 租户列单独写,且值是租户 id
let tenant_idx = cols
.iter()
.position(|c| c == "f_tenant_id")
.expect("应有租户列");
assert_eq!(plan.main.params[tenant_idx], Value::String("0".into()));
}
/// 🔴 反自证:系统列名**不能硬编码**。
///
/// 官方模型里 `F_CreatorTime` 的列是 `f_creatortime`(无下划线)。
/// 若代码里写死 `f_creator_time`,真实库上直接 `column does not exist`。
///
/// 断言方式:带 `createTime` 控件的表单,生成出来的列必须是**模型里的**那个。
#[test]
fn system_columns_come_from_model_not_hardcoded() {
let f = FormSchema::from_str(
r#"{"fields":[
{"__vModel__":"F_CreatorTime","__config__":{"jnpfKey":"createTime","label":"创建时间","tableName":"biz_main"}}
]}"#,
)
.unwrap();
let plan = plan_insert(&f, &model(), &serde_json::json!({}), &ctx(), "main-1").unwrap();
let cols = insert_columns(&plan.main);
assert!(
cols.iter().any(|c| c == "f_creatortime"),
"应使用模型推导出的列名: {cols:?}"
);
assert!(
!cols.iter().any(|c| c == "f_creator_time"),
"出现了硬编码的 f_creator_time —— 真实库上会 column does not exist: {cols:?}"
);
}
/// 🔴 表里没有的列**不许**出现在 INSERT 里(否则真实库报 column does not exist)。
#[test]
fn no_column_outside_model_is_emitted() {
let plan = plan_insert(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"main-1",
)
.unwrap();
let cols = insert_columns(&plan.main);
let allowed = model().main_table().unwrap().column_names();
for c in &cols {
assert!(
allowed.contains(c),
"列 {c} 不在模型里: {cols:?}"
);
}
}
/// 🔴 标识符注入:模型里塞了带分号的表名必须被拒。
#[test]
fn identifier_injection_is_rejected() {
let evil = ModelSchema::from_str(
r#"[{ "table": "biz_main; DROP TABLE users", "tableName": "坏表", "typeId": "1", "fields": [
{ "field": "F_Id", "columnName": "f_id", "primaryKey": true }
]}]"#,
)
.unwrap();
let err = plan_insert(&form(), &evil, &serde_json::json!({}), &ctx(), "m1")
.expect_err("非法标识符必须被拒");
assert_eq!(err.code(), "ILLEGAL_IDENTIFIER");
}
/// 列白名单:表单引用了模型里没有的列 ⇒ 跳过而不是报错。
#[test]
fn column_not_in_model_is_skipped() {
let f = FormSchema::from_str(
r#"{"fields":[
{"__vModel__":"F_Ghost","__config__":{"jnpfKey":"input","label":"幽灵列","tableName":"biz_main"}}
]}"#,
)
.unwrap();
let plan = plan_insert(&f, &model(), &serde_json::json!({ "F_Ghost": "x" }), &ctx(), "m1")
.expect("应能生成计划");
let cols = insert_columns(&plan.main);
assert!(
!cols.iter().any(|c| c == "f_ghost"),
"模型里没有的列不应出现在 INSERT 里: {cols:?}"
);
}
/// 空模型 ⇒ 解析失败。
#[test]
fn empty_model_array_fails_to_parse() {
assert!(ModelSchema::from_str("[]").is_err());
}
/// 逻辑删除:**表里没有删除列 ⇒ 报错**(不是生成空 UPDATE)。
///
/// 🔴 生成空 UPDATE = 「什么都没删但返回成功」—— 用户以为删了,实际行还在。
#[test]
fn soft_delete_rejects_table_without_delete_columns() {
let err = plan_soft_delete(&model(), &ctx(), "main-1")
.expect_err("没有删除列的表不支持逻辑删除");
assert_eq!(err.code(), "LOGICAL_DELETE_UNSUPPORTED");
}
/// 逻辑删除:表里**有**删除列时,正常生成带 WHERE 的 UPDATE。
#[test]
fn soft_delete_writes_delete_columns_when_present() {
let model = ModelSchema::from_str(
r#"[{ "table": "biz_main", "typeId": "1", "fields": [
{ "field": "F_Id", "columnName": "f_id", "primaryKey": 1 },
{ "field": "f_delete_mark", "columnName": "f_delete_mark", "dataType": "int" },
{ "field": "f_delete_time", "columnName": "f_delete_time", "dataType": "timestamp" }
]}]"#,
)
.unwrap();
let sql = plan_soft_delete(&model, &ctx(), "main-1").expect("应能生成");
assert!(
sql.text.contains("WHERE f_id = $"),
"逻辑删除必须带 WHERE: {}",
sql.text
);
assert!(
sql.text.contains("f_delete_mark"),
"应写删除标记: {}",
sql.text
);
assert_eq!(sql.kind, SqlKind::SoftDelete);
}
/// 空串 → NULL(对齐基线 `valueToNull()`)。
#[test]
fn empty_string_becomes_null() {
let plan = plan_insert(
&form(),
&model(),
&serde_json::json!({ "F_Room": "" }),
&ctx(),
"m1",
)
.unwrap();
let cols = insert_columns(&plan.main);
let idx = cols.iter().position(|c| c == "f_room").expect("应有 f_room");
assert!(
plan.main.params[idx].is_null(),
"空串应归一化成 NULL,实际: {:?}",
plan.main.params[idx]
);
}
/// 空数组 → NULL(前端多选清空时的常见形态)。
#[test]
fn empty_array_becomes_null() {
let plan = plan_insert(
&form(),
&model(),
&serde_json::json!({ "F_Room": [] }),
&ctx(),
"m1",
)
.unwrap();
let cols = insert_columns(&plan.main);
let idx = cols.iter().position(|c| c == "f_room").expect("应有 f_room");
assert!(
plan.main.params[idx].is_null(),
"空数组应归一化成 NULL,实际: {:?}",
plan.main.params[idx]
);
}
/// 非空数组 → JSON 字符串(前端多选就是这么存的)。
#[test]
fn non_empty_array_becomes_json_string() {
let plan = plan_insert(
&form(),
&model(),
&serde_json::json!({ "F_Room": ["A", "B"] }),
&ctx(),
"m1",
)
.unwrap();
let cols = insert_columns(&plan.main);
let idx = cols.iter().position(|c| c == "f_room").expect("应有 f_room");
assert_eq!(
plan.main.params[idx],
Value::String(r#"["A","B"]"#.into()),
"非空数组应序列化成 JSON 字符串"
);
}
/// 🔴 反自证:如果 WHERE 被谁删掉,这把尺子必须变红。
#[test]
fn every_update_like_sql_has_where() {
let model = ModelSchema::from_str(
r#"[{ "table": "biz_main", "typeId": "1", "fields": [
{ "field": "F_Id", "columnName": "f_id", "primaryKey": 1 },
{ "field": "F_Room", "columnName": "f_room" },
{ "field": "f_delete_mark", "columnName": "f_delete_mark" }
]}]"#,
)
.unwrap();
let ups = [
plan_update(&form(), &model, &serde_json::json!({ "F_Room": "x" }), &ctx(), "m1")
.unwrap()
.main,
plan_soft_delete(&model, &ctx(), "m1").unwrap(),
];
for s in ups {
assert!(
s.text.contains(" WHERE "),
"{} 缺 WHERE —— 会改全表: {}",
s.kind.as_str(),
s.text
);
}
}
// ---------------------------------------------------------------
// 子表差集对账(对齐 Java `FlowFormDataUtil.updateTable()`)
// ---------------------------------------------------------------
/// 差集上下文(旧行主键 = `old-1` / `old-2`)。
fn sub_ctx(old_keys: &[&str], logical: bool) -> SubUpdateContext {
SubUpdateContext::new(
old_keys.iter().map(|s| s.to_string()).collect(),
"f_main_id",
"main-1",
SubUpdateOptions {
only_update: false,
logical_delete: logical,
},
)
}
/// 🔴 三种归属必须分清:更新 / 新增 / 删除。
///
/// 对齐 Java:
/// ```java
/// deleteList = childIdList 中不在 formDataIdList 的;
/// 主键在 childIdList 里 ⇒ UPDATE,否则 ⇒ INSERT
/// ```
#[test]
fn diff_classifies_update_insert_and_delete() {
let rows = serde_json::json!([
{ "F_Id": "old-1", "F_Item": "A" }, // 旧库有 ⇒ 更新
{ "F_Id": "new-9", "F_Item": "B" } // 旧库没有 ⇒ 新增
]);
let diff = diff_sub_rows(rows.as_array().unwrap(), "f_id", &sub_ctx(&["old-1", "old-2"], false));
assert_eq!(diff.updates.len(), 1, "old-1 应是更新: {diff:?}");
assert_eq!(diff.inserts.len(), 1, "new-9 应是新增: {diff:?}");
assert_eq!(diff.deletes, vec!["old-2".to_string()], "old-2 应被删: {diff:?}");
}
/// 🔴 入参里没给主键的行 ⇒ 新增,且主键由生成器补。
#[test]
fn diff_assigns_generated_key_to_new_rows() {
let rows = serde_json::json!([{ "F_Item": "A" }]);
let mut c = sub_ctx(&[], false);
c.row_key_generator = Some(|i| format!("gen-{i}"));
let diff = diff_sub_rows(rows.as_array().unwrap(), "f_id", &c);
assert_eq!(diff.inserts.len(), 1);
assert_eq!(row_key_of(&diff.inserts[0], "f_id").as_deref(), Some("gen-0"));
}
/// 🔴 没有生成器且入参没给主键 ⇒ 主键为空 ⇒ 上层必须拒绝(不写空主键)。
#[test]
fn diff_without_generator_leaves_key_empty() {
let rows = serde_json::json!([{ "F_Item": "A" }]);
let diff = diff_sub_rows(rows.as_array().unwrap(), "f_id", &sub_ctx(&[], false));
assert_eq!(diff.inserts.len(), 1);
// 空主键 ⇒ `row_key_of` 视为「没有主键」⇒ 上层 `plan_update_full` 会报
// `NoPrimaryKey`,绝不写空主键(空主键 = 多行挤成一行)。
assert!(
row_key_of(&diff.inserts[0], "f_id").is_none(),
"空主键必须被视作缺失: {diff:?}"
);
}
/// `only_update = true` ⇒ 缺失的旧行**不删**。
#[test]
fn only_update_keeps_missing_rows() {
let rows = serde_json::json!([{ "F_Id": "old-1" }]);
let mut c = sub_ctx(&["old-1", "old-2"], false);
c.options.only_update = true;
let diff = diff_sub_rows(rows.as_array().unwrap(), "f_id", &c);
assert!(diff.deletes.is_empty(), "only_update 不该删行: {diff:?}");
assert_eq!(diff.updates.len(), 1);
}
/// 🔴 主键比较必须**字符串化**(Java `String.valueOf(t)`)。
#[test]
fn diff_compares_keys_as_strings() {
let rows = serde_json::json!([{ "F_Id": 123 }]);
let diff = diff_sub_rows(rows.as_array().unwrap(), "f_id", &sub_ctx(&["123"], false));
assert_eq!(diff.updates.len(), 1, "数字主键应与字符串主键视为同一行: {diff:?}");
assert!(diff.inserts.is_empty());
assert!(diff.deletes.is_empty());
}
// ---------------------------------------------------------------
// 参数 ↔ 列映射(执行层靠它决定 cast)
// ---------------------------------------------------------------
/// 🔴 `param_columns` 必须与 `params` 一一对应,且列名是真的。
///
/// 之前执行层是「按模型字段顺序猜占位符对应哪一列」——
/// 而**写入列顺序 ≠ 模型字段顺序**(系统列是运行时追加的)⇒ 猜错就写脏数据。
#[test]
fn param_columns_line_up_with_params() {
let plan = plan_insert(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"m1",
)
.unwrap();
assert_eq!(
plan.main.param_columns.len(),
plan.main.params.len(),
"参数与列映射长度必须一致"
);
let cols = insert_columns(&plan.main);
assert_eq!(&plan.main.param_columns, &cols, "映射顺序应与 INSERT 列一致");
assert_eq!(plan.main.column_of(0), Some("f_id"));
}
/// UPDATE 的 WHERE 主键占位符也要带列名(执行层要按它 cast)。
#[test]
fn update_param_columns_include_where_key() {
let plan = plan_update(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"m1",
)
.unwrap();
let last = plan.main.param_columns.len() - 1;
assert_eq!(
plan.main.column_of(last),
Some("f_id"),
"最后一个参数是 WHERE 里的主键: {:?}",
plan.main.param_columns
);
assert_eq!(plan.main.params.len(), plan.main.param_columns.len());
}
/// 🔴 主键**不能出现在 SET** 里(改主键 = 改对外契约)。
#[test]
fn primary_key_is_never_in_set_clause() {
let plan = plan_update(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"m1",
)
.unwrap();
let set_part = plan
.main
.text
.split_once(" SET ")
.unwrap()
.1
.split_once(" WHERE ")
.unwrap()
.0;
assert!(
!set_part.contains("f_id"),
"SET 里不该有主键: {set_part}"
);
}
// ============================================================
// 🔴 回归测试:列与值必须同源(修「列数 ≠ 参数数」)
// ============================================================
/// 🔴 **每一条**生成的 SQL,占位符个数必须等于列数。
///
/// 之前 `render_insert` 收的是「`cols` 数组 + 平行的 `params` 数组」,
/// 两个数组靠下标对齐 —— 少 push 一次参数就**不报错**,
/// 只是把值错位写到别的列上(静默写坏数据)。
///
/// 现在的防线是**类型**:`render_insert` 只收 `cols`,
/// 参数自己生成 ⇒ 两个数组不可能不一致。
/// 这条测试是那道防线的守门人。
#[test]
fn every_statement_has_one_placeholder_per_column() {
let plan = plan_insert(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"m1",
)
.unwrap();
for sql in plan.all() {
let marks = sql.text.matches("$").count();
assert_eq!(
marks,
sql.params.len(),
"🔴 {} 的占位符数与参数数不一致 ⇒ 值会错位写进别的列: {}",
sql.kind.as_str(),
sql.text
);
assert_eq!(
sql.param_columns.len(),
sql.params.len(),
"🔴 {} 的参数↔列映射长度不一致: {}",
sql.kind.as_str(),
sql.text
);
}
}
/// 🔴 UPDATE 的 SET 列数必须等于「参数数 - 1」(最后一个是 WHERE 的主键)。
#[test]
fn update_placeholder_count_matches_set_columns() {
let plan = plan_update(
&form(),
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"m1",
)
.unwrap();
let set_part = plan.main.text.split_once(" SET ").unwrap().1;
let set_part = set_part.split_once(" WHERE ").unwrap().0;
let set_cols = set_part.split(", ").count();
assert_eq!(
set_cols + 1,
plan.main.params.len(),
"🔴 SET 列数({set_cols}) 与参数数({}) 不匹配: {}",
plan.main.params.len(),
plan.main.text
);
}
// ============================================================
// 🔴 回归测试:modifyTime / modifyUser 的更新语义
// ============================================================
/// 带 modifyTime / modifyUser 控件的表单(合成,但语义照 Java)。
const FORM_WITH_MODIFY: &str = r#"{
"formRef": "formRef", "formModel": "formData",
"fields": [
{ "__vModel__": "F_Room", "__config__": { "jnpfKey": "input", "label": "房间", "layout": "colFormItem", "tableName": "biz_main" } },
{ "__vModel__": "F_LastModifyTime", "__config__": { "jnpfKey": "modifyTime", "label": "修改时间", "layout": "colFormItem", "tableName": "biz_main" } },
{ "__vModel__": "F_LastModifyUserId", "__config__": { "jnpfKey": "modifyUser", "label": "修改人", "layout": "colFormItem", "tableName": "biz_main" } }
]
}"#;
/// 🔴 **更新**时最后修改时间/人**必须被写**。
///
/// Java `update()`:
/// ```java
/// case MODIFYTIME: if (!childNeedAdd) { value = new Date(); } break;
/// case MODIFYUSER: if (!childNeedAdd) { value = user.getUserId(); } break;
/// ```
///
/// 之前两者都归到 `AutoFill::Null` ⇒ 更新时被整段跳过 ⇒
/// 「最后修改人/时间」永远停在旧值 —— 审计链断掉。
#[test]
fn update_writes_modify_time_and_modify_user() {
let form = FormSchema::from_str(FORM_WITH_MODIFY).expect("表单应可解析");
let plan = plan_update(
&form,
&model_with_modify(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"m1",
)
.unwrap();
let cols = &plan.main.param_columns;
assert!(
cols.iter().any(|c| c == "f_lastmodifytime"),
"🔴 更新时没写最后修改时间: {cols:?}"
);
assert!(
cols.iter().any(|c| c == "f_lastmodifyuserid"),
"🔴 更新时没写最后修改人: {cols:?}"
);
// 值也要对:时间 = ctx.now,人 = ctx.user_id
let time_idx = cols.iter().position(|c| c == "f_lastmodifytime").unwrap();
let user_idx = cols.iter().position(|c| c == "f_lastmodifyuserid").unwrap();
assert_eq!(
plan.main.params[time_idx],
Value::String("2026-10-31T12:00:00".to_string()),
"最后修改时间应写当前时间"
);
assert_eq!(
plan.main.params[user_idx],
Value::String("u-1".to_string()),
"最后修改人应写当前用户 id"
);
}
/// 🔴 **新增**时最后修改时间/人**必须置 null**(Java `create()` 两个分支都是 null)。
///
/// 「刚建就显示被人改过」是脏审计。
#[test]
fn insert_nulls_modify_time_and_modify_user() {
let form = FormSchema::from_str(FORM_WITH_MODIFY).expect("表单应可解析");
let plan = plan_insert(
&form,
&model_with_modify(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"m1",
)
.unwrap();
let cols = &plan.main.param_columns;
for c in ["f_lastmodifytime", "f_lastmodifyuserid"] {
let idx = cols.iter().position(|x| x == c);
assert!(idx.is_some(), "新增时应该写 {c}(置 null): {cols:?}");
assert_eq!(
plan.main.params[idx.unwrap()],
Value::Null,
"🔴 新增时 {c} 应为 null"
);
}
}
/// 🔴 反自证:**列不在模型里 ⇒ 不能写**(列白名单先于自动填充生效)。
///
/// 这条测试的意义:如果哪天有人把列白名单去掉,
/// 上面两条会「因为列写不进去而假通过」——
/// 这条保证白名单真的在拦。
#[test]
fn modify_columns_are_skipped_when_not_in_model() {
let form = FormSchema::from_str(FORM_WITH_MODIFY).expect("表单应可解析");
// MODEL 里没有 F_LastModifyTime / F_LastModifyUserId
let plan = plan_insert(
&form,
&model(),
&serde_json::json!({ "F_Room": "A-101" }),
&ctx(),
"m1",
)
.unwrap();
assert!(
!plan
.main
.param_columns
.iter()
.any(|c| c == "f_lastmodifytime"),
"🔴 模型里没有的列不该被写: {:?}",
plan.main.param_columns
);
}
}