@aiao/rxdb-model 0.0.19 → 0.0.26

package/src/entity-form/interfaces.ts

@@ -0,0 +1,116 @@
+/**
+ * Entity Form 类型定义
+ * @module entity-form/interfaces
+ */
+import type { FieldFormat, FieldOptions } from '@aiao/rxdb';
+import type { EntityFieldType, KeyValueSchemaEntry } from '../entity-field.utils.js';
+
+/**
+ * 表单模式
+ */
+export type FormMode = 'view' | 'edit' | 'create';
+
+/**
+ * 表单字段配置
+ */
+export interface FormFieldConfig {
+  /** 字段名 */
+  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?: FieldFormat;
+  /** 枚举/多选值的展示元数据（label / color / disabled） */
+  options?: FieldOptions;
+  /** 是否为加密列 */
+  encrypted?: boolean;
+  /** 是否隐藏 */
+  hidden?: boolean;
+  /** 排序权重 */
+  order?: number;
+  /** 占位提示 */
+  placeholder?: string;
+  /** 帮助文本 */
+  helpText?: string;
+  /** 占据的栅格列数（1 或 2） */
+  span?: 1 | 2;
+}
+
+/**
+ * 表单字段值变更事件
+ */
+export interface FormFieldChangeEvent {
+  /** 字段名 */
+  field: string;
+  /** 字段类型 */
+  type: EntityFieldType;
+  /** 变更后的值 */
+  value: unknown;
+  /** 变更前的值 */
+  previousValue: unknown;
+}
+
+/**
+ * 表单数据（字段名到字段值的映射）
+ */
+export interface EntityFormData {
+  /** 字段值（字段名 → 值） */
+  [field: string]: unknown;
+}
+
+/**
+ * 表单校验结果
+ */
+export interface FormValidationResult {
+  /** 是否通过校验 */
+  valid: boolean;
+  /** 错误列表 */
+  errors: FormFieldValidationError[];
+}
+
+/**
+ * 表单字段校验错误
+ */
+export interface FormFieldValidationError {
+  /** 出错字段名 */
+  field: string;
+  /** 错误提示信息 */
+  message: string;
+}
+
+/**
+ * 关联实体数据提供者
+ * @remarks 根据实体名（与可选命名空间）返回可选的关联实体列表
+ */
+export interface RelatedEntityProvider {
+  /** 按实体名（与可选命名空间）取得可关联实体条目 */
+  (entityName: string, namespace?: string): RelatedEntityItem[];
+}
+
+/**
+ * 关联实体条目
+ */
+export interface RelatedEntityItem {
+  /** 实体 ID */
+  id: string;
+  /** 显示名称 */
+  displayName: string;
+}

