- 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
16 KiB
jnpf 在线开发(visualdev)运行时机制 —— 对齐笔记
这份文件解决什么问题:
PLAN.md第 4 条要求「以 jnpf 源码迁移,数据库脚本一致, API 调用/行为一致」。要做到「行为一致」,必须先知道原平台到底怎么跑。 本文件是从 Java 源码逐条读出来的机制。P2-a/P2-b 已按它落地(sspf-lowcode+data.record.*), §9 是「机制 ↔ 实现」的对照表;后续阶段(读 release / 单据号 / 乐观锁)仍以本文为准。每条结论都标了源码位置,改代码前先回来核对,别凭印象。
源码根:/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 字符串,不是对象
// VisualdevModelDataController.create()
Map<String, Object> map = JsonUtil.stringToMap(visualdevModelDataCrForm.getData());
⇒ 请求体长这样:
{ "data": "{\"F_Title\":\"标题\",\"F_Amount\":100}", "menuId": "..." }
传对象会被反序列化失败。VisualdevModelDataCrForm 里 private String data; 是硬证据。
② 新增成功不返回 id
return ActionResult.success(MsgCode.SU001.get()); // 只有「新建成功」
visualCreate 内部生成了 mainId 并塞进 DataModel,但 controller 没往外传。
⇒ 调用方要拿 id 必须再查一次列表。MCP 层必须补上这个返回值(见 §7)。
③ 列表用 POST 不是 GET
PaginationModel 里 queryJson / superQueryJson 都是字符串:
Map<String, Object> keyJsonMap = JsonUtil.stringToMap(paginationModel.getQueryJson());
// 格式:{ "<字段id>": <值> } 的扁平 map
配合 columnData.searchList(搜索项定义)解释每个键怎么查。
这不是通用条件表达式 —— 它是「列表页搜索框」的序列化。
2. 读写的是发布版,不是草稿
// 几乎每个 handler 的第一行
VisualdevEntity visualdevEntity = visualdevService.getReleaseInfo(modelId);
base_visual_dev 是草稿,base_visual_release 是发布快照。
运行时(列表/详情/新增/修改/删除)全部读 release。
⇒ 改了 dev 不发布,前端看不到效果。这不是 bug。
只有 GET /{modelId}/Config?type=0 明确读 dev。
3. 列名规则(最重要的一条)
结论
低代码动态建的表,列名 = lower(__vModel__)。
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
// fieldList()
String vmodel = fieLdsModel.getVModel();
...
fieldForm.setField(vmodel); // ← 原样写,不做任何拆分
② 数据库类型决定大小写
// 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:一律大写。
🔴 两条禁令
- 不要「驼峰转下划线」:
F_CreatorTime若拆成f_creator_time,和 jnpf 建出来的f_creatortime对不上,SQL 直接column does not exist。 - 不要拿平台表类比:
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() 在用户字段之后无条件追加:
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
}
子表额外多一个外键列,列名来自模型的 tableField —— 实测 test_details 是
f_receivableid(不是常量 f_foreign_id)。f_foreign_id 是早期猜测,已在
sspf-lowcode/src/sql.rs 与建表模块里按真实数据纠正。
字段名常量见 $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。
🔴 生成 DDL 的口径:模型驱动(Java 是表单驱动)
jnpf VisualDevTableCre |
本仓 sspf-lowcode::ddl |
|
|---|---|---|
| 列来源 | 表单控件(FieLdsModel)+ 追加系统列 |
模型 f_tables_data + 补齐缺失的系统列 |
| 列序 | 控件顺序 + 系统列在后 | 模型顺序(= 官方回写后的真实列序) |
| 类型/长度 | 按控件类型与 dataType 配置推 |
按模型 dataType / dataLength 直接映射 |
| 适用场景 | 第一次建表(只有设计稿) | 设计稿已含模型(官方数据的常态) |
为什么可以不照抄表单驱动:库里真实的 f_tables_data 本来就是建表之后回写的产物
(entity.setVisualTables(...)),列序与官方 DDL 逐列一致 —— 再拿表单控件反推一遍
只会多一层「控件类型 ↔ DDL 类型」的多对一映射,反而容易错。
前置条件是 模型与表单自洽,这由 form.validate 负责(列集合对不上会报 COLUMN_NOT_IN_TABLE)。
🔴 DEFAULT 差异:动态建表 vs 官方手写 SQL
| 列 | Java 动态建表 | 官方手写 jnpf_db_init.sql |
|---|---|---|
f_tenant_id |
VARCHAR(50) DEFAULT '0' NOT NULL |
同(有 DEFAULT) |
f_version |
INTEGER DEFAULT '0' |
INTEGER(没有 DEFAULT) |
f_flow_state |
INTEGER DEFAULT '0' |
INTEGER(没有 DEFAULT) |
原因:ConcurrencyUtils.getDbFieldModel() 对 TENANTID / FLOWSTATE / VERSION 设了
defaultValue="0",FormatSql.defaultCheck() 所有类型都加引号 ⇒ 输出 DEFAULT '0'。
官方初始化脚本是手写的,不是这条链路的产物,所以没有 DEFAULT。
⇒ 本仓生成的是「Java 动态建表」的结果(带 DEFAULT)。语义等价(PG 里
INTEGER DEFAULT '0' 合法,字符串常量会转成目标类型),但逐字对比官方脚本时会看到差异 ——
这不是 bug,是两条不同来源的 DDL。
5. 主键与流程字段
FlowFormDataUtil.createMast():
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 |
两条推论(已写进代码)
calculate接收入参 —— 它走getIntValue(dataValue, ...),不是只读。 把它当只读会导致「计算字段永远存不进去」。- 被覆盖的字段不能标
acceptsInput—— 否则调用方以为传了有用,实际被丢弃。
🔴 子表 modifyTime / modifyUser 策略(已定,刻意与 Java 有一处差异)
口径:自动填充跟随表单控件 —— 表单里有 modifyTime / modifyUser 控件才写,
没有这个控件就不写(列可以存在,但没人填)。
| 场景 | Java | 本仓 |
|---|---|---|
| 新增(主表 / 子表) | 置 null |
置 null(一致) |
| 更新(主表 / 子表已有行) | 写当前时间 / 当前用户 | 写当前时间 / 当前用户(一致) |
| 更新时新增的子表行 | childNeedAdd=true ⇒ 跳过填充,保留入参值 |
按「新增」语义置 null |
最后一处是刻意的:让调用方能给新子行伪造 modifyUser / modifyTime 没有好处,
而「新行没有修改人」在审计上自洽。差异只落在审计列,不碰业务列 ——
P4 影子对账时按「忽略审计列」处理即可。
代码落点:
crates/sspf-lowcode/src/sql.rs::sub_row_columns(is_update分支) 测试钉死:update_writes_modify_time_and_modify_user/insert_nulls_modify_time_and_modify_user
代码落点:
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,外键列(模型tableField,如f_receivableid)= 主表 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 / ddl::SystemColumn |
| 自动填充表 | ✅ 已对齐 | widget::auto_fill |
| 控件分类(54 种) | ✅ 已覆盖实测 top 12 | widget::classify |
| 子表归属看父节点 | ✅ 已对齐 | form::sub_tables |
| 建表 DDL(类型映射/复合主键/系统列) | ✅ 已对齐 | ddl::plan_create + rewrite_model |
建表后回写 f_tables_data |
✅ 已对齐 | lowcode_ddl::create_and_sync |
| 动态 CRUD(写数据) | ✅ 已对齐 | lowcode_crud + data.record.* |
f_flow_task_id = 主键 |
✅ 已对齐 | sql::main_guard.flow_task_id |
| 逻辑删除 | ✅ 已对齐(f_delete_mark 是 INTEGER) |
sql::soft_delete_row |
| 读 release 而非 dev | 🟡 只读工具读的是 dev | 运行时读 release 待补(P2-c) |
| 单据号生成器 | ❌ 未做(需序号表);billRule 入参不被覆盖已实现 |
P2-c |
并发锁 f_version |
🟡 只写初值 0,不校验版本 | 真乐观锁待补(P3) |
10. 单租户口径的交叉证据
「f_tenant_id 固定 '0'」不是约定俗成,有三条独立证据:
| 证据 | 内容 |
|---|---|
| 部署配置 | jnpf-k8s/k8s/20-admin.yaml 的 config.MultiTenancy: false(2026-10-31 起)⇒ admin 只查 j7 库的 public schema;登录账号不带租户号;jnpf-tenant 服务仍在跑但已成孤儿 |
| Java 代码链 | FlowFormDataUtil.addTenantId() → TenantDataSourceUtil.getTenantColumn() → 多租户关闭时返回 GlobalConst.DEFAULT_TENANT_VALUE,其值就是 "0" |
| 官方手写 DDL | test_receivable:f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL + PRIMARY KEY (f_id, f_tenant_id) |
⇒ 单租户下 f_tenant_id 恒为 "0",且这一列 NOT NULL 并参与复合主键 ——
即使只有一个租户也不能省略。本仓 DEFAULT_TENANT_ID = "0"、建表生成
f_tenant_id VARCHAR(50) DEFAULT '0' NOT NULL,与上表逐字对得上。
⚠️ 未做的人工核对:JNPF 完整部署(http://192.168.1.26:30093/)里动态表的
f_tenant_id 实际分布没抽查 —— 需要登录凭据(本次自动运行未提供,按约定不入档)。
要核:SELECT f_tenant_id, count(*) FROM test_receivable GROUP BY 1,或多建几条记录看是否为 0。
11. 复核方法
改任何与「列名 / 系统字段 / 自动填充」相关的代码前,重跑这几条:
cargo test -p sspf-lowcode # 112 条,含列名 / 自动填充 / 建表 DDL 的对齐断言
bash scripts/lowcode-smoke.sh # 15 条,含 4 条反自证(L6/L7/L13/L14)
源码复核入口(按重要性):
# 列名规则
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