JX-BPOS/api-report/apps/api/src/modules/process/contract.d.ts

/**
 * module: process —— 对外类型(编码规范 §10.1;语义出处 OS 03)。
 *
 * 流程层:流程包定义与版本、**边映射闭合校验**、工作流实例
 * (网关 / 审批点 / 失败走向 / 负责人四策略 / 聚合)。
 *
 * M5 进行中:domain 已落(闭合校验 / 四策略解析 / 状态聚合),
 * 用例与 Mastra 工作流编译随后(编码规范 §6.1)。
 */
import type { ClosureReport, ClosureViolation, OwnerSpec, ProcessNode, ProcessPackage, TerminalState, WorkflowState } from '@contracts';
import type { ActivityContractFace, ClosureInput } from './internal/domain/closure.ts';
import type { Candidate, NodeInstance, ResolveContext, Resolution } from './internal/domain/owner-resolution.ts';
import type { AssembleScope, Dispatch, RejectRoute } from './internal/domain/routing.ts';
import type { WorkflowRecord } from './port.ts';
export type { ActivityContractFace, AssembleScope, Candidate, ClosureInput, Dispatch, RejectRoute, WorkflowRecord, ClosureReport, ClosureViolation, NodeInstance, OwnerSpec, ProcessPackage, ProcessNode, ResolveContext, Resolution, TerminalState, WorkflowState, };
/** 起单入参 —— 触发器与上游系统一律经**调用接口**调起(OS 03) */
export type StartWorkflowInput = {
    readonly packageId: string;
    readonly packageVersion?: number;
    readonly subject: string;
    /** 凡单必有来源:触发器即来源;纪要登记起单的,登记人即来源 */
    readonly source: {
        kind: 'periodic' | 'event' | 'registration';
        ref: string;
        by?: string;
    };
    readonly data: Record<string, unknown>;
};
export type ProcessService = {
    /**
     * 保存 —— **不检查、不生效**:恒存为新版本号(服务端算,不采信入参的 version),
     * 状态为未生效。画图的中间态天然不完整,保存不设闸;完整性闸在 `setPackageState` 激活时。
     */
    savePackage(pkg: ProcessPackage): Promise<ProcessPackage>;
    listPackages(): Promise<ProcessPackage[]>;
    getPackage(id: string, version?: number): Promise<ProcessPackage | undefined>;
    /**
     * 版本启停 —— 运行时开关,**不改定义一个字**。
     * 激活先过闭合校验(不闭合抛 `NotClosedError`),过了即独占:同流其余版本一并停用;
     * 停用生效版:整条流下线,新起单被拒。在途按启动时钉住的版本跑完,启停零影响。
     */
    setPackageState(id: string, version: number, state: 'active' | 'retired'): Promise<ProcessPackage[]>;
    /** 画图即校验 —— 与前端画布同源;只算不存 */
    validate(pkg: ProcessPackage): Promise<ClosureReport>;
    start(input: StartWorkflowInput): Promise<WorkflowRecord>;
    getWorkflow(id: string): Promise<WorkflowRecord>;
    listWorkflows(limit?: number): Promise<WorkflowRecord[]>;
    instancesOf(workflowId: string): Promise<NodeInstance[]>;
    /** 任务终态到达:完成即继续流转;非完成即走声明的失败走向 */
    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 declare class CallInterfaceViolationError extends Error {
    readonly packageId: string;
    readonly errors: readonly string[];
    constructor(packageId: string, errors: readonly string[]);
}
/** 不闭合不得**激活** —— 画图与保存不拦(中间态天然不完整),上线这一步拦 */
export declare class NotClosedError extends Error {
    readonly report: ClosureReport;
    constructor(report: ClosureReport);
}
export declare class PositionVacantError extends Error {
    readonly position: string;
    constructor(position: string);
}