元数据驱动架构设计

配置（Configuration）
  → 影响行为但不定义结构，如「每页 20 条」
  → 特点：扁平、少量、可硬编码默认值

元数据（Metadata）
  → 描述应用的结构，如「这个表单有哪些字段」
  → 特点：结构化、层级、是运行时的输入

代码（Code）
  → 元数据无法表达的兜底，如复杂算法
  → 特点：灵活、不可配置、需发布

第一层：数据模型    实体、字段、类型、关系、约束
第二层：界面        页面、组件树、布局、样式
第三层：行为        事件、表达式、动作、联动
第四层：权限        角色、资源、操作、行级规则
第五层：流程        节点、连线、条件、触发
第六层：应用与导航  菜单、路由、入口、主题

// 字段定义：平台最核心的元数据类型
interface FieldSchema {
  id: string;                 // 稳定标识，不可变
  name: string;               // 机器名，用于绑定
  label: string;              // 显示名，可 i18n
  type: FieldType;            // string/number/date/ref/enum...
  required?: boolean;
  defaultValue?: unknown;
  validators?: Validator[];   // 校验规则
  visibleWhen?: string;       // 显隐表达式
  editableWhen?: string;      // 可编辑表达式
  options?: OptionSource;     // 枚举/引用来源
  meta?: Record<string, unknown>; // 组件私有配置
}

type FieldType =
  | 'string' | 'text' | 'number' | 'boolean'
  | 'date' | 'datetime' | 'enum' | 'ref'
  | 'file' | 'json' | 'richText';

{
  "id": "form_leave_001",
  "version": 3,
  "fields": [
    {
      "id": "f_1",
      "name": "applicant",
      "label": "申请人",
      "type": "ref",
      "options": { "source": "user", "displayField": "fullName" },
      "required": true,
      "editableWhen": "false"
    },
    {
      "id": "f_2",
      "name": "days",
      "label": "请假天数",
      "type": "number",
      "required": true,
      "validators": [{ "type": "min", "value": 0.5 }]
    },
    {
      "id": "f_3",
      "name": "reason",
      "label": "事由",
      "type": "text",
      "visibleWhen": "days > 3",
      "required": true
    }
  ]
}

描述层（Design Time）
  设计器产出元数据
  元数据 = 纯数据，无副作用

  ── 编译/加载 ──

运行层（Run Time）
  渲染器读取元数据 → 生成视图
  求值器读取表达式 → 计算结果
  执行器读取动作 → 调用接口

版本化三要素：
  1. 快照：每次发布生成不可变快照
  2. 差异：能对比任意两个版本的差异
  3. 回滚：能一键回到任意历史版本

版本粒度：
  应用级（整体发布）vs 元素级（单个表单）
  推荐：应用级发布 + 元素级 diff

# 发布记录
release:
  app: leave-approval
  version: 12
  baseVersion: 11
  author: leeting
  changes:
    - op: add
      path: /fields/3
      value: { name: "attachment", type: "file" }
    - op: update
      path: /fields/1/required
      from: false
      to: true

-- 元数据主表：当前生效版本
CREATE TABLE app_metadata (
  app_id      VARCHAR(64) PRIMARY KEY,
  tenant_id   VARCHAR(64) NOT NULL,
  version     INT NOT NULL,
  schema      JSONB NOT NULL,       -- 完整元数据
  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_by  VARCHAR(64) NOT NULL
);

-- 版本历史：只读归档
CREATE TABLE app_metadata_history (
  app_id      VARCHAR(64) NOT NULL,
  version     INT NOT NULL,
  schema      JSONB NOT NULL,
  release_note TEXT,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (app_id, version)
);

路线 A：解释（Interpret）
  运行时直接读取元数据 → 逐步解释执行
  优点：改动即时生效、无需构建
  缺点：运行时开销、逻辑分散

路线 B：编译（Compile）
  构建期把元数据编译为代码/IR → 运行代码
  优点：运行时快、可静态分析
  缺点：需要构建步骤、改动有延迟

路线 C：混合
  结构解释（渲染）、热点编译（复杂表达式）

const cache = new Map<string, (ctx: Context) => unknown>();

function compile(expr: string) {
  if (cache.has(expr)) return cache.get(expr)!;
  const ast = parse(expr);
  const fn = (ctx: Context) => evaluate(ast, ctx);
  cache.set(expr, fn);
  return fn;
}

设计目标：
  1. 安全：不能执行任意代码
  2. 可分析：能提取依赖字段
  3. 可解释：错误信息可读
  4. 有限：不图灵完备（避免死循环）

常见语法：
  days > 3 && status == "pending"
  $user.dept == $record.dept
  CONCAT(firstName, " ", lastName)

function extractDeps(ast: Node): string[] {
  const deps = new Set<string>();
  walk(ast, (n) => { if (n.type === 'Identifier') deps.add(n.name); });
  return [...deps];
}

// 校验器：同一份 Schema 在前端与后端都能跑
type Validator =
  | { type: 'min'; value: number }
  | { type: 'max'; value: number }
  | { type: 'pattern'; value: string }
  | { type: 'minLength'; value: number }
  | { type: 'custom'; expr: string };

function validateField(field: FieldSchema, value: unknown): string | null {
  if (field.required && isEmpty(value)) return `${field.label} 不能为空`;
  for (const v of field.validators ?? []) {
    const err = runValidator(v, value);
    if (err) return err;
  }
  return null;
}

缓存层级：
  L1 进程内（Map）：解析后的元数据对象
  L2 分布式（Redis）：跨实例共享
  L3 CDN/边缘：静态渲染场景

失效方式：
  - 主动失效：发布时发布事件，各实例清缓存
  - 版本号：元数据带 version，读取时校验
  - TTL 兜底：即使事件丢失，也能最终一致

async function getMetadata(appId: string) {
  const cached = l1.get(appId);
  if (cached && cached.version === await latestVersion(appId)) return cached;
  const fresh = await loadFromDb(appId);
  l1.set(appId, fresh);
  return fresh;
}