@southwind-ai/shared 0.1.0

package/src/rbac.ts

@@ -0,0 +1,117 @@
+import type {
+  EntityAuditFields,
+  EntityId,
+  LifecycleStatus,
+} from "./primitives.js";
+
+export type HttpMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+  | "OPTIONS";
+
+export type PermissionAction =
+  | "access"
+  | "read"
+  | "create"
+  | "update"
+  | "delete"
+  | "import"
+  | "export"
+  | "reveal"
+  | "approve"
+  | "execute"
+  | "manage";
+
+export type PermissionAccessRisk =
+  | "standard"
+  | "sensitive-disclosure"
+  | "governed-export";
+
+export type MenuNodeType = "catalog" | "menu" | "button";
+
+export type DataScope =
+  | "all"
+  | "tenant"
+  | "department"
+  | "department-and-children"
+  | "self"
+  | "custom";
+
+export type CredentialState = "active" | "must-change-password";
+
+export interface PermissionDefinition {
+  key: string;
+  label: string;
+  module: string;
+  moduleLabel: string;
+  resource: string;
+  resourceLabel: string;
+  action: PermissionAction;
+  accessRisk?: PermissionAccessRisk;
+  description?: string;
+}
+
+export interface ApiPermissionBinding {
+  method: HttpMethod;
+  path: string;
+  permissionKey: string;
+  anonymous?: boolean;
+  featureKey?: string;
+}
+
+export interface MenuNode {
+  key: string;
+  title: string;
+  type: MenuNodeType;
+  order: number;
+  visible: boolean;
+  path?: string;
+  component?: string;
+  icon?: string;
+  permissionKey?: string;
+  featureKey?: string;
+  children?: MenuNode[];
+}
+
+export interface RoleDefinition extends EntityAuditFields {
+  id: EntityId;
+  code: string;
+  name: string;
+  status: LifecycleStatus;
+  dataScope: DataScope;
+  permissionKeys: string[];
+  menuKeys: string[];
+  departmentIds?: EntityId[];
+}
+
+export interface UserAccount extends EntityAuditFields {
+  id: EntityId;
+  username: string;
+  displayName: string;
+  email?: string;
+  phone?: string;
+  status: LifecycleStatus;
+  roleIds: EntityId[];
+  departmentId?: EntityId;
+  postIds?: EntityId[];
+}
+
+export interface DepartmentNode extends EntityAuditFields {
+  id: EntityId;
+  parentId?: EntityId;
+  name: string;
+  code: string;
+  order: number;
+  status: LifecycleStatus;
+}
+
+export interface PostDefinition extends EntityAuditFields {
+  id: EntityId;
+  code: string;
+  name: string;
+  order: number;
+  status: LifecycleStatus;
+}

package/src/ruoyi.ts

@@ -0,0 +1,98 @@
+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",
+];

package/src/scheduler.ts

