schemagine

Schemagine

Schema 驱动的 Vue 3 动态表单与数据管理引擎。 · MIT 许可证

English | 简体中文

只需用一份 JSON ModuleSchema 定义字段、权限、公式与关联关系，Schemagine 即可渲染出完整的列表 / 卡片 / 新增三种视图：支持排序筛选的表格、乐观锁行内编辑、公式字段、级联权限、Schema 平滑迁移，以及可插拔的 Service 层对接你自己的后端。

基于 Vue 3.5 + TypeScript + Pinia + Element Plus + vxe-table 构建，以 ESM + CJS 双格式库发布，附带完整类型声明。

✨ 功能特性

🏗 架构

SchemaEngine（入口）               ← 加载 Schema、权限、用户配置，编排全局流程
  └─ SchemaContextProvider        ← provide 上下文（schemaMeta / recordState / uiState）
       └─ ViewContainer           ← 根据 viewMode 切换子视图
            ├─ ListView           ← 列表视图
            │    ├─ 每列表头排序 / 筛选弹层
            │    ├─ ListActionBar ← 列表级操作按钮
            │    ├─ SchemaTable   ← vxe-table 封装
            │    └─ BottomTabs + SchemaPagination
            ├─ CardView           ← 卡片浏览（上/下条导航）
            │    └─ SchemaCard    ← 16 列 Grid 布局
            └─ CreateView / CardCreateView  ← 批量 / 单条录入
  └─ GlobalDialogHost             ← 快速新建、列设置、公式详情、版本冲突等弹窗宿主

数据流（严格单向）：UI → Composables/状态 → Service → 你的后端

📦 安装

pnpm add schemagine

对等依赖（需在宿主项目中安装）：vue ^3.5、pinia ^3.0、element-plus ^2.13、vue-router ^5.0、vxe-table ^4.18、vxe-pc-ui ^4.13、xe-utils ^4.0、mathjs ^15。

pnpm add vue pinia element-plus vue-router vxe-table vxe-pc-ui xe-utils mathjs

在应用入口注册插件：

import { createPinia } from 'pinia'
import ElementPlus from 'element-plus'
import VxePcUI from 'vxe-pc-ui'
import VxeTable from 'vxe-table'

app.use(createPinia())
app.use(ElementPlus)
app.use(VxePcUI)
app.use(VxeTable)

引入样式（Element Plus / vxe-table 样式 + 引擎样式，引擎样式内含 --sg-* Token 基线）：

import 'element-plus/dist/index.css'
import 'vxe-pc-ui/lib/style.css'
import 'vxe-table/lib/style.css'
import 'schemagine/dist/schemagine.css'

⚠️ 必须配置 Vite resolve.dedupe。 Schemagine 以库模式构建，vue / pinia / vue-router 均为 external。不去重时可能出现两份 Pinia 实例，导致 Cannot read properties of undefined (reading '_s') 崩溃：

// vite.config.ts
export default defineConfig({
  resolve: { dedupe: ['pinia', 'vue', 'vue-router'] },
})

🚀 快速开始

方式 A — Mock 模式（无需后端）

// main.ts
// 0.3.19 起 mock 从子路径导入，根入口不再携带 mock 代码
import { initMockServices } from 'schemagine/mock'

initMockServices() // 基于 localStorage 的示例模块，刷新后数据保留

<script setup lang="ts">
import { SchemaEngine } from 'schemagine'
</script>

<template>
  <SchemaEngine module-id="module-voucher" />
</template>

内置示例模块：module-voucher（凭证管理，完整功能演示）、module-ap（FK 关联）、module-invoice、module-sales-order、module-receivable、module-user、module-workshop，以及边界场景模块（module-empty、module-no-perm）。调用 resetAllStorage() 可重置数据（同样自 schemagine/mock 导入——根导出已标注废弃，0.4.0 移除）。也支持只 Mock 部分 Service，其余覆盖为真实实现。

方式 B — 对接自己的后端（Service 注入）

引擎本身不包含任何业务 API。实现以下接口并在挂载前注入：

import { setRecordService, setSchemaService, setCandidateService,
         setUserViewConfigService, setRelationService, setMediaService } from 'schemagine'

setRecordService(new MyRecordService())          // list / getDetail / patchField / create / batchCreate / listFieldValueCandidates
setSchemaService(new MySchemaService())          // loadModuleSchema / loadModulePermissions / validateSchema / saveModuleSchema / listModuleIds
setCandidateService(new MyCandidateService())    // FK 下拉候选值
setUserViewConfigService(new MyViewConfigService()) // 按用户持久化的列宽、布局等
setRelationService(new MyRelationService())      // 一对多 / 多对多关联
setMediaService(new MyMediaService())            // 可选：图片字段的媒体库

