- 新增 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
11 KiB
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:一律大写。
🔴 两条禁令
- 不要「驼峰转下划线」:
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
}
子表额外多一个外键列 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 |
两条推论(已写进代码)
calculate接收入参 —— 它走getIntValue(dataValue, ...),不是只读。 把它当只读会导致「计算字段永远存不进去」。- 被覆盖的字段不能标
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