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

293 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```