Entity Definition Meta-Driven Save Pipeline（最终方案）

一、最终统一口径

1.1 规则来源

统一来自 geDomainModel 返回的元数据：

*FieldMeta（如 TextFieldMeta）
Meta 基类

规则包括：

默认值
默认长度
校验约束
可扩展属性

1.2 运行时定义

后端运行时/领域对象以既有定义为准：

TextField
各类基类领域对象

保存不是“前端传啥存啥”，而是：

payload
-> 转领域对象
-> 补默认
-> 校验
-> 序列化
-> 落库

1.3 保存阶段边界

默认值补齐

仅缺失补：

不覆盖用户输入
不做业务推断

合法性校验

统一按 Meta：

最大长度
格式
范围
必填
引用存在性

持久化

最终序列化 JSON 落：

md_entity_definition

二、分层原则

entity（语义层）

仅保留语义字段：

不放 Unique
不放 Indexed
不放 PrimaryKey

table（物理层）

保留建表约束：

Unique
Indexed
PrimaryKey

三、前端职责

前端仅负责：

输入
展示
基础结构规范化
基础提示

不负责：

默认规则真相
长度规则
业务规则

四、当前问题根因

4.1 Items/entity 双结构不一致

导致：

删除回滚
字段复活
状态错乱

4.2 前端硬编码默认逻辑

导致：

空串冲突
默认值不一致
前后端规则冲突

4.3 绑定字段空值问题

导致：

list/filter binding 报错
IllegalArgumentException
500

五、实施步骤

P0（先止血）

5.1 保存入口统一 normalize

包括：

trim
空值处理
结构对齐

5.2 entity/table 分离

entity

剔除：

Unique
Indexed
PrimaryKey

table

保留：

Unique
Indexed
PrimaryKey

5.3 错误模型

统一返回：

4xx Validation Error

不要再抛：

500 IllegalArgumentException

错误结构必须带：

code
message
path
traceId

P1（核心改造）

5.4 接入 Meta 驱动

统一来源：

geDomainModel

使用：

BaseMeta
*FieldMeta

生成：

EffectiveMeta

5.5 保存链路

payload
-> normalize
-> EffectiveMeta补默认
-> EffectiveMeta校验
-> 转领域对象
-> definition序列化
-> md_entity_definition

P2（收敛）

5.6 前端移除硬编码

移除：

默认长度
默认值推断
类型默认逻辑

5.7 回显统一

统一：

md_entity_definition

反序列化结果作为页面真源。

六、核心规则（必须固化）

6.1 规则真源

仅：

geDomainModel.*FieldMeta

6.2 运行时真源

既有领域对象：

TextField + BaseField

6.3 落库真源

md_entity_definition

6.4 默认补齐原则

仅缺失补
不覆盖用户值

6.5 校验原则

只做：

合法性校验

不做：

业务推断

七、验收标准

7.1 默认一致性

同字段：

不同入口
默认长度一致
默认值一致

全部由 Meta 驱动。

7.2 默认补齐

未传长度

自动补默认长度。

已传长度

不覆盖，仅校验。

7.3 错误定位

非法输入：

返回 4xx
返回字段 path

7.4 回显一致

刷新/切页/重进：

字段不丢
字段不复活

7.5 entity/table 分层正确

entity

无：

Unique
Indexed
PrimaryKey

table

保留：

Unique
Indexed
PrimaryKey

八、Epic 与 Story 拆分

Story 1：Meta 接入

Task

定义 Meta 读取接口
实现 BaseMeta + 子类Meta 合并
增加缓存与版本

验收

能生成：

EffectiveMeta

Story 2：保存链路领域化

Task

payload normalize
payload -> TextField
禁止前端结构直存

验收

落库内容来自：

领域对象序列化

Story 3：默认值补齐

Task

defaultValue/defaultLength
仅缺失补
补齐日志

验收

用户输入不被覆盖。

Story 4：合法性校验

Task

长度校验
格式校验
范围校验
必填校验
引用存在性校验

验收

非法输入：

不写库
返回 Validation Error

Story 5：entity/table 分层

Task

entity

剔除：

Unique
Indexed
PrimaryKey

table

保留：

Unique
Indexed
PrimaryKey

Story 6：错误模型

Task

统一：

{
  "code": "",
  "message": "",
  "details": [
    {
      "path": "",
      "message": ""
    }
  ],
  "traceId": ""
}

Story 7：回读一致性

Task

definition 回显
兼容旧 Items/entity
防止字段复活

九、Meta 扩展架构

9.1 总体模型

BaseModel（平台）
+ VendorOverlay（厂商）
+ TenantOverlay（租户）
+ FormOverlay（表单）
=
EffectiveModel

优先级：

PLATFORM
-> VENDOR
-> TENANT
-> FORM

十、扩展内容

10.1 字段扩展

新字段类型
新属性

10.2 默认值扩展

defaultLength
defaultValue

10.3 校验扩展

regex
range
requiredWhen

10.4 保存扩展

pre-save normalize
validate hooks
post-save hooks

十一、合并规则

基类优先

Base -> Child

Vendor 覆盖 Base

同 key：

后者覆盖前者

validators 合并

按 id：

同 id 覆盖
不同 id 追加

十二、表单级扩展（重点）

12.1 两种 Snapshot

A. Meta Snapshot

模型定义：

TextFieldMeta
BaseFieldMeta

B. Form Snapshot（重点）

具体表单：

ui
formmeta
entitymeta
bizLogic

十三、Form Snapshot 结构

{
  "formId": "purchase_order",
  "modelType": "ui",
  "version": 12,
  "source": {
    "scopeType": "FORM",
    "scopeId": "purchase_order"
  },
  "uiInfo": {
    "ui": {},
    "formmeta": {},
    "entitymeta": {
      "entity": [],
      "table": []
    }
  },
  "bizLogic": {
    "validators": [],
    "beforeSave": [],
    "operations": []
  },
  "meta": {
    "tenantId": "",
    "vendorCode": "",
    "savedAt": ""
  }
}

十四、表单级 Overlay

支持：

addFields
removeFields
updateFields
bizLogicPatch

示例：

{
  "targetFormId": "purchase_order",
  "ops": {
    "addFields": [],
    "removeFields": [],
    "updateFields": [],
    "bizLogicPatch": {}
  }
}

十五、配置表方案

15.1 md_form_extension

新增字段

字段	含义
vendor_code	当前厂商
base_vendor_code	来源厂商
base_ref	来源版本
overlay_json	增量 patch
snapshot_json	完整快照
snapshot_hash	快照摘要
ext_version	版本号
publish_status	draft/published
published_at	发布时间

15.2 md_form_extension_history

字段

字段	含义
before_snapshot_json	保存前完整快照
after_snapshot_json	保存后完整快照
overlay_json	patch
op_type	create/update/publish/rollback

十六、保存流程

读取当前快照
-> before_snapshot
-> 应用 overlay
-> after_snapshot
-> 更新 snapshot_json
-> 写 history

十七、发布流程

draft
-> published
-> 刷缓存

十八、回滚流程

history.after_snapshot
-> 新 draft
-> publish

不是反向操作。

十九、运行时读取

PLATFORM
-> VENDOR
-> TENANT
-> FORM

生成：

EffectiveMeta

并缓存。

二十、最终结论

20.1 模型级

Meta 驱动：

*FieldMeta + BaseMeta

20.2 表单级

Form Snapshot 驱动：

overlay + snapshot + history

20.3 真源统一

规则真源

geDomainModel

运行时真源

领域对象

落库真源

md_entity_definition

表单状态真源

snapshot_json