@southwind-ai/shared 0.1.0

package/src/license-legacy.ts

@@ -0,0 +1,153 @@
+import type { EntityId, ISODateTime } from "./primitives.js";
+
+/** 仅供迁移前原型签发服务和 JSON.stringify 验签链路使用。 */
+export type LegacyPrototypeLicenseEdition =
+  | "community"
+  | "standard"
+  | "professional"
+  | "enterprise";
+export type LegacyPrototypeLicenseStatus =
+  | "valid"
+  | "invalid"
+  | "expired"
+  | "clock-rollback";
+
+export interface LegacyPrototypeMachineFingerprint {
+  machineCode: string;
+  hostname?: string;
+  os?: string;
+  arch?: string;
+  cpuSerial?: string;
+  diskSerial?: string;
+}
+
+export interface LegacyPrototypeLicenseLimits {
+  maxUsers: number;
+  maxTenants?: number;
+  expiresAt?: ISODateTime;
+}
+
+export interface LegacyPrototypeModuleGrant {
+  module: string;
+  enabled: boolean;
+  expiresAt?: ISODateTime;
+  maxRecords?: number;
+}
+
+export interface LegacyPrototypeLicenseClaims {
+  licenseId: EntityId;
+  subject: string;
+  edition: LegacyPrototypeLicenseEdition;
+  issuedAt: ISODateTime;
+  expiresAt?: ISODateTime;
+  machineCode: string;
+  limits: LegacyPrototypeLicenseLimits;
+  modules: LegacyPrototypeModuleGrant[];
+}
+
+export interface LegacyPrototypeSignedLicense {
+  claims: LegacyPrototypeLicenseClaims;
+  signature: string;
+  publicKeyId: string;
+  algorithm: "ED25519";
+}
+
+export type LegacyPrototypeLicenseFailureReason =
+  | "invalid-signature"
+  | "expired"
+  | "machine-mismatch"
+  | "clock-rollback"
+  | "module-not-granted"
+  | "user-limit-exceeded";
+
+export interface LegacyPrototypeLicenseVerificationResult {
+  valid: boolean;
+  claims?: LegacyPrototypeLicenseClaims;
+  failures: LegacyPrototypeLicenseFailureReason[];
+}
+
+export interface LegacyPrototypeLicenseKeyPair {
+  keyId: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+  createdAt: ISODateTime;
+  rotatedFromKeyId?: string;
+}
+
+export interface LegacyPrototypeLicenseIssueRequest {
+  projectId?: EntityId;
+  subject: string;
+  edition: LegacyPrototypeLicenseEdition;
+  machineCode: string;
+  modules: LegacyPrototypeModuleGrant[];
+  limits: LegacyPrototypeLicenseLimits;
+  expiresAt?: ISODateTime;
+}
+
+export interface LegacyPrototypeLicenseIssueResult {
+  license: LegacyPrototypeSignedLicense;
+  issuedAt: ISODateTime;
+}
+
+export type LegacyPrototypeLicenseOperatorPermission =
+  | "license.issue"
+  | "license.project.manage"
+  | "license.record.read"
+  | "license.key.rotate"
+  | "license.operator.manage";
+
+export interface LegacyPrototypeLicenseOperator {
+  id: EntityId;
+  username: string;
+  displayName: string;
+  tokenHash: string;
+  permissions: LegacyPrototypeLicenseOperatorPermission[];
+  status: "active" | "disabled";
+  createdAt: ISODateTime;
+  lastUsedAt?: ISODateTime;
+}
+
+export interface LegacyPrototypeLicenseOperatorCreateResult {
+  operator: LegacyPrototypeLicenseOperator;
+  token: string;
+}
+
+export interface LegacyPrototypeLicenseProject {
+  id: EntityId;
+  code: string;
+  name: string;
+  customerName: string;
+  contactName?: string;
+  notes?: string;
+  status: "active" | "archived";
+  createdAt: ISODateTime;
+  updatedAt: ISODateTime;
+}
+
+export interface LegacyPrototypeLicenseIssueRecord {
+  id: EntityId;
+  projectId: EntityId;
+  operatorId: EntityId;
+  subject: string;
+  machineCode: string;
+  edition: LegacyPrototypeLicenseEdition;
+  publicKeyId: string;
+  licenseId: EntityId;
+  issuedAt: ISODateTime;
+  expiresAt?: ISODateTime;
+  modules: LegacyPrototypeModuleGrant[];
+  limits: LegacyPrototypeLicenseLimits;
+  license: LegacyPrototypeSignedLicense;
+  status: "issued" | "revoked" | "superseded";
+  revokedAt?: ISODateTime;
+  revokedBy?: EntityId;
+  revokeReason?: string;
+}
+
+export interface LegacyPrototypeLicenseUsageRecord {
+  machineCode: string;
+  openedAt: ISODateTime;
+  previousOpenedAt?: ISODateTime;
+  status: LegacyPrototypeLicenseStatus;
+  reason?: LegacyPrototypeLicenseFailureReason;
+}

