Files
ssw-platform/docs/visualdev-mechanism.md
T
admin 343772be42 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
2026-10-31 12:02:15 +08:00

11 KiB
Raw Blame History

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 字符串,不是对象

// 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
}

子表额外多一个外键列 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():

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. 复核方法

改任何与「列名 / 系统字段 / 自动填充」相关的代码前,重跑这几条:

cargo test -p sspf-lowcode                    # 40 条,含列名与自动填充的对齐断言
bash scripts/lowcode-smoke.sh                 # 8 条,含反自证

源码复核入口(按重要性):

# 列名规则
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