docs(lowcode): 对齐 jnpf 运行时机制,纠正两处已实现代码的错误判断

- 新增 docs/visualdev-mechanism.md:接口契约 15 端点 / 列名规则 / 系统字段 / 自动填充 / 主子表,
  每条结论标了源码位置与复核命令
- 纠正①:列名 = lower(vModel)(VisualDevTableCre 原样写 vModel + PG toLowerCase),
  不是「剥前缀」;f_creatortime 就是真实列名,f_creator_time 属于平台表手写 DDL
- 纠正②:calculate 接收入参(create() 走 getIntValue),归入 Number,删掉 Computed 枚举
- 新增 widget::auto_fill/AutoFill:把 Java create() 的自动填充固化成可测枚举,
  并加交叉断言「被覆盖的字段不能标 acceptsInput」
- 影响:测试 344 → 346;十二闸全绿;v_model_to_column 简化为 to_lowercase
This commit is contained in:
admin committed 2026-10-31 12:02:15 +08:00
1 parent f0c77f731c
commit 343772be42
8 files changed
+531 -43

No files matched your search

+31 -16
View File
@@ -35,8 +35,8 @@
//!
//! ## 三个必须记住的方言(踩错就是静默错数据)
//!
//! 1. **`__vModel__` 是 `F_` 开头的大写**(`F_Room`),而物理列是小写 `f_room`。
//! 映射规则只有一条:`f_` + `__vModel__` 去前缀后转小写。
//! 1. **`__vModel__` 是 `F_` 开头的大写**(`F_Room`),物理列是 `lower(vModel)`
//! —— jnpf 建表时原样写 vModel,PG 折叠成小写(见 [`v_model_to_column`])。
//! 2. **`rowFormItem` 是布局容器**,本身不占列;它的 `children` 才是控件。
//! 3. **`table` 是子表**,它的 `children` 属于**另一张物理表**
//! (`__config__.tableName` 指明的那个),不能混进主表字段。
@@ -141,29 +141,44 @@ impl FieldNode {
}
}
/// `__vModel__` → 物理列名。
/// `__vModel__` → 物理列名(**与 jnpf 建表逻辑逐字一致**)。
///
/// 规则(实测唯一正确的一条):
/// - 去掉任意数量的 `F_` / `f_` 前缀(官方两种写法都出现过)
/// - 其余部分整体转**小写**,不做驼峰拆分
/// ## 规则溯源(不是猜的)
///
/// 🔴 **不要做驼峰转下划线**:`F_CertificatesType` 对应的列是
/// `f_certificates_type`,但 `F_Building` 对应 `f_building`(没有下划线)。
/// 官方列名由建表时的人工输入决定,没有机械规则 —— 所以这里只做
/// 「前缀剥离 + 小写」,真实列名一律以 `f_tables_data` 为准。
/// jnpf 建表时:
/// 1. `VisualDevTableCre.fieldList()` 里 `fieldForm.setField(fieLdsModel.getVModel())`
/// —— 列名**原样用 vModel**
/// 2. 同一文件的 `tableList()` 里
/// `isLowerCase = (DbBase.POSTGRE_SQL.equals(type) || DbBase.KINGBASE_ES.equals(type))`
/// ⇒ PostgreSQL / Kingbase 对表名与列名一律 `toLowerCase()`
///
/// 两条合起来:**PG 下的列名就是 `lower(vModel)`**。
///
/// ```text
/// F_Room → f_room
/// F_Company_name → f_company_name (本身带下划线,保留)
/// F_CreatorTime → f_creatortime ← 真实列名就这样,不是 f_creator_time
/// ```
///
/// 🔴 **不要「驼峰转下划线」**:那会把 `F_CreatorTime` 变成 `f_creator_time`,
/// 而动态建表实际落的是 `f_creatortime`。
///
/// 🔴 **不要拿平台表(`base_*`)类比**:那些表的 DDL 是**手写**的,
/// 列名(如 `base_user.f_creator_time`)与任何 vModel 无关。
/// 本函数只适用于**低代码动态建的表**。
pub fn v_model_to_column(v_model: &str) -> Option<String> {
let s = v_model.trim();
if s.is_empty() {
return None;
}
let stripped = s
.strip_prefix("F_")
.or_else(|| s.strip_prefix("f_"))
.unwrap_or(s);
if stripped.is_empty() {
// jnpf 原样写 vModel,由数据库折叠大小写。
// 实测 vModel 一律是 `F_xxx`,但历史上也见过小写 `f_xxx` 的手工数据 ⇒ 统一兜住。
let lowered = s.to_lowercase();
// 只剩前缀(`F_` / `f_`)不算有效列名
if lowered == "f_" {
return None;
}
Some(format!("f_{}", stripped.to_lowercase()))
Some(lowered)
}
/// 解析后的表单(保留原始 JSON)。
+1 -1
View File
@@ -49,7 +49,7 @@ pub mod widget;
pub use form::{v_model_to_column, FieldNode, FormError, FormSchema};
pub use model::{ColumnDef, ModelError, ModelSchema, TableSchema};
pub use validate::{validate, Diagnostic, Report, Severity};
pub use widget::{classify, WidgetKind};
pub use widget::{auto_fill, classify, AutoFill, WidgetKind};
/// 版本(与 workspace 一致,供 MCP 输出用)。
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
+107 -10
View File
@@ -8,7 +8,7 @@
//! | 类别 | 举例 | 存成什么 | 接收入参 |
//! |---|---|---|---|
//! | 文本 | `input` `textarea` `editor` | 字符串 | ✅ |
//! | 数值 | `inputNumber` `calculate` `rate` | 数字 | 视情况(`calculate` 只读) |
//! | 数值 | `inputNumber` `calculate` `rate` | 数字 | ✅(`calculate` 的值由前端算好传入) |
//! | 日期时间 | `datePicker` `timePicker` `createTime` | 时间戳 / 字符串 | 视情况 |
//! | 枚举 | `select` `radio` `checkbox` `switch` | 字符串 / 整数 | ✅ |
//! | 实体引用 | `userSelect` `organizeSelect` `depSelect` | 对象 id | ✅(存 id) |
@@ -51,8 +51,6 @@ pub enum WidgetKind {
Attachment,
/// 布局(`groupTitle` / `divider` / `tabItem` …)—— 不占任何列。
Layout,
/// 计算字段(`calculate`)—— 只读,由公式算出。
Computed,
/// 未知控件 —— 降级为文本并警告。
Unknown,
}
@@ -65,7 +63,7 @@ impl WidgetKind {
/// 该类别是否允许从请求入参接收值。
///
/// 🔴 `SystemGenerated` / `Computed` / `SubTable` / `Layout` 一律拒绝 ——
/// 🔴 `SystemGenerated` / `SubTable` / `Layout` 一律拒绝 ——
/// 让入参覆盖单号、创建人、计算结果,是最常见的「数据被写坏」来源。
pub fn accepts_input(self) -> bool {
matches!(
@@ -91,12 +89,79 @@ impl WidgetKind {
WidgetKind::SubTable => "subTable",
WidgetKind::Attachment => "attachment",
WidgetKind::Layout => "layout",
WidgetKind::Computed => "computed",
WidgetKind::Unknown => "unknown",
}
}
}
/// 系统生成控件在**新增时**自动填什么值。
///
/// ## 溯源
///
/// 逐条对齐 jnpf `FlowFormDataUtil.create(FieLdsModel, dataValue, ...)` 的 switch
/// (`jnpf-visualdev-base-biz`)。这段逻辑决定了「哪些字段不用传、后端自己填」——
/// 它不是可选优化:`createUser` 不填就是 null,等于审计链路断了。
///
/// ## 🔴 `modifyTime` / `modifyUser` 在新增时被置 null
///
/// 不是「保持入参」:新增的行还没被改过,「最后修改人」为空才是正确的。
/// 如果照抄入参,会出现「刚建就显示被别人改过」的脏审计。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AutoFill {
/// 用入参原值(普通业务字段)。
Passthrough,
/// 当前登录用户 id(`createUser`)。
CurrentUserId,
/// 当前时间(`createTime`)。
Now,
/// 当前用户的组织 id 列表,序列化成 JSON 字符串(`currOrganize` / `currDept`)。
CurrentOrganizeIds,
/// 当前用户的岗位 id 列表,序列化成 JSON 字符串(`currPosition`)。
CurrentPositionIds,
/// 新增时置 `null`(`modifyTime` / `modifyUser`)。
Null,
/// 单据号生成器产出(`billRule`,`ruleType=1` 时)。
BillNumber,
}
impl AutoFill {
/// 稳定字符串(JSON 输出 / 诊断用)。
pub fn as_str(self) -> &'static str {
match self {
AutoFill::Passthrough => "passthrough",
AutoFill::CurrentUserId => "currentUserId",
AutoFill::Now => "now",
AutoFill::CurrentOrganizeIds => "currentOrganizeIds",
AutoFill::CurrentPositionIds => "currentPositionIds",
AutoFill::Null => "null",
AutoFill::BillNumber => "billNumber",
}
}
/// 后端是否必须自己产生值(= 入参给了也会被覆盖)。
pub fn overrides_input(self) -> bool {
!matches!(self, AutoFill::Passthrough)
}
}
/// 控件 → 新增时的自动填充行为。
///
/// 对齐 `FlowFormDataUtil.create()` 的 switch 分支;未知控件走 `Passthrough`。
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
}
"billRule" => AutoFill::BillNumber,
_ => AutoFill::Passthrough,
}
}
/// `jnpfKey` → 类别。
///
/// 映射取自实测分布(71 张真表单 / 54 种控件,覆盖率见测试)。
@@ -109,7 +174,13 @@ pub fn classify(jnpf_key: &str) -> WidgetKind {
| "phoneNumber" | "email" | "url" | "richText" | "codeEditor" => WidgetKind::Text,
// ---- 数值 ----
"inputNumber" | "rate" | "slider" | "money" | "percent" => WidgetKind::Number,
// 🔴 `calculate` 在这里而不是「只读计算」:Java 侧
// `FlowFormDataUtil.create()` 对 CALCULATE 走 `getIntValue(dataValue,...)`
// ⇒ 它**接收入参**(公式由前端算好后随提交带上),后端只做数值转换。
// 把它当只读会导致「计算字段永远存不进去」。
"inputNumber" | "rate" | "slider" | "money" | "percent" | "calculate" => {
WidgetKind::Number
}
// ---- 日期时间 ----
"datePicker" | "timePicker" | "dateRange" | "timeRange" | "dateCalculate" => {
@@ -145,9 +216,6 @@ pub fn classify(jnpf_key: &str) -> WidgetKind {
WidgetKind::Layout
}
// ---- 计算字段(只读)----
"calculate" => WidgetKind::Computed,
_ => WidgetKind::Unknown,
}
}
@@ -229,6 +297,36 @@ mod tests {
assert!(h.contains("widget.rs"), "提示要指明改哪里");
}
/// 🔴 自动填充必须与基线平台 `FlowFormDataUtil.create()` 的 switch 一致。
#[test]
fn auto_fill_matches_baseline_create_switch() {
assert_eq!(auto_fill("createUser"), AutoFill::CurrentUserId);
assert_eq!(auto_fill("createTime"), AutoFill::Now);
assert_eq!(auto_fill("currOrganize"), AutoFill::CurrentOrganizeIds);
assert_eq!(auto_fill("currDept"), AutoFill::CurrentOrganizeIds);
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("input"), AutoFill::Passthrough);
assert_eq!(auto_fill("calculate"), AutoFill::Passthrough);
}
/// 凡是被覆盖的,`accepts_input` 必须是 false —— 否则「传了也没用」但没人告知。
#[test]
fn overridden_fields_do_not_accept_input() {
for key in ["createUser", "createTime", "currOrganize", "currPosition", "billRule"] {
let f = auto_fill(key);
assert!(f.overrides_input(), "{key} 应被后端覆盖");
assert!(
!classify(key).accepts_input(),
"{key} 被覆盖却还标着接收入参 —— 会让调用方以为传了有用"
);
}
}
/// 类别字符串必须唯一且稳定(它们会出现在 JSON 输出里,改成对账就漂了)。
#[test]
fn kind_names_are_unique() {
@@ -242,7 +340,6 @@ mod tests {
WidgetKind::SubTable,
WidgetKind::Attachment,
WidgetKind::Layout,
WidgetKind::Computed,
WidgetKind::Unknown,
];
let mut seen = std::collections::HashSet::new();