@southwind-ai/shared 0.2.8 → 0.3.1

package/index.ts

@@ -17,13 +17,13 @@ export * from "./src/migration-bundle-validation.js";
 export * from "./src/mcp.js";
 export * from "./src/module-configuration.js";
 export * from "./src/correlation.js";
+export * from "./src/structured-log.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";
 // @windy-module system.agent begin
@@ -31,3 +31,5 @@ export * from "./src/screenshot-context-digest.js";
 // @windy-module system.agent end
 export * from "./src/stable-key.js";
 export * from "./src/workflow.js";
+
+export * from "./src/license-console-capabilities.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -15,7 +15,8 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "exports": {
-    ".": "./index.ts"
+    ".": "./index.ts",
+    "./structured-log": "./src/structured-log.ts"
   },
   "publishConfig": {
     "access": "public"

package/src/license-console-capabilities.ts

@@ -0,0 +1,163 @@
+import type { LicenseOperatorPermission } from "./license.js";
+
+/** 厂商签发中心独立认证域；不装配到客户 system.license。 */
+export const LICENSE_CONSOLE_CAPABILITIES = {
+  records: {
+    feature: "license.record",
+    permission: "license.record.read",
+    entry: "records",
+    apis: [
+      "GET /api/licenses",
+      "GET /api/licenses/:id",
+      "GET /api/licenses/:id/download",
+      "GET /api/licenses/:id/activation-code",
+      "GET /api/licenses/:id/events",
+      "GET /api/events",
+      "GET /api/customers",
+      "GET /api/customers/:id",
+      "GET /api/projects",
+      "GET /api/projects/:id",
+      "GET /api/contracts",
+      "GET /api/contracts/:id",
+      "GET /api/license-versions",
+      "GET /api/license-versions/:id",
+      "GET /api/nodes",
+      "GET /api/nodes/:id",
+      "GET /api/keys/active",
+      "GET /api/projects/:projectId/contracts",
+      "GET /api/projects/:projectId/nodes",
+      "GET /api/projects/:projectId/license-versions",
+      "GET /api/projects/:projectId/licenses",
+      "GET /api/keys",
+      "GET /api/signing/diagnostics",
+    ],
+    auditActions: ["license.downloaded"],
+  },
+  projects: {
+    feature: "license.project",
+    permission: "license.project.manage",
+    entry: "maintenance",
+    apis: [
+      "POST /api/customers",
+      "POST /api/projects",
+      "POST /api/contracts",
+      "POST /api/license-versions",
+      "POST /api/nodes",
+      "PATCH /api/customers/:id",
+      "PATCH /api/projects/:id",
+      "PATCH /api/contracts/:id",
+      "PATCH /api/license-versions/:id",
+      "PATCH /api/nodes/:id",
+      "PATCH /api/customers/:id/archive",
+      "PATCH /api/projects/:id/archive",
+      "PATCH /api/contracts/:id/archive",
+      "PATCH /api/license-versions/:id/archive",
+      "PATCH /api/nodes/:id/archive",
+    ],
+    auditActions: ["crud.create", "crud.update"],
+  },
+  issuance: {
+    feature: "license.issue",
+    permission: "license.issue",
+    entry: "project-issuance",
+    apis: [
+      "POST /api/projects/:projectId/licenses",
+      "POST /api/projects/:projectId/license-review",
+      "GET /api/projects/:projectId/issuance-requests/:key",
+      "POST /api/licenses",
+      "POST /api/licenses/:id/revocation-marks",
+      "POST /api/licenses/:id/note-corrections",
+    ],
+    auditActions: [
+      "license.issued",
+      "license.replaced",
+      "license.superseded",
+      "license.revocation-marked",
+      "license.note-corrected",
+    ],
+  },
+  keys: {
+    feature: "license.key",
+    permission: "license.key.rotate",
+    entry: "operations",
+    apis: ["POST /api/keys/rotate", "POST /api/keys/:keyId/compatibility"],
+    auditActions: ["license.key.rotated", "license.key.compatibility-declared"],
+  },
+  operators: {
+    feature: "license.operator",
+    permission: "license.operator.manage",
+    entry: "administration",
+    apis: [
+      "GET /api/operators",
+      "POST /api/operators",
+      "PATCH /api/operators/:id",
+    ],
+    auditActions: ["license.operator.created", "license.operator.updated"],
+  },
+  sessions: {
+    feature: "license.session",
+    permission: "license.session.revoke",
+    entry: "administration",
+    apis: ["POST /api/auth/sessions/:id/revoke"],
+    auditActions: ["auth.session.revoke"],
+  },
+  audit: {
+    feature: "license.audit",
+    permission: "license.audit.read",
+    entry: "administration",
+    apis: ["GET /api/audit-logs"],
+    auditActions: [],
+  },
+} as const satisfies Record<
+  string,
+  {
+    feature: string;
+    permission: LicenseOperatorPermission;
+    entry: string;
+    apis: readonly string[];
+    auditActions: readonly string[];
+  }
+>;
+
+export interface LicenseConsoleCapability {
+  feature: string;
+  permission: LicenseOperatorPermission;
+  entry: string;
+  apis: readonly string[];
+  auditActions: readonly string[];
+}
+export function validateLicenseConsoleCapabilities(
+  items: readonly LicenseConsoleCapability[] = Object.values(
+    LICENSE_CONSOLE_CAPABILITIES,
+  ),
+): void {
+  const features = new Set<string>();
+  const permissions = new Set<string>();
+  const apis = new Set<string>();
+  for (const item of items) {
+    if (features.has(item.feature) || permissions.has(item.permission))
+      throw new Error("签发中心能力声明重复");
+    if (
+      item.permission !== item.feature &&
+      !item.permission.startsWith(`${item.feature}.`)
+    )
+      throw new Error("签发中心权限基础 Key 不匹配");
+    features.add(item.feature);
+    permissions.add(item.permission);
+    for (const api of item.apis) {
+      if (apis.has(api)) throw new Error("签发中心 API 声明重复");
+      apis.add(api);
+    }
+  }
+}
+
+export function hasLicenseConsolePermission(
+  permissions: readonly string[],
+  permission: string,
+): boolean {
+  return (
+    Object.values(LICENSE_CONSOLE_CAPABILITIES).some(
+      (item) => item.permission === permission,
+    ) && permissions.includes(permission)
+  );
+}

package/src/license-console.ts

@@ -0,0 +1,94 @@
+import type {
+  LicenseContractVersion,
+  LicenseCustomer,
+  LicenseIssueRecord,
+  LicenseNode,
+  LicenseProject,
+  LicenseReplacement,
+  LicenseV1Claims,
+  LicenseVersion,
+} from "./license.js";
+
+export interface LicenseIssueSummary {
+  id: string;
+  customerId: string;
+  projectId: string;
+  contractVersionId: string;
+  nodeId: string;
+  operatorId: string;
+  claims: LicenseV1Claims;
+  targetSoftwareVersion?: string;
+  predecessor?: LicenseReplacement;
+  successor?: LicenseReplacement;
+  revocationMarked: boolean;
+}
+export interface LicenseConsoleCollections {
+  customers: LicenseCustomer;
+  projects: LicenseProject;
+  contracts: LicenseContractVersion;
+  nodes: LicenseNode;
+  "license-versions": LicenseVersion;
+  licenses: LicenseIssueSummary;
+}
+export interface LicenseListQuery {
+  page: number;
+  pageSize: number;
+  q?: string;
+  customerId?: string;
+  projectId?: string;
+  status?: string;
+  contractVersionId?: string;
+  nodeId?: string;
+  machineCode?: string;
+  licenseVersionKey?: string;
+  issuedFrom?: string;
+  issuedTo?: string;
+  expiresFrom?: string;
+  expiresTo?: string;
+  expiresWithinDays?: 7 | 30 | 60;
+}
+export interface LicensePage<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+export interface LicenseNewNode {
+  code: string;
+  name: string;
+  purpose?: string;
+  machineCode: string;
+}
+export interface LicenseReviewCommand {
+  contractVersionId: string;
+  nodeId?: string;
+  newNode?: LicenseNewNode;
+  expiresAt: string;
+  softwareVersion: string;
+  replacementOfLicenseId?: string;
+  replacementReason?: string;
+}
+export interface LicenseReviewConfirmation {
+  customer: LicenseCustomer;
+  project: LicenseProject;
+  contract: LicenseContractVersion;
+  licenseVersion: LicenseVersion;
+  node: LicenseNewNode;
+  keyId: string;
+  expiresAt: string;
+  softwareVersion: string;
+  replacementOfLicenseId?: string;
+  replacementReason?: string;
+}
+export interface LicenseReviewResult {
+  reviewDigest: string;
+  confirmation: LicenseReviewConfirmation;
+  blockingReasons: string[];
+}
+export interface LicenseRequestStatus {
+  status: "processing" | "failed" | "completed";
+  licenseId: string;
+  result?: LicenseIssueRecord;
+  error?: { code: string; reason: string };
+  retryAfterSeconds?: number;
+}

package/src/license.ts

@@ -1,6 +1,7 @@
 import type { EntityId, ISODateTime } from "./primitives.js";
 
 export * from "./license-legacy.js";
+export * from "./license-console.js";
 
 declare const entitlementKeyBrand: unique symbol;
 declare const licenseVersionKeyBrand: unique symbol;
@@ -132,6 +133,8 @@ export interface LicenseProject {
 }
 
 export interface LicenseContractVersion {
+  predecessorId?: EntityId;
+  issuedCount?: number;
   id: EntityId;
   projectId: EntityId;
   contractNumber: string;
@@ -147,6 +150,7 @@ export interface LicenseContractVersion {
 }
 
 export interface LicenseNode {
+  issuedCount?: number;
   id: EntityId;
   projectId: EntityId;
   code: string;
@@ -200,6 +204,7 @@ export type LicenseOperatorRole =
 
 export type LicenseOperatorPermission =
   | "license.record.read"
+  | "license.audit.read"
   | "license.issue"
   | "license.project.manage"
   | "license.key.rotate"

package/src/structured-log.ts

@@ -0,0 +1,215 @@
+/** 运行日志只承载排障线索；业务审计和 Agent Run 事实使用各自的持久化入口。 */
+export const STRUCTURED_LOG_MAX_BYTES = 2048;
+
+export type StructuredLogLevel = "info" | "warn" | "error";
+export type StructuredLogOutcome = "success" | "failure" | "denied";
+
+export interface StructuredLogInput {
+  event: string;
+  requestId?: string;
+  runId?: string;
+  jobId?: string;
+  traceId?: string;
+  diagnosticId?: string;
+  outcome?: StructuredLogOutcome;
+  errorCode?: string;
+  stageKey?: string;
+  handlerKey?: string;
+  queue?: string;
+  attemptNumber?: number;
+  method?: string;
+  /** 只接受框架登记的路由模板，不能传请求 URL 或实际对象路径。 */
+  route?: string;
+  statusCode?: number;
+  durationMs?: number;
+  actorType?: string;
+  authority?: string;
+  port?: number;
+  created?: number;
+  metadataUpdated?: number;
+  archived?: number;
+  unchanged?: number;
+  queued?: number;
+  dropped?: number;
+  completedUnits?: number;
+  totalUnits?: number;
+  count?: number;
+  /** 兼容现有 Logger 接口；未知字段在序列化时一律丢弃。 */
+  [key: string]: unknown;
+}
+
+export interface StructuredLogSink {
+  info(record: Record<string, unknown>): void;
+  warn(record: Record<string, unknown>): void;
+  error(record: Record<string, unknown>): void;
+}
+
+export interface StructuredLogger {
+  info(input: StructuredLogInput, message?: string): void;
+  warn(input: StructuredLogInput, message?: string): void;
+  error(input: StructuredLogInput, message?: string): void;
+}
+
+const stableKey = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const correlationKey = /^[A-Za-z0-9._-]{1,128}$/;
+const errorKey = /^[A-Z][A-Z0-9_]{0,95}$/;
+const methodKey = /^[A-Z]{1,12}$/;
+const routeTemplate =
+  /^\/(?:[A-Za-z][A-Za-z0-9_-]*|:[A-Za-z][A-Za-z0-9_]*|\*)(?:\/(?:[A-Za-z][A-Za-z0-9_-]*|:[A-Za-z][A-Za-z0-9_]*|\*))*$/;
+
+/** Adapter 可接 Pino、stdout 或测试 Sink；自由文本 message 不进入日志。 */
+export function createStructuredLogger(
+  sink: StructuredLogSink,
+  component: string,
+  now: () => Date = () => new Date(),
+): StructuredLogger {
+  if (!stableKey.test(component) || component.length > 64) {
+    throw new Error("运行日志 component 必须是有界稳定 Key");
+  }
+  const emit = (level: StructuredLogLevel, input: StructuredLogInput) => {
+    const record = structuredLogRecord(level, component, input, now());
+    try {
+      sink[level](record);
+    } catch {
+      // 排障日志是旁路输出；审计和业务结果由各自的可靠存储决定。
+    }
+  };
+  return {
+    info: (input) => emit("info", input),
+    warn: (input) => emit("warn", input),
+    error: (input) => emit("error", input),
+  };
+}
+
+export function structuredLogRecord(
+  level: StructuredLogLevel,
+  component: string,
+  input: StructuredLogInput,
+  at: Date,
+): Record<string, unknown> {
+  const record: Record<string, unknown> = {
+    timestamp: at.toISOString(),
+    level,
+    component,
+    event:
+      stableKey.test(input.event) && input.event.length <= 96
+        ? input.event
+        : "logging.event.invalid",
+    retentionClass: "operational",
+  };
+  for (const key of [
+    "requestId",
+    "runId",
+    "jobId",
+    "traceId",
+    "diagnosticId",
+  ] as const) {
+    const value = input[key];
+    if (typeof value === "string" && correlationKey.test(value)) {
+      record[key] = value;
+    }
+  }
+  if (
+    input.outcome === "success" ||
+    input.outcome === "failure" ||
+    input.outcome === "denied"
+  )
+    record.outcome = input.outcome;
+  if (typeof input.errorCode === "string" && errorKey.test(input.errorCode)) {
+    record.errorCode = input.errorCode;
+  }
+  for (const key of [
+    "stageKey",
+    "handlerKey",
+    "queue",
+    "actorType",
+    "authority",
+  ] as const) {
+    const value = input[key];
+    if (
+      typeof value === "string" &&
+      value.length <= 64 &&
+      stableKey.test(value)
+    ) {
+      record[key] = value;
+    }
+  }
+  if (typeof input.method === "string" && methodKey.test(input.method)) {
+    record.method = input.method;
+  }
+  if (
+    typeof input.route === "string" &&
+    input.route.length <= 160 &&
+    (input.route === "/" || routeTemplate.test(input.route))
+  )
+    record.route = input.route;
+  if (validNumber(input.statusCode, 100, 599, true))
+    record.statusCode = input.statusCode;
+  if (validNumber(input.durationMs, 0, 3_600_000))
+    record.durationMs = input.durationMs;
+  if (validNumber(input.port, 1, 65535, true)) record.port = input.port;
+  if (validNumber(input.attemptNumber, 1, 1_000_000_000, true))
+    record.attemptNumber = input.attemptNumber;
+  for (const key of [
+    "created",
+    "metadataUpdated",
+    "archived",
+    "unchanged",
+    "queued",
+    "dropped",
+    "completedUnits",
+    "totalUnits",
+    "count",
+  ] as const) {
+    const value = input[key];
+    if (validNumber(value, 0, 1_000_000_000, true)) record[key] = value;
+  }
+  for (const key of [
+    "dropped",
+    "completedUnits",
+    "totalUnits",
+    "count",
+    "route",
+    "queued",
+    "unchanged",
+    "archived",
+    "metadataUpdated",
+    "created",
+    "port",
+    "attemptNumber",
+    "queue",
+    "handlerKey",
+    "authority",
+    "actorType",
+    "stageKey",
+    "diagnosticId",
+    "traceId",
+    "jobId",
+    "runId",
+    "requestId",
+  ] as const) {
+    if (
+      new TextEncoder().encode(JSON.stringify(record)).length <=
+      STRUCTURED_LOG_MAX_BYTES
+    )
+      break;
+    delete record[key];
+    record.truncated = true;
+  }
+  return record;
+}
+
+function validNumber(
+  value: unknown,
+  min: number,
+  max: number,
+  integer = false,
+): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isFinite(value) &&
+    value >= min &&
+    value <= max &&
+    (!integer || Number.isInteger(value))
+  );
+}

package/src/ruoyi.ts

@@ -1,98 +0,0 @@
-import type { AuditEvent, AuditLogWriter } from "./audit.js";
-import type { LegacyTableMapping } from "./database.js";
-import type { EntityId, ISODateTime } from "./primitives.js";
-import type {
-  MenuNode,
-  PermissionDefinition,
-  RoleDefinition,
-  UserAccount,
-} from "./rbac.js";
-
-export type RuoYiCoreTable =
-  | "sys_user"
-  | "sys_role"
-  | "sys_user_role"
-  | "sys_dept"
-  | "sys_post"
-  | "sys_user_post"
-  | "sys_menu"
-  | "sys_role_menu"
-  | "sys_role_dept"
-  | "sys_dict_type"
-  | "sys_dict_data"
-  | "sys_config"
-  | "sys_notice"
-  | "sys_logininfor"
-  | "sys_oper_log"
-  | "sys_job"
-  | "sys_job_log";
-
-export interface RuoYiConnectionConfig {
-  mysqlDsn: string;
-  redisDsn?: string;
-  readonly: boolean;
-}
-
-export interface RuoYiMigrationPlan {
-  id: EntityId;
-  createdAt: ISODateTime;
-  tables: RuoYiCoreTable[];
-  dryRun: boolean;
-  resetPasswords: boolean;
-}
-
-export interface RuoYiMigrationReport {
-  planId: EntityId;
-  startedAt: ISODateTime;
-  finishedAt?: ISODateTime;
-  importedRows: Record<RuoYiCoreTable, number>;
-  failedRows: Record<RuoYiCoreTable, number>;
-  warnings: string[];
-  auditEvents: AuditEvent[];
-}
-
-export interface RuoYiPermissionSnapshot {
-  user: UserAccount;
-  roles: RoleDefinition[];
-  menus: MenuNode[];
-  permissions: PermissionDefinition[];
-}
-
-export interface RuoYiImportAdapter {
-  dryRun(plan: RuoYiMigrationPlan): Promise<RuoYiMigrationReport>;
-  import(
-    plan: RuoYiMigrationPlan,
-    audit: AuditLogWriter,
-  ): Promise<RuoYiMigrationReport>;
-}
-
-export interface RuoYiLegacyRuntimeAdapter {
-  connect(config: RuoYiConnectionConfig): Promise<void>;
-  disconnect(): Promise<void>;
-  readPermissionSnapshot(userId: EntityId): Promise<RuoYiPermissionSnapshot>;
-}
-
-export interface RuoYiReportAdapter {
-  compareUserPermissions(userId: EntityId): Promise<RuoYiMigrationReport>;
-  tableMappings(): LegacyTableMapping[];
-}
-
-export const ruoyiCoreTables: RuoYiCoreTable[] = [
-  "sys_user",
-  "sys_role",
-  "sys_user_role",
-  "sys_dept",
-  "sys_post",
-  "sys_user_post",
-  "sys_menu",
-  "sys_role_menu",
-  "sys_role_dept",
-  "sys_dict_type",
-  "sys_dict_data",
-  "sys_config",
-  "sys_notice",
-  "sys_logininfor",
-  "sys_oper_log",
-  "sys_job",
-  "sys_job_log",
-];