package/src/license.ts

@@ -0,0 +1,267 @@
+import type { EntityId, ISODateTime } from "./primitives.js";
+
+export * from "./license-legacy.js";
+
+declare const entitlementKeyBrand: unique symbol;
+declare const licenseVersionKeyBrand: unique symbol;
+
+/** @deprecated 业务应用的新功能授权请改用 LicenseVersionKey。 */
+export type EntitlementKey = string & {
+  readonly [entitlementKeyBrand]: "EntitlementKey";
+};
+export type LicenseAlgorithm = "ED25519";
+export type LicenseVersionKey = string & {
+  readonly [licenseVersionKeyBrand]: "LicenseVersionKey";
+};
+export type LicenseFormatVersion = 1;
+export type LicenseLifecycleStatus = "active" | "archived";
+
+export function licenseVersionKey(value: string): LicenseVersionKey {
+  return value as LicenseVersionKey;
+}
+
+/** @deprecated 仅供尚未迁移的业务配置读取。 */
+export function entitlementKey(value: string): EntitlementKey {
+  return value as EntitlementKey;
+}
+
+export interface LicenseCustomerReference {
+  id: EntityId;
+  code: string;
+  name: string;
+}
+
+export interface LicenseProjectReference {
+  id: EntityId;
+  code: string;
+  name: string;
+}
+
+export interface LicenseContractReference {
+  id: EntityId;
+  contractNumber: string;
+  version: string;
+}
+
+export interface LicenseVersionReference {
+  key: LicenseVersionKey;
+  name: string;
+}
+
+export interface LicenseV1Claims {
+  licenseId: EntityId;
+  productCode: string;
+  customer: LicenseCustomerReference;
+  project: LicenseProjectReference;
+  contract: LicenseContractReference;
+  machineCode: string;
+  issuedAt: ISODateTime;
+  expiresAt: ISODateTime;
+  licenseVersion: LicenseVersionReference;
+}
+
+export interface SignedLicenseV1 {
+  formatVersion: 1;
+  claims: LicenseV1Claims;
+  signature: string;
+  publicKeyId: string;
+  algorithm: LicenseAlgorithm;
+}
+
+export type LicenseClaims = LicenseV1Claims;
+export type SignedLicense = SignedLicenseV1;
+
+export type LicenseStatus = "valid" | "invalid" | "expired" | "clock-rollback";
+export type LicenseFailureReason =
+  | "invalid-format"
+  | "unsupported-format"
+  | "invalid-signature"
+  | "unknown-public-key"
+  | "expired"
+  | "product-mismatch"
+  | "machine-mismatch"
+  | "clock-rollback"
+  | "license-version-not-allowed";
+
+export interface LicenseVerificationResult {
+  valid: boolean;
+  claims?: LicenseClaims;
+  failures: LicenseFailureReason[];
+}
+
+export interface LicenseVersion {
+  id: EntityId;
+  projectId: EntityId;
+  key: LicenseVersionKey;
+  name: string;
+  description?: string;
+  status: LicenseLifecycleStatus;
+  createdAt: ISODateTime;
+  createdBy: EntityId;
+  updatedAt: ISODateTime;
+  updatedBy: EntityId;
+  archivedAt?: ISODateTime;
+  archivedBy?: EntityId;
+}
+
+export interface LicenseCustomer {
+  id: EntityId;
+  code: string;
+  name: string;
+  status: LicenseLifecycleStatus;
+  createdAt: ISODateTime;
+  createdBy: EntityId;
+  updatedAt: ISODateTime;
+  updatedBy: EntityId;
+  archivedAt?: ISODateTime;
+  archivedBy?: EntityId;
+}
+
+export interface LicenseProject {
+  id: EntityId;
+  customerId: EntityId;
+  code: string;
+  name: string;
+  status: LicenseLifecycleStatus;
+  createdAt: ISODateTime;
+  createdBy: EntityId;
+  updatedAt: ISODateTime;
+  updatedBy: EntityId;
+  archivedAt?: ISODateTime;
+  archivedBy?: EntityId;
+}
+
+export interface LicenseContractVersion {
+  id: EntityId;
+  projectId: EntityId;
+  contractNumber: string;
+  version: string;
+  licenseVersionId: EntityId;
+  status: LicenseLifecycleStatus;
+  createdAt: ISODateTime;
+  createdBy: EntityId;
+  updatedAt: ISODateTime;
+  updatedBy: EntityId;
+  archivedAt?: ISODateTime;
+  archivedBy?: EntityId;
+}
+
+export interface LicenseNode {
+  id: EntityId;
+  projectId: EntityId;
+  code: string;
+  name: string;
+  purpose?: string;
+  machineCode: string;
+  status: LicenseLifecycleStatus;
+  createdAt: ISODateTime;
+  createdBy: EntityId;
+  updatedAt: ISODateTime;
+  updatedBy: EntityId;
+  archivedAt?: ISODateTime;
+  archivedBy?: EntityId;
+}
+
+export interface LicenseIssueRequest {
+  productCode: string;
+  customerId: EntityId;
+  projectId: EntityId;
+  contractVersionId: EntityId;
+  nodeId: EntityId;
+  machineCode: string;
+  expiresAt: ISODateTime;
+  softwareVersion: string;
+  replacementOfLicenseId?: EntityId;
+}
+
+export interface LicenseIssueResult {
+  license: SignedLicenseV1;
+  issuedAt: ISODateTime;
+}
+
+export interface LicenseIssueRecord {
+  id: EntityId;
+  customerId: EntityId;
+  projectId: EntityId;
+  contractVersionId: EntityId;
+  nodeId: EntityId;
+  operatorId: EntityId;
+  license: SignedLicense;
+  signedPayload: string;
+  payloadDigest: string;
+  targetSoftwareVersion?: string;
+}
+
+export type LicenseOperatorRole =
+  | "readonly"
+  | "issuer"
+  | "super-admin"
+  | "developer";
+
+export type LicenseOperatorPermission =
+  | "license.record.read"
+  | "license.issue"
+  | "license.project.manage"
+  | "license.key.rotate"
+  | "license.operator.manage"
+  | "license.session.revoke";
+
+export interface LicenseOperator {
+  id: EntityId;
+  username: string;
+  displayName: string;
+  role: LicenseOperatorRole;
+  status: "active" | "disabled";
+  createdAt: ISODateTime;
+  lastLoginAt?: ISODateTime;
+}
+
+export interface LicenseOperatorSession {
+  id: EntityId;
+  operatorId: EntityId;
+  status: "active" | "revoked";
+  issuedAt: ISODateTime;
+  expiresAt: ISODateTime;
+  revokedAt?: ISODateTime;
+  lastSeenAt?: ISODateTime;
+}
+
+export interface LicenseReplacement {
+  id: EntityId;
+  replacedLicenseId: EntityId;
+  replacementLicenseId: EntityId;
+  reason?: string;
+  createdAt: ISODateTime;
+  createdBy: EntityId;
+}
+
+export type LicenseEventType =
+  | "license.issued"
+  | "license.downloaded"
+  | "license.replaced"
+  | "license.revocation-marked"
+  | "license.note-corrected";
+
+export type LicenseGovernanceEventType =
+  | LicenseEventType
+  | "license.superseded"
+  | "license.key.rotated"
+  | "license.operator.created"
+  | "license.operator.updated";
+
+export interface LicenseEvent {
+  id: EntityId;
+  licenseId: EntityId;
+  type: LicenseEventType;
+  actorId: EntityId;
+  occurredAt: ISODateTime;
+  payload: Record<string, unknown>;
+}
+
+export interface LicenseUsageRecord {
+  machineCode: string;
+  openedAt: ISODateTime;
+  previousOpenedAt?: ISODateTime;
+  status: LicenseStatus;
+  reason?: LicenseFailureReason;
+}

