@aiao/rxdb-model 0.0.19 → 0.0.26

package/src/query-builder/services/schema-parser.service.ts

@@ -0,0 +1,309 @@
+/**
+ * @fileoverview Schema 解析服务
+ * 从 EntityMetadata 解析字段元数据，用于 QueryBuilder 组件
+ */
+
+import type { EntityMetadata, KeyValuePropertyMetadata, PropertyType } from '@aiao/rxdb';
+import type { FieldMetadata } from '../models/query-builder-state.js';
+import { extractKeyValueFields } from '../utils/metadata-field-extractor.js';
+
+/**
+ * 属性类型到 QueryBuilder 类型的映射
+ * 将 RxDB 的 PropertyType 映射到 QueryBuilder 支持的简化类型
+ */
+const PROPERTY_TYPE_MAP: Record<string, FieldMetadata['type']> = {
+  uuid: 'uuid',
+  string: 'string',
+  enum: 'enum',
+  number: 'number',
+  integer: 'number',
+  boolean: 'boolean',
+  date: 'date',
+  stringArray: 'array',
+  numberArray: 'array',
+  keyValue: 'keyValue',
+  json: 'object'
+};
+
+/**
+ * 解析器配置选项
+ */
+export interface SchemaParserOptions {
+  /**
+   * 是否包含外键字段
+   * @default false
+   */
+  includeForeignKeys?: boolean;
+
+  /**
+   * 是否包含计算属性
+   * @default false
+   */
+  includeComputedProperties?: boolean;
+
+  /**
+   * 是否包含关系字段（用于 EXISTS 操作符）
+   * @default false
+   */
+  includeRelations?: boolean;
+
+  /**
+   * 实体元数据映射（用于解析关系字段的目标实体字段）
+   * 键为实体名称，值为实体元数据
+   */
+  entityMetadataMap?: Map<string, EntityMetadata>;
+
+  /**
+   * 自定义字段过滤器
+   */
+  fieldFilter?: (field: FieldMetadata) => boolean;
+
+  /**
+   * 自定义显示名称生成器
+   */
+  displayNameGenerator?: (fieldName: string, metadata?: { displayName?: string }) => string;
+}
+
+/**
+ * 默认显示名称生成器。
+ *
+ * 优先使用字段元数据中的 `displayName`，如果未提供，则根据字段名生成可读的标题。
+ * 生成规则是将 camelCase / PascalCase 名称转换为以空格分隔的形式，并将首字母大写。
+ *
+ * 例如：
+ * - `"userName"`   -> `"User Name"`
+ * - `"createdAt"`  -> `"Created At"`
+ * - `"URLValue"`   -> `"URL Value"`
+ *
+ * @param fieldName 原始字段名称（通常为 camelCase 或 PascalCase）。
+ * @param metadata  字段元数据，可选。如果包含 `displayName`，则直接返回该值。
+ * @returns 适合在界面上展示的字段标题字符串。
+ */
+function defaultDisplayNameGenerator(fieldName: string, metadata?: { displayName?: string }): string {
+  if (metadata?.displayName) {
+    return metadata.displayName;
+  }
+  // camelCase -> Camel Case
+  return fieldName
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, str => str.toUpperCase())
+    .trim();
+}
+
+/**
+ * Schema 解析服务
+ * 负责将 RxDB EntityMetadata 转换为 QueryBuilder 可用的字段元数据
+ */
+export class SchemaParser {
+  private readonly options: Required<Omit<SchemaParserOptions, 'entityMetadataMap'>> & {
+    entityMetadataMap?: Map<string, EntityMetadata>;
+  };
+
+  private readonly relationFieldsCache = new Map<string, FieldMetadata[]>();
+
+  /** @param options - 解析器配置（含关系目标字段递归解析缓存） */
+  constructor(options: SchemaParserOptions = {}) {
+    this.options = {
+      includeForeignKeys: options.includeForeignKeys ?? false,
+      includeComputedProperties: options.includeComputedProperties ?? false,
+      includeRelations: options.includeRelations ?? false,
+      entityMetadataMap: options.entityMetadataMap,
+      fieldFilter: options.fieldFilter ?? (() => true),
+      displayNameGenerator: options.displayNameGenerator ?? defaultDisplayNameGenerator
+    };
+  }
+
+  /**
+   * 从 EntityMetadata 解析字段元数据
+   *
+   * @param metadata - RxDB 实体元数据
+   * @returns 字段元数据数组
+   *
+   * @example
+   * ```typescript
+   * const parser = new SchemaParser();
+   * const fields = parser.parse(userMetadata);
+   * // [{ name: 'id', displayName: 'ID', type: 'string' }, ...]
+   * ```
+   */
+  parse(metadata: EntityMetadata): FieldMetadata[] {
+    const fields: FieldMetadata[] = [];
+
+    // 解析普通属性
+    for (const property of metadata.properties) {
+      // 跳过外键（如果配置不包含）
+      if (!this.options.includeForeignKeys && metadata.isForeignKey(property.name)) {
+        continue;
+      }
+
+      const field = this.parseProperty(property);
+      if (field && this.options.fieldFilter(field)) {
+        // keyValue 属性：提取子字段
+        if (field.type === 'keyValue') {
+          const kvProperties = (property as unknown as { properties: KeyValuePropertyMetadata[] }).properties;
+          if (kvProperties?.length > 0) {
+            field.keyValueFields = extractKeyValueFields(kvProperties);
+            for (const kvField of field.keyValueFields) {
+              const childField: FieldMetadata = {
+                ...kvField,
+                name: `${field.name}.${kvField.name}`,
+                displayName: `${field.displayName}.${kvField.displayName}`
+              };
+              if (this.options.fieldFilter(childField)) {
+                fields.push(childField);
+              }
+            }
+          }
+        }
+        fields.push(field);
+      }
+    }
+
+    // 解析计算属性（如果配置包含）
+    if (this.options.includeComputedProperties) {
+      for (const property of metadata.computedProperties) {
+        const field = this.parseProperty(property);
+        if (field && this.options.fieldFilter(field)) {
+          fields.push(field);
+        }
+      }
+    }
+
+    // 解析关系字段（如果配置包含）
+    if (this.options.includeRelations && metadata.relations) {
+      for (const relation of metadata.relations) {
+        const field = this.parseRelation(relation);
+        if (field && this.options.fieldFilter(field)) {
+          fields.push(field);
+        }
+      }
+    }
+
+    return fields;
+  }
+
+  /**
+   * 从多个 EntityMetadata 批量解析
+   *
+   * @param metadataMap - 实体名称到元数据的映射
+   * @returns 实体名称到字段数组的映射
+   */
+  parseMany(metadataMap: Map<string, EntityMetadata>): Map<string, FieldMetadata[]> {
+    const result = new Map<string, FieldMetadata[]>();
+
+    for (const [entityName, metadata] of metadataMap) {
+      result.set(entityName, this.parse(metadata));
+    }
+
+    return result;
+  }
+
+  /**
+   * 解析单个属性
+   */
+  private parseProperty(property: {
+    name: string;
+    displayName?: string;
+    type: PropertyType | `${PropertyType}`;
+    description?: string;
+    nullable?: boolean;
+    enum?: readonly unknown[];
+    pattern?: string;
+  }): FieldMetadata | null {
+    const type = this.mapPropertyType(property.type);
+    if (!type) {
+      return null;
+    }
+
+    const field: FieldMetadata = {
+      name: property.name,
+      displayName: this.options.displayNameGenerator(property.name, property),
+      type
+    };
+
+    // ✨ T071-T073: 提取额外的字段元数据
+
+    // 从 nullable 推导 required（nullable 为 false 或 undefined 时为必填）
+    if (property.nullable !== undefined) {
+      field.required = !property.nullable;
+      field.nullable = property.nullable;
+    }
+
+    // 提取 description
+    if (property.description) {
+      field.description = property.description;
+    }
+
+    // 提取 enum 值
+    if (property.enum && Array.isArray(property.enum)) {
+      field.enum = property.enum;
+    }
+
+    // 提取正则验证模式
+    if (property.pattern) {
+      field.pattern = property.pattern;
+    }
+
+    return field;
+  }
+
+  /**
+   * 将 RxDB PropertyType 映射到 QueryBuilder 类型
+   */
+  private mapPropertyType(propertyType: PropertyType | `${PropertyType}`): FieldMetadata['type'] | null {
+    const typeString = typeof propertyType === 'string' ? propertyType : String(propertyType);
+    return PROPERTY_TYPE_MAP[typeString] ?? null;
+  }
+
+  /**
+   * 解析关系字段
+   */
+  private parseRelation(relation: {
+    name: string;
+    displayName?: string;
+    kind: string;
+    mappedEntity: string;
+    mappedNamespace?: string;
+  }): FieldMetadata | null {
+    const field: FieldMetadata = {
+      name: relation.name,
+      displayName: this.options.displayNameGenerator(relation.name, relation),
+      type: 'relation',
+      isRelation: true,
+      relationTarget: relation.mappedEntity,
+      relationKind: relation.kind as FieldMetadata['relationKind']
+    };
+
+    // 如果提供了实体元数据映射，解析关系目标实体的字段
+    if (this.options.entityMetadataMap) {
+      const targetEntityName = relation.mappedEntity;
+      const targetMetadata = this.options.entityMetadataMap.get(targetEntityName);
+      if (targetMetadata) {
+        const cached = this.relationFieldsCache.get(targetEntityName);
+        if (cached) {
+          field.relationFields = cached;
+        } else {
+          const targetParser = new SchemaParser({
+            ...this.options,
+            includeRelations: false
+          });
+          const parsed = targetParser.parse(targetMetadata);
+          this.relationFieldsCache.set(targetEntityName, parsed);
+          field.relationFields = parsed;
+        }
+      }
+    }
+
+    return field;
+  }
+}
+
+/**
+ * 创建 SchemaParser 实例的工厂函数
+ *
+ * @param options - 解析器配置选项
+ * @returns 新的 SchemaParser 实例
+ */
+export function createSchemaParser(options?: SchemaParserOptions): SchemaParser {
+  return new SchemaParser(options);
+}

