@southwind-ai/shared 0.1.0

package/index.ts

@@ -0,0 +1,19 @@
+export * from "./src/audit.js";
+export * from "./src/database.js";
+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/migration.js";
+export * from "./src/module-configuration.js";
+export * from "./src/correlation.js";
+export * from "./src/notification.js";
+export * from "./src/password.js";
+export * from "./src/platform-settings.js";
+export * from "./src/profile.js";
+export * from "./src/primitives.js";
+export * from "./src/rbac.js";
+export * from "./src/ruoyi.js";
+export * from "./src/scheduler.js";
+export * from "./src/search-provider.js";
+export * from "./src/workflow.js";

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@southwind-ai/shared",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/audit.ts

@@ -0,0 +1,258 @@
+import type { EntityId, ISODateTime } from "./primitives.js";
+
+export interface AuditActionDefinition {
+  key: AuditActionType;
+  label: string;
+  description: string;
+}
+
+export const AUDIT_ACTION_DEFINITIONS = [
+  { key: "auth.login", label: "账号登录", description: "用户登录平台。" },
+  { key: "auth.logout", label: "账号退出", description: "用户退出平台。" },
+  {
+    key: "auth.password.update",
+    label: "密码更新",
+    description: "用户或管理员更新账号密码。",
+  },
+  {
+    key: "auth.session.revoke",
+    label: "会话撤销",
+    description: "管理员强制结束登录会话。",
+  },
+  {
+    key: "user.profile.update",
+    label: "个人资料更新",
+    description: "用户更新自己的个人资料。",
+  },
+  { key: "crud.create", label: "数据新增", description: "新增业务记录。" },
+  { key: "crud.update", label: "数据更新", description: "修改业务记录。" },
+  { key: "crud.delete", label: "数据删除", description: "删除业务记录。" },
+  { key: "crud.restore", label: "数据恢复", description: "恢复已删除记录。" },
+  { key: "data.import", label: "数据导入", description: "同步导入数据。" },
+  { key: "data.export", label: "数据导出", description: "同步导出数据。" },
+  {
+    key: "data.search",
+    label: "数据搜索",
+    description: "用户主动提交搜索条件并查询业务数据。",
+  },
+  {
+    key: "data.plaintext.read",
+    label: "敏感数据明文查看",
+    description: "单条查看经服务端授权的敏感字段明文。",
+  },
+  {
+    key: "data.plaintext.batch-read",
+    label: "敏感数据批量明文查询",
+    description: "批量查询经服务端授权且受数据范围约束的敏感字段明文。",
+  },
+  {
+    key: "data.governed-export.request",
+    label: "敏感数据导出申请",
+    description: "提交受策略、范围和可选审批约束的敏感数据导出申请。",
+  },
+  {
+    key: "data.governed-export.generate",
+    label: "敏感数据导出生成",
+    description: "后台生成带服务端水印的受治理导出文件。",
+  },
+  {
+    key: "data.governed-export.download",
+    label: "敏感数据导出下载",
+    description: "下载已完成且仍满足授权边界的受治理导出文件。",
+  },
+  {
+    key: "data.governed-export.cancel",
+    label: "敏感数据导出取消",
+    description: "取消本人尚未完成的受治理导出任务。",
+  },
+  {
+    key: "search.query",
+    label: "全局检索查询",
+    description: "提交全局检索；只记录摘要、长度和 Provider，不记录查询词。",
+  },
+  {
+    key: "search.result.access",
+    label: "检索结果访问",
+    description: "访问已脱敏的全局检索结果。",
+  },
+  {
+    key: "data.bulk-import.create",
+    label: "创建批量导入",
+    description: "创建后台批量导入任务。",
+  },
+  {
+    key: "data.bulk-export.create",
+    label: "创建批量导出",
+    description: "创建后台批量导出任务。",
+  },
+  {
+    key: "data.bulk-artifact.download",
+    label: "下载批量任务文件",
+    description: "下载批量任务结果或失败明细。",
+  },
+  {
+    key: "file.upload.create",
+    label: "创建文件上传",
+    description: "创建受控文件上传会话。",
+  },
+  {
+    key: "file.upload.complete",
+    label: "完成文件上传",
+    description: "校验并完成文件上传。",
+  },
+  {
+    key: "file.upload.abort",
+    label: "终止文件上传",
+    description: "终止上传并清理已提交分片。",
+  },
+  {
+    key: "file.download",
+    label: "文件下载",
+    description: "通过授权边界下载文件。",
+  },
+  {
+    key: "config.update",
+    label: "全局配置更新",
+    description: "更新平台全局配置。",
+  },
+  {
+    key: "config.rollback",
+    label: "配置版本回滚",
+    description: "基于历史版本创建并应用新的配置版本。",
+  },
+  {
+    key: "license.verify",
+    label: "License 校验",
+    description: "校验 License 有效性。",
+  },
+  {
+    key: "license.update",
+    label: "License 更新",
+    description: "安装或更新 License。",
+  },
+  {
+    key: "feature.update",
+    label: "功能开关更新",
+    description: "更新功能开关状态、可见性或 License 适用范围。",
+  },
+  {
+    key: "menu.structure.update",
+    label: "菜单结构更新",
+    description: "调整菜单父级、顺序或可见性。",
+  },
+  {
+    key: "notification.publish",
+    label: "通知发布",
+    description: "发布站内通知。",
+  },
+  {
+    key: "notification.read",
+    label: "通知已读",
+    description: "用户阅读站内通知。",
+  },
+  {
+    key: "notification.archive",
+    label: "通知归档",
+    description: "归档已发布通知。",
+  },
+  {
+    key: "workflow.create",
+    label: "创建审批任务",
+    description: "创建最小审批任务。",
+  },
+  {
+    key: "workflow.claim",
+    label: "领取审批任务",
+    description: "候选角色领取审批任务。",
+  },
+  {
+    key: "workflow.transfer",
+    label: "转交审批任务",
+    description: "当前领取人或管理员转交审批任务。",
+  },
+  {
+    key: "workflow.decide",
+    label: "提交审批决定",
+    description: "当前领取人批准或驳回审批任务。",
+  },
+  {
+    key: "workflow.cancel",
+    label: "取消审批任务",
+    description: "发起人或管理员取消审批任务。",
+  },
+  {
+    key: "workflow.timeout",
+    label: "审批任务超时",
+    description: "后台服务将到期审批任务置为超时。",
+  },
+  { key: "task.trigger", label: "任务触发", description: "人工触发后台任务。" },
+  { key: "task.read", label: "任务查看", description: "查看任务状态或历史。" },
+  { key: "task.execute", label: "任务执行", description: "后台任务实际执行。" },
+  { key: "task.recover", label: "任务恢复", description: "人工恢复异常任务。" },
+  {
+    key: "agent.tool.execute",
+    label: "Agent 工具执行",
+    description: "Agent 调用受控平台工具。",
+  },
+  {
+    key: "security.denied",
+    label: "安全拒绝",
+    description: "权限或安全策略拒绝请求。",
+  },
+  {
+    key: "system.error",
+    label: "系统错误",
+    description: "平台记录系统级异常。",
+  },
+] as const;
+
+export type BuiltInAuditActionType =
+  (typeof AUDIT_ACTION_DEFINITIONS)[number]["key"];
+
+/**
+ * 审计日志持久化保持字符串协议；业务动作是否有效由 Module Composition
+ * 对 AuditActionDefinition 目录进行 fail-fast 校验。
+ */
+export type AuditActionType = BuiltInAuditActionType | (string & {});
+
+export type AuditActionRegistration = AuditActionType | AuditActionDefinition;
+
+export function isAuditActionDefinition(
+  registration: AuditActionRegistration,
+): registration is AuditActionDefinition {
+  return typeof registration !== "string";
+}
+
+export type AuditOutcome = "attempted" | "success" | "failure" | "denied";
+
+export interface AuditActor {
+  id: EntityId;
+  type: "user" | "service" | "system";
+  name: string;
+  roleCodes?: string[];
+  ip?: string;
+  userAgent?: string;
+}
+
+export interface AuditTarget {
+  type: string;
+  id?: EntityId;
+  label?: string;
+}
+
+export interface AuditEvent {
+  id: EntityId;
+  action: AuditActionType;
+  outcome: AuditOutcome;
+  actor: AuditActor;
+  target?: AuditTarget;
+  module?: string;
+  requestId?: string;
+  message?: string;
+  metadata?: Record<string, unknown>;
+  occurredAt: ISODateTime;
+}
+
+export interface AuditLogWriter {
+  write(event: AuditEvent): Promise<void>;
+}