所有方法返回统一响应结构：

interface ApiResponse<T> {
  success: boolean
  data: T
  message?: string
  errorCode?: string
  details?: unknown[]
}

未注入 Service 时，引擎回退到返回 SERVICE_NOT_INITIALIZED 错误的 Stub 实现，不会崩溃。

然后渲染模块：

<script setup lang="ts">
import { SchemaEngine } from 'schemagine'

function onDataChanged(payload: { moduleId: string }) {
  // 刷新角标、通知等
}
</script>

<template>
  <SchemaEngine
    module-id="my-module"
    :readonly="false"
    :global-context="{ currentUser, systemSettings }"
    @module-loaded="onLoaded"
    @data-changed="onDataChanged"
  />
</template>

🧩 <SchemaEngine> API

// Props
moduleId: string                        // 必填 — 要加载的 Schema / 数据模块
initialViewMode?: 'list' | 'card' | 'create'
embedded?: boolean                      // 嵌入模式（移除外边距与背景）
readonly?: boolean                      // 全局只读
globalContext?: Record<string, unknown> // 供 visibleWhen / editableWhen 条件表达式使用

// 事件
module-loaded       { moduleId }
view-mode-change    { mode }
data-changed        { moduleId }
error               { moduleId, code, message }
request-open-dialog { dialogType, payload }
action-trigger      { action: ListAction, context? }  // 列表级操作，含批量删除（type: 'delete'）
row-action          { rowId, field, actionId }        // 行级操作，含已确认的删除

// 通过 ref 暴露
refresh(): void                     // 重新加载模块
setViewMode(mode): void             // 切换视图
getCurrentRecord(): RecordEntity | undefined

删除是标准数据操作：引擎负责渲染操作列、批量工具栏及全部二次确认弹窗（由 schema.operations.delete 与 permissions.delete 共同决定是否可用），实际的删除执行通过 row-action / action-trigger 事件交由宿主完成。

📐 Schema 一览

interface ModuleSchema {
  id: string
  name: string
  version: string                       // 语义化版本号，驱动迁移
  moduleType: 'list' | 'card' | 'both'
  fields: FieldSchema[]
  permissions: ModulePermissions        // view / create / edit / delete / export / configure
  defaultViewMode: 'list' | 'card' | 'create'
  createMode?: 'list' | 'card'
  listEditMode?: 'inline-dblclick' | 'select-then-edit'
  operations?: { delete?: DeleteOperationConfig }  // 标准数据操作
  formulaConfig?: FormulaConfig
  listActions?: ListAction[]
  migrations?: SchemaMigration[]
  status: 'active' | 'disabled' | 'error'
}

interface FieldSchema {
  id: string; name: string; key: string; label: string
  type: FieldType
  required: boolean; readonly: boolean; visible: boolean; sortable: boolean; filterable: boolean
  // 布局：order / width / fixed …
  // 行为：defaultValue、validationRules、permission、visibleWhen / editableWhen
  // 组合：formula、dynamicMax、options、targetModule + displayField（FK）、
  //       relationConfig / reverseRefConfig、aggregation、rowAction、prefixStr / suffixStr
  // 演进：previousKeys（重命名映射）
}

type FieldType =
  | 'text' | 'number' | 'date' | 'datetime' | 'boolean'
  | 'select' | 'multi-select' | 'status' | 'percent' | 'currency' | 'money'
  | 'phone' | 'email' | 'url'
  | 'fk' | 'one-to-many' | 'many-to-many' | 'reverse-ref'
  | 'formula' | 'image' | 'mediaImage' | 'attachment' | 'json' | 'action'

筛选采用标准化的 FilterClause[] 协议，支持 10 种算子：eq · neq · like · notLike · in · notIn · between · notBetween · isNull · isNotNull。

🔧 组合式函数

工具函数：formatMoney、getOperatorLabel / OPERATOR_LABEL_MAP、resolveDataOperations / applyBuiltinOperations、resolveEnumTagStyle、resolveMediaUrl 等，均从包根导出并附带类型。

📜 声明式规则（schemagine/rules）

