@southwind-ai/shared 0.1.0 → 0.1.2

package/index.ts

@@ -5,6 +5,7 @@ export * from "./src/feature.js";
 export * from "./src/license.js";
 export * from "./src/license-catalog.js";
 export * from "./src/migration.js";
+export * from "./src/migration-bundle-validation.js";
 export * from "./src/module-configuration.js";
 export * from "./src/correlation.js";
 export * from "./src/notification.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/src/license-catalog.ts

@@ -7,6 +7,8 @@ export interface LicenseCatalogDefinition {
   order: number;
 }
 
+const licenseCatalogFields = new Set(["key", "label", "description", "order"]);
+
 export const LICENSE_CATALOG = [
   {
     key: licenseVersionKey("free-trial"),
@@ -31,3 +33,96 @@ export const LICENSE_CATALOG = [
 export function licenseCatalogKeys(): ReadonlySet<LicenseVersionKey> {
   return new Set(LICENSE_CATALOG.map(({ key }) => key));
 }
+
+/** 校验宿主配置的 License 版本目录：Key 与 order 均唯一，目录非空。 */
+export function validateLicenseCatalog(
+  definitions: readonly LicenseCatalogDefinition[],
+): void {
+  if (definitions.length === 0) {
+    throw new Error("License 版本目录不能为空");
+  }
+  const keys = new Set<string>();
+  const orders = new Set<number>();
+  for (const definition of definitions) {
+    if (!definition.key.trim() || !definition.label.trim()) {
+      throw new Error("License 版本目录的 Key 与名称不能为空");
+    }
+    if (!Number.isSafeInteger(definition.order)) {
+      throw new Error(`License 版本 ${definition.key} 的 order 必须是安全整数`);
+    }
+    if (keys.has(definition.key)) {
+      throw new Error(`License 版本目录 Key 重复：${definition.key}`);
+    }
+    if (orders.has(definition.order)) {
+      throw new Error(
+        `License 版本目录 order 重复：${definition.order}（${definition.key}）`,
+      );
+    }
+    keys.add(definition.key);
+    orders.add(definition.order);
+  }
+}
+
+/** 从未知输入解析并归一化宿主 License 版本目录。 */
+export function parseLicenseCatalog(
+  input: unknown,
+): LicenseCatalogDefinition[] {
+  if (!Array.isArray(input)) {
+    throw new Error("License 版本目录必须是数组");
+  }
+  const catalog = input.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`License 版本目录第 ${index + 1} 项必须是对象`);
+    }
+    const record = entry as Record<string, unknown>;
+    const unknownField = Object.keys(record).find(
+      (key) => !licenseCatalogFields.has(key),
+    );
+    if (unknownField) {
+      throw new Error(`License 版本目录包含未知字段：${unknownField}`);
+    }
+    if (
+      typeof record.key !== "string" ||
+      typeof record.label !== "string" ||
+      (record.description !== undefined &&
+        typeof record.description !== "string") ||
+      typeof record.order !== "number"
+    ) {
+      throw new Error(`License 版本目录第 ${index + 1} 项字段类型无效`);
+    }
+    return {
+      key: licenseVersionKey(record.key.trim()),
+      label: record.label.trim(),
+      description: record.description?.trim() ?? "",
+      order: record.order,
+    };
+  });
+  validateLicenseCatalog(catalog);
+  return catalog;
+}
+
+/** 解析环境变量 JSON，错误消息不包含原始配置内容。 */
+export function parseLicenseCatalogJson(
+  raw: string,
+  source = "License 版本目录",
+): LicenseCatalogDefinition[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${source} 必须是合法 JSON 数组`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${source} 必须是合法 JSON 数组`);
+  }
+  return parseLicenseCatalog(parsed);
+}
+
+/** 有宿主配置时校验并返回，未配置时回退平台默认三级目录。 */
+export function resolveLicenseCatalog(
+  configured?: readonly LicenseCatalogDefinition[],
+): readonly LicenseCatalogDefinition[] {
+  if (!configured) return LICENSE_CATALOG;
+  validateLicenseCatalog(configured);
+  return configured;
+}

package/src/migration-bundle-validation.ts

@@ -0,0 +1,219 @@
+import {
+  MIGRATION_BUNDLE_FORMAT_VERSION,
+  type BundleMigrationDefinition,
+  type MigrationBundle,
+  type MigrationDefinition,
+  type MigrationManifestSource,
+} from "./migration.js";
+
+export function normalizeManifestBundles(
+  modules: readonly MigrationManifestSource[],
+): MigrationBundle[] {
+  return modules.map((manifest) => {
+    const bundle =
+      manifest.migrationBundle ||
+      legacyManifestBundle(manifest, manifest.migrations);
+    if (bundle.module !== manifest.name) {
+      throw new Error(
+        `Migration Bundle ${bundle.module} 与 Manifest ${manifest.name} 不一致`,
+      );
+    }
+    if (bundle.version !== manifest.version) {
+      throw new Error(
+        `Migration Bundle ${bundle.module} 版本 ${bundle.version} 与 Manifest ${manifest.version} 不一致`,
+      );
+    }
+    assertSameDependencies(manifest, bundle);
+    assertSameMigrations(manifest, bundle);
+    assertSchemaMigrationReferences(manifest, bundle);
+    return bundle;
+  });
+}
+
+function assertSameDependencies(
+  manifest: MigrationManifestSource,
+  bundle: MigrationBundle,
+): void {
+  const declared = manifest.dependencies || [];
+  const bundled = bundle.dependencies || [];
+  if (
+    declared.length !== bundled.length ||
+    declared.some((dependency) => !bundled.includes(dependency))
+  ) {
+    throw new Error(
+      `Manifest ${manifest.name} 的 dependencies 必须与 Migration Bundle 一致`,
+    );
+  }
+}
+
+function legacyManifestBundle(
+  manifest: MigrationManifestSource,
+  migrations: readonly MigrationDefinition[],
+): MigrationBundle {
+  return {
+    formatVersion: MIGRATION_BUNDLE_FORMAT_VERSION,
+    module: manifest.name,
+    version: manifest.version,
+    dependencies: manifest.dependencies,
+    migrations: migrations.map((migration) => ({
+      ...migration,
+      checksum:
+        migration.checksum ||
+        `legacy:${manifest.name}:${manifest.version}:${migration.id}`,
+    })),
+  };
+}
+
+function assertSameMigrations(
+  manifest: MigrationManifestSource,
+  bundle: MigrationBundle,
+): void {
+  const declared = manifest.migrations.map(({ id }) => id);
+  const bundled = bundle.migrations.map(({ id }) => id);
+  if (
+    declared.length !== bundled.length ||
+    declared.some((id, index) => id !== bundled[index])
+  ) {
+    throw new Error(
+      `Manifest ${manifest.name} 的 migrations 必须与 Migration Bundle 完全一致`,
+    );
+  }
+}
+
+function assertSchemaMigrationReferences(
+  manifest: MigrationManifestSource,
+  bundle: MigrationBundle,
+): void {
+  const ids = new Set(bundle.migrations.map(({ id }) => id));
+  for (const schema of manifest.schemaExports || []) {
+    for (const migrationId of schema.migrationIds) {
+      if (!ids.has(migrationId)) {
+        throw new Error(
+          `Schema Export ${schema.key} 引用了 Bundle 中不存在的 Migration：${migrationId}`,
+        );
+      }
+    }
+  }
+}
+
+export function validateAndOrderBundles(
+  bundles: readonly MigrationBundle[],
+): MigrationBundle[] {
+  const byModule = new Map<string, MigrationBundle>();
+  const migrationOwner = new Map<string, string>();
+  for (const bundle of bundles) {
+    validateBundle(bundle);
+    if (byModule.has(bundle.module)) {
+      throw new Error(`Migration Bundle 模块重复：${bundle.module}`);
+    }
+    byModule.set(bundle.module, bundle);
+    for (const migration of bundle.migrations) {
+      const owner = migrationOwner.get(migration.id);
+      if (owner) {
+        throw new Error(
+          `Migration ID 重复：${migration.id}（${owner} / ${bundle.module}）`,
+        );
+      }
+      migrationOwner.set(migration.id, bundle.module);
+    }
+  }
+  for (const bundle of bundles) {
+    for (const dependency of bundle.dependencies || []) {
+      if (!byModule.has(dependency)) {
+        throw new Error(
+          `Migration Bundle ${bundle.module} 依赖未安装模块：${dependency}`,
+        );
+      }
+    }
+    validateMigrationDependencies(bundle, migrationOwner);
+    orderBundleMigrations(bundle);
+  }
+  return topologicalBundles(byModule);
+}
+
+function validateBundle(bundle: MigrationBundle): void {
+  if (bundle.formatVersion !== MIGRATION_BUNDLE_FORMAT_VERSION) {
+    throw new Error(
+      `Migration Bundle ${bundle.module} 格式版本不受支持：${bundle.formatVersion}`,
+    );
+  }
+  if (!bundle.module.trim()) throw new Error("Migration Bundle 缺少 module");
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(bundle.version)) {
+    throw new Error(
+      `Migration Bundle ${bundle.module} 版本无效：${bundle.version}`,
+    );
+  }
+  for (const migration of bundle.migrations) {
+    if (migration.module !== bundle.module) {
+      throw new Error(
+        `Migration ${migration.id} 的模块归属应为 ${bundle.module}`,
+      );
+    }
+    if (!migration.id.trim()) throw new Error("Migration ID 不能为空");
+    if (!migration.checksum.trim()) {
+      throw new Error(`Migration ${migration.id} 缺少 checksum`);
+    }
+  }
+}
+
+function validateMigrationDependencies(
+  bundle: MigrationBundle,
+  owners: ReadonlyMap<string, string>,
+): void {
+  for (const migration of bundle.migrations) {
+    for (const dependency of migration.dependsOn || []) {
+      const owner = owners.get(dependency);
+      if (!owner) {
+        throw new Error(`Migration ${migration.id} 依赖不存在：${dependency}`);
+      }
+      if (
+        owner !== bundle.module &&
+        !(bundle.dependencies || []).includes(owner)
+      ) {
+        throw new Error(
+          `Migration ${migration.id} 跨模块依赖 ${owner}，但 Bundle 未声明该模块依赖`,
+        );
+      }
+    }
+  }
+}
+
+function topologicalBundles(
+  pendingSource: ReadonlyMap<string, MigrationBundle>,
+): MigrationBundle[] {
+  const pending = new Map(pendingSource);
+  const sorted: MigrationBundle[] = [];
+  while (pending.size > 0) {
+    const ready = Array.from(pending.values()).find((bundle) =>
+      (bundle.dependencies || []).every(
+        (dependency) => !pending.has(dependency),
+      ),
+    );
+    if (!ready) throw new Error("Migration Bundle 模块依赖存在循环");
+    sorted.push(ready);
+    pending.delete(ready.module);
+  }
+  return sorted;
+}
+
+export function orderBundleMigrations(
+  bundle: MigrationBundle,
+): BundleMigrationDefinition[] {
+  const pending = new Map(
+    bundle.migrations.map((migration) => [migration.id, migration]),
+  );
+  const sorted: BundleMigrationDefinition[] = [];
+  while (pending.size > 0) {
+    const ready = Array.from(pending.values()).find((migration) =>
+      (migration.dependsOn || []).every(
+        (dependency) => !pending.has(dependency),
+      ),
+    );
+    if (!ready) {
+      throw new Error(`Migration Bundle ${bundle.module} 的迁移依赖存在循环`);
+    }
+    sorted.push(ready);
+    pending.delete(ready.id);
+  }
+  return sorted;
+}

package/src/platform-settings.ts

@@ -3,3 +3,16 @@ export interface PlatformBrandingSettings {
   logoUrl?: string;
   description?: string;
 }
+
+export interface PlatformWatermarkPolicy {
+  enabled: boolean;
+  businessPagesEnabled: boolean;
+  customContent: string;
+}
+
+export const DEFAULT_PLATFORM_WATERMARK_POLICY: Readonly<PlatformWatermarkPolicy> =
+  {
+    enabled: true,
+    businessPagesEnabled: false,
+    customContent: "",
+  };