package/src/correlation.ts

@@ -0,0 +1,11 @@
+const CORRELATION_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
+
+export function correlationId(
+  value: string | null | undefined,
+  factory: () => string = () => crypto.randomUUID(),
+): string {
+  const candidate = value?.trim();
+  return candidate && CORRELATION_ID_PATTERN.test(candidate)
+    ? candidate
+    : factory();
+}

package/src/data-governance.ts

@@ -0,0 +1,89 @@
+import type { FeatureKey } from "./feature.js";
+
+export type FieldClassification =
+  | "public"
+  | "internal"
+  | "personal"
+  | "sensitive"
+  | "secret";
+
+export type FieldMaskStrategy =
+  | { kind: "redact"; replacement?: string }
+  | { kind: "partial"; prefix: number; suffix: number }
+  | { kind: "omit" };
+
+export interface GovernedFieldPolicy {
+  fieldKey: string;
+  classification: FieldClassification;
+  mask: FieldMaskStrategy;
+}
+
+export interface RoleDisplayStrategy {
+  /** 普通读取对已治理字段只能返回掩码结果。 */
+  read: "masked";
+  /** 明文仍须由 Server 有效权限签发一次性访问上下文。 */
+  reveal: "plaintext";
+  unauthorized: "hidden";
+}
+
+export interface DataGovernancePolicyDefinition {
+  key: string;
+  resourceType: string;
+  version: string;
+  featureKey: FeatureKey;
+  readPermissionKey: string;
+  revealPermissionKey: string;
+  exportPermissionKey: string;
+  display: RoleDisplayStrategy;
+  fields: GovernedFieldPolicy[];
+}
+
+export type MaskResult<T> =
+  | {
+      kind: "plaintext";
+      classification: FieldClassification;
+      value: T;
+      grantId: string;
+    }
+  | {
+      kind: "masked";
+      classification: FieldClassification;
+      display: string;
+    }
+  | {
+      kind: "hidden";
+      classification: FieldClassification;
+    };
+
+export type MaskedValue = Extract<MaskResult<never>, { kind: "masked" }>;
+
+export function maskGovernedValue(
+  value: unknown,
+  policy: GovernedFieldPolicy,
+): MaskedValue | Extract<MaskResult<never>, { kind: "hidden" }> {
+  if (policy.mask.kind === "omit") {
+    return { kind: "hidden", classification: policy.classification };
+  }
+  const text = value === undefined || value === null ? "" : String(value);
+  if (policy.mask.kind === "redact") {
+    return {
+      kind: "masked",
+      classification: policy.classification,
+      display: text ? policy.mask.replacement || "[已脱敏]" : "",
+    };
+  }
+  const prefix = Math.max(0, policy.mask.prefix);
+  const suffix = Math.max(0, policy.mask.suffix);
+  if (!text || text.length <= prefix + suffix) {
+    return {
+      kind: "masked",
+      classification: policy.classification,
+      display: text ? "*".repeat(text.length) : "",
+    };
+  }
+  return {
+    kind: "masked",
+    classification: policy.classification,
+    display: `${text.slice(0, prefix)}${"*".repeat(text.length - prefix - suffix)}${suffix ? text.slice(-suffix) : ""}`,
+  };
+}

