JX-BPOS/apps/api/src/modules/process/port.ts

/**
 * module: process —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
 */
import type { ProcessNode, ProcessPackage, StaffId, TerminalState, WorkflowState } from '@contracts';
import type { NodeInstance } from './internal/domain/owner-resolution.ts';
import type { ActivityContractFace } from './internal/domain/closure.ts';

export type Clock = { now(): Date };
export type IdGenerator = { next(): string };

/** 工作流实例的持久面 —— 崩溃后可续跑 */
export type WorkflowRecord = {
  readonly id: string;
  readonly packageId: string;
  readonly packageVersion: number;
  readonly subject: string;
  readonly state: WorkflowState;
  /** 来源:凡单必有来源(触发器 / 登记人 / 上游系统) */
  readonly source: { kind: 'periodic' | 'event' | 'registration'; ref: string; by?: string };
  readonly initiation: Record<string, unknown>;
  /**
   * 工作组绑定的**快照**(ADR-011):起单时按来源人装载,之后改组不影响这条单。
   * 留痕要能解释「当时为什么派给他」,而不是被今天的组织调整改写(同 AM 9.1 版本信封)。
   */
  readonly workGroup?: Record<string, string>;
  /**
   * 节点指派 `{ 节点id → 员工id }` —— **起单时定死某几个节点归谁**。
   * 分派仍是运营时的事:这只是在轮值之前插一句「这个节点就他了」,
   * 指的人不在岗则退回轮值(单不能没人接)。测试台用它把整条流走给指定账号。
   */
  readonly assignments?: Record<string, string>;
  /** 各节点输出口载荷 —— 边映射装配的来源 */
  readonly ports: Record<string, Record<string, unknown>>;
  readonly vars: Record<string, unknown>;
  readonly startedAt: string;
  readonly finishedAt?: string;
};

/**
 * 流程运行时 —— **执行面的可替换切面**(M5-1):按结构调度节点、条件出边选路、
 * 失败走向、审批裁决、状态聚合。自持状态机(internal/runtime/self-hosted-runtime)
 * 是默认实现;Mastra 编译产物(workflow-compiler)将是第二实现 ——
 * 八例端到端是两个实现的等价性护栏。
 * 定义生命周期(保存/激活/校验)不在此内:那决定「编译哪一份定义」,与引擎选型无关。
 */
export type FlowRuntime = {
  /** 起单后进入起点(起单前置 —— 校验/建单/留痕 —— 归 usecase,不在此内) */
  begin(record: WorkflowRecord, pkg: ProcessPackage): Promise<void>;
  onTaskTerminal(
    taskId: string,
    terminal: TerminalState,
    ports: Record<string, Record<string, unknown>>,
  ): Promise<WorkflowState | undefined>;
  applyFailure(
    workflowId: string,
    nodeId: string,
    instance: number,
    node: Extract<ProcessNode, { kind: 'activity' }>,
    terminal: TerminalState,
  ): Promise<WorkflowState>;
  onApprovalVerdict(
    workflowId: string,
    nodeId: string,
    verdict: 'pass' | 'reject',
    payload: Record<string, unknown>,
  ): Promise<WorkflowState>;
  refreshState(workflowId: string): Promise<WorkflowState>;
  terminate(workflowId: string, reason: string): Promise<WorkflowState>;
};