package/src/migration.ts

@@ -0,0 +1,39 @@
+import type { MigrationExecutionContext } from "./database.js";
+
+export const MIGRATION_BUNDLE_FORMAT_VERSION = "1" as const;
+
+export type MigrationDirection = "up" | "down";
+
+export interface MigrationDefinition {
+  id: string;
+  module: string;
+  description: string;
+  direction: MigrationDirection;
+  checksum?: string;
+  dependsOn?: readonly string[];
+  run(context: MigrationExecutionContext): Promise<void>;
+}
+
+export interface BundleMigrationDefinition extends MigrationDefinition {
+  checksum: string;
+}
+
+export interface MigrationBundle {
+  formatVersion: typeof MIGRATION_BUNDLE_FORMAT_VERSION;
+  module: string;
+  version: string;
+  dependencies?: readonly string[];
+  migrations: readonly BundleMigrationDefinition[];
+}
+
+export interface MigrationManifestSource {
+  name: string;
+  version: string;
+  dependencies?: readonly string[];
+  migrations: readonly MigrationDefinition[];
+  schemaExports?: readonly {
+    key: string;
+    migrationIds: readonly string[];
+  }[];
+  migrationBundle?: MigrationBundle;
+}

package/src/module-configuration.ts

@@ -0,0 +1,50 @@
+export type ModuleConfigValue = string | number | boolean | null;
+export type ModuleConfigValues = Record<string, ModuleConfigValue>;
+
+export type ModuleConfigApplyStatus =
+  | "applying"
+  | "effective"
+  | "failed"
+  | "superseded";
+
+export interface ModuleConfigDiffEntry {
+  path: string;
+  before?: ModuleConfigValue;
+  after?: ModuleConfigValue;
+}
+
+export interface ModuleConfigFieldDescriptor {
+  path: string;
+  label: string;
+  description: string;
+  input: "boolean" | "integer" | "text";
+  minimum?: number;
+  maximum?: number;
+}
+
+export interface ModuleConfigVersion {
+  id: string;
+  moduleKey: string;
+  version: number;
+  values: ModuleConfigValues;
+  diff: ModuleConfigDiffEntry[];
+  applyStatus: ModuleConfigApplyStatus;
+  applyError?: string;
+  rollbackOfVersion?: number;
+  reason?: string;
+  createdAt: string;
+  createdBy: string;
+  appliedAt?: string;
+}
+
+export interface ModuleConfigSummary {
+  moduleKey: string;
+  label: string;
+  fields: ModuleConfigFieldDescriptor[];
+  effectiveValues: ModuleConfigValues;
+  effectiveSource: "environment" | "version";
+  effectiveVersion?: number;
+  latestVersion?: number;
+  latestStatus?: ModuleConfigApplyStatus;
+  latestApplyError?: string;
+}