@@ -0,0 +1,108 @@
+import type { ISODateTime } from "./primitives.js";
+
+export type SchedulerRunTrigger = "scheduled" | "manual" | "retry";
+export type SchedulerRunStatus =
+  | "running"
+  | "succeeded"
+  | "retry-pending"
+  | "failed"
+  | "blocked";
+
+export type SchedulerObservedState =
+  | "idle"
+  | "running"
+  | "stale"
+  | "retry-pending"
+  | "succeeded"
+  | "failed"
+  | "blocked";
+
+export interface SchedulerRunSummary {
+  id: string;
+  taskKey: string;
+  trigger: SchedulerRunTrigger;
+  status: SchedulerRunStatus;
+  attempt: number;
+  requestedBy: string;
+  scheduledFor: ISODateTime;
+  startedAt: ISODateTime;
+  finishedAt?: ISODateTime;
+  nextAttemptAt?: ISODateTime;
+  errorSummary?: string;
+}
+
+export interface SchedulerRunHistoryItem extends SchedulerRunSummary {
+  taskLabel: string;
+}
+
+export interface SchedulerOperationsTask {
+  definition: {
+    source: "code-registered";
+    key: string;
+    label: string;
+    description?: string;
+    featureKey: string;
+    permissionKey: string;
+    intervalSeconds: number;
+    maxAttempts: number;
+    retryDelaySeconds: number;
+  };
+  persistence: {
+    enabled: boolean;
+    status: "active" | "archived";
+    nextRunAt: ISODateTime;
+    lastRunAt?: ISODateTime;
+  };
+  observability: {
+    state: SchedulerObservedState;
+    runningSeconds?: number;
+    stale: boolean;
+    staleThresholdSeconds: number;
+    retryPendingCount: number;
+    nextRetryAt?: ISODateTime;
+  };
+  latestRun?: SchedulerRunSummary;
+}
+
+export interface SchedulerOperationsSnapshot {
+  generatedAt: ISODateTime;
+  source: "scheduler";
+  stalePolicy: {
+    mode: "observe-only";
+    thresholdSeconds: number;
+    action: "manual-intervention";
+  };
+  summary: {
+    total: number;
+    running: number;
+    stale: number;
+    retryPending: number;
+    failed: number;
+  };
+  tasks: SchedulerOperationsTask[];
+  recentRuns: SchedulerRunSummary[];
+}
+
+export interface SchedulerManualTriggerResponse {
+  id: string;
+  taskKey: string;
+  trigger: SchedulerRunTrigger;
+  status: SchedulerRunStatus;
+  attempt: number;
+  requestedBy: string;
+  scheduledFor: ISODateTime;
+  startedAt: ISODateTime;
+  finishedAt?: ISODateTime;
+  nextAttemptAt?: ISODateTime;
+  error?: string;
+}
+
+export interface SchedulerStaleRecoveryRequest {
+  expectedStartedAt: ISODateTime;
+  reason: string;
+}
+
+export interface SchedulerStaleRecoveryResponse {
+  recoveryId: string;
+  run: SchedulerManualTriggerResponse;
+}

package/src/search-provider.ts

@@ -0,0 +1,24 @@
+export const SEARCH_PROVIDER_CONTRACT_VERSION = "1" as const;
+
+export interface SearchProviderManifestDefinition {
+  key: string;
+  kind: "search";
+  contractVersion: typeof SEARCH_PROVIDER_CONTRACT_VERSION;
+  providerVersion: string;
+  label: string;
+  enabledByDefault: boolean;
+  permissionKey: string;
+  featureKey: string;
+  deepLink: {
+    surface: "business";
+    routeTemplate: string;
+    idParameter: string;
+  };
+}
+
+/** 让业务模块在注册点得到完整的 SearchProvider Manifest 类型校验。 */
+export function defineSearchProvider(
+  definition: SearchProviderManifestDefinition,
+): SearchProviderManifestDefinition {
+  return definition;
+}

package/src/workflow.ts

