@svadmin/core 0.53.0 → 0.55.0

package/src/index.ts

@@ -1,4 +1,6 @@
 // Core barrel exports
+export { decodeApprovalRecord, decodeApprovalList, decodeApprovalTransition, decodeApprovalReceipt, ApprovalContractError } from './approval-contract';
+export type { ApprovalRecord, ApprovalTransition, ApprovalList, ApprovalReceipt, ApprovalProvider } from './approval-contract';
 
 export {
   setDataProvider, getDataProvider, getDataProviderForResource, getDataProviderNames,
@@ -65,7 +67,7 @@ export {
   useCreate, useUpdate, useDelete, useCreateMany, useUpdateMany, useDeleteMany, useForm,
   useInvalidate,
 } from './strict-hooks.svelte';
-export { defineResource, getContractFormFields } from './resource-contract';
+export { defineResource, getContractFormFields, withContractProjection } from './resource-contract';
 export { UpdateManyPartialError } from './update-many-contract';
 export { CreateManyPartialError } from './create-many-contract';
 export type { ContractCreateOptions as UseCreateOptions } from './create-hooks.svelte';
@@ -75,6 +77,7 @@ export type { ContractUpdateParams as UseUpdateMutateParams } from './update-con
 export type { ContractDeleteOptions as UseDeleteOptions } from './delete-hooks.svelte';
 export type { ContractDeleteParams as UseDeleteMutateParams } from './delete-contract';
 export type { ContractFormAction, ContractFormDraft, ContractFormValues } from './resource-contract';
+export type { ContractProjectionOptions } from './resource-contract';
 export type { ResourceContract, ContractSchemas, ContractRecord, ContractId, ContractInput } from './resource-contract';
 export type { ContractFilter, ContractSort } from './strict-hooks.svelte';
 export { defineCommand } from './command-contract';
@@ -114,6 +117,12 @@ export {
 export type { NotificationParams } from './notification.svelte';
 export { t, setLocale, getLocale, getAvailableLocales, addTranslations, useTranslation, setI18nProvider, getI18nProvider, createI18nScope, provideI18nScope, getI18nScope, resetI18n } from './i18n.svelte';
 export type { I18nProvider, I18nScope, I18nScopeOptions } from './i18n.svelte';
+export { buildPivot, buildPivotCacheKey, buildPivotDrilldown, buildPivotExportRequest, decodePivotResult, snapshotPivotQuery, snapshotPivotExportTaskResult, formatPivotValue, PIVOT_LIMITS } from './pivot';
+export type { PivotAggregation, PivotCache, PivotDimension, PivotDimensionValue, PivotOptions, PivotPayload, PivotProvider, PivotQuery, PivotResult, PivotDrilldown, PivotExportRequest, PivotExportTaskResult } from './pivot';
+export { civilDateTimeToInstant, parseDateTimeInstant, formatCivilDateTime } from './date-time';
+export type { DateTimeValueMode, DateTimeDisambiguation } from './date-time';
+export { validateGantt, GANTT_LIMITS } from './gantt';
+export type { GanttTaskShape, GanttValidationError } from './gantt';
 export { audit, auditWithProvider, writeAuditEntry, recordMutationRollback, setAuditHandler, setAuditLogProvider, getAuditLogProvider, withValidatedAuditProvider, AuditError } from './audit';
 export type { AuditLogProvider, AuditLogTransport, AuditCreateParams, AuditQueryParams, AuditDraft } from './audit';
 export { TaskError } from './task-contract';
@@ -143,7 +152,17 @@ export type {
   WebhookSummary,
 } from './enterprise';
 export { assertEnterpriseRequestContext, createEnterpriseRequestContext } from './enterprise';
+export {
+  DashboardContractError, decodeDashboardQuery, decodeDashboardSnapshot,
+  type DashboardMetric, type DashboardProvider, type DashboardQuery, type DashboardSnapshot, type DashboardWidget,
+} from './dashboard-contract';
 export { setChatProvider, getChatProvider, setChatContext, getChatContext, setAgentProvider, getAgentProvider, registerApproval, resolveApproval, hasPendingApprovals, resetChatProvider, defineAdminTool, decodeAdminToolArgs, executeAdminTool, projectAdminToolSchema } from './chatProvider.svelte';
+export { ENTERPRISE_MATURITY, enterpriseMaturityFor } from './enterprise-maturity';
+export type {
+  EnterpriseMaturityEntry,
+  EnterpriseMaturityStatus,
+  EnterpriseMaturityTier,
+} from './enterprise-maturity';
 export type {
   ChatProvider, ChatMessage, ChatMessagePart, ChatContext, ChatAttachment, ChatSource,
   MessageStatus, ToolState, AgentProvider, AgentEvent, AgentOptions, ApprovalResponseOptions,
@@ -175,7 +194,7 @@ export type {
   DeleteManyParams, DeleteManyResult,
   Pagination, Sort, Filter, Identity,
   ResourceDefinition, ResourceProviderConfig, ResourceTransportConfig, ResourceAdapterConfig,
-  FieldDefinition, MenuItem,
+  FieldDefinition, DateInputOptions, MenuItem,
   AuthActionResult, CheckResult,
   ResourceTypeMap, ResourceInputMap, ResourceInputOperation, InferResourceInput, KnownResources, InferData,
   BaseRecord, Role, AuditLog
@@ -190,9 +209,26 @@ export { createCaslAccessControl } from './adapters/casl';
 export { createCasbinAccessControl } from './adapters/casbin';
 export type { CasbinAdapterOptions } from './adapters/casbin';
 export { downloadData, toCsv, toJson, toXlsx, parseCSV } from './data-transfer.svelte';
+export { parseSpreadsheetClipboard, serializeSpreadsheetClipboard } from './spreadsheet-clipboard';
+export { parseSpreadsheetWorkbook, serializeSpreadsheetWorkbook, snapshotSpreadsheetWorkbook, SPREADSHEET_WORKBOOK_LIMITS } from './spreadsheet-workbook';
+export type { SpreadsheetCellFormat, SpreadsheetSheet, SpreadsheetWorkbook } from './spreadsheet-workbook';
+export { FILTER_COLLECTION_LIMIT, isNumericFilterField, isCollectionFilterOperator,
+  filterOperatorsForField, isFilterScalarValue, isFilterCollectionValue } from './filter-values';
+export {
+  assertSchemaFormSchema, prepareSchemaFormValue, readSchemaFormPath,
+  matchesSchemaFormCondition, isSchemaFormNodeVisible, validateSchemaFormValue,
+} from './schema-form';
+export type {
+  SchemaFormScalar, SchemaFormCondition, SchemaFormSchema, SchemaFormValidationError,
+} from './schema-form';
 export { useExport } from './export-hooks.svelte';
+export { snapshotExportTaskResult, downloadExportArtifact, safeArtifactUrl } from './export-format';
+export type { ExportTaskResult } from './export-format';
 export type { UseExportOptions } from './export-hooks.svelte';
 export { useImport } from './import-hooks.svelte';
+export type { ImportArtifact, ImportArtifactProvider, ImportTaskResult } from './import-contract';
+export { snapshotImportArtifact, snapshotImportTaskResult } from './import-contract';
+export { IMPORT_LIMITS } from './import-contract';
 export type { UseImportOptions, ImportProgress, ImportResult } from './import-hooks.svelte';
 export type { ExportFormat } from './data-transfer.svelte';
 export {

package/src/pivot.ts

@@ -0,0 +1,367 @@
+import type { Filter } from './types';
+import { snapshotPlainData } from './plain-data';
+import { snapshotListParams } from './query-snapshot';
+import { snapshotExportTaskResult, type ExportFormat, type ExportTaskResult } from './export-format';
+
+export type PivotAggregation = 'sum' | 'count' | 'avg' | 'min' | 'max';
+export type PivotDimensionValue = string | number | boolean | null;
+export interface PivotDimension {
+  key: string;
+  value: PivotDimensionValue;
+  label: string;
+}
+export interface PivotOptions {
+  rowField: string;
+  columnField: string;
+  valueField: string;
+  aggregator?: PivotAggregation;
+}
+export interface PivotResult {
+  error?: 'invalidData' | 'limit' | 'invalidNumber' | 'overflow';
+  rows: PivotDimension[];
+  columns: PivotDimension[];
+  cells: Map<string, Map<string, number | null>>;
+  rowTotals: Map<string, number | null>;
+  columnTotals: Map<string, number | null>;
+  grandTotal: number | null;
+}
+
+export interface PivotQuery extends PivotOptions {
+  resource: string;
+  filters?: Filter[];
+  meta?: Record<string, unknown>;
+}
+
+export interface PivotDrilldown {
+  resource: string;
+  scopeKey: string;
+  rowField: string;
+  columnField: string;
+  valueField: string;
+  aggregator: PivotAggregation;
+  row: PivotDimension;
+  column: PivotDimension;
+  filters?: Filter[];
+  meta?: Record<string, unknown>;
+}
+
+export interface PivotProvider {
+  aggregate: (query: PivotQuery) => Promise<unknown>;
+}
+
+export interface PivotCache {
+  /** 相同缓存中的不同数据源必须使用不同命名空间。 */
+  providerKey: string;
+  get: (key: string) => Promise<unknown | undefined> | unknown | undefined;
+  set: (key: string, value: unknown) => Promise<void> | void;
+}
+
+export function buildPivotCacheKey(query: unknown, scopeKey: unknown, providerKey: unknown): string | undefined {
+  const snapshot = snapshotPivotQuery(query);
+  if (!snapshot || typeof scopeKey !== 'string' || !scopeKey.trim() || scopeKey.length > 4000
+    || typeof providerKey !== 'string' || !providerKey.trim() || providerKey.length > 4000) return;
+  return JSON.stringify({ protocolVersion: 1, providerKey, scopeKey, query: snapshot });
+}
+
+export interface PivotExportRequest {
+  protocolVersion: 1;
+  kind: 'pivot';
+  scopeKey: string;
+  format: ExportFormat;
+  query: PivotQuery;
+  requestFingerprint: string;
+}
+
+export interface PivotExportTaskResult extends ExportTaskResult {
+  kind: 'pivot';
+  taskName: string;
+  idempotencyKey: string;
+  scopeKey: string;
+  requestFingerprint: string;
+}
+
+/** 只生成服务端导出请求，不将当前页或预聚合单元格当作原始记录导出。 */
+export function buildPivotExportRequest(query: unknown, scopeKey: unknown, format: unknown = 'csv'): PivotExportRequest | undefined {
+  const snapshot = snapshotPivotQuery(query);
+  if (!snapshot || typeof scopeKey !== 'string' || !scopeKey.trim() || scopeKey.length > 4000
+    || (format !== 'csv' && format !== 'json' && format !== 'xlsx')) return;
+  const request: Omit<PivotExportRequest, 'requestFingerprint'> = { protocolVersion: 1, kind: 'pivot', scopeKey, format, query: snapshot };
+  return { ...request, requestFingerprint: JSON.stringify(request) };
+}
+
+export function snapshotPivotExportTaskResult(value: unknown, expected: {
+  taskName: string; idempotencyKey: string; request: PivotExportRequest;
+}): PivotExportTaskResult | undefined {
+  try {
+    const plain = snapshotPlainData(value);
+    if (!isRecord(plain)) return;
+    const { kind, taskName, idempotencyKey, scopeKey, requestFingerprint, ...artifact } = plain;
+    const result = snapshotExportTaskResult(artifact);
+    if (!result || kind !== 'pivot' || taskName !== expected.taskName
+      || idempotencyKey !== expected.idempotencyKey || scopeKey !== expected.request.scopeKey
+      || requestFingerprint !== expected.request.requestFingerprint
+      || result.format !== expected.request.format) return;
+    return { ...result, kind: 'pivot', taskName: expected.taskName,
+      idempotencyKey: expected.idempotencyKey, scopeKey: expected.request.scopeKey,
+      requestFingerprint: expected.request.requestFingerprint };
+  } catch { return; }
+}
+
+/** 保留原条件树的顶层 AND 语义，不能把维度约束塞入已有 OR 组。 */
+export function buildPivotDrilldown(query: unknown, scopeKey: unknown, row: unknown, column: unknown): PivotDrilldown | undefined {
+  try {
+    const snapshot = snapshotPivotQuery(query);
+    if (!snapshot || typeof scopeKey !== 'string' || !scopeKey.trim() || scopeKey.length > 4000) return;
+    const rowSnapshot = wireDimension(snapshotPlainData(row));
+    const columnSnapshot = wireDimension(snapshotPlainData(column));
+    if (!rowSnapshot || !columnSnapshot) return;
+    const constraints: Filter[] = [
+      { field: snapshot.rowField, operator: rowSnapshot.value === null ? 'null' : 'eq', value: rowSnapshot.value },
+      { field: snapshot.columnField, operator: columnSnapshot.value === null ? 'null' : 'eq', value: columnSnapshot.value },
+    ];
+    const narrowed = snapshotPivotQuery({ ...snapshot, filters: [...snapshot.filters ?? [], ...constraints] });
+    if (!narrowed) return;
+    return {
+      resource: narrowed.resource,
+      rowField: narrowed.rowField,
+      columnField: narrowed.columnField,
+      valueField: narrowed.valueField,
+      aggregator: narrowed.aggregator ?? 'sum',
+      scopeKey,
+      row: rowSnapshot,
+      column: columnSnapshot,
+      ...(narrowed.filters ? { filters: narrowed.filters } : {}),
+      ...(narrowed.meta ? { meta: narrowed.meta } : {}),
+    };
+  } catch {
+    return;
+  }
+}
+
+/** 服务端计算所有汇总值；客户端不能对预聚合结果再次求平均或计数。 */
+export interface PivotPayload {
+  rows: PivotDimension[];
+  columns: PivotDimension[];
+  cells: Array<{ rowKey: string; columnKey: string; value: number | null }>;
+  rowTotals: Array<{ key: string; value: number | null }>;
+  columnTotals: Array<{ key: string; value: number | null }>;
+  grandTotal: number | null;
+}
+
+export function snapshotPivotQuery(value: unknown): PivotQuery | undefined {
+  try {
+    const plain = snapshotPlainData(value);
+    if (!isRecord(plain)) return;
+    const { rowField, columnField, valueField, aggregator = 'sum', ...base } = plain;
+    if (![rowField, columnField, valueField].every(field => typeof field === 'string'
+      && field.trim().length > 0 && field.length <= PIVOT_LIMITS.dimensionLength)
+      || typeof aggregator !== 'string' || !['sum', 'count', 'avg', 'min', 'max'].includes(aggregator)) return;
+    const query = snapshotListParams(base);
+    if (Object.keys(base).some(key => !['resource', 'filters', 'meta'].includes(key))) return;
+    return {
+      ...query, rowField: rowField as string, columnField: columnField as string,
+      valueField: valueField as string, aggregator: aggregator as PivotAggregation,
+    };
+  } catch {
+    return;
+  }
+}
+
+export const PIVOT_LIMITS = Object.freeze({
+  records: 10_000,
+  rows: 200,
+  columns: 200,
+  cells: 40_000,
+  dimensionLength: 1000,
+});
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+interface Aggregate {
+  count: number;
+  value: number;
+}
+
+function dimension(value: unknown): PivotDimension | undefined {
+  if (value == null) return { key: 'null:', value: null, label: '—' };
+  if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') return;
+  if (typeof value === 'number' && !Number.isFinite(value)) return;
+  if (typeof value === 'string' && value.length > PIVOT_LIMITS.dimensionLength) return;
+  return { key: `${typeof value}:${value}`, value, label: String(value) };
+}
+
+function sortedDimensions(values: Map<string, PivotDimension>): PivotDimension[] {
+  const labels = new Map<string, number>();
+  for (const item of values.values()) labels.set(item.label, (labels.get(item.label) ?? 0) + 1);
+  // 同一轴存在歧义时统一转义所有文本，避免加引号后与另一个原始标签重名。
+  const quoteStrings = [...labels.values()].some(count => count > 1) || values.has('string:');
+  return [...values.values()].sort((a, b) => a.label < b.label ? -1 : a.label > b.label ? 1 : a.key < b.key ? -1 : 1)
+    .map(item => ({
+      ...item,
+      label: quoteStrings && typeof item.value === 'string'
+        ? JSON.stringify(item.value) : item.label,
+    }));
+}
+
+function result(error?: PivotResult['error']): PivotResult {
+  return {
+    ...(error === undefined ? {} : { error }),
+    rows: [], columns: [], cells: new Map(), rowTotals: new Map(), columnTotals: new Map(), grandTotal: null,
+  };
+}
+
+function wireDimension(value: unknown): PivotDimension | undefined {
+  if (!isRecord(value) || typeof value['key'] !== 'string' || typeof value['label'] !== 'string') return;
+  const dimensionValue = value['value'];
+  if (dimensionValue !== null && typeof dimensionValue !== 'string'
+    && typeof dimensionValue !== 'number' && typeof dimensionValue !== 'boolean') return;
+  if (typeof dimensionValue === 'number' && !Number.isFinite(dimensionValue)) return;
+  if (!value['key'].trim() || !value['label'].trim()
+    || value['key'].length > PIVOT_LIMITS.dimensionLength || value['label'].length > PIVOT_LIMITS.dimensionLength
+    || (typeof dimensionValue === 'string' && dimensionValue.length > PIVOT_LIMITS.dimensionLength)) return;
+  return { key: value['key'], value: dimensionValue, label: value['label'] };
+}
+
+function wireNumber(value: unknown): number | null | undefined {
+  if (value === null) return null;
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function wireTotals(value: unknown, keys: Set<string>): Map<string, number | null> | undefined {
+  if (!Array.isArray(value) || value.length !== keys.size) return;
+  const result = new Map<string, number | null>();
+  for (const item of value) {
+    if (!isRecord(item) || typeof item['key'] !== 'string' || !keys.has(item['key']) || result.has(item['key'])) return;
+    const number = wireNumber(item['value']);
+    if (number === undefined) return;
+    result.set(item['key'], number);
+  }
+  return result;
+}
+
+/** 服务端汇总回执必须是有界纯数据，不能包含访问器或未知维度引用。 */
+export function decodePivotResult(value: unknown): PivotResult {
+  try {
+    const plain = snapshotPlainData(value);
+    if (!isRecord(plain) || !Array.isArray(plain['rows']) || !Array.isArray(plain['columns'])
+      || !Array.isArray(plain['cells'])) return result('invalidData');
+    if (plain['rows'].length > PIVOT_LIMITS.rows || plain['columns'].length > PIVOT_LIMITS.columns
+      || plain['cells'].length > PIVOT_LIMITS.cells) return result('limit');
+    const rows: PivotDimension[] = [];
+    const columns: PivotDimension[] = [];
+    const rowKeys = new Set<string>();
+    const columnKeys = new Set<string>();
+    for (const item of plain['rows']) {
+      const dimension = wireDimension(item);
+      if (!dimension || rowKeys.has(dimension.key)) return result('invalidData');
+      rowKeys.add(dimension.key);
+      rows.push(dimension);
+    }
+    for (const item of plain['columns']) {
+      const dimension = wireDimension(item);
+      if (!dimension || columnKeys.has(dimension.key)) return result('invalidData');
+      columnKeys.add(dimension.key);
+      columns.push(dimension);
+    }
+    if (rows.length * columns.length > PIVOT_LIMITS.cells) return result('limit');
+    const cells = new Map<string, Map<string, number | null>>();
+    for (const item of plain['cells']) {
+      if (!isRecord(item) || typeof item['rowKey'] !== 'string' || typeof item['columnKey'] !== 'string'
+        || !rowKeys.has(item['rowKey']) || !columnKeys.has(item['columnKey'])) return result('invalidData');
+      if (cells.get(item['rowKey'])?.has(item['columnKey'])) return result('invalidData');
+      const number = wireNumber(item['value']);
+      if (number === undefined) return result('invalidNumber');
+      let row = cells.get(item['rowKey']);
+      if (!row) { row = new Map(); cells.set(item['rowKey'], row); }
+      row.set(item['columnKey'], number);
+    }
+    const rowTotals = wireTotals(plain['rowTotals'], rowKeys);
+    const columnTotals = wireTotals(plain['columnTotals'], columnKeys);
+    const grandTotal = wireNumber(plain['grandTotal']);
+    if (!rowTotals || !columnTotals || grandTotal === undefined) return result('invalidData');
+    return { rows, columns, cells, rowTotals, columnTotals, grandTotal };
+  } catch {
+    return result('invalidData');
+  }
+}
+
+function add(aggregate: Aggregate, value: number, operator: PivotAggregation): boolean {
+  aggregate.count++;
+  switch (operator) {
+    case 'count': aggregate.value = aggregate.count; break;
+    case 'sum': aggregate.value += value; break;
+    // 分别缩放两项，避免有限输入的均值因中间求和溢出。
+    case 'avg': aggregate.value = aggregate.value * ((aggregate.count - 1) / aggregate.count) + value / aggregate.count; break;
+    case 'min': aggregate.value = aggregate.count === 1 ? value : Math.min(aggregate.value, value); break;
+    case 'max': aggregate.value = aggregate.count === 1 ? value : Math.max(aggregate.value, value); break;
+  }
+  return Number.isFinite(aggregate.value);
+}
+
+function valueOf(aggregate: Aggregate): number | null {
+  return aggregate.count ? aggregate.value : null;
+}
+
+/** 有界的记录聚合；不把分页数据解释为整个资源的统计结果。 */
+export function buildPivot(data: readonly Record<string, unknown>[], options: PivotOptions): PivotResult {
+  const operator = options.aggregator ?? 'sum';
+  if (!Array.isArray(data) || !['sum', 'count', 'avg', 'min', 'max'].includes(operator)
+    || ![options.rowField, options.columnField, options.valueField].every(field => typeof field === 'string' && field.length > 0)) {
+    return result('invalidData');
+  }
+  if (data.length > PIVOT_LIMITS.records) return result('limit');
+  const rows = new Map<string, PivotDimension>();
+  const columns = new Map<string, PivotDimension>();
+  const cells = new Map<string, Map<string, Aggregate>>();
+  const rowTotals = new Map<string, Aggregate>();
+  const columnTotals = new Map<string, Aggregate>();
+  const grand: Aggregate = { count: 0, value: 0 };
+  for (const record of data) {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) return result('invalidData');
+    const own = (field: string) => Object.hasOwn(record, field) ? record[field] : undefined;
+    const row = dimension(own(options.rowField));
+    const column = dimension(own(options.columnField));
+    if (!row || !column) return result('invalidData');
+    rows.set(row.key, row);
+    columns.set(column.key, column);
+    if (rows.size > PIVOT_LIMITS.rows || columns.size > PIVOT_LIMITS.columns
+      || rows.size * columns.size > PIVOT_LIMITS.cells) return result('limit');
+    if (!rowTotals.has(row.key)) rowTotals.set(row.key, { count: 0, value: 0 });
+    if (!columnTotals.has(column.key)) columnTotals.set(column.key, { count: 0, value: 0 });
+    let rowCells = cells.get(row.key);
+    if (!rowCells) { rowCells = new Map(); cells.set(row.key, rowCells); }
+    let cell = rowCells.get(column.key);
+    if (!cell) { cell = { count: 0, value: 0 }; rowCells.set(column.key, cell); }
+    const raw = operator === 'count' ? 1 : own(options.valueField);
+    if (raw == null) continue;
+    if (typeof raw !== 'number' || !Number.isFinite(raw)) return result('invalidNumber');
+    const rowTotal = rowTotals.get(row.key);
+    const columnTotal = columnTotals.get(column.key);
+    if (!rowTotal || !columnTotal) return result('invalidData');
+    const targets = [cell, rowTotal, columnTotal, grand];
+    for (const target of targets) {
+      if (!add(target, raw, operator)) return result('overflow');
+    }
+  }
+  return {
+    rows: sortedDimensions(rows),
+    columns: sortedDimensions(columns),
+    cells: new Map([...cells].map(([key, values]) => [key, new Map([...values].map(([col, agg]) => [col, valueOf(agg)]))])),
+    rowTotals: new Map([...rowTotals].map(([key, agg]) => [key, valueOf(agg)])),
+    columnTotals: new Map([...columnTotals].map(([key, agg]) => [key, valueOf(agg)])),
+    grandTotal: valueOf(grand),
+  };
+}
+
+/** 空格和异常格式化器不能把一个有值的单元格伪装为空值。 */
+export function formatPivotValue(value: number | null | undefined, formatter: (value: number) => string): string {
+  if (value == null) return '—';
+  try {
+    const formatted = formatter(value);
+    return typeof formatted === 'string' && formatted.trim() ? formatted : String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/query-session.svelte.ts

@@ -183,10 +183,15 @@ export function createQuerySession<O extends QuerySessionOptions>(context: Admin
       }
     });
   }
+  // 清理微任务只读取普通快照，不访问已经销毁或退出动画中的派生状态。
+  let lastQueryKey: QueryKey | undefined;
+  $effect(() => { lastQueryKey = options.queryKey; });
   $effect(() => () => {
     disposed = true;
+    const queryKey = lastQueryKey;
+    if (!queryKey) return;
     queueMicrotask(() => {
-      const query = client.getQueryCache().find({ queryKey: options.queryKey, exact: true });
+      const query = client.getQueryCache().find({ queryKey, exact: true });
       if (query?.getObserversCount() === 0) void query.cancel();
     });
   });

package/src/resource-contract.ts

@@ -2,8 +2,8 @@ import { CloneType, Kind, TransformKind, Type, type Static, type TObject, type T
 import { checkExact, createExactSchemaValidator } from './schema-validation';
 import { TypeGuard } from '@sinclair/typebox/type';
 import { DeleteManyPartialError, HttpError, type DataProvider, type KnownResources, type BaseRecord,
-  type GetManyParams, type CreateManyParams, type UpdateManyParams, type DeleteManyParams,
-  type GetOneResult, type GetManyResult } from './types';
+  type GetListResult, type GetManyParams, type CreateManyParams, type UpdateManyParams, type DeleteManyParams,
+  type GetOneParams, type GetOneResult, type GetManyResult } from './types';
 import { withResourceSchemas, createResourceRequestValidator, type ResourceSchemas } from './resource-schemas';
 import { decodeBaseRecord } from './record-decoder';
 import { snapshotPlainData } from './plain-data';
@@ -166,6 +166,115 @@ export function parseContractRecord(contract: ResourceContract, value: unknown):
   throw new HttpError('Invalid provider response', 502, undefined, { code: 'INVALID_PROVIDER_RESPONSE' });
 }
 
+export interface ContractProjectionOptions {
+  /** Supplies the id when the backend record has no declared contract id. */
+  readonly getId?: (input: {
+    resource: string;
+    requestedId: string | number | undefined;
+    record: unknown;
+    index: number;
+  }) => string | number | undefined;
+}
+
+function projectBySchema(schema: TSchema, value: unknown): unknown {
+  if (TypeGuard.IsObject(schema)) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return value;
+    const source = value as Record<string, unknown>;
+    const projected: Record<string, unknown> = {};
+    for (const [key, property] of Object.entries(schema.properties)) {
+      if (Object.hasOwn(source, key)) projected[key] = projectBySchema(property, source[key]);
+    }
+    return projected;
+  }
+  if (TypeGuard.IsArray(schema)) {
+    return Array.isArray(value) ? value.map(item => projectBySchema(schema.items, item)) : value;
+  }
+  if (TypeGuard.IsTuple(schema)) {
+    return Array.isArray(value)
+      ? value.map((item, index) => schema.items?.[index] ? projectBySchema(schema.items[index], item) : item)
+      : value;
+  }
+  if (TypeGuard.IsUnion(schema)) {
+    const branch = schema.anyOf.find(candidate => checkExact(candidate, value));
+    return branch ? projectBySchema(branch, value) : value;
+  }
+  return value;
+}
+
+function projectRecord(
+  contract: ResourceContract,
+  resource: string,
+  record: unknown,
+  index: number,
+  requestedId: string | number | undefined,
+  options: ContractProjectionOptions,
+): unknown {
+  const projected = projectBySchema(definitionOf(contract).schemas.record, record);
+  if (typeof projected !== 'object' || projected === null || Array.isArray(projected)) return projected;
+  const result = projected as Record<string, unknown>;
+  if (!Object.hasOwn(result, 'id')) {
+    const id = options.getId?.({ resource, requestedId, record, index })
+      ?? requestedId
+      ?? (typeof record === 'object' && record !== null && !Array.isArray(record)
+        ? ['id', '_id', 'uuid', 'key', 'name'].map(key => (record as Record<string, unknown>)[key])
+          .find(candidate => typeof candidate === 'string' || typeof candidate === 'number')
+        : undefined)
+      ?? `${resource}:${index}`;
+    result['id'] = id;
+  }
+  return result;
+}
+
+/**
+ * Projects read responses into the exact closed shape required by resource contracts.
+ * Write responses remain untouched so mutation validation keeps its existing semantics.
+ */
+export function withContractProjection(
+  provider: DataProvider,
+  contracts: Readonly<Record<string, ResourceContract>>,
+  options: ContractProjectionOptions = {},
+): Readonly<DataProvider> {
+  function contractFor(resource: string): ResourceContract | undefined {
+    return contracts[resource];
+  }
+  function projectList(resource: string, result: GetListResult): GetListResult {
+    const contract = contractFor(resource);
+    if (!contract) return result;
+    return {
+      ...result,
+      data: result.data.map((record, index) =>
+        projectRecord(contract, resource, record, index, undefined, options) as BaseRecord),
+    };
+  }
+  function projectMany(resource: string, result: GetManyResult): GetManyResult {
+    const contract = contractFor(resource);
+    if (!contract) return result;
+    return {
+      ...result,
+      data: result.data.map((record, index) =>
+        projectRecord(contract, resource, record, index, undefined, options) as BaseRecord),
+    };
+  }
+  function projectOne(params: GetOneParams, result: GetOneResult): GetOneResult {
+    const contract = contractFor(params.resource);
+    return contract
+      ? { ...result, data: projectRecord(contract, params.resource, result.data, 0, params.id, options) as BaseRecord }
+      : result;
+  }
+
+  const adapted: DataProvider = {
+    ...provider,
+    getList: async params => projectList(params.resource, await provider.getList(params)),
+    getOne: async params => projectOne(params, await provider.getOne(params)),
+    getApiUrl: () => provider.getApiUrl(),
+  };
+  if (provider.getMany) {
+    const getMany = provider.getMany.bind(provider);
+    adapted.getMany = async params => projectMany(params.resource, await getMany(params));
+  }
+  return Object.freeze(adapted);
+}
+
 function idSchema(schemas: ContractSchemas): TSchema {
   const schema = schemas.record.properties['id'];
   if (!schema) throw new HttpError('Missing contract ID schema', 400, undefined, { code: 'INVALID_RESOURCE_CONTRACT' });