package/src/database.ts

@@ -0,0 +1,67 @@
+import type { FieldMapping, PageRequest } from "./primitives.js";
+
+export type DatabaseDialect = "postgresql" | "mysql" | "dm" | "kingbase";
+
+export type IdentifierStrategy =
+  | "identity"
+  | "serial"
+  | "sequence"
+  | "auto-increment";
+export type JsonColumnStrategy = "jsonb" | "json" | "text";
+
+export interface DialectCapabilities {
+  dialect: DatabaseDialect;
+  identifierStrategy: IdentifierStrategy;
+  jsonColumnStrategy: JsonColumnStrategy;
+  supportsReturning: boolean;
+  supportsRecursiveCte: boolean;
+  supportsFullTextSearch: boolean;
+  reservedWords: string[];
+}
+
+export interface PaginationSqlParts {
+  limit: number;
+  offset: number;
+}
+
+export interface ColumnTypeMapping {
+  logicalType:
+    | "id"
+    | "string"
+    | "text"
+    | "integer"
+    | "boolean"
+    | "datetime"
+    | "json";
+  physicalType: string;
+}
+
+export interface DatabaseCompatibilityAdapter {
+  dialect: DatabaseDialect;
+  capabilities: DialectCapabilities;
+  mapColumnType(
+    logicalType: ColumnTypeMapping["logicalType"],
+  ): ColumnTypeMapping;
+  mapIdentifier(name: string): string;
+  mapJsonPath(column: string, path: string[]): string;
+  mapPagination(request: PageRequest): PaginationSqlParts;
+}
+
+export interface LegacyTableMapping {
+  sourceTable: string;
+  targetTable: string;
+  fields: FieldMapping[];
+}
+
+export interface MigrationStatement {
+  sql: string;
+  params?: unknown[];
+  description?: string;
+}
+
+export interface MigrationExecutionContext {
+  dialect: DatabaseDialect;
+  dryRun: boolean;
+  adapter: DatabaseCompatibilityAdapter;
+  execute(statement: MigrationStatement): Promise<void>;
+}