package/src/entity-list/manual-order-list.ts

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview 实体列表的手动排序：拖拽启用谓词、默认排序与落库协调（US-028 阶段 B）
+ *
+ * 列表只在「看到的行就是一条完整排序域」时允许拖拽：邻居才是真邻居，
+ * `Repository.reorder()` 才能按 `{ prevId, nextId }` 落到用户看到的位置。
+ * 三端 `EntityList` 共用这一份判定与协调，框架层只负责收集状态和接线。
+ */
+import {
+  type EntityMetadata,
+  type OrderBy,
+  PropertyType,
+  isManualOrderEntity,
+  manualOrderGroupFields,
+  normalizeManualOrderBy
+} from '@aiao/rxdb';
+import type { RowMoveEvent } from '../entity-table/vtable/table-row-move.js';
+
+/** 列表排序判定需要的实体元数据 */
+export type ManualOrderListMetadata = Pick<EntityMetadata, 'manualOrder' | 'propertyMap'>;
+
+/** 列表的固定查询（详情页关系标签传入），结构同查询构建器的规则组 */
+export interface ListFixedQuery {
+  /** 规则组合方式 */
+  readonly combinator: 'and' | 'or';
+  /** 规则；嵌套规则组视为不能钉住排序域 */
+  readonly rules: readonly unknown[];
+}
+
+/**
+ * 判定列表能否拖拽排序时用到的列表状态
+ */
+export interface ListReorderState {
+  /** 当前实体元数据；未注册实体为 `undefined` */
+  readonly metadata: ManualOrderListMetadata | undefined;
+  /** 列头排序状态；只有 `normal`（未按列排序）时显示的才是手动顺序 */
+  readonly sortOrder: 'asc' | 'desc' | 'normal';
+  /** 用户在筛选框里加了条件 */
+  readonly hasUserFilter: boolean;
+  /** 列表处于关联选择模式 */
+  readonly selectMode: boolean;
+  /** 外部传入的固定查询 */
+  readonly fixedQuery: ListFixedQuery | undefined;
+  /** 排序域已全部加载：没有下一页且不在加载中 */
+  readonly fullyLoaded: boolean;
+  /** 存在只读行（无编辑权限） */
+  readonly hasReadonlyRows: boolean;
+  /** 存在未落库的草稿行 */
+  readonly hasDrafts: boolean;
+  /** 存在未完成的单元格编辑写入 */
+  readonly hasPendingEdits: boolean;
+  /** 上一次拖拽的重排还没落定 */
+  readonly reorderPending: boolean;
+}
+
+const STRING_KEY_TYPES: ReadonlySet<string> = new Set<string>([PropertyType.string, PropertyType.uuid]);
+
+const isPinRule = (rule: unknown): rule is { field: string; operator: string } => {
+  if (typeof rule !== 'object' || rule === null || 'rules' in rule) return false;
+  const { field, operator } = rule as { field?: unknown; operator?: unknown };
+  return typeof field === 'string' && (operator === '=' || operator === 'null');
+};
+
+/**
+ * 固定查询是否恰好钉住一条完整的排序域
+ *
+ * @param groupFields - 实体声明的分组字段
+ * @param fixedQuery - 列表的固定查询
+ * @returns 整表排序要求没有固定条件；分组排序要求只有对全部分组字段各一条等值（或 `null`）条件
+ */
+export function pinsSingleOrderDomain(groupFields: readonly string[], fixedQuery: ListFixedQuery | undefined): boolean {
+  const rules = fixedQuery?.rules ?? [];
+  if (groupFields.length === 0) return rules.length === 0;
+  if (rules.length !== groupFields.length) return false;
+  if (rules.length > 1 && fixedQuery?.combinator !== 'and') return false;
+  if (!rules.every(isPinRule)) return false;
+  const pinned = new Set(rules.map(rule => (rule as { field: string }).field));
+  return pinned.size === groupFields.length && groupFields.every(field => pinned.has(field));
+}
+
+/**
+ * 实体列表当前是否允许拖拽排序
+ *
+ * @param state - 列表状态
+ * @returns 全部条件满足时为 `true`：手动排序实体、字符串主键、未按列排序、无用户筛选、非选择模式、
+ *   固定查询钉住一条完整排序域、已全部加载、没有只读行 / 草稿 / 未完成编辑 / 未落定的重排
+ *
+ * @example
+ * ```typescript
+ * const enabled = canReorderEntityList({ metadata, sortOrder: 'normal', fixedQuery, ...flags });
+ * ```
+ */
+export function canReorderEntityList(state: ListReorderState): boolean {
+  const { metadata } = state;
+  if (!metadata || !isManualOrderEntity(metadata)) return false;
+  const keyType = metadata.propertyMap.get('id')?.type;
+  if (keyType === undefined || !STRING_KEY_TYPES.has(keyType)) return false;
+  if (state.sortOrder !== 'normal' || state.hasUserFilter || state.selectMode) return false;
+  if (!pinsSingleOrderDomain(manualOrderGroupFields(metadata), state.fixedQuery)) return false;
+  if (!state.fullyLoaded || state.hasReadonlyRows || state.hasDrafts) return false;
+  return !state.hasPendingEdits && !state.reorderPending;
+}
+
+/**
+ * 列表未按列排序时的游标排序
+ *
+ * @param metadata - 实体元数据；未注册实体为 `undefined`
+ * @returns 手动排序实体为 `[分组字段… asc, sortOrder asc, id asc]`，其余为 `[id desc]`
+ */
+export function defaultListOrderBy(metadata: Pick<EntityMetadata, 'manualOrder'> | undefined): OrderBy[] {
+  if (metadata && isManualOrderEntity(metadata))
+    return normalizeManualOrderBy<{ orderBy?: OrderBy[] }>(metadata, {}).orderBy ?? [];
+  return [{ field: 'id', sort: 'desc' }];
+}
+
+/**
+ * 行拖放落库时与界面交互的钩子
+ */
+export interface RowMoveCommitHooks {
+  /** 放下这一刻列表是否允许拖拽排序（{@link canReorderEntityList} 的结论） */
+  readonly enabled: boolean;
+  /** 落库重排，通常是 `repository.reorder(move.id, { prevId, nextId })` */
+  reorder(move: RowMoveEvent): Promise<unknown>;
+  /** 把表格行恢复成最近一次已提交的顺序 */
+  restore(): void;
+  /** 重排进行中状态变化 */
+  setPending(pending: boolean): void;
+  /** 显示（或用 `null` 清除）落库错误 */
+  setError(error: unknown): void;
+}
+
+/**
+ * 协调一次行拖放的落库
+ *
+ * @param move - 表格读出的拖放结果
+ * @param hooks - 界面钩子
+ * @returns 落库成功为 `true`；不允许拖拽或落库失败为 `false`，此时表格已恢复原顺序
+ *
+ * @remarks
+ * 不允许时零写入，直接恢复表格（程序触发的拖放事件同样被拒）。成功后不改表格，
+ * 由活查询按数据库重查的结果刷新；失败时显式恢复，下一次拖拽照常可用。
+ */
+export async function commitRowMove(move: RowMoveEvent, hooks: RowMoveCommitHooks): Promise<boolean> {
+  if (!hooks.enabled) {
+    hooks.restore();
+    return false;
+  }
+  hooks.setError(null);
+  hooks.setPending(true);
+  try {
+    await hooks.reorder(move);
+    return true;
+  } catch (error) {
+    hooks.setError(error);
+    hooks.restore();
+    return false;
+  } finally {
+    hooks.setPending(false);
+  }
+}