export type ProcessStore = {
  savePackage(pkg: ProcessPackage): Promise<void>;
  /** 就地写回一版的定义(编辑即其身)—— 撞不存在的版本报错,不静默插入 */
  updatePackageDefinition(id: string, version: number, pkg: ProcessPackage): Promise<void>;
  /** 钉在该版上的未完结工作流数 —— 在途钉版不可变的判据 */
  countPinnedInFlight(id: string, version: number): Promise<number>;
  /** 只改状态,不动定义 —— state 在列上与 definition 里各存一份,两处要一起改 */
  setPackageState(id: string, version: number, state: 'active' | 'retired'): Promise<void>;
  deletePackage(id: string, version: number): Promise<void>;
  /** 只改一版的名 —— 名字是版本自己的属性(列上与 definition 里各一份,两处一起改) */
  renameVersion(id: string, version: number, name: string): Promise<void>;
  /**
   * 改版本号 —— 号在三处:包的列上、definition 里、**跑过的单的 `packageVersion` 上**。
   * 三处一起改:号只是这一版的名牌,搬号连引用一起搬,谁也不会指空或指错。
   * 撞号与在途钉版由用例层先挡。
   */
  renumberVersion(id: string, from: number, to: number): Promise<void>;
  getPackage(id: string, version?: number): Promise<ProcessPackage | undefined>;
  listPackages(): Promise<ProcessPackage[]>;

  insertWorkflow(record: WorkflowRecord): Promise<void>;
  getWorkflow(id: string): Promise<WorkflowRecord | undefined>;
  listWorkflows(limit: number): Promise<WorkflowRecord[]>;
  updateWorkflow(id: string, patch: Partial<WorkflowRecord>): Promise<WorkflowRecord>;

  listInstances(workflowId: string): Promise<NodeInstance[]>;
  insertInstance(workflowId: string, instance: NodeInstance): Promise<void>;
  updateInstance(
    workflowId: string,
    nodeId: string,
    instance: number,
    patch: Partial<NodeInstance> & { taskId?: string },
  ): Promise<void>;
  findInstanceByTask(taskId: string): Promise<{ workflowId: string; nodeId: string; instance: number } | undefined>;

  /* ── 节点负责人(运营配置) ──────────────────────────────── */
  nodeOwners(packageId: string): Promise<Record<string, string>>;
  setNodeOwner(packageId: string, nodeId: string, staffId: string | undefined): Promise<void>;
};

/** 活动契约面 —— app 注入 `activity-registry`(L4):编排校验与起单都要它 */
export type ActivityDirectory = {
  faces(): Promise<Map<string, ActivityContractFace>>;
};

/** 岗位与在岗人员 —— app 注入 `org`(L1):负责人四策略解析的候选集 */
export type OrgDirectory = {
  positions(): Promise<Set<string>>;
  candidates(position: string): Promise<Array<{ staffId: string; name: string; openTasks: number }>>;
  /** 某人的工作组绑定(ADR-011)—— 起单时按来源人取,取不到即不装载 */
  workGroupBinding(staffId: string): Promise<Readonly<Record<string, string>> | undefined>;
  /** 在岗与否 —— 绑定的人已离岗就不硬用,退回四策略 */
  isActive(staffId: string): Promise<boolean>;
};

/** 起单与终态 —— app 注入 `task`(L6) */
export type TaskGateway = {
  start(input: {
    activityId: string;
    ownerId: StaffId;
    title: string;
    workflowId: string;
    nodeId: string;
    data: Record<string, unknown>;
    message?: string;
  }): Promise<{ id: string }>;
};

/** 审批点 —— app 注入 `human-tool`(L3):审批单卡到审批人工位 */
export type ApprovalGateway = {
  raise(input: {
    workflowId: string;
    nodeId: string;
    approverId: StaffId;
    subject: string;
    basis: ReadonlyArray<{ k: string; v: string }>;
  }): Promise<{ id: string }>;
};

/**
 * 调用接口的入参校验 —— app 注入 ajv。
 * 「凡单必有来源」的另一半是「凡单必合契约」:不合契约**不得起单**,
 * 且必须在**建工作流之前**判掉,否则会留下一条永远推不动的在途单。
 */
export type SchemaValidator = {
  validate(schema: Record<string, unknown>, value: unknown): { ok: boolean; errors: string[] };
};

/** S-FEEL —— app 注入 `@sfeel`:流转零 LLM */
export type Sfeel = {
  condition(expression: string, scope: Readonly<Record<string, unknown>>): boolean;
  expression(expression: string, scope: Readonly<Record<string, unknown>>): unknown;
};

/** 流转记入事件 —— app 注入 `event`(L1) */
export type FlowEventPublisher = {
  publish(input: { workflowId: string; kind: string; detail: Record<string, unknown> }): Promise<void>;
};

/** 终态回执 —— 登记人收消息 */
export type ReceiptNotifier = {
  notify(input: { to: StaffId; workflowId: string; subject: string; state: WorkflowState }): Promise<void>;
};

export type { TerminalState };