@svadmin/core 0.53.0 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "author": "zuohuadong",
   "repository": {
     "type": "git",
@@ -16,19 +16,45 @@
     "@testing-library/user-event": "^14.6.6",
     "@types/bun": "^1.4.2",
     "@types/jsdom": "^30.0.0",
+    "exceljs": "4.4.0",
     "happy-dom": "^20.11.12",
     "jsdom": "^30.0.1",
     "vitest": "^4.1.11"
   },
   "peerDependencies": {
+    "exceljs": "^4.4.0",
     "svelte": "^5.56.10",
     "@tanstack/svelte-query": "^6.1.48"
   },
   "exports": {
+    "./spreadsheet-xlsx": {
+      "types": "./src/spreadsheet-xlsx.ts",
+      "default": "./src/spreadsheet-xlsx.ts"
+    },
+    "./filter-values": {
+      "types": "./src/filter-values.ts",
+      "default": "./src/filter-values.ts"
+    },
+    "./date-time": {
+      "types": "./src/date-time.ts",
+      "default": "./src/date-time.ts"
+    },
+    "./pivot": {
+      "types": "./src/pivot.ts",
+      "default": "./src/pivot.ts"
+    },
+    "./gantt": {
+      "types": "./src/gantt.ts",
+      "default": "./src/gantt.ts"
+    },
     "./schema": {
       "types": "./src/schema.ts",
       "default": "./src/schema.ts"
     },
+    "./schema-form": {
+      "types": "./src/schema-form.ts",
+      "default": "./src/schema-form.ts"
+    },
     "./options": {
       "types": "./src/defined-options.ts",
       "default": "./src/defined-options.ts"
@@ -107,10 +133,14 @@
   "type": "module",
   "types": "src/index.ts",
   "dependencies": {
+    "@internationalized/date": "^3.12.3",
     "@sinclair/typebox": "^0.34.52",
     "papaparse": "^5.5.4"
   },
   "peerDependenciesMeta": {
+    "exceljs": {
+      "optional": true
+    },
     "svelte": {
       "optional": true
     },

package/src/approval-contract.ts

@@ -0,0 +1,131 @@
+import { Type, type Static } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
+import type { EnterpriseProviderRequestContext } from './enterprise';
+
+const identifier = Type.String({ minLength: 1, maxLength: 200, pattern: '^\\S(?:[\\s\\S]*\\S)?$' });
+const version = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+const comment = Type.String({ maxLength: 10000 });
+const action = Type.Object({
+  id: identifier,
+  label: Type.String({ minLength: 1, maxLength: 200 }),
+  commentRequired: Type.Boolean(),
+  targetRequired: Type.Boolean(),
+}, { additionalProperties: false });
+const attachment = Type.Object({
+  id: identifier,
+  name: Type.String({ minLength: 1, maxLength: 500 }),
+}, { additionalProperties: false });
+const history = Type.Object({
+  id: identifier,
+  action: identifier,
+  actor: Type.String({ minLength: 1, maxLength: 200 }),
+  at: Type.String({ pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$' }),
+  comment,
+}, { additionalProperties: false });
+const recordSchema = Type.Object({
+  id: identifier,
+  version,
+  title: Type.String({ minLength: 1, maxLength: 500 }),
+  status: identifier,
+  applicant: Type.String({ minLength: 1, maxLength: 200 }),
+  allowedActions: Type.Array(action, { maxItems: 30 }),
+  attachments: Type.Array(attachment, { maxItems: 100 }),
+  history: Type.Array(history, { maxItems: 1000 }),
+}, { additionalProperties: false });
+const transitionSchema = Type.Object({
+  id: identifier,
+  expectedVersion: version,
+  action: identifier,
+  comment,
+  targetId: Type.Optional(identifier),
+  idempotencyKey: identifier,
+}, { additionalProperties: false });
+const listSchema = Type.Object({
+  data: Type.Array(recordSchema, { maxItems: 200 }),
+  total: Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
+}, { additionalProperties: false });
+
+export type ApprovalRecord = Static<typeof recordSchema>;
+export type ApprovalTransition = Static<typeof transitionSchema>;
+export type ApprovalList = Static<typeof listSchema>;
+export type ApprovalReceipt =
+  | { ok: true; record: ApprovalRecord }
+  | { ok: false; code: 'VERSION_CONFLICT'; current: ApprovalRecord };
+
+/** 宿主执行授权与状态机；附件仅返回引用，不接受任意下载 URL。 */
+export interface ApprovalProvider {
+  list(context: EnterpriseProviderRequestContext, query: {
+    view: 'pending' | 'history'; page: number; pageSize: number; search: string;
+  }): Promise<unknown>;
+  get(context: EnterpriseProviderRequestContext, id: string): Promise<unknown>;
+  transition?(context: EnterpriseProviderRequestContext, input: ApprovalTransition): Promise<unknown>;
+}
+
+export class ApprovalContractError extends Error {
+  constructor(readonly code: 'INVALID_APPROVAL_INPUT' | 'INVALID_APPROVAL_RESPONSE') {
+    super(code === 'INVALID_APPROVAL_INPUT' ? 'Invalid approval input.' : 'Invalid approval response.');
+    this.name = 'ApprovalContractError';
+  }
+}
+
+function unique(items: readonly { id: string }[]): boolean {
+  return new Set(items.map(item => item.id)).size === items.length;
+}
+
+export function decodeApprovalRecord(value: unknown, expectedId?: string): ApprovalRecord {
+  try {
+    const record = snapshotPlainData(value);
+    if (checkExact(recordSchema, record)
+      && (expectedId === undefined || record.id === expectedId)
+      && unique(record.allowedActions) && unique(record.attachments) && unique(record.history)
+      && record.history.every(event => {
+        const parsed = new Date(event.at);
+        return Number.isFinite(parsed.getTime())
+          && parsed.toISOString().replace('.000Z', 'Z') ===
+            event.at.replace(/(?:\.0{1,3})Z$/, 'Z').replace(/\.(\d{1,2})Z$/, (_, digits: string) => `.${digits.padEnd(3, '0')}Z`);
+      })) return record;
+  } catch { /* 不回显 Provider 载荷或执行访问器。 */ }
+  throw new ApprovalContractError('INVALID_APPROVAL_RESPONSE');
+}
+
+export function decodeApprovalList(value: unknown): ApprovalList {
+  try {
+    const result = snapshotPlainData(value);
+    if (checkExact(listSchema, result) && result.total >= result.data.length && unique(result.data)) {
+      return { data: result.data.map(record => decodeApprovalRecord(record)), total: result.total };
+    }
+  } catch { /* 统一失败，不返回部分合法记录。 */ }
+  throw new ApprovalContractError('INVALID_APPROVAL_RESPONSE');
+}
+
+export function decodeApprovalTransition(value: unknown, current: ApprovalRecord): ApprovalTransition {
+  try {
+    const input = snapshotPlainData(value);
+    const record = decodeApprovalRecord(current);
+    if (checkExact(transitionSchema, input) && input.id === record.id && input.expectedVersion === record.version) {
+      const permitted = record.allowedActions.find(candidate => candidate.id === input.action);
+      if (permitted && (!permitted.commentRequired || !!input.comment.trim())
+        && (permitted.targetRequired ? input.targetId !== undefined : input.targetId === undefined)) return input;
+    }
+  } catch { /* 不将本地允许动作视为服务端授权。 */ }
+  throw new ApprovalContractError('INVALID_APPROVAL_INPUT');
+}
+
+export function decodeApprovalReceipt(value: unknown, input: ApprovalTransition): ApprovalReceipt {
+  try {
+    const request = snapshotPlainData(input);
+    const receipt = snapshotPlainData(value);
+    if (!checkExact(transitionSchema, request) || typeof receipt !== 'object' || receipt === null || Array.isArray(receipt)) throw new Error();
+    if (receipt['ok'] === true && Object.keys(receipt).every(key => ['ok', 'record'].includes(key))) {
+      const record = decodeApprovalRecord(receipt['record'], request.id);
+      if (record.version > request.expectedVersion) return { ok: true, record };
+    }
+    if (receipt['ok'] === false && receipt['code'] === 'VERSION_CONFLICT'
+      && Object.keys(receipt).every(key => ['ok', 'code', 'current'].includes(key))) {
+      const current = decodeApprovalRecord(receipt['current'], request.id);
+      if (current.version >= request.expectedVersion) return { ok: false, code: 'VERSION_CONFLICT', current };
+    }
+  } catch { /* 错配和未知回执不作为成功。 */ }
+  throw new ApprovalContractError('INVALID_APPROVAL_RESPONSE');
+}

package/src/dashboard-contract.ts

@@ -0,0 +1,72 @@
+import { Type, type Static } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
+import type { EnterpriseProviderRequestContext } from './enterprise';
+
+const id = Type.String({ minLength: 1, maxLength: 200, pattern: '^\\S(?:[\\s\\S]*\\S)?$' });
+const scalar = Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()]);
+const metric = Type.Object({
+  id,
+  label: Type.String({ minLength: 1, maxLength: 200 }),
+  value: scalar,
+  tone: Type.Optional(Type.Union([
+    Type.Literal('default'), Type.Literal('primary'), Type.Literal('success'),
+    Type.Literal('warning'), Type.Literal('danger'), Type.Literal('info'),
+  ])),
+  href: Type.Optional(Type.String({ minLength: 1, maxLength: 2000, pattern: '^(?:/|#)' })),
+}, { additionalProperties: false });
+const widget = Type.Object({
+  id,
+  title: Type.String({ minLength: 1, maxLength: 300 }),
+  kind: Type.Union([Type.Literal('metric'), Type.Literal('text')]),
+  metrics: Type.Array(metric, { maxItems: 100 }),
+  text: Type.Optional(Type.String({ maxLength: 10000 })),
+}, { additionalProperties: false });
+const snapshot = Type.Object({
+  version: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+  widgets: Type.Array(widget, { maxItems: 100 }),
+}, { additionalProperties: false });
+const query = Type.Object({
+  dashboardId: id,
+  filters: Type.Optional(Type.Array(Type.Object({
+    field: id,
+    value: scalar,
+  }, { additionalProperties: false }), { maxItems: 50 })),
+}, { additionalProperties: false });
+
+export type DashboardMetric = Static<typeof metric>;
+export type DashboardWidget = Static<typeof widget>;
+export type DashboardSnapshot = Static<typeof snapshot>;
+export type DashboardQuery = Static<typeof query>;
+
+export interface DashboardProvider {
+  get(context: EnterpriseProviderRequestContext, query: DashboardQuery): Promise<unknown>;
+}
+
+export class DashboardContractError extends Error {
+  constructor() {
+    super('Invalid dashboard response.');
+    this.name = 'DashboardContractError';
+  }
+}
+
+export function decodeDashboardSnapshot(value: unknown): DashboardSnapshot {
+  try {
+    const result = snapshotPlainData(value);
+    if (checkExact(snapshot, result)
+      && new Set(result.widgets.map(item => item.id)).size === result.widgets.length
+      && result.widgets.every(item => new Set(item.metrics.map(metricItem => metricItem.id)).size === item.metrics.length)
+      && result.widgets.every(item => item.kind === 'text' ? item.text !== undefined : item.metrics.length > 0)) {
+      return result;
+    }
+  } catch { /* Provider payloads fail closed. */ }
+  throw new DashboardContractError();
+}
+
+export function decodeDashboardQuery(value: unknown): DashboardQuery {
+  try {
+    const result = snapshotPlainData(value);
+    if (checkExact(query, result)) return result;
+  } catch { /* Query payloads fail closed. */ }
+  throw new DashboardContractError();
+}

package/src/date-time.ts

@@ -0,0 +1,55 @@
+import { fromDate, parseAbsolute, parseDateTime, toCalendarDateTime, toZoned } from '@internationalized/date';
+
+export type DateTimeValueMode = 'civil' | 'instant';
+export type DateTimeDisambiguation = 'reject' | 'earlier' | 'later';
+
+const civilPattern = /^(?!0000)\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,3})?)?$/;
+const absolutePattern = /^(?!0000)\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d{1,3})?)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+
+function validTimeZone(timeZone: string): boolean {
+  if (typeof timeZone !== 'string' || !timeZone.trim() || timeZone.length > 200) return false;
+  try {
+    new Intl.DateTimeFormat('en', { timeZone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 默认拒绝夏令时重复或不存在的本地时间；消歧必须由调用方明确选择。 */
+export function civilDateTimeToInstant(
+  value: string, timeZone: string, disambiguation: DateTimeDisambiguation = 'reject',
+): number | undefined {
+  if (!civilPattern.test(value) || !validTimeZone(timeZone)
+    || !['reject', 'earlier', 'later'].includes(disambiguation)) return;
+  try {
+    const civil = parseDateTime(value);
+    const zoned = toZoned(civil, timeZone, disambiguation);
+    // 不允许消歧策略把不存在的时间自动挪到夏令时跳跃前后。
+    if (toCalendarDateTime(zoned).compare(civil) !== 0) return;
+    return zoned.toDate().getTime();
+  } catch {
+    return;
+  }
+}
+
+export function parseDateTimeInstant(value: string): number | undefined {
+  if (!absolutePattern.test(value)) return;
+  try {
+    return parseAbsolute(value, 'UTC').toDate().getTime();
+  } catch {
+    return;
+  }
+}
+
+export function formatCivilDateTime(instant: number, timeZone: string): string | undefined {
+  if (!Number.isSafeInteger(instant) || !validTimeZone(timeZone)) return;
+  try {
+    const date = fromDate(new Date(instant), timeZone);
+    if (date.era !== 'AD' || date.year < 1 || date.year > 9999) return;
+    const civil = toCalendarDateTime(date).toString();
+    return date.second === 0 && date.millisecond === 0 ? civil.slice(0, 16) : civil;
+  } catch {
+    return;
+  }
+}

package/src/enterprise-maturity.ts

@@ -0,0 +1,54 @@
+export type EnterpriseMaturityTier = 'P0' | 'P1' | 'P2';
+export type EnterpriseMaturityStatus = 'stable' | 'verified' | 'experimental' | 'planned';
+
+export interface EnterpriseMaturityEntry {
+  readonly id: string;
+  readonly tier: EnterpriseMaturityTier;
+  readonly status: EnterpriseMaturityStatus;
+  readonly surfaces: readonly string[];
+  readonly acceptance: readonly string[];
+}
+
+export const ENTERPRISE_MATURITY: readonly EnterpriseMaturityEntry[] = [
+  {
+    id: 'platform-foundation',
+    tier: 'P0',
+    status: 'stable',
+    surfaces: ['AdminApp', 'ProviderBundle', 'SSR', 'Lite'],
+    acceptance: ['公共契约可类型检查', '失败状态不伪造成功', '关键路径有 SSR 和 Lite 证据'],
+  },
+  {
+    id: 'resource-operations',
+    tier: 'P0',
+    status: 'stable',
+    surfaces: ['CRUD', 'AutoTable', 'AutoForm', 'Import', 'Export'],
+    acceptance: ['资源读写、表格、表单和批量数据操作有直接行为测试'],
+  },
+  {
+    id: 'governance-and-audit',
+    tier: 'P0',
+    status: 'stable',
+    surfaces: ['Permissions', 'Tenant', 'Audit', 'Session'],
+    acceptance: ['操作按租户和权限边界执行，并保留可追踪回执'],
+  },
+  {
+    id: 'competitive-workflows',
+    tier: 'P1',
+    status: 'verified',
+    surfaces: ['AdvancedTable', 'SavedViews', 'ImportWizard', 'TaskQueue', 'Approval', 'VersionDiff', 'Dashboard', 'MultiTab'],
+    acceptance: ['跨 UI/Core/Lite 聚焦测试覆盖异步回执和错误边界'],
+  },
+  {
+    id: 'extension-modules',
+    tier: 'P2',
+    status: 'experimental',
+    surfaces: ['Kanban', 'Gantt', 'Pivot', 'Spreadsheet', 'DecisionTable', 'PDF', 'Print', 'Signature', 'Annotation', 'Media', 'Collaboration', 'OfflineSync'],
+    acceptance: ['按场景逐项完成 API、SSR/Lite、集成和线上验收后再升级状态'],
+  },
+] as const;
+
+export function enterpriseMaturityFor(
+  tier: EnterpriseMaturityTier,
+): readonly EnterpriseMaturityEntry[] {
+  return ENTERPRISE_MATURITY.filter((entry) => entry.tier === tier);
+}

package/src/export-format.ts

@@ -1,8 +1,52 @@
 // Pure export formatting helpers with no Svelte rune or browser API dependencies except downloadData.
 // These helpers can be tested directly with bun:test.
 
+import { Type, type Static } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
+
 /** Supported export and import formats. */
 export type ExportFormat = 'csv' | 'json' | 'xlsx';
+const exportTaskResultSchema = Type.Object({
+  downloadUrl: Type.String({ minLength: 1, maxLength: 4096 }),
+  format: Type.Union([Type.Literal('csv'), Type.Literal('json'), Type.Literal('xlsx')]),
+  fileName: Type.Optional(Type.String({ minLength: 1, maxLength: 200 })),
+}, { additionalProperties: false });
+export type ExportTaskResult = Static<typeof exportTaskResultSchema>;
+
+export function snapshotExportTaskResult(value: unknown): ExportTaskResult | undefined {
+  try {
+    const snapshot = snapshotPlainData(value);
+    if (!checkExact(exportTaskResultSchema, snapshot)) return undefined;
+    if (snapshot.fileName && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(snapshot.fileName)) return undefined;
+    return snapshot;
+  } catch {
+    return undefined;
+  }
+}
+
+export function safeArtifactUrl(value: string): string | undefined {
+  try {
+    const url = new URL(value, document.baseURI);
+    if (url.origin !== location.origin || !['http:', 'https:'].includes(url.protocol) ||
+        url.username || url.password) return undefined;
+    return url.href;
+  } catch {
+    return undefined;
+  }
+}
+
+export function downloadExportArtifact(result: ExportTaskResult, resource: string): void {
+  if (typeof document === 'undefined' || typeof location === 'undefined') throw new Error('Browser required');
+  const checked = snapshotExportTaskResult(result);
+  const href = checked && safeArtifactUrl(checked.downloadUrl);
+  if (!href) throw new Error('Invalid export artifact URL');
+  const anchor = document.createElement('a');
+  anchor.href = href;
+  anchor.download = checked.fileName ?? `${resource.replace(/[^A-Za-z0-9_-]/g, '_')}_export.${checked.format}`;
+  anchor.rel = 'noopener';
+  anchor.click();
+}
 
 /** Escapes a CSV field and prevents formula injection. */
 export function escapeCsvField(fieldValue: string): string {