- 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
366 lines
16 KiB
Markdown
366 lines
16 KiB
Markdown
# 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 字符串,不是对象**
|
||
|
||
```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
|
||
}
|
||
```
|
||
|
||
子表额外多一个**外键列**,列名来自模型的 `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()`:
|
||
|
||
```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`** —— 否则调用方以为传了有用,实际被丢弃。
|
||
|
||
### 🔴 子表 `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. 复核方法
|
||
|
||
改任何与「列名 / 系统字段 / 自动填充」相关的代码前,重跑这几条:
|
||
|
||
```bash
|
||
cargo test -p sspf-lowcode # 112 条,含列名 / 自动填充 / 建表 DDL 的对齐断言
|
||
bash scripts/lowcode-smoke.sh # 15 条,含 4 条反自证(L6/L7/L13/L14)
|
||
```
|
||
|
||
源码复核入口(按重要性):
|
||
|
||
```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
|
||
```
|