create-windy 0.1.0

package/template/packages/shared/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/template/packages/shared/src/feature.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { entitlementKey } from "./license.js";
+import type { FeatureFlagDefinition } from "./feature.js";
+import { featureKey, resolveFeatureState } from "./feature.js";
+
+const baseFlag: FeatureFlagDefinition = {
+  key: featureKey("system.report"),
+  label: "报表中心",
+  module: "system",
+  visible: "visible",
+  enabled: true,
+  stage: "stable",
+};
+
+describe("resolveFeatureState", () => {
+  test("启用且可见的功能默认可用", () => {
+    const state = resolveFeatureState(baseFlag, new Set(), true);
+
+    expect(state).toEqual({
+      key: "system.report",
+      enabled: true,
+      visible: "visible",
+      entitlementGranted: true,
+    });
+  });
+
+  test("关闭、隐藏、缺少 Entitlement 和缺少依赖时返回明确原因", () => {
+    expect(
+      resolveFeatureState({ ...baseFlag, enabled: false }, new Set(), true)
+        .reason,
+    ).toBe("disabled");
+    expect(
+      resolveFeatureState({ ...baseFlag, visible: "hidden" }, new Set(), true)
+        .reason,
+    ).toBe("hidden");
+    expect(
+      resolveFeatureState(
+        {
+          ...baseFlag,
+          requiredEntitlement: entitlementKey("capability.report"),
+        },
+        new Set(),
+        false,
+      ).reason,
+    ).toBe("entitlement-not-granted");
+    expect(
+      resolveFeatureState(
+        { ...baseFlag, dependencies: [featureKey("system.audit")] },
+        new Set(),
+        true,
+      ).reason,
+    ).toBe("dependency-missing");
+  });
+});

package/template/packages/shared/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/template/packages/shared/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/template/packages/shared/src/license.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import type { FeatureKey } from "./feature.js";
+import {
+  licenseVersionKey,
+  type EntitlementKey,
+  type LicenseV1Claims,
+  type SignedLicenseV1,
+} from "./license.js";
+
+type IsAssignable<From, To> = [From] extends [To] ? true : false;
+type ForbiddenV1Fields = Extract<
+  keyof LicenseV1Claims,
+  "notBefore" | "limits" | "modules" | "maxUsers" | "maxTenants" | "maxRecords"
+>;
+
+const entitlementIsNotFeatureKey: IsAssignable<EntitlementKey, FeatureKey> =
+  false;
+const v1HasNoLegacyFields: ForbiddenV1Fields extends never ? true : false =
+  true;
+
+const license: SignedLicenseV1 = {
+  formatVersion: 1,
+  algorithm: "ED25519",
+  publicKeyId: "key_2026_01",
+  signature: "base64-signature",
+  claims: {
+    licenseId: "license_1",
+    productCode: "windy-platform",
+    customer: { id: "customer_1", code: "C001", name: "示例客户" },
+    project: { id: "project_1", code: "P001", name: "生产系统" },
+    contract: {
+      id: "contract_1",
+      contractNumber: "HT-2026-001",
+      version: "1",
+    },
+    machineCode: "machine_1",
+    issuedAt: "2026-07-10T00:00:00.000Z",
+    expiresAt: "2027-07-10T00:00:00.000Z",
+    licenseVersion: {
+      key: licenseVersionKey("advanced"),
+      name: "高级付费版",
+    },
+  },
+};
+
+describe("License V1 contract", () => {
+  test("固定格式版本并要求正式引用和到期时间", () => {
+    expect(license.formatVersion).toBe(1);
+    expect(license.claims.customer.code).toBe("C001");
+    expect(license.claims.project.code).toBe("P001");
+    expect(license.claims.contract.contractNumber).toBe("HT-2026-001");
+    expect(license.claims.expiresAt).toBe("2027-07-10T00:00:00.000Z");
+  });
+
+  test("V1 只携带 License 版本标记且无原型容量字段", () => {
+    expect(entitlementIsNotFeatureKey).toBe(false);
+    expect(v1HasNoLegacyFields).toBe(true);
+    expect(license.claims.licenseVersion).toEqual({
+      key: "advanced",
+      name: "高级付费版",
+    });
+  });
+});

package/template/packages/shared/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;
+}