@aiao/rxdb-model 0.0.18 → 0.0.26

package/dist/query-builder/utils/value-input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-input.d.ts","sourceRoot":"","sources":["../../../src/query-builder/utils/value-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAGtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAGjF,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,OAAO,EAAE,EACvB,gBAAgB,GAAE,gBAA+C,GAChE,MAAM,CAiCR;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAqB5D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE,CASnF"}
+{"version":3,"file":"value-input.d.ts","sourceRoot":"","sources":["../../../src/query-builder/utils/value-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAGtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAGjF,oDAAoD;AACpD,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,OAAO,EAAE,EACvB,gBAAgB,GAAE,gBAA+C,GAChE,MAAM,CAiCR;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAqB5D;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE,CASnF"}

package/dist/structural-equal.d.ts

@@ -2,6 +2,10 @@
  * 结构化深比较，替代 JSON.stringify 比较。
  * 递归比较对象和数组，不依赖 key 序列化顺序。
  * 支持循环引用检测，避免无限递归。
+ * @param a - 参与比较的第一个值
+ * @param b - 参与比较的第二个值
+ * @param seen - 已访问的对象集合，用于循环引用检测
+ * @returns 两者结构相等时返回 true
  */
-export declare function structuralEqual(a: unknown, b: unknown, seen?: WeakSet<object>): boolean;
+export declare function structuralEqual(a: unknown, b: unknown): boolean;
 //# sourceMappingURL=structural-equal.d.ts.map

package/dist/structural-equal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structural-equal.d.ts","sourceRoot":"","sources":["../src/structural-equal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,kBAAwB,GAAG,OAAO,CA+B7F"}
+{"version":3,"file":"structural-equal.d.ts","sourceRoot":"","sources":["../src/structural-equal.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAE/D"}

package/package.json

@@ -1,14 +1,33 @@
 {
   "name": "@aiao/rxdb-model",
-  "version": "0.0.18",
+  "version": "0.0.26",
+  "description": "Framework-agnostic entity model core for Aiao RxDB: metadata-driven forms, details, editable tables and query builder.",
+  "homepage": "https://rxdb.netlify.app/docs",
+  "bugs": {
+    "url": "https://github.com/aiao-io/rxdb/issues"
+  },
+  "keywords": [
+    "aiao",
+    "rxdb",
+    "entity",
+    "form",
+    "table",
+    "query-builder"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aiao-io/rxdb.git",
+    "directory": "packages/rxdb-model"
+  },
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "@aiao/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
@@ -16,18 +35,23 @@
   },
   "files": [
     "dist",
+    "src",
+    "!src/**/*.spec.*",
+    "!src/**/*.test.*",
+    "!src/**/__tests__/**",
     "!**/*.tsbuildinfo"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
-    "uuid": "^13.0.0",
-    "@aiao/rxdb": "0.0.18"
+    "clsx": "^2.1.1",
+    "rxjs": "^7.8.2",
+    "uuid": "^14.0.2",
+    "@aiao/rxdb": "0.0.26"
   },
   "peerDependencies": {
-    "rxjs": ">=7.0.0",
-    "@visactor/vtable": ">=1.0.0",
-    "@visactor/vtable-editors": ">=1.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
+    "@visactor/vtable": "~1.26.5",
+    "@visactor/vtable-editors": "~1.26.5"
   }
 }

package/src/cn.ts

@@ -0,0 +1,21 @@
+import { clsx, type ClassValue } from 'clsx';
+
+/**
+ * 拼接 CSS 类名（clsx 的薄封装）。
+ *
+ * 过滤 falsy 值并支持对象 / 数组形式的条件类名，用于替代模板字符串拼接：
+ * 模板字符串中条件类名前的分隔空格若位于行尾，会被格式化工具的尾随空白
+ * 裁剪吃掉，产生 `flex-coloverflow-auto` 这类拼接错误；本函数不存在该问题。
+ *
+ * @param inputs - 字符串类名、条件对象或数组，falsy 值会被自动忽略
+ * @returns 以单个空格连接后的类名字符串
+ *
+ * @example
+ * ```ts
+ * cn('tab-content flex-col', isForm ? 'overflow-auto p-4' : 'overflow-hidden')
+ * // 'tab-content flex-col overflow-auto p-4'
+ * ```
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return clsx(inputs);
+}

package/src/entity-capabilities.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview 实体界面能力派生（US-027）
+ *
+ * 实体管理界面的「新增 / 编辑 / 删除」入口只读这一份结论，结论只来自实体的 `permissions` 声明：
+ * 是不是系统表、在哪个命名空间都不参与——系统表已经显式声明三项都为 `'system'`。
+ */
+
+import { type EntityMetadata, getEntityPermission } from '@aiao/rxdb';
+
+/**
+ * 实体在公开写入口上允许的界面操作
+ */
+export interface EntityCapabilities {
+  /** 可新增：`create` 为 `'both'` */
+  readonly canCreate: boolean;
+  /** 已有行可编辑：`update` 为 `'both'`；否则行只读、详情以查看模式打开 */
+  readonly canEdit: boolean;
+  /** 已有行可删除：`delete` 为 `'both'` */
+  readonly canDelete: boolean;
+}
+
+/**
+ * 由实体元数据派生界面能力
+ *
+ * @param metadata - 实体元数据（只读其中的 `permissions`）
+ * @returns 三项能力；未声明的操作按 `'both'` 计，即可用
+ *
+ * @example
+ * ```typescript
+ * const { canCreate, canEdit, canDelete } = deriveEntityCapabilities(getEntityMetadata(Invoice));
+ * ```
+ */
+export const deriveEntityCapabilities = (metadata: Pick<EntityMetadata, 'permissions'>): EntityCapabilities => ({
+  canCreate: getEntityPermission(metadata, 'create') === 'both',
+  canEdit: getEntityPermission(metadata, 'update') === 'both',
+  canDelete: getEntityPermission(metadata, 'delete') === 'both'
+});

package/src/entity-detail/detail-tabs.ts

@@ -0,0 +1,48 @@
+/**
+ * Entity Detail 标签构建工具
+ * 根据实体元数据生成详情页标签配置
+ * @module entity-detail/detail-tabs
+ */
+import { RelationKind, type EntityMetadata } from '@aiao/rxdb';
+
+import type { DetailFormTab, DetailTab, DetailTableTab } from './interfaces.js';
+
+/**
+ * 根据实体元数据构建详情页标签列表
+ * @remarks 基本信息表单标签固定排在首位，其后为每个一对多 / 多对多关系生成一个表格标签
+ * @param metadata - 实体元数据
+ * @returns 详情页标签配置列表
+ */
+export function buildDetailTabs(metadata: EntityMetadata): DetailTab[] {
+  const formTab: DetailFormTab = {
+    key: 'basic',
+    label: '基本信息',
+    type: 'form'
+  };
+
+  const relationTabs: DetailTableTab[] = [];
+
+  metadata.relationMap.forEach((relation, name) => {
+    if (relation.kind !== RelationKind.ONE_TO_MANY && relation.kind !== RelationKind.MANY_TO_MANY) return;
+
+    const tab: DetailTableTab = {
+      key: name,
+      label: relation.displayName ?? name,
+      type: 'table',
+      relationName: name,
+      relatedEntityName: relation.mappedEntity,
+      relatedNamespace: relation.mappedNamespace ?? 'public',
+      relationKind: relation.kind
+    };
+
+    if (relation.kind === RelationKind.ONE_TO_MANY) {
+      tab.foreignKeyField = `${relation.mappedProperty}Id`;
+    } else if (relation.kind === RelationKind.MANY_TO_MANY) {
+      tab.mappedProperty = relation.mappedProperty;
+    }
+
+    relationTabs.push(tab);
+  });
+
+  return [formTab, ...relationTabs];
+}

package/src/entity-detail/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Entity Detail 模块
+ * 提供实体详情页标签的类型定义与构建工具
+ * @module entity-detail
+ */
+export * from './detail-tabs.js';
+export * from './interfaces.js';

package/src/entity-detail/interfaces.ts

@@ -0,0 +1,55 @@
+/**
+ * Entity Detail 类型定义
+ * @module entity-detail/interfaces
+ */
+import type { RelationKind } from '@aiao/rxdb';
+
+/**
+ * 详情页标签类型
+ */
+export type DetailTabType = 'form' | 'table';
+
+/**
+ * 详情页标签基础配置
+ */
+export interface DetailTabBase {
+  /** 标签唯一标识 */
+  key: string;
+  /** 标签显示名称 */
+  label: string;
+  /** 标签类型 */
+  type: DetailTabType;
+}
+
+/**
+ * 表单标签配置（展示实体的基本信息表单）
+ */
+export interface DetailFormTab extends DetailTabBase {
+  /** 标签类型：表单 */
+  type: 'form';
+}
+
+/**
+ * 表格标签配置（展示关联实体的关系数据）
+ */
+export interface DetailTableTab extends DetailTabBase {
+  /** 标签类型：表格 */
+  type: 'table';
+  /** 关系名 */
+  relationName: string;
+  /** 关联实体名 */
+  relatedEntityName: string;
+  /** 关联实体命名空间 */
+  relatedNamespace: string;
+  /** 关系类型 */
+  relationKind: RelationKind;
+  /** ONE_TO_MANY: 关联实体中指向当前实体的外键字段，如 'ownerId' */
+  foreignKeyField?: string;
+  /** MANY_TO_MANY: 关联实体中指向当前实体的关系属性名，如 'orderItems' */
+  mappedProperty?: string;
+}
+
+/**
+ * 详情页标签配置
+ */
+export type DetailTab = DetailFormTab | DetailTableTab;

package/src/entity-field.utils.ts

@@ -0,0 +1,205 @@
+/**
+ * RxDB Model 实体字段工具模块
+ * 提供实体字段值的解析、格式化、验证等功能
+ * @module entity-field.utils
+ */
+import type { EntityMetadata } from '@aiao/rxdb';
+import {
+  PropertyType,
+  RelationKind,
+  type EntityPropertyMetadata,
+  type EntityRelationMetadata,
+  type FieldFormat,
+  type FieldOptions,
+  type KeyValuePropertyMetadata
+} from '@aiao/rxdb';
+
+/**
+ * 实体字段类型
+ * @remarks 兼容 PropertyType 枚举值及其字符串字面量形式，并包含关系字段（oneToOne / manyToOne）与计算字段（computed）的标识
+ */
+export type EntityFieldType =
+  | PropertyType
+  | `${PropertyType.bigint}`
+  | `${PropertyType.binary}`
+  | `${PropertyType.boolean}`
+  | `${PropertyType.date}`
+  | `${PropertyType.enum}`
+  | `${PropertyType.integer}`
+  | `${PropertyType.number}`
+  | `${PropertyType.string}`
+  | `${PropertyType.uuid}`
+  | `${PropertyType.numberArray}`
+  | `${PropertyType.stringArray}`
+  | `${PropertyType.keyValue}`
+  | `${PropertyType.json}`
+  | 'oneToOne'
+  | 'manyToOne'
+  | 'computed';
+
+/**
+ * 键值类型字段中单个键的 Schema 配置
+ */
+export interface KeyValueSchemaEntry {
+  /** 键的显示名称 */
+  label?: string;
+  /** 值的类型 */
+  type?: 'string' | 'number' | 'integer' | 'boolean' | 'date';
+  /** 是否必填 */
+  required?: boolean;
+  /** 是否可为空 */
+  nullable?: boolean;
+}
+
+/**
+ * 实体字段配置
+ */
+export interface EntityFieldConfig {
+  /** 字段名 */
+  field: string;
+  /** 显示名称 */
+  displayName: string;
+  /** 字段类型 */
+  type: EntityFieldType;
+  /** 是否只读 */
+  readonly?: boolean;
+  /** 是否可为空 */
+  nullable?: boolean;
+  /** 是否必填 */
+  required?: boolean;
+  /** 是否唯一 */
+  unique?: boolean;
+  /** 枚举类型的可选值 */
+  enumValues?: readonly string[];
+  /** 键值类型字段的 Schema */
+  keyValueSchema?: Record<string, KeyValueSchemaEntry>;
+  /** 关系字段关联的实体名 */
+  relatedEntityName?: string;
+  /** 关系字段关联实体的命名空间 */
+  relatedNamespace?: string;
+  /**
+   * 字段语义标注（只影响展示与控件选择，不改变运行时值类型）
+   * 仅在元数据声明 `format` 时输出该键
+   */
+  format?: FieldFormat;
+  /**
+   * 枚举/多选值的展示元数据（label / color / disabled），键是 `enum` 的子集
+   * 仅在元数据声明 `options` 时输出该键
+   */
+  options?: FieldOptions;
+  /**
+   * 是否为加密列
+   * 仅在元数据声明 `encrypted: true` 时输出该键
+   */
+  encrypted?: boolean;
+}
+
+const SYSTEM_FIELDS = new Set(['id', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy']);
+
+/** 只在显式声明 `true` 时才把布尔标志读成 true。 */
+const readFlag = (source: object, key: string): boolean => (source as Record<string, unknown>)[key] === true;
+
+/**
+ * 将属性元数据转换为字段配置
+ */
+function propertyToField(key: string, prop: EntityPropertyMetadata): EntityFieldConfig {
+  const raw = prop as Record<string, unknown>;
+  const field: EntityFieldConfig = {
+    field: key,
+    displayName: prop.displayName ?? key,
+    type: prop.type as PropertyType,
+    readonly: readFlag(prop, 'readonly'),
+    nullable: prop.nullable,
+    required: prop.required,
+    unique: prop.unique,
+    // 只在元数据声明过时才输出这些键，保证既有「全等断言」的字段形状不漂移
+    ...(raw['format'] === undefined ? {} : { format: raw['format'] as FieldFormat }),
+    ...(raw['options'] === undefined ? {} : { options: raw['options'] as FieldOptions }),
+    ...(raw['encrypted'] === undefined ? {} : { encrypted: raw['encrypted'] as boolean })
+  };
+  if (prop.type === PropertyType.enum || prop.type === PropertyType.stringArray) {
+    field.enumValues = (prop as { enum: readonly string[] }).enum;
+  }
+  if (prop.type === PropertyType.keyValue) {
+    const kvProp = prop as { properties: KeyValuePropertyMetadata[] };
+    field.keyValueSchema = Object.fromEntries(
+      kvProp.properties.map(p => [
+        p.name,
+        {
+          label: p.displayName,
+          type: p.type as KeyValueSchemaEntry['type'],
+          required: p.required,
+          nullable: p.nullable
+        }
+      ])
+    );
+  }
+  return field;
+}
+
+/**
+ * 将关系元数据转换为字段配置
+ */
+function relationToField(fkField: string, relation: EntityRelationMetadata): EntityFieldConfig {
+  return {
+    field: fkField,
+    displayName: relation.displayName ?? fkField,
+    type: relation.kind === RelationKind.ONE_TO_ONE ? 'oneToOne' : 'manyToOne',
+    nullable: (relation as Record<string, unknown>)['nullable'] === true,
+    relatedEntityName: relation.mappedEntity,
+    relatedNamespace: relation.mappedNamespace
+  };
+}
+
+/**
+ * 从实体元数据中提取全部业务字段配置
+ * @remarks 跳过系统字段，依次收集普通属性、计算属性与关系字段
+ * @param metadata - 实体元数据
+ * @returns 字段配置列表
+ */
+export function extractEntityFields(metadata: EntityMetadata): EntityFieldConfig[] {
+  const fields: EntityFieldConfig[] = [];
+
+  metadata.propertyMap.forEach((prop, key) => {
+    if (SYSTEM_FIELDS.has(key)) return;
+    fields.push(propertyToField(key, prop));
+  });
+
+  metadata.computedPropertyMap.forEach((prop, key) => {
+    fields.push({
+      field: key,
+      displayName: prop.displayName ?? key,
+      type: 'computed',
+      readonly: true
+    });
+  });
+
+  metadata.foreignKeyRelationMap.forEach((relation, fkField) => {
+    fields.push(relationToField(fkField, relation));
+  });
+
+  return fields;
+}
+
+const SYSTEM_FIELD_CONFIGS: ReadonlyArray<Omit<EntityFieldConfig, 'readonly'>> = [
+  { field: 'createdAt', displayName: '创建时间', type: PropertyType.date },
+  { field: 'updatedAt', displayName: '更新时间', type: PropertyType.date },
+  { field: 'createdBy', displayName: '创建者', type: PropertyType.string },
+  { field: 'updatedBy', displayName: '更新者', type: PropertyType.string }
+];
+
+/**
+ * 从实体元数据中提取系统字段配置
+ * @remarks 始终包含只读的 id 字段，并按元数据中实际存在的属性补充时间戳与审计字段
+ * @param metadata - 实体元数据
+ * @returns 系统字段配置列表
+ */
+export function extractSystemFields(metadata: EntityMetadata): EntityFieldConfig[] {
+  const fields: EntityFieldConfig[] = [{ field: 'id', displayName: 'ID', type: PropertyType.uuid, readonly: true }];
+  for (const cfg of SYSTEM_FIELD_CONFIGS) {
+    if (metadata.propertyMap.has(cfg.field)) {
+      fields.push({ ...cfg, readonly: true });
+    }
+  }
+  return fields;
+}

package/src/entity-form/form-data.ts

@@ -0,0 +1,83 @@
+/**
+ * 实体表单数据转换工具
+ * 提供实体对象与表单数据之间的转换及默认表单数据创建
+ * @module entity-form/form-data
+ */
+import { parseEntityFieldValue } from '../entity-value.utils.js';
+import { structuralEqual } from '../structural-equal.js';
+import type { EntityFormData, FormFieldConfig } from './interfaces.js';
+
+/**
+ * 将实体对象转换为表单数据
+ * @remarks 实体上不存在的字段以 null 填充
+ * @param entity - 源实体对象
+ * @param fields - 表单字段配置
+ * @returns 仅包含字段配置中声明字段的表单数据
+ */
+export function entityToFormData(entity: Record<string, unknown>, fields: FormFieldConfig[]): EntityFormData {
+  const data: EntityFormData = {};
+  for (const field of fields) {
+    data[field.field] = entity[field.field] ?? null;
+  }
+  return data;
+}
+
+/**
+ * 计算表单数据相对原实体对象的变更集
+ * @remarks 只读字段跳过；值相同（引用相等或结构化相等）的字段不进入变更集
+ * @param original - 原实体对象
+ * @param formData - 表单数据
+ * @param fields - 表单字段配置
+ * @returns 发生变化的字段及其解析后的新值
+ */
+export function formDataToEntityChanges(
+  original: Record<string, unknown>,
+  formData: EntityFormData,
+  fields: FormFieldConfig[]
+): Record<string, unknown> {
+  const changes: Record<string, unknown> = {};
+  for (const field of fields) {
+    if (field.readonly) continue;
+    const parsed = parseEntityFieldValue(field.type, formData[field.field]);
+    const orig = original[field.field] ?? null;
+    // 快速路径：引用相等或同为原始类型时跳过深比较
+    if (parsed === orig) continue;
+    if (parsed === null || orig === null || (typeof parsed !== 'object' && typeof orig !== 'object')) {
+      changes[field.field] = parsed;
+      continue;
+    }
+    if (!structuralEqual(parsed, orig)) {
+      changes[field.field] = parsed;
+    }
+  }
+  return changes;
+}
+
+/**
+ * 根据字段配置创建默认表单数据
+ * @remarks 只读字段不参与；布尔字段默认为 false，字符串 / 数字数组默认为空数组，其余字段默认为 null
+ * @param fields - 表单字段配置
+ * @returns 默认表单数据
+ */
+export function createDefaultFormData(fields: FormFieldConfig[]): EntityFormData {
+  const data: EntityFormData = {};
+  for (const field of fields) {
+    if (field.readonly) continue;
+    switch (field.type) {
+      case 'boolean':
+        data[field.field] = false;
+        break;
+      case 'stringArray':
+      case 'numberArray':
+        data[field.field] = [];
+        break;
+      case 'keyValue':
+      case 'json':
+        data[field.field] = null;
+        break;
+      default:
+        data[field.field] = null;
+    }
+  }
+  return data;
+}

package/src/entity-form/form-fields.ts

@@ -0,0 +1,48 @@
+/**
+ * 表单字段构建工具
+ * 根据实体元数据与表单模式生成、排序与过滤表单字段
+ * @module entity-form/form-fields
+ */
+import type { EntityMetadata } from '@aiao/rxdb';
+import { extractEntityFields, extractSystemFields } from '../entity-field.utils.js';
+import type { FormFieldConfig, FormMode } from './interfaces.js';
+
+/**
+ * 根据实体元数据和表单模式构建表单字段列表
+ * @remarks 创建模式排除计算字段且不含系统字段；编辑模式追加只读的系统字段；查看模式全部字段设为只读
+ * @param metadata - 实体元数据
+ * @param mode - 表单模式
+ * @returns 表单字段配置列表
+ */
+export function buildFormFields(metadata: EntityMetadata, mode: FormMode): FormFieldConfig[] {
+  const entityFields = extractEntityFields(metadata).map(f => f as FormFieldConfig);
+  const systemFields = extractSystemFields(metadata).map(f => ({ ...f, readonly: true }) as FormFieldConfig);
+
+  switch (mode) {
+    case 'create':
+      return entityFields.filter(f => f.type !== 'computed');
+    case 'edit':
+      return [...entityFields, ...systemFields];
+    case 'view':
+      return [...entityFields, ...systemFields].map(f => ({ ...f, readonly: true }));
+  }
+}
+
+/**
+ * 按字段的 order 升序排序
+ * @remarks 未设置 order 的字段按 0 处理，返回新数组而不修改原数组
+ * @param fields - 表单字段配置
+ * @returns 排序后的字段列表
+ */
+export function sortFormFields(fields: FormFieldConfig[]): FormFieldConfig[] {
+  return [...fields].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+}
+
+/**
+ * 过滤掉标记为隐藏的字段
+ * @param fields - 表单字段配置
+ * @returns 可见字段列表
+ */
+export function filterVisibleFields(fields: FormFieldConfig[]): FormFieldConfig[] {
+  return fields.filter(f => !f.hidden);
+}

package/src/entity-form/form-validation.ts

@@ -0,0 +1,34 @@
+/**
+ * 表单校验工具
+ * 基于字段配置校验单个字段值与整份表单数据
+ * @module entity-form/form-validation
+ */
+import { validateEntityFieldValue, type FieldValidationError } from '../entity-value.utils.js';
+import type { EntityFormData, FormFieldConfig, FormValidationResult } from './interfaces.js';
+
+/**
+ * 校验单个表单字段值
+ * @param field - 表单字段配置
+ * @param value - 待校验的字段值
+ * @returns 校验错误；校验通过时返回 null
+ */
+export function validateField(field: FormFieldConfig, value: unknown): FieldValidationError | null {
+  return validateEntityFieldValue(field, value);
+}
+
+/**
+ * 校验整份表单数据
+ * @remarks 只读与隐藏字段不参与校验
+ * @param fields - 表单字段配置
+ * @param data - 表单数据
+ * @returns 校验结果（是否通过及错误列表）
+ */
+export function validateForm(fields: FormFieldConfig[], data: EntityFormData): FormValidationResult {
+  const errors: FieldValidationError[] = [];
+  for (const field of fields) {
+    if (field.readonly || field.hidden) continue;
+    const error = validateEntityFieldValue(field, data[field.field]);
+    if (error) errors.push(error);
+  }
+  return { valid: errors.length === 0, errors };
+}

package/src/entity-form/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Entity Form 模块
+ * 提供表单数据转换、字段构建与校验等工具
+ * @module entity-form
+ */
+export * from './form-data.js';
+export * from './form-fields.js';
+export * from './form-validation.js';
+export * from './interfaces.js';