package/src/notification.ts

@@ -0,0 +1,46 @@
+import type { ISODateTime } from "./primitives.js";
+import type { TargetRef } from "./workflow.js";
+
+export type NotificationStatus = "published" | "archived";
+
+export interface PlatformNotification {
+  id: string;
+  title: string;
+  summary: string;
+  content: string;
+  category: string;
+  status: NotificationStatus;
+  publishedAt: ISODateTime;
+  createdAt: ISODateTime;
+  createdBy: string;
+  updatedAt: ISODateTime;
+  updatedBy: string;
+  archivedAt?: ISODateTime;
+  archivedBy?: string;
+  target?: TargetRef;
+  recipientUserId?: string;
+  recipientRoleCodes?: string[];
+  sourceKey?: string;
+}
+
+export interface NotificationInboxItem extends PlatformNotification {
+  read: boolean;
+  readAt?: ISODateTime;
+}
+
+export interface PublishNotificationInput {
+  title: string;
+  summary: string;
+  content: string;
+  category: string;
+  target?: TargetRef;
+  recipientUserId?: string;
+  recipientRoleCodes?: string[];
+  sourceKey?: string;
+}
+
+export interface MarkNotificationReadResult {
+  success: true;
+  alreadyRead: boolean;
+  readAt: ISODateTime;
+}

package/src/password.ts

@@ -0,0 +1,4 @@
+export const PASSWORD_POLICY = {
+  minLength: 12,
+  maxLength: 128,
+} as const;

package/src/platform-settings.ts

@@ -0,0 +1,5 @@
+export interface PlatformBrandingSettings {
+  softwareName: string;
+  logoUrl?: string;
+  description?: string;
+}

package/src/primitives.ts

@@ -0,0 +1,47 @@
+export type EntityId = string;
+export type ISODateTime = string;
+
+export type LifecycleStatus = "draft" | "active" | "disabled" | "archived";
+
+export interface EntityAuditFields {
+  createdAt: ISODateTime;
+  createdBy: EntityId;
+  updatedAt: ISODateTime;
+  updatedBy: EntityId;
+  deletedAt?: ISODateTime;
+  deletedBy?: EntityId;
+}
+
+export type SortOrder = "asc" | "desc";
+
+export const DEFAULT_PAGE_SIZE = 10;
+export const MAX_PAGE_SIZE = 100;
+
+export interface SortRule {
+  field: string;
+  order: SortOrder;
+}
+
+export interface PageRequest {
+  page: number;
+  pageSize: number;
+  sort?: SortRule[];
+}
+
+export interface PageResult<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+
+export interface FieldMapping {
+  source: string;
+  target: string;
+  transform?: string;
+  required?: boolean;
+}
+
+export function assertUnreachable(value: never): never {
+  throw new Error(`Unhandled value reached: ${String(value)}`);
+}

package/src/profile.ts

@@ -0,0 +1,13 @@
+export interface UserProfile {
+  id: string;
+  username: string;
+  displayName: string;
+  email?: string;
+  phone?: string;
+}
+
+export interface UserProfileUpdate {
+  displayName: string;
+  email?: string;
+  phone?: string;
+}