Files
ssw-platform/docs/visualdev-mechanism.md
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

16 KiB
Raw Blame History

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:一律大写。

🔴 两条禁令

  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() 在用户字段之后无条件追加:

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

两条推论(已写进代码)

  1. calculate 接收入参 —— 它走 getIntValue(dataValue, ...),不是只读。 把它当只读会导致「计算字段永远存不进去」。
  2. 被覆盖的字段不能标 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