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:
1 parent
f0c77f731c
commit
343772be42
8 files changed
+531
-43
No files matched your search
@@ -619,3 +619,73 @@ fixture 落盘:`crates/sspf-lowcode/tests/fixtures/sample_{form,model}.json`
|
||||
|
||||
`cargo test` **344**(+38)|十二道闸门全绿
|
||||
| `lowcode-smoke` 8/8 | `mcp-smoke` 32/32 | `baseline-smoke` 10/10 | 内存 7 MB
|
||||
|
||||
---
|
||||
|
||||
## 对齐 jnpf 运行时机制(11:52 起)
|
||||
|
||||
按指示去读 jnpf Java 源码,把运行时机制对齐。产出 `docs/visualdev-mechanism.md`
|
||||
(每条结论都标了源码位置,含复核用的 sed 命令)。
|
||||
|
||||
### 🔴 纠正了 P2-a 的两个错误判断
|
||||
|
||||
**① 列名规则:我之前归因反了**
|
||||
|
||||
之前写「`F_CreatorTime` → `f_creatortime` 是错的,真实是 `f_creator_time`」——
|
||||
**完全说反了**。真相:
|
||||
|
||||
```
|
||||
VisualDevTableCre.fieldList(): fieldForm.setField(fieLdsModel.getVModel()) ← 原样写
|
||||
VisualDevTableCre.tableList(): isLowerCase = (POSTGRE_SQL || KINGBASE_ES) ← PG 强制小写
|
||||
⇒ 低代码表列名 = lower(vModel)
|
||||
```
|
||||
|
||||
所以 `f_creatortime` **就是**真实列名。`f_creator_time` 那种带下划线的来自**平台表手写 DDL**,
|
||||
与 vModel 无关。两类表的命名规则不同,不能互相类比。
|
||||
|
||||
`v_model_to_column` 简化成 `s.to_lowercase()`(原来「剥前缀再加 f_」是等价但绕)。
|
||||
|
||||
**② `calculate` 不是只读**
|
||||
|
||||
Java `FlowFormDataUtil.create()` 里 `CALCULATE` 走 `getIntValue(dataValue, ...)`
|
||||
⇒ **接收入参**(公式前端算好传过来)。归到 `Computed`(只读)会导致计算字段永远存不进去。
|
||||
已改成 `WidgetKind::Number`,删掉 `Computed` 枚举。
|
||||
|
||||
### 新增的可测规则:`widget::auto_fill()` → `AutoFill`
|
||||
|
||||
把 Java create() 的 switch 固化成枚举,不再只写在注释里:
|
||||
|
||||
| 控件 | 填什么 |
|
||||
|---|---|
|
||||
| createUser | 当前用户 id |
|
||||
| createTime | now |
|
||||
| currOrganize / currDept | 用户组织 id 列表 JSON |
|
||||
| currPosition | 用户岗位 id 列表 JSON |
|
||||
| modifyTime / modifyUser | **null**(新增时清空,否则「刚建就显示被人改过」) |
|
||||
| billRule | 单据号生成器 |
|
||||
| calculate | 接收入参(Passthrough) |
|
||||
|
||||
并加了一条交叉断言:凡被覆盖的字段,`accepts_input()` 必须是 false
|
||||
(否则「传了也没用」却没人告知)。
|
||||
|
||||
### 接口契约(P2-b 直接依据)
|
||||
|
||||
`/api/visualdev/OnlineDev` 下 15 个端点。三条最容易踩的:
|
||||
|
||||
1. **新增的 `data` 是 JSON 字符串不是对象**(`private String data;` + `JsonUtil.stringToMap`)
|
||||
2. **新增成功不返回 id**(`ActionResult.success(MsgCode.SU001.get())` 只有消息)
|
||||
⇒ MCP 层要补返回 id,否则 AI 得再查一次列表
|
||||
3. **列表是 POST 不是 GET**,`queryJson` 是字符串 map(列表页搜索框的序列化,不是通用条件)
|
||||
|
||||
### 其它机制
|
||||
|
||||
- 运行时读 `base_visual_release`(发布快照),**只有 `Config?type=0` 读 dev**
|
||||
⇒ 「改了 dev 不发布看不到效果」是设计不是 bug
|
||||
- 权限按 `modelId` 判(`StpUtil.checkPermission(modelId)`),不是菜单路径
|
||||
- 建表自动追加:`f_tenant_id` / `f_version` / `f_flow_id` / `f_flow_task_id` / `f_flow_state`
|
||||
(+ 逻辑删除时 `f_delete_*`);子表多一个 `f_foreign_id`
|
||||
- **非流程功能也写 `f_flow_task_id` = 主键**
|
||||
|
||||
### 数字
|
||||
|
||||
`cargo test` **346**(+2:AutoFill 两条)|十二道闸门全绿 | `lowcode-smoke` 8/8
|
||||
@@ -869,6 +869,10 @@ tools/diff-harness/
|
||||
**第一波刻意没做的**:动态 CRUD(写数据)、写表单定义。原因:写的前置是「解析 + 校验被真实数据验证透」,
|
||||
否则等于让 AI 生成前端画不出来的 JSON。
|
||||
|
||||
**P2-b 的前置件已完成**:`docs/visualdev-mechanism.md` —— 从 jnpf Java 源码逐条读出的运行时机制
|
||||
(接口契约 15 个端点 / 列名规则 / 系统字段 / 自动填充 / 主子表),每条结论标了源码位置。
|
||||
读这份文档时纠正了两个已实现代码里的错误判断(列名归因反了、`calculate` 不是只读)。
|
||||
|
||||
**实测发现的三条方言**(都已写进代码注释与测试):
|
||||
|
||||
1. `f_tables_data` 的 `columnName` **全是 null** ⇒ 只能从 `field` 推导,而推导**不等于**真实列名
|
||||
|
||||
@@ -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)。
|
||||
|
||||
@@ -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");
|
||||
@@ -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();
|
||||
|
||||
@@ -162,34 +162,37 @@ fn raw_is_isomorphic_to_source() {
|
||||
assert_eq!(model.raw, msrc);
|
||||
}
|
||||
|
||||
/// 🔴 把「推导 ≠ 真实列名」这条边界钉死。
|
||||
/// 🔴 列名规则与 jnpf 建表逻辑逐字对齐:**列名 = `lower(vModel)`**。
|
||||
///
|
||||
/// `F_CreatorTime` 推导出 `f_creatortime`,但官方建表用的是 `f_creator_time`。
|
||||
/// 这不是 bug,是「设计态没有 columnName 时的信息缺失」——
|
||||
/// 所以本 crate **不承诺**推导结果等于数据库列名,只承诺两边用同一套推导做自洽性检查。
|
||||
/// 溯源:`VisualDevTableCre.fieldList()` 里 `setField(vModel)` 原样写,
|
||||
/// 同文件 `tableList()` 里 PG ⇒ `isLowerCase = true` ⇒ `toLowerCase()`。
|
||||
///
|
||||
/// 所以 `F_CreatorTime` 的**真实列名就是 `f_creatortime`** ——
|
||||
/// 不存在 `f_creator_time`(那是**平台表**手写 DDL 的命名,与低代码表无关)。
|
||||
#[test]
|
||||
fn derivation_is_not_ground_truth() {
|
||||
fn column_name_equals_lowercase_vmodel() {
|
||||
use sspf_lowcode::v_model_to_column;
|
||||
|
||||
// 推导一致(本 crate 的自洽性基础)
|
||||
assert_eq!(v_model_to_column("F_Room").as_deref(), Some("f_room"));
|
||||
assert_eq!(
|
||||
v_model_to_column("F_Company_name").as_deref(),
|
||||
Some("f_company_name"),
|
||||
"已含下划线的字段能推导对"
|
||||
"本身就带下划线的,原样保留"
|
||||
);
|
||||
|
||||
// 推导不一致(真实数据库用的是 f_creator_time)
|
||||
assert_eq!(
|
||||
v_model_to_column("F_CreatorTime").as_deref(),
|
||||
Some("f_creatortime"),
|
||||
"驼峰字段推导不出下划线形态 —— 这正是必须拿 information_schema 复核的原因"
|
||||
"驼峰**不拆**:jnpf 原样写 vModel,PG 只折叠大小写"
|
||||
);
|
||||
assert_ne!(
|
||||
v_model_to_column("F_CreatorTime").as_deref(),
|
||||
Some("f_creator_time"),
|
||||
"如果哪天这条断言挂了,说明推导规则改了 —— 全仓的列映射都要重查"
|
||||
"如果哪天这条挂了,说明有人加了驼峰拆分的自作聪明 —— 那会和 jnpf 建出来的表对不上"
|
||||
);
|
||||
|
||||
// 平台表的 `f_creator_time` 与本函数无关(手写 DDL,不经过 vModel)
|
||||
assert_eq!(v_model_to_column("f_tenant_id").as_deref(), Some("f_tenant_id"));
|
||||
assert_eq!(v_model_to_column("F_").as_deref(), None, "纯前缀不算列名");
|
||||
}
|
||||
|
||||
/// 未知控件在真实数据里存在吗?答案应该是否 —— 说明分类覆盖了实测在用控件。
|
||||
|
||||
+12
-5
@@ -169,12 +169,19 @@ inline 模式是刻意的:AI 生成一份表单 JSON 后**先校验、后落
|
||||
🔴 让入参覆盖 `billRule`(单据号)或 `createUser`,会破坏业务编号规则与审计链路 ——
|
||||
这是「数据被写坏」最常见的来源,所以 `acceptsInput` 在 `describe` 里显式返回。
|
||||
|
||||
**`form.validate` 只保证「设计稿自洽」,不等于「能直接跑 SQL」**:
|
||||
**列名规则是确定的**(已对齐 jnpf 建表逻辑,见 `docs/visualdev-mechanism.md` §3):
|
||||
|
||||
它比对的是「表单 `__vModel__` 推导的列」与「模型 `field` 推导的列」,两边同一套推导。
|
||||
但官方数据里 `columnName` 全是 null,推导必然有偏差
|
||||
(`F_CreatorTime` → `f_creatortime`,真实列是 `f_creator_time`)。
|
||||
与真实数据库列的一致性要拿 `information_schema` 比 —— P2-b 补。
|
||||
```
|
||||
低代码动态建的表:列名 = lower(__vModel__)
|
||||
F_Room → f_room F_CreatorTime → f_creatortime(不是 f_creator_time)
|
||||
```
|
||||
|
||||
jnpf 建表时原样写 vModel,PG/Kingsbase 再 `toLowerCase()`。
|
||||
⚠️ 平台表(`base_*`)的 `f_creator_time` 是**手写 DDL**,与这条规则无关 —— 别混。
|
||||
|
||||
**`form.validate` 只保证「设计稿自洽」,不等于「表已经建好了」**:
|
||||
它比对表单推导的列与模型 `field` 推导的列(两边同一套规则,所以能验出「表单引用了模型里没有的字段」)。
|
||||
但库里到底有没有这张表、列够不够,要拿 `information_schema` 比 —— P2-b 补。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,292 @@
|
||||
# jnpf 在线开发(visualdev)运行时机制 —— 对齐笔记
|
||||
|
||||
> **这份文件解决什么问题**:`PLAN.md` 第 4 条要求「以 jnpf 源码迁移,数据库脚本一致,
|
||||
> API 调用/行为一致」。要做到「行为一致」,必须先知道**原平台到底怎么跑**。
|
||||
> 本文件是从 Java 源码逐条读出来的机制,是 P2-b(动态 CRUD)的实施依据。
|
||||
>
|
||||
> **每条结论都标了源码位置**,改代码前先回来核对,别凭印象。
|
||||
|
||||
源码根:`/Users/xs/Desktop/workspace/jnpf/jnpf-java-boot/`(下称 `$SRC`)
|
||||
|
||||
---
|
||||
|
||||
## 1. 接口契约(面 B 在线开发)
|
||||
|
||||
`$SRC/jnpf-visualdev/jnpf-visualdev-onlinedev/jnpf-visualdev-onlinedev-controller/src/main/java/jnpf/onlinedev/controller/VisualdevModelDataController.java`
|
||||
|
||||
类级 `@RequestMapping("/api/visualdev/OnlineDev")`。
|
||||
|
||||
| 方法 | 路径 | 用途 | 关键入参 |
|
||||
|---|---|---|---|
|
||||
| POST | `/{modelId}/List` | 列表 | body `PaginationModel` |
|
||||
| POST | `/{modelId}/List/{id}` | 树形子列表 | body `PaginationModel` + 父 id |
|
||||
| GET | `/{modelId}/Config` | 功能配置 | `?type=0` 读**草稿**,其它读**发布** |
|
||||
| GET | `/{modelId}/FormData` | 表单 JSON | — |
|
||||
| GET | `/{modelId}/{id}` | 详情 | — |
|
||||
| POST | `/{modelId}/DataChange` | 详情(带关联转换) | body `VisualInfoParam` |
|
||||
| POST | `/{modelId}` | **新增** | body `VisualdevModelDataCrForm` |
|
||||
| PUT | `/{modelId}/{id}` | 修改 | 同上(UpForm 继承 CrForm) |
|
||||
| DELETE | `/{modelId}/{id}` | 删除 | — |
|
||||
| POST | `batchDelete/{modelId}` | 批量删除 | body `BatchRemoveIdsVo` |
|
||||
| POST | `/{modelId}/ImportData` | 导入 | — |
|
||||
| POST | `/{modelId}/Actions/ExportData` | 导出 | — |
|
||||
| POST | `/RelationQuery` | 关联查询 | body `RelationQuery` |
|
||||
| GET | `/getFields?menuId=` | AI 取字段 | — |
|
||||
| GET | `/Config?menuId=` | 按菜单取配置 | — |
|
||||
|
||||
### 三条容易踩的契约细节
|
||||
|
||||
**① 新增的 `data` 是 JSON 字符串,不是对象**
|
||||
|
||||
```java
|
||||
// VisualdevModelDataController.create()
|
||||
Map<String, Object> map = JsonUtil.stringToMap(visualdevModelDataCrForm.getData());
|
||||
```
|
||||
|
||||
⇒ 请求体长这样:
|
||||
|
||||
```json
|
||||
{ "data": "{\"F_Title\":\"标题\",\"F_Amount\":100}", "menuId": "..." }
|
||||
```
|
||||
|
||||
传对象会被反序列化失败。`VisualdevModelDataCrForm` 里 `private String data;` 是硬证据。
|
||||
|
||||
**② 新增成功不返回 id**
|
||||
|
||||
```java
|
||||
return ActionResult.success(MsgCode.SU001.get()); // 只有「新建成功」
|
||||
```
|
||||
|
||||
`visualCreate` 内部生成了 `mainId` 并塞进 `DataModel`,但 controller **没往外传**。
|
||||
⇒ 调用方要拿 id 必须再查一次列表。**MCP 层必须补上这个返回值**(见 §7)。
|
||||
|
||||
**③ 列表用 POST 不是 GET**
|
||||
|
||||
`PaginationModel` 里 `queryJson` / `superQueryJson` 都是**字符串**:
|
||||
|
||||
```java
|
||||
Map<String, Object> keyJsonMap = JsonUtil.stringToMap(paginationModel.getQueryJson());
|
||||
// 格式:{ "<字段id>": <值> } 的扁平 map
|
||||
```
|
||||
|
||||
配合 `columnData.searchList`(搜索项定义)解释每个键怎么查。
|
||||
这不是通用条件表达式 —— 它是「列表页搜索框」的序列化。
|
||||
|
||||
---
|
||||
|
||||
## 2. 读写的是发布版,不是草稿
|
||||
|
||||
```java
|
||||
// 几乎每个 handler 的第一行
|
||||
VisualdevEntity visualdevEntity = visualdevService.getReleaseInfo(modelId);
|
||||
```
|
||||
|
||||
`base_visual_dev` 是**草稿**,`base_visual_release` 是**发布快照**。
|
||||
运行时(列表/详情/新增/修改/删除)**全部读 release**。
|
||||
|
||||
⇒ 改了 dev 不发布,前端看不到效果。**这不是 bug**。
|
||||
只有 `GET /{modelId}/Config?type=0` 明确读 dev。
|
||||
|
||||
---
|
||||
|
||||
## 3. 列名规则(最重要的一条)
|
||||
|
||||
### 结论
|
||||
|
||||
**低代码动态建的表,列名 = `lower(__vModel__)`。**
|
||||
|
||||
```text
|
||||
F_Room → f_room
|
||||
F_Company_name → f_company_name (本身带下划线,原样保留)
|
||||
F_CreatorTime → f_creatortime ← 真实列名就这样
|
||||
```
|
||||
|
||||
### 源码依据(两处)
|
||||
|
||||
**① 列名原样用 vModel**
|
||||
|
||||
`$SRC/jnpf-visualdev/jnpf-visualdev-base/jnpf-visualdev-base-biz/src/main/java/jnpf/base/util/VisualDevTableCre.java`
|
||||
|
||||
```java
|
||||
// fieldList()
|
||||
String vmodel = fieLdsModel.getVModel();
|
||||
...
|
||||
fieldForm.setField(vmodel); // ← 原样写,不做任何拆分
|
||||
```
|
||||
|
||||
**② 数据库类型决定大小写**
|
||||
|
||||
```java
|
||||
// tableList()
|
||||
boolean isUpperCase = (DbBase.DM.equals(type) || DbBase.ORACLE.equals(type));
|
||||
boolean isLowerCase = (DbBase.POSTGRE_SQL.equals(type) || DbBase.KINGBASE_ES.equals(type));
|
||||
...
|
||||
private String tableName(String tableName, boolean isUpperCase, boolean isLowerCase) {
|
||||
return isUpperCase ? tableName.toUpperCase()
|
||||
: (isLowerCase ? tableName.toLowerCase() : tableName);
|
||||
}
|
||||
```
|
||||
|
||||
⇒ PostgreSQL / Kingbase:**表名与列名一律小写**;Oracle / DM:一律大写。
|
||||
|
||||
### 🔴 两条禁令
|
||||
|
||||
1. **不要「驼峰转下划线」**:`F_CreatorTime` 若拆成 `f_creator_time`,和 jnpf 建出来的
|
||||
`f_creatortime` 对不上,SQL 直接 `column does not exist`。
|
||||
2. **不要拿平台表类比**:`base_user.f_creator_time` 是**手写 DDL** 的结果,
|
||||
与任何 vModel 无关。列名规则只对**动态建的表**成立。
|
||||
|
||||
> 代码落点:`crates/sspf-lowcode/src/form.rs::v_model_to_column`
|
||||
> 测试钉死:`crates/sspf-lowcode/tests/real_sample.rs::column_name_equals_lowercase_vmodel`
|
||||
|
||||
---
|
||||
|
||||
## 4. 建表时自动追加的系统字段
|
||||
|
||||
`VisualDevTableCre.tableList()` 在用户字段之后**无条件追加**:
|
||||
|
||||
```java
|
||||
fieldList.add(ConcurrencyUtils.getDbFieldModel(TableFeildsEnum.TENANTID, ...)); // f_tenant_id
|
||||
fieldList.add(ConcurrencyUtils.getDbFieldModel(TableFeildsEnum.FLOWID, ...)); // f_flow_id
|
||||
fieldList.add(ConcurrencyUtils.getDbFieldModel(TableFeildsEnum.VERSION, ...)); // f_version
|
||||
fieldList.add(ConcurrencyUtils.getDbFieldModel(TableFeildsEnum.FLOWTASKID,...)); // f_flow_task_id
|
||||
fieldList.add(ConcurrencyUtils.getDbFieldModel(TableFeildsEnum.FLOWSTATE, ...)); // f_flow_state
|
||||
if (logicalDelete) {
|
||||
// f_delete_mark / f_delete_time / f_delete_user_id
|
||||
}
|
||||
```
|
||||
|
||||
子表额外多一个外键列 `f_foreign_id`(指向主表主键)。
|
||||
|
||||
字段名常量见 `$SRC/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/constant/TableFieldsNameConst.java`。
|
||||
|
||||
### 两类列名混在一张表里
|
||||
|
||||
以实测的 `test_receivable` 为例:
|
||||
|
||||
| 来源 | 命名 | 例子 |
|
||||
|---|---|---|
|
||||
| 设计器控件(vModel) | `lower(vModel)` | `f_building` / `f_room` / `f_creatortime` |
|
||||
| 建表时追加(常量) | 常量字面量(带下划线) | `f_id` / `f_tenant_id` / `f_version` / `f_flow_task_id` / `f_flow_id` / `f_flow_state` |
|
||||
|
||||
⇒ 看到 `f_creator_time` 样式不要以为规律统一了 —— 那多半是控件叫 `F_Creator_Time`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 主键与流程字段
|
||||
|
||||
`FlowFormDataUtil.createMast()`:
|
||||
|
||||
```java
|
||||
String keyName = this.getKey(tableModel, dataModel.getDbType()); // 主键列名(f_id 或自增列)
|
||||
String flowTaskId = this.getFlowTaskId(tableModel, dataModel.getDbType());
|
||||
GeneralInsertDSL dsl = insertInto(sqlTable)
|
||||
.set(column(keyName)).toValue(mainId)
|
||||
.set(column(flowTaskId)).toValue(mainId); // ← 流程任务 id 也写 mainId
|
||||
```
|
||||
|
||||
- 主键:`primaryKeyPolicy == 2` ⇒ 自增;否则 UUID(`RandomUtil.uuId()`)
|
||||
- **非流程功能也会写 `f_flow_task_id`**,值 = 主键
|
||||
- 有 `f_flow_id` 时才写 `f_flow_state = 0`
|
||||
- 并发锁开启 ⇒ 额外写 `f_version = 0`
|
||||
|
||||
---
|
||||
|
||||
## 6. 新增时的自动填充(`create()` 的 switch)
|
||||
|
||||
`FlowFormDataUtil.create(FieLdsModel, dataValue, boolean, UserEntity, boolean)`
|
||||
|
||||
| 控件 | 填什么 |
|
||||
|---|---|
|
||||
| `createUser` | 当前用户 id |
|
||||
| `createTime` | `new Date()` |
|
||||
| `currOrganize` / `currDept` | 当前用户**组织 id 列表**,序列化成 JSON 字符串 |
|
||||
| `currPosition` | 当前用户**岗位 id 列表**,JSON 字符串 |
|
||||
| `modifyTime` / `modifyUser` | **`null`**(新增时清空) |
|
||||
| `billRule` | `serviceUtil.getBillNumber(rule)`;`ruleType≠1` 时保持入参 |
|
||||
| `datePicker` / `dateCalculate` | 按 `format` 格式化 |
|
||||
| `inputNumber` / `calculate` | 数值转换(`getIntValue`) |
|
||||
| 其它 | 空串 ⇒ `null` |
|
||||
|
||||
### 两条推论(已写进代码)
|
||||
|
||||
1. **`calculate` 接收入参** —— 它走 `getIntValue(dataValue, ...)`,不是只读。
|
||||
把它当只读会导致「计算字段永远存不进去」。
|
||||
2. **被覆盖的字段不能标 `acceptsInput`** —— 否则调用方以为传了有用,实际被丢弃。
|
||||
|
||||
> 代码落点:`crates/sspf-lowcode/src/widget.rs::auto_fill` / `AutoFill`
|
||||
> 测试钉死:`auto_fill_matches_jnpf_create_switch` / `overridden_fields_do_not_accept_input`
|
||||
|
||||
---
|
||||
|
||||
## 7. 子表
|
||||
|
||||
`createTable()` 与 `createMast()` 的差别:
|
||||
|
||||
- 子表数据来自**父节点**的 `__config__.children`,写到 `__config__.tableName` 指定的表
|
||||
- 每行由服务端生成自己的 `f_id`,并把 **`f_foreign_id` = 主表 id**
|
||||
- 🔴 子表内字段**自身的 `tableName` 不可信**:实测指向的是主表
|
||||
|
||||
> 代码落点:`crates/sspf-lowcode/src/form.rs::sub_tables`(只看父节点)
|
||||
> 测试钉死:`tests/real_sample.rs::subtable_field_own_table_name_is_misleading`
|
||||
|
||||
---
|
||||
|
||||
## 8. 我们刻意不照抄的地方
|
||||
|
||||
| 项 | jnpf 做法 | 我们怎么做 | 理由 |
|
||||
|---|---|---|---|
|
||||
| 新增返回 | 只返回「新建成功」,无 id | **返回 `id` 与完整行** | AI 拿不到 id 就得再查一次,多一次往返且可能查到别人的数据 |
|
||||
| 列表查询条件 | `queryJson` 是字符串 map | MCP 层用结构化条件(`[{column,op,value}]`) | 字符串 map 无法表达操作符;HTTP 层仍按 jnpf 形状兼容 |
|
||||
| 建管理员 | — | `permission.user.create` 硬编码非管理员 | 权限风险 |
|
||||
| `calculate` | 接收入参 | 同样接收入参(已对齐) | — |
|
||||
|
||||
---
|
||||
|
||||
## 9. 与当前实现的对照
|
||||
|
||||
| 机制 | 状态 | 落点 |
|
||||
|---|---|---|
|
||||
| 列名 = `lower(vModel)` | ✅ 已对齐 | `form::v_model_to_column` |
|
||||
| 系统字段清单 | ✅ 已记录 | 本文件 §4 |
|
||||
| 自动填充表 | ✅ 已对齐 | `widget::auto_fill` |
|
||||
| 控件分类(54 种) | ✅ 已覆盖实测 top 12 | `widget::classify` |
|
||||
| 子表归属看父节点 | ✅ 已对齐 | `form::sub_tables` |
|
||||
| 读 release 而非 dev | 🟡 只读工具读的是 **dev** | P2-b 要补 release 读取 |
|
||||
| 动态 CRUD(写数据) | ❌ 未做 | P2-b |
|
||||
| `f_flow_task_id` = 主键 | ❌ 未做 | P2-b |
|
||||
| 单据号生成器 | ❌ 未做 | P2-b(需序号表) |
|
||||
| 并发锁 `f_version` | ❌ 未做 | P2-b |
|
||||
| 逻辑删除 | ❌ 未做 | P2-b |
|
||||
|
||||
---
|
||||
|
||||
## 10. 复核方法
|
||||
|
||||
改任何与「列名 / 系统字段 / 自动填充」相关的代码前,重跑这几条:
|
||||
|
||||
```bash
|
||||
cargo test -p sspf-lowcode # 40 条,含列名与自动填充的对齐断言
|
||||
bash scripts/lowcode-smoke.sh # 8 条,含反自证
|
||||
```
|
||||
|
||||
源码复核入口(按重要性):
|
||||
|
||||
```bash
|
||||
# 列名规则
|
||||
sed -n '211,340p' $SRC/jnpf-visualdev/jnpf-visualdev-base/jnpf-visualdev-base-biz/\
|
||||
src/main/java/jnpf/base/util/VisualDevTableCre.java
|
||||
|
||||
# 自动填充
|
||||
sed -n '566,632p' $SRC/jnpf-visualdev/jnpf-visualdev-base/jnpf-visualdev-base-biz/\
|
||||
src/main/java/jnpf/base/util/FlowFormDataUtil.java
|
||||
|
||||
# 主表插入(主键 / 流程字段 / 并发锁)
|
||||
sed -n '815,900p' $SRC/jnpf-visualdev/jnpf-visualdev-base/jnpf-visualdev-base-biz/\
|
||||
src/main/java/jnpf/base/util/FlowFormDataUtil.java
|
||||
|
||||
# 接口契约
|
||||
sed -n '310,640p' $SRC/jnpf-visualdev/jnpf-visualdev-onlinedev/\
|
||||
jnpf-visualdev-onlinedev-controller/src/main/java/jnpf/onlinedev/controller/\
|
||||
VisualdevModelDataController.java
|
||||
```
|
||||
Reference in new issue
Block a user