package/src/feature.ts

@@ -0,0 +1,104 @@
+import type { EntitlementKey, LicenseVersionKey } from "./license.js";
+
+export type FeatureVisibility = "visible" | "hidden";
+export type FeatureStage = "stable" | "beta" | "internal";
+
+declare const featureKeyBrand: unique symbol;
+
+export type FeatureKey = string & { readonly [featureKeyBrand]: "FeatureKey" };
+
+export function featureKey(value: string): FeatureKey {
+  return value as FeatureKey;
+}
+
+export interface FeatureFlagDefinition {
+  key: FeatureKey;
+  label: string;
+  module: string;
+  description?: string;
+  visible: FeatureVisibility;
+  enabled: boolean;
+  stage: FeatureStage;
+  requiredEntitlement?: EntitlementKey;
+  /** 由业务应用维护；License 签发平台不配置此映射。 */
+  allowedLicenseVersions?: LicenseVersionKey[];
+  dependencies?: FeatureKey[];
+}
+
+export function isLicenseVersionAllowed(
+  flag: FeatureFlagDefinition,
+  versionKey: LicenseVersionKey | undefined,
+): boolean {
+  return (
+    !flag.allowedLicenseVersions ||
+    Boolean(versionKey && flag.allowedLicenseVersions.includes(versionKey))
+  );
+}
+
+export interface FeatureFlagState {
+  key: FeatureKey;
+  enabled: boolean;
+  visible: FeatureVisibility;
+  entitlementGranted: boolean;
+  reason?:
+    | "disabled"
+    | "hidden"
+    | "entitlement-not-granted"
+    | "dependency-missing";
+}
+
+export function resolveFeatureState(
+  flag: FeatureFlagDefinition,
+  enabledDependencies: ReadonlySet<string>,
+  entitlementGranted: boolean,
+): FeatureFlagState {
+  if (flag.requiredEntitlement && !entitlementGranted) {
+    return {
+      key: flag.key,
+      enabled: false,
+      visible: flag.visible,
+      entitlementGranted,
+      reason: "entitlement-not-granted",
+    };
+  }
+
+  if (!flag.enabled) {
+    return {
+      key: flag.key,
+      enabled: false,
+      visible: flag.visible,
+      entitlementGranted,
+      reason: "disabled",
+    };
+  }
+
+  if (flag.visible === "hidden") {
+    return {
+      key: flag.key,
+      enabled: false,
+      visible: flag.visible,
+      entitlementGranted,
+      reason: "hidden",
+    };
+  }
+
+  const missingDependency = flag.dependencies?.some(
+    (key) => !enabledDependencies.has(key),
+  );
+  if (missingDependency) {
+    return {
+      key: flag.key,
+      enabled: false,
+      visible: flag.visible,
+      entitlementGranted,
+      reason: "dependency-missing",
+    };
+  }
+
+  return {
+    key: flag.key,
+    enabled: true,
+    visible: flag.visible,
+    entitlementGranted,
+  };
+}

package/src/license-catalog.ts

@@ -0,0 +1,33 @@
+import { licenseVersionKey, type LicenseVersionKey } from "./license.js";
+
+export interface LicenseCatalogDefinition {
+  key: LicenseVersionKey;
+  label: string;
+  description: string;
+  order: number;
+}
+
+export const LICENSE_CATALOG = [
+  {
+    key: licenseVersionKey("free-trial"),
+    label: "免费试用版",
+    description: "用于产品体验和非生产验证的基础版本。",
+    order: 10,
+  },
+  {
+    key: licenseVersionKey("standard"),
+    label: "标准版",
+    description: "面向常规企业业务场景的标准能力版本。",
+    order: 20,
+  },
+  {
+    key: licenseVersionKey("advanced"),
+    label: "高级版",
+    description: "包含高级治理、自动化和大批量处理能力。",
+    order: 30,
+  },
+] as const satisfies readonly LicenseCatalogDefinition[];
+
+export function licenseCatalogKeys(): ReadonlySet<LicenseVersionKey> {
+  return new Set(LICENSE_CATALOG.map(({ key }) => key));
+}