package/src/entity-table/columns/build-editable-columns.ts

@@ -0,0 +1,184 @@
+import type {
+  EntityMetadata,
+  EntityPropertyMetadata,
+  EntityRelationMetadata,
+  FieldFormat,
+  FieldOptions
+} from '@aiao/rxdb';
+import { PropertyType, RelationKind } from '@aiao/rxdb';
+import type { ColumnDefine } from '@visactor/vtable/es/ts-types/index.js';
+import { deriveEntityCapabilities } from '../../entity-capabilities.js';
+import type { RelatedEntityItem } from '../../entity-form/interfaces.js';
+import { actionsColumn, buildPropertyColumn, formatDateValue, type KVSchemaEntry } from './column-utils.js';
+
+/** 仅展示（不可编辑）的系统字段 */
+export const DISPLAY_ONLY_FIELDS = new Set(['createdBy', 'updatedBy']);
+
+/** 跳过（不显示为独立列）的系统字段 */
+export const SKIP_FIELDS = new Set(['id', 'createdAt', 'updatedAt']);
+
+/** 关联实体候选 provider 工厂：根据外键字段和关联实体名返回 provider 函数 */
+export type RelatedItemsProviderFactory = (
+  fkField: string,
+  relatedEntityName: string
+) => (() => RelatedEntityItem[]) | undefined;
+
+/** 构建可编辑列的选项 */
+export interface BuildEditableColumnsOptions {
+  /** 关联实体候选 provider 工厂（按外键字段与关联实体名返回 provider） */
+  relatedItemsProviderFactory?: RelatedItemsProviderFactory;
+  /** 操作列标题（默认「操作」） */
+  actionsTitle?: string;
+  /** 删除按钮文案（默认「删除」） */
+  deleteLabel?: string;
+  /** 查看按钮文案（默认「查看」） */
+  viewLabel?: string;
+  /** 创建时间列标题（默认「创建时间」） */
+  createdAtTitle?: string;
+  /** 更新时间列标题（默认「更新时间」） */
+  updatedAtTitle?: string;
+}
+
+function buildKeyValueSchema(prop: EntityPropertyMetadata): Record<string, KVSchemaEntry> {
+  const schema: Record<string, KVSchemaEntry> = {};
+  const properties = (
+    prop as EntityPropertyMetadata & {
+      properties?: ReadonlyArray<{
+        name: string;
+        displayName?: string;
+        type: EntityPropertyMetadata['type'];
+        required?: boolean;
+        nullable?: boolean;
+      }>;
+    }
+  ).properties;
+  if (!properties) return schema;
+  for (const p of properties) {
+    schema[p.name] = {
+      label: p.displayName,
+      type: normalizeKVSchemaEntryType(p.type),
+      required: p.required,
+      nullable: p.nullable
+    };
+  }
+  return schema;
+}
+
+/**
+ * 将实体属性类型归一化为 keyValue Schema 值类型
+ *
+ * 仅 string / enum / uuid / number / integer / boolean / date 可直接映射，
+ * 其余类型返回 undefined。
+ *
+ * @param type 实体属性类型（PropertyType 枚举值）
+ * @returns 对应的 KVSchemaEntry 值类型；无法映射时返回 undefined
+ */
+export function normalizeKVSchemaEntryType(type: EntityPropertyMetadata['type']): KVSchemaEntry['type'] | undefined {
+  switch (typeof type === 'string' ? type : String(type)) {
+    case PropertyType.string:
+    case PropertyType.enum:
+    case PropertyType.uuid:
+      return 'string';
+    case PropertyType.number:
+      return 'number';
+    case PropertyType.integer:
+      return 'integer';
+    case PropertyType.boolean:
+      return 'boolean';
+    case PropertyType.date:
+      return 'date';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * 根据 EntityMetadata 构建可编辑的 VTable 列定义
+ *
+ * 按照以下顺序排列列：
+ * 1. ID 列
+ * 2. 普通属性列（跳过 SKIP_FIELDS 和 DISPLAY_ONLY_FIELDS）
+ * 3. 计算属性列
+ * 4. 外键关系列
+ * 5. createdAt / updatedAt 系统时间列
+ * 6. 操作列（查看 + 删除；删除按实体 `permissions.delete` 派生，见 {@link deriveEntityCapabilities}）
+ *
+ * @param metadata 实体元数据
+ * @param options 可选构建选项
+ * @returns 可编辑的列定义数组
+ */
+export function buildEditableColumns(
+  metadata: EntityMetadata,
+  options: BuildEditableColumnsOptions = {}
+): ColumnDefine[] {
+  const {
+    relatedItemsProviderFactory,
+    actionsTitle = '操作',
+    deleteLabel = '删除',
+    viewLabel = '查看',
+    createdAtTitle = '创建时间',
+    updatedAtTitle = '更新时间'
+  } = options;
+
+  const { canDelete } = deriveEntityCapabilities(metadata);
+  const columns: ColumnDefine[] = [{ field: 'id', title: 'ID', width: 260, sort: true }];
+
+  for (const [key, prop] of metadata.propertyMap) {
+    if (DISPLAY_ONLY_FIELDS.has(key) || SKIP_FIELDS.has(key)) continue;
+    const raw = prop as Record<string, unknown>;
+    columns.push(
+      buildPropertyColumn({
+        field: key,
+        title: prop.displayName ?? key,
+        type: prop.type,
+        readonly: raw['readonly'] === true,
+        enumValues: raw['enum'] as string[] | undefined,
+        keyValueSchema: prop.type === PropertyType.keyValue ? buildKeyValueSchema(prop) : undefined,
+        format: raw['format'] as FieldFormat | undefined,
+        options: raw['options'] as FieldOptions | undefined
+      })
+    );
+  }
+
+  for (const [key, prop] of metadata.computedPropertyMap) {
+    columns.push(
+      buildPropertyColumn({
+        field: key,
+        title: prop.displayName ?? key,
+        type: 'computed',
+        readonly: true
+      })
+    );
+  }
+
+  for (const [fkField, relation] of metadata.foreignKeyRelationMap as Map<string, EntityRelationMetadata>) {
+    const type = relation.kind === RelationKind.ONE_TO_ONE ? 'oneToOne' : 'manyToOne';
+    columns.push(
+      buildPropertyColumn({
+        field: fkField,
+        title: relation.displayName ?? fkField,
+        type,
+        nullable: (relation as Record<string, unknown>)['nullable'] === true,
+        relatedItemsProvider: relatedItemsProviderFactory?.(fkField, relation.mappedEntity)
+      })
+    );
+  }
+
+  columns.push(
+    {
+      field: 'createdAt',
+      title: createdAtTitle,
+      width: 160,
+      fieldFormat: (r: Record<string, unknown>) => formatDateValue(r['createdAt'])
+    },
+    {
+      field: 'updatedAt',
+      title: updatedAtTitle,
+      width: 160,
+      fieldFormat: (r: Record<string, unknown>) => formatDateValue(r['updatedAt'])
+    },
+    actionsColumn(actionsTitle, deleteLabel, () => canDelete, viewLabel)
+  );
+
+  return columns;
+}