@@ -0,0 +1,307 @@
+import type { ISODateTime } from "./primitives.js";
+
+export type WorkItemStatus =
+  | "pending"
+  | "claimed"
+  | "approved"
+  | "rejected"
+  | "cancelled"
+  | "timed-out";
+
+export interface CandidateRole {
+  code: string;
+  name?: string;
+}
+
+export interface Assignee {
+  id: string;
+  name: string;
+  roleCodes: string[];
+}
+
+export type DueAt = ISODateTime;
+
+export interface Reason {
+  text: string;
+}
+
+export interface Decision {
+  outcome: "approved" | "rejected";
+  reason: Reason;
+}
+
+export interface TargetRef {
+  type: string;
+  id: string;
+  /** 仅允许站内绝对路径，供通知等通用入口跳转。 */
+  route: string;
+}
+
+export interface WorkItem {
+  id: string;
+  title: string;
+  status: WorkItemStatus;
+  requesterId: string;
+  candidateRoles: CandidateRole[];
+  assignee?: Assignee;
+  dueAt: DueAt;
+  target: TargetRef;
+  createdAt: ISODateTime;
+  updatedAt: ISODateTime;
+  version: number;
+}
+
+export interface WorkflowActor {
+  id: string;
+  name: string;
+  type: "user" | "service";
+  roleCodes: string[];
+  canManage?: boolean;
+}
+
+export type WorkItemCommand =
+  | { type: "claim"; actor: WorkflowActor; at: ISODateTime }
+  | {
+      type: "transfer";
+      actor: WorkflowActor;
+      assignee: Assignee;
+      reason: Reason;
+      at: ISODateTime;
+    }
+  | { type: "approve"; actor: WorkflowActor; reason: Reason; at: ISODateTime }
+  | { type: "reject"; actor: WorkflowActor; reason: Reason; at: ISODateTime }
+  | { type: "cancel"; actor: WorkflowActor; reason: Reason; at: ISODateTime }
+  | { type: "timeout"; actor: WorkflowActor; at: ISODateTime };
+
+export interface WorkItemTransition {
+  workItem: WorkItem;
+  fact: {
+    command: WorkItemCommand["type"];
+    beforeStatus: WorkItemStatus;
+    afterStatus: WorkItemStatus;
+    actorId: string;
+    occurredAt: ISODateTime;
+    target: TargetRef;
+    decision?: Decision;
+    reason?: Reason;
+    previousAssigneeId?: string;
+    assigneeId?: string;
+  };
+}
+
+export type WorkflowInvariantCode =
+  | "INVALID_WORK_ITEM"
+  | "INVALID_REASON"
+  | "INVALID_TARGET"
+  | "INVALID_DUE_AT"
+  | "TERMINAL_WORK_ITEM"
+  | "WORK_ITEM_OVERDUE"
+  | "ROLE_NOT_CANDIDATE"
+  | "ASSIGNEE_REQUIRED"
+  | "ASSIGNEE_MISMATCH"
+  | "MANAGE_REQUIRED"
+  | "SERVICE_REQUIRED"
+  | "DUE_AT_NOT_REACHED";
+
+export class WorkflowInvariantError extends Error {
+  constructor(
+    readonly code: WorkflowInvariantCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "WorkflowInvariantError";
+  }
+}
+
+export interface CreateWorkItemInput {
+  id: string;
+  title: string;
+  requesterId: string;
+  candidateRoles: CandidateRole[];
+  dueAt: DueAt;
+  target: TargetRef;
+  createdAt: ISODateTime;
+}
+
+export function createWorkItem(input: CreateWorkItemInput): WorkItem {
+  if (!input.id.trim() || !input.title.trim() || !input.requesterId.trim()) {
+    fail("INVALID_WORK_ITEM", "审批任务标识、标题和发起人不能为空");
+  }
+  const roles = uniqueRoles(input.candidateRoles);
+  if (!roles.length) fail("INVALID_WORK_ITEM", "审批任务至少需要一个候选角色");
+  assertTarget(input.target);
+  if (dateValue(input.dueAt) <= dateValue(input.createdAt)) {
+    fail("INVALID_DUE_AT", "审批截止时间必须晚于创建时间");
+  }
+  return {
+    ...input,
+    title: input.title.trim(),
+    candidateRoles: roles,
+    status: "pending",
+    version: 1,
+    updatedAt: input.createdAt,
+  };
+}
+
+export function transitionWorkItem(
+  item: WorkItem,
+  command: WorkItemCommand,
+): WorkItemTransition {
+  assertMutable(item);
+  assertChronology(item, command.at);
+  const beforeStatus = item.status;
+  const previousAssigneeId = item.assignee?.id;
+  let status = item.status;
+  let assignee = item.assignee;
+  let decision: Decision | undefined;
+  let reason: Reason | undefined;
+
+  switch (command.type) {
+    case "claim":
+      assertPending(item);
+      assertCandidate(item, command.actor.roleCodes);
+      assignee = actorAssignee(command.actor);
+      status = "claimed";
+      break;
+    case "transfer":
+      assertClaimed(item);
+      if (item.assignee?.id !== command.actor.id && !command.actor.canManage) {
+        fail("MANAGE_REQUIRED", "仅当前领取人或管理员可以转交审批任务");
+      }
+      assertCandidate(item, command.assignee.roleCodes);
+      reason = validReason(command.reason);
+      assignee = command.assignee;
+      break;
+    case "approve":
+    case "reject":
+      assertClaimedBy(item, command.actor.id);
+      assertBeforeDue(item, command.at);
+      reason = validReason(command.reason);
+      status = command.type === "approve" ? "approved" : "rejected";
+      decision = { outcome: status, reason };
+      break;
+    case "cancel":
+      if (command.actor.id !== item.requesterId && !command.actor.canManage) {
+        fail("MANAGE_REQUIRED", "仅发起人或管理员可以取消审批任务");
+      }
+      reason = validReason(command.reason);
+      status = "cancelled";
+      break;
+    case "timeout":
+      if (command.actor.type !== "service") {
+        fail("SERVICE_REQUIRED", "仅后台服务可以执行审批超时");
+      }
+      if (dateValue(command.at) < dateValue(item.dueAt)) {
+        fail("DUE_AT_NOT_REACHED", "尚未到达审批截止时间");
+      }
+      status = "timed-out";
+      break;
+  }
+
+  const workItem = {
+    ...item,
+    status,
+    assignee,
+    updatedAt: command.at,
+    version: item.version + 1,
+  };
+  return {
+    workItem,
+    fact: {
+      command: command.type,
+      beforeStatus,
+      afterStatus: status,
+      actorId: command.actor.id,
+      occurredAt: command.at,
+      target: item.target,
+      decision,
+      reason,
+      previousAssigneeId,
+      assigneeId: assignee?.id,
+    },
+  };
+}
+
+function assertMutable(item: WorkItem) {
+  if (!["pending", "claimed"].includes(item.status)) {
+    fail("TERMINAL_WORK_ITEM", "终态审批任务不能再次变更");
+  }
+}
+
+function assertChronology(item: WorkItem, at: ISODateTime) {
+  if (dateValue(at) < dateValue(item.updatedAt)) {
+    fail("INVALID_WORK_ITEM", "命令时间不能早于审批任务最后更新时间");
+  }
+}
+
+function assertPending(item: WorkItem) {
+  if (item.status !== "pending")
+    fail("INVALID_WORK_ITEM", "仅待领取任务可以领取");
+}
+
+function assertClaimed(item: WorkItem) {
+  if (item.status !== "claimed" || !item.assignee) {
+    fail("ASSIGNEE_REQUIRED", "审批任务尚未领取");
+  }
+}
+
+function assertClaimedBy(item: WorkItem, actorId: string) {
+  assertClaimed(item);
+  if (item.assignee?.id !== actorId) {
+    fail("ASSIGNEE_MISMATCH", "仅当前领取人可以提交审批决定");
+  }
+}
+
+function assertCandidate(item: WorkItem, roleCodes: string[]) {
+  if (!item.candidateRoles.some(({ code }) => roleCodes.includes(code))) {
+    fail("ROLE_NOT_CANDIDATE", "领取人不属于候选角色");
+  }
+}
+
+function assertBeforeDue(item: WorkItem, at: ISODateTime) {
+  if (dateValue(at) >= dateValue(item.dueAt)) {
+    fail("WORK_ITEM_OVERDUE", "审批任务已到期，不能再提交决定");
+  }
+}
+
+function actorAssignee(actor: WorkflowActor): Assignee {
+  return { id: actor.id, name: actor.name, roleCodes: [...actor.roleCodes] };
+}
+
+function validReason(reason: Reason) {
+  const text = reason.text.trim();
+  if (!text || text.length > 500) {
+    fail("INVALID_REASON", "审批理由必须为 1 至 500 个字符");
+  }
+  return { text };
+}
+
+function uniqueRoles(roles: CandidateRole[]) {
+  const byCode = new Map<string, CandidateRole>();
+  for (const role of roles) {
+    const code = role.code.trim();
+    if (code) byCode.set(code, { ...role, code });
+  }
+  return [...byCode.values()];
+}
+
+function assertTarget(target: TargetRef) {
+  if (
+    !target.type.trim() ||
+    !target.id.trim() ||
+    !target.route.startsWith("/") ||
+    target.route.startsWith("//")
+  ) {
+    fail("INVALID_TARGET", "审批目标必须包含合法的站内引用");
+  }
+}
+
+function dateValue(value: ISODateTime) {
+  const result = Date.parse(value);
+  if (!Number.isFinite(result)) fail("INVALID_WORK_ITEM", "时间格式无效");
+  return result;
+}
+
+function fail(code: WorkflowInvariantCode, message: string): never {
+  throw new WorkflowInvariantError(code, message);
+}