package/src/query-builder/services/validation.service.ts

@@ -0,0 +1,390 @@
+/**
+ * @fileoverview 校验服务
+ * 提供规则值的即时校验功能
+ */
+
+import type { OperatorName } from '@aiao/rxdb';
+import type { FieldMetadata, QueryBuilderRule, QueryBuilderRuleGroup, UIRule } from '../models/query-builder-state.js';
+import type {
+  ValidationContext,
+  ValidationError,
+  ValidationResult,
+  ValidationRule
+} from '../models/validation.interface.js';
+import { BUILTIN_VALIDATION_RULES } from '../models/validation.interface.js';
+import { OperatorRegistry, getDefaultOperatorRegistry } from './operator-registry.service.js';
+
+/**
+ * 单条校验规则输入（兼容 QueryBuilderRule 与 UIRule）
+ */
+type ValidationRuleInput = QueryBuilderRule<Record<string, unknown>> | UIRule;
+
+/**
+ * 校验规则组输入（宽松递归结构）
+ */
+export type ValidationGroupInput = {
+  /**
+   * 规则组唯一标识符
+   */
+  id: string;
+
+  /**
+   * 逻辑组合符
+   */
+  combinator: 'and' | 'or';
+
+  /**
+   * 子规则列表（支持嵌套）
+   */
+  rules: Array<ValidationRuleInput | ValidationGroupInput>;
+};
+
+type RuleWithWhere = ValidationRuleInput & {
+  where?: ValidationGroupInput | null;
+};
+
+function hasWhereSubquery(rule: ValidationRuleInput): rule is RuleWithWhere {
+  return typeof rule === 'object' && rule !== null && 'where' in rule;
+}
+
+function isValidationGroup(item: ValidationRuleInput | ValidationGroupInput): item is ValidationGroupInput {
+  return 'combinator' in item && 'rules' in item;
+}
+
+function isValidationRule(item: ValidationRuleInput | ValidationGroupInput): item is ValidationRuleInput {
+  return 'field' in item && 'operator' in item;
+}
+
+/**
+ * 校验服务选项
+ */
+export interface ValidationServiceOptions {
+  /**
+   * 自定义校验规则
+   */
+  customRules?: ValidationRule[];
+
+  /**
+   * 操作符注册表
+   */
+  operatorRegistry?: OperatorRegistry;
+
+  /**
+   * 是否启用内置校验规则
+   * @default true
+   */
+  useBuiltinRules?: boolean;
+}
+
+/**
+ * 从规则中提取值（处理不同规则类型）。
+ *
+ * @template T 规则字段值的类型。
+ * @param rule 要从中提取值的规则对象。
+ * @returns 规则中的值；如果规则不包含 `value` 属性，则返回 `undefined`。
+ */
+function extractValueFromRule(rule: ValidationRuleInput): unknown {
+  // Rule 类型是联合类型，需要检查是否有 value 属性
+  if ('value' in rule) {
+    return rule.value;
+  }
+  return undefined;
+}
+
+/**
+ * 校验服务
+ * 负责验证 QueryBuilder 规则和值
+ */
+export class ValidationService {
+  private readonly rules: Map<string, ValidationRule>;
+  private readonly operatorRegistry: OperatorRegistry;
+
+  /** @param options - 校验服务配置（自定义规则等） */
+  constructor(options: ValidationServiceOptions = {}) {
+    this.rules = new Map();
+    this.operatorRegistry = options.operatorRegistry ?? getDefaultOperatorRegistry();
+
+    // 合并内置与自定义规则（后者覆盖同名规则）
+    const sources: ValidationRule[][] = [];
+    if (options.useBuiltinRules !== false) sources.push(BUILTIN_VALIDATION_RULES as ValidationRule[]);
+    if (options.customRules) sources.push(options.customRules);
+    for (const group of sources) {
+      for (const rule of group) this.rules.set(rule.name, rule);
+    }
+  }
+
+  /**
+   * 校验单条规则
+   */
+  validateRule(rule: ValidationRuleInput, field: FieldMetadata): ValidationResult {
+    const errors: ValidationError[] = [];
+    const value = extractValueFromRule(rule);
+
+    // 创建校验上下文
+    const context: ValidationContext = {
+      fieldType: field.type,
+      operator: rule.operator as OperatorName,
+      value,
+      enum: field.enum,
+      pattern: field.pattern
+    };
+
+    // 1. 检查操作符是否支持该字段
+    if (!this.operatorRegistry.isOperatorSupportedForField(rule.operator as OperatorName, field)) {
+      errors.push({
+        field: rule.field as string,
+        rule: 'operatorTypeMatch',
+        message: `操作符 "${rule.operator}" 不支持字段 "${field.name}"`
+      });
+    }
+
+    // 2. 检查值类型
+    const valueType = this.operatorRegistry.getValueType(rule.operator as OperatorName);
+
+    // EXISTS/NOT EXISTS 操作符的特殊处理
+    if (valueType === 'subquery') {
+      // 对于 EXISTS 操作符，value 字段可以是任何值（包括空字符串、undefined 等）
+      // 真正需要验证的是可选的 where 字段
+      if (hasWhereSubquery(rule) && rule.where !== undefined && rule.where !== null) {
+        const where = rule.where;
+
+        // 如果提供了 where，验证其有效性
+        if (typeof where === 'object' && 'combinator' in where && 'rules' in where) {
+          // 检查 where 子查询是否为空
+          if (!where.rules || where.rules.length === 0) {
+            errors.push({
+              field: rule.field as string,
+              rule: 'valueType',
+              message: 'EXISTS 子查询条件不能为空'
+            });
+          } else {
+            // 验证 where 子查询内部规则的基本有效性
+            const subqueryErrors = this.validateSubqueryRules(where as QueryBuilderRuleGroup<Record<string, unknown>>);
+            if (subqueryErrors.length > 0) {
+              errors.push(
+                ...subqueryErrors.map(err => ({
+                  ...err,
+                  field: `${rule.field}.${err.field}` // 添加父字段前缀
+                }))
+              );
+            }
+          }
+        } else {
+          // where 格式无效
+          errors.push({
+            field: rule.field as string,
+            rule: 'valueType',
+            message: 'EXISTS 子查询格式无效'
+          });
+        }
+      }
+      // 如果没有 where 或 where 为 undefined/null，是有效的简单 EXISTS
+    } else {
+      // 非子查询类型，正常验证 value
+      const valueError = this.validateValueType(value, valueType, rule.field as string, field.displayName);
+      if (valueError) {
+        errors.push(valueError);
+      }
+    }
+
+    // 3. 运行类型相关的内置校验规则
+    for (const validationRule of this.rules.values()) {
+      // 检查规则是否适用于当前字段类型
+      if (validationRule.appliesTo && !validationRule.appliesTo.includes(field.type)) {
+        continue;
+      }
+
+      const isValid = validationRule.validate(context);
+      if (!isValid) {
+        errors.push({
+          field: rule.field as string,
+          rule: validationRule.name,
+          message: validationRule.message
+        });
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors: errors.length > 0 ? errors : undefined
+    };
+  }
+
+  /**
+   * 校验整个规则组
+   */
+  validateGroup(group: ValidationGroupInput, fields: Map<string, FieldMetadata>): ValidationResult {
+    const errors: ValidationError[] = [];
+
+    for (const item of group.rules) {
+      if (isValidationGroup(item)) {
+        const result = this.validateGroup(item, fields);
+        if (!result.valid && result.errors) {
+          errors.push(...result.errors);
+        }
+      } else if (isValidationRule(item)) {
+        const field = fields.get(item.field as string);
+        if (!field) {
+          errors.push({
+            field: item.field as string,
+            rule: 'fieldExists',
+            message: `字段 "${item.field}" 不存在`
+          });
+          continue;
+        }
+
+        const result = this.validateRule(item, field);
+        if (!result.valid && result.errors) {
+          errors.push(...result.errors);
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors: errors.length > 0 ? errors : undefined
+    };
+  }
+
+  /**
+   * 注册自定义校验规则
+   */
+  registerRule(rule: ValidationRule): void {
+    this.rules.set(rule.name, rule);
+  }
+
+  /**
+   * 移除校验规则
+   */
+  unregisterRule(name: string): boolean {
+    return this.rules.delete(name);
+  }
+
+  /**
+   * 获取所有校验规则
+   */
+  getRules(): ValidationRule[] {
+    return Array.from(this.rules.values());
+  }
+
+  /**
+   * 校验值类型
+   */
+  private validateValueType(
+    value: unknown,
+    valueType: 'single' | 'array' | 'range' | 'none' | 'subquery' | undefined,
+    fieldName: string,
+    displayName?: string
+  ): ValidationError | null {
+    if (valueType === 'none') {
+      // 不需要值（null/notNull）
+      return null;
+    }
+
+    // 注意：subquery 类型的验证在 validateRule 中处理，不应该调用此方法
+    if (valueType === 'subquery') {
+      return null;
+    }
+
+    if (valueType === 'array') {
+      // 需要数组
+      if (!Array.isArray(value) || value.length === 0) {
+        return {
+          field: fieldName,
+          rule: 'valueType',
+          message: `${displayName || fieldName}需要提供一个或多个值`
+        };
+      }
+      return null;
+    }
+
+    if (valueType === 'range') {
+      // 需要两个值（between）
+      if (!Array.isArray(value) || value.length !== 2) {
+        return {
+          field: fieldName,
+          rule: 'valueType',
+          message: `${displayName || fieldName}需要提供两个值（范围）`
+        };
+      }
+      return null;
+    }
+
+    // single 或 undefined（默认单值）
+    if (value === undefined || value === null || value === '') {
+      return {
+        field: fieldName,
+        rule: 'valueType',
+        message: `${displayName || fieldName}需要提供一个值`
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * 验证子查询规则的基本有效性（不依赖字段元数据）
+   *
+   * @description
+   * 子查询可能引用关系实体的字段，我们无法获取其 FieldMetadata。
+   * 因此只验证规则的基本结构和值类型，不验证字段是否存在或操作符是否匹配。
+   */
+  private validateSubqueryRules(group: ValidationGroupInput): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    for (const item of group.rules) {
+      if (isValidationGroup(item)) {
+        // 递归验证嵌套组
+        const nestedErrors = this.validateSubqueryRules(item);
+        errors.push(...nestedErrors);
+      } else if (isValidationRule(item)) {
+        const value = extractValueFromRule(item);
+        const valueType = this.operatorRegistry.getValueType(item.operator as OperatorName);
+
+        // 只验证值类型，不验证字段存在性和操作符匹配
+        const valueError = this.validateValueType(value, valueType, item.field as string);
+        if (valueError) {
+          errors.push(valueError);
+        }
+
+        // 如果是嵌套的 EXISTS，递归验证其 where
+        if (valueType === 'subquery') {
+          const ruleWithWhere = item as RuleWithWhere;
+          if ('where' in ruleWithWhere && ruleWithWhere.where) {
+            const where = ruleWithWhere.where;
+            if (typeof where === 'object' && 'combinator' in where && 'rules' in where) {
+              if (!where.rules || where.rules.length === 0) {
+                errors.push({
+                  field: item.field as string,
+                  rule: 'valueType',
+                  message: 'EXISTS 子查询条件不能为空'
+                });
+              } else {
+                const subErrors = this.validateSubqueryRules(where);
+                errors.push(...subErrors);
+              }
+            } else {
+              errors.push({
+                field: item.field as string,
+                rule: 'valueType',
+                message: 'EXISTS 子查询格式无效'
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return errors;
+  }
+}
+
+/**
+ * 创建 ValidationService 实例的工厂函数
+ *
+ * @param options - 校验服务选项
+ * @returns 新的 ValidationService 实例
+ */
+export function createValidationService(options?: ValidationServiceOptions): ValidationService {
+  return new ValidationService(options);
+}