独立子路径导出的规则运行时：框架无关、零依赖——库只产出 Effect 描述符（"规划"），宿主负责执行（"解释"）。求值器（如 mathjs）、函数词典（内置仅 now/sum/count/min/max/abs/ceilTo/roundTo，业务函数一律由宿主经词典注册）、动作与 Flow 均以注入接入。

import { createRuntime, validateRules } from 'schemagine/rules'

const runtime = createRuntime({ evaluate, parse, functions, flows, actions })
const compiled = runtime.compileModule(schema)
runtime.evalCondition(['status', 'eq', 0], { record })     // 对象形 | 三段形 | 表达式串
runtime.runComputes(compiled, { record }, 'price')         // watch 触发 + 声明序级联 → SET/FORCE
runtime.runValidates(compiled, { record }, 'price', 5, 0)  // { ok, message?, force? }
runtime.planAction(actionRule, { record })                 // confirm → invoke/open/navigate → toast
await runtime.runFlow(flow, { record }, executor)          // 步骤四要素 action/params/when/as

八类规则位 condition/compute/map/lookup/validate/action/style/aggregate，挂载于 ModuleSchema.rules、FieldSchema.rules 与 RowActionConfig.action。schema 交 <SchemaEngine> 渲染时引擎原生接线：行内编辑触发 compute 链与 validate 门禁，action 点击产出 Effect 交 rulesExecutor prop，labelWhen 按行切换按钮文案，aggregate 规则扩展统计条；Schema Editor 内置规则编辑面板，validateSchema 对非法规则给出 error 诊断。同构校验器 validateRules / validateFlow / validateDictionary 可在服务端复用。

🎨 主题定制

全部组件样式 Token 化为 --sg-* CSS 变量（随库打包在 schemagine.css 中）。三种可叠加的定制方式：

/* 1) 零配置 — 跟随 Element Plus 主题，含 html.dark 暗色模式 */

/* 2) 在任意祖先覆盖 Token — 支持只改部分 */
:root {
  --sg-color-primary: #7c3aed;  /* 品牌色；浅色阶与 focus 光晕自动跟随 */
  --sg-radius-md: 6px;
  --sg-font-size-base: 13px;
}

/* 3) 覆盖 Element Plus 的 --el-* 变量 — 引擎基色经 var(--el-*, 回退) 传导，同样生效 */

已 Token 化的维度：颜色（品牌 / 功能 / 文字 / 边框 / 填充 / 背景）、8 档字号、2px 网格间距、控件高度、7 档圆角、4 档阴影 + focus 光晕、z-index 层级、过渡时长。完整基线见 docs/15-样式Token基线.md。

🖥 演示应用（本仓库）

pnpm install
pnpm dev        # 启动 Vite，默认打开凭证管理演示模块（Mock 模式）

🛠 开发

pnpm install
pnpm dev              # 开发服务器
pnpm type-check       # vue-tsc 类型检查
pnpm test:unit        # Vitest 单元测试
pnpm test:e2e         # Playwright E2E（需先构建）
pnpm test:e2e:p0      # 仅 P0 核心链路用例（另有 :p1 / :p2 / :all；PowerShell 脚本）
pnpm lint             # ESLint + oxlint
pnpm format           # oxfmt
pnpm build            # 类型检查 + 应用构建
pnpm build:lib        # 库构建 → dist/schemagine.{mjs,cjs} + schemagine.css + *.d.ts

环境要求：Node ^20.19.0 || >=22.12.0，pnpm。

发布（pnpm publish，prepublishOnly 自动构建）仅包含 dist/：ESM + CJS + CSS + 类型声明。CI 发布示例见 引用指南.md 发布章节。

📚 文档

❓ 常见问题

引擎会和宿主应用的 Pinia 状态冲突吗？ 不会。每个 <SchemaEngine> 通过 create*State() 工厂创建隔离的实例状态，Pinia Store 也是动态注册的，多实例安全共存（配合上文必需的 Vite dedupe 配置）。

大数据量下表现如何？ 表格基于 vxe-table 虚拟滚动；列表走服务端分页；CSV 导出按页拉取并设有安全上限（5,000 行）。

Schema 变更后旧数据怎么办？ 在 migrations[] 中声明迁移（fromVersion → toVersion），重命名字段用 previousKeys — 引擎加载时自动迁移记录、视图配置与筛选预设。

可以替换 UI 层吗？ 可以 — 通过 useSchemaMeta() / useRecords() 消费状态，用导出的积木（SchemaTable、FieldEditorFactory、ValueRenderer 等）自由组合自己的视图。

📄 许可证

MIT