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:
admin committed 2026-10-31 12:02:15 +08:00
1 parent f0c77f731c
commit 343772be42
8 files changed
+531 -43

No files matched your search

+12 -5
View File
@@ -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 补。
---
+292
View File
@@ -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
```