Files
ssw-platform/docs/visualdev-mechanism.md
T
admin 1d1a3b1ef9 feat(mcp): schema.table.create 落地 + P2-b 冒烟闭环,修 data.query 泄漏口令列
- 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
2026-10-31 21:34:37 +08:00

366 lines
16 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-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
```