@southwind-ai/shared 0.1.1 → 0.2.0

package/index.ts

@@ -4,7 +4,9 @@ export * from "./src/data-governance.js";
 export * from "./src/feature.js";
 export * from "./src/license.js";
 export * from "./src/license-catalog.js";
+export * from "./src/json.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.1",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/src/audit.ts

@@ -145,11 +145,36 @@ export const AUDIT_ACTION_DEFINITIONS = [
     label: "通知发布",
     description: "发布站内通知。",
   },
+  {
+    key: "notification.schedule",
+    label: "通知定时发布",
+    description: "创建等待调度器发布的通知。",
+  },
+  {
+    key: "notification.preference.update",
+    label: "通知偏好更新",
+    description: "用户更新外部通知渠道和分类偏好。",
+  },
+  {
+    key: "notification.update",
+    label: "通知修改",
+    description: "修改已发布通知并保留版本历史。",
+  },
   {
     key: "notification.read",
     label: "通知已读",
     description: "用户阅读站内通知。",
   },
+  {
+    key: "notification.favorite",
+    label: "收藏通知",
+    description: "用户收藏可见的站内通知。",
+  },
+  {
+    key: "notification.unfavorite",
+    label: "取消收藏通知",
+    description: "用户取消收藏可见的站内通知。",
+  },
   {
     key: "notification.archive",
     label: "通知归档",

package/src/json.ts

@@ -0,0 +1,8 @@
+export type JsonPrimitive = string | number | boolean | null;
+
+export type JsonValue =
+  | JsonPrimitive
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type JsonObject = { [key: string]: JsonValue };

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/module-configuration.ts

@@ -5,8 +5,11 @@ export type ModuleConfigApplyStatus =
   | "applying"
   | "effective"
   | "failed"
+  | "pending-restart"
   | "superseded";
 
+export type ModuleConfigApplyMode = "live" | "restart";
+
 export interface ModuleConfigDiffEntry {
   path: string;
   before?: ModuleConfigValue;
@@ -18,6 +21,7 @@ export interface ModuleConfigFieldDescriptor {
   label: string;
   description: string;
   input: "boolean" | "integer" | "text";
+  applyMode?: ModuleConfigApplyMode;
   minimum?: number;
   maximum?: number;
 }
@@ -42,6 +46,7 @@ export interface ModuleConfigSummary {
   label: string;
   fields: ModuleConfigFieldDescriptor[];
   effectiveValues: ModuleConfigValues;
+  pendingValues?: ModuleConfigValues;
   effectiveSource: "environment" | "version";
   effectiveVersion?: number;
   latestVersion?: number;

package/src/notification.ts

@@ -1,7 +1,14 @@
 import type { ISODateTime } from "./primitives.js";
 import type { TargetRef } from "./workflow.js";
 
-export type NotificationStatus = "published" | "archived";
+export type NotificationStatus = "scheduled" | "published" | "archived";
+export type ExternalNotificationChannel = "email" | "sms";
+export type NotificationDeliveryStatus =
+  | "pending"
+  | "processing"
+  | "retrying"
+  | "delivered"
+  | "dead";
 
 export interface PlatformNotification {
   id: string;
@@ -11,6 +18,7 @@ export interface PlatformNotification {
   category: string;
   status: NotificationStatus;
   publishedAt: ISODateTime;
+  scheduledFor?: ISODateTime;
   createdAt: ISODateTime;
   createdBy: string;
   updatedAt: ISODateTime;
@@ -19,13 +27,29 @@ export interface PlatformNotification {
   archivedBy?: string;
   target?: TargetRef;
   recipientUserId?: string;
+  recipientUserIds?: string[];
   recipientRoleCodes?: string[];
+  recipientDepartmentIds?: string[];
+  includeChildDepartments?: boolean;
+  deliveryChannels?: ExternalNotificationChannel[];
   sourceKey?: string;
+  revision: number;
 }
 
 export interface NotificationInboxItem extends PlatformNotification {
   read: boolean;
   readAt?: ISODateTime;
+  favorite: boolean;
+  favoritedAt?: ISODateTime;
+}
+
+export type NotificationReadFilter = "read" | "unread";
+
+export interface NotificationInboxFilters {
+  q?: string;
+  category?: string;
+  read?: NotificationReadFilter;
+  favorite?: boolean;
 }
 
 export interface PublishNotificationInput {
@@ -35,12 +59,79 @@ export interface PublishNotificationInput {
   category: string;
   target?: TargetRef;
   recipientUserId?: string;
+  recipientUserIds?: string[];
   recipientRoleCodes?: string[];
+  recipientDepartmentIds?: string[];
+  includeChildDepartments?: boolean;
+  deliveryChannels?: ExternalNotificationChannel[];
+  scheduledFor?: ISODateTime;
   sourceKey?: string;
 }
 
+export interface NotificationPreference {
+  userId: string;
+  enabledChannels: ExternalNotificationChannel[];
+  disabledCategories: string[];
+  updatedAt?: ISODateTime;
+}
+
+export type UpdateNotificationPreferenceInput = Pick<
+  NotificationPreference,
+  "enabledChannels" | "disabledCategories"
+>;
+
+export interface NotificationAudienceOption {
+  id: string;
+  label: string;
+  code?: string;
+}
+
+export interface NotificationAudienceOptions {
+  users: NotificationAudienceOption[];
+  roles: NotificationAudienceOption[];
+  departments: NotificationAudienceOption[];
+}
+
+export interface NotificationDelivery {
+  id: string;
+  notificationId: string;
+  userId: string;
+  channel: ExternalNotificationChannel;
+  status: NotificationDeliveryStatus;
+  attemptCount: number;
+  nextAttemptAt: ISODateTime;
+  deliveredAt?: ISODateTime;
+  lastErrorCode?: string;
+  createdAt: ISODateTime;
+  updatedAt: ISODateTime;
+}
+
+export type UpdateNotificationInput = Pick<
+  PublishNotificationInput,
+  "title" | "summary" | "content" | "category"
+>;
+
+export interface NotificationRevision extends UpdateNotificationInput {
+  notificationId: string;
+  revision: number;
+  editedAt: ISODateTime;
+  editedBy: string;
+}
+
+export interface UpdateNotificationResult {
+  notification: PlatformNotification;
+  changed: boolean;
+}
+
 export interface MarkNotificationReadResult {
   success: true;
   alreadyRead: boolean;
   readAt: ISODateTime;
 }
+
+export interface SetNotificationFavoriteResult {
+  success: true;
+  favorite: boolean;
+  changed: boolean;
+  favoritedAt?: ISODateTime;
+}

package/src/password.ts

@@ -1,4 +1,9 @@
-export const PASSWORD_POLICY = {
+export interface PasswordPolicy {
+  minLength: number;
+  maxLength: number;
+}
+
+export const PASSWORD_POLICY: Readonly<PasswordPolicy> = {
   minLength: 12,
   maxLength: 128,
-} as const;
+};

package/src/platform-settings.ts

@@ -2,4 +2,35 @@ export interface PlatformBrandingSettings {
   softwareName: string;
   logoUrl?: string;
   description?: string;
+  /** Runtime display timezone. It is managed by platform.runtime, not branding storage. */
+  timeZone?: string;
 }
+
+export const WATERMARK_DENSITIES = ["low", "medium", "high"] as const;
+export type WatermarkDensity = (typeof WATERMARK_DENSITIES)[number];
+
+export const WATERMARK_CONTENT_FIELDS = [
+  "username",
+  "displayName",
+  "phone",
+  "email",
+  "custom",
+] as const;
+export type WatermarkContentField = (typeof WATERMARK_CONTENT_FIELDS)[number];
+
+export interface PlatformWatermarkPolicy {
+  enabled: boolean;
+  businessPagesEnabled: boolean;
+  density: WatermarkDensity;
+  contentFields: WatermarkContentField[];
+  customContent: string;
+}
+
+export const DEFAULT_PLATFORM_WATERMARK_POLICY: Readonly<PlatformWatermarkPolicy> =
+  {
+    enabled: true,
+    businessPagesEnabled: true,
+    density: "medium",
+    contentFields: ["username", "displayName"],
+    customContent: "",
+  };