@mldong/jeeflow 1.6.1 → 1.6.3

package/dist/engine.js

@@ -124,16 +124,9 @@ export class EngineImpl {
                     return (await this.repo.findInstanceById(inst.id));
             }
             for (const node of followEdges(flow, curNode.id)) {
-                if (node.type === TypeEnd) {
-                    // 聚合根：流程完成
-                    inst.finish(new Date());
-                    inst.variables = vars;
-                    await this.repo.updateInstance(inst);
-                    await this.fireEvent({ type: EventType.ProcessFinish, instanceId: inst.id, operator });
-                }
-                else {
-                    await this.executeNode(flow, inst, node, operator, vars);
-                }
+                // 统一走 executeNode：结束节点也经节点执行链（拦截器/事件完整触发），
+                // executeNode 内部 TypeEnd 分支完成聚合根 finish + 事件发布
+                await this.executeNode(flow, inst, node, operator, vars);
             }
         }
         return (await this.repo.findInstanceById(inst.id));

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { HandlerRegistry, type IAssignmentHandler, type IDecisionHandler, type H
 export { enumDict, enumDictKeys, type DictItem } from './metadata.js';
 export * from './model.js';
 export type { ProcessRepository, UserProvider, OrgUserProvider, IDGenerator, ExpressionEvaluator } from './spi.js';
+export { SqliteDynamicTableWriter, PersistPostInterceptor, type DynamicTableWriter, type DefineLoader, } from './persist.js';
 export { registerBuiltinAssignments, OperatorAssignmentHandler, FormFieldAssigneeHandler, DeptLeaderAssignmentHandler, DeptMainLeaderAssignmentHandler, ApplicantDeptLeaderAssignmentHandler, ApplicantDeptMainLeaderAssignmentHandler, TaskRoleAssigneeHandler, HANDLER_OPERATOR_ASSIGNMENT, HANDLER_FORM_FIELD_ASSIGNEE, HANDLER_DEPT_LEADER, HANDLER_DEPT_MAIN_LEADER, HANDLER_APPLICANT_DEPT_LEADER, HANDLER_APPLICANT_DEPT_MAIN_LEADER, HANDLER_TASK_ROLE_ASSIGNEE, } from './builtin.js';

package/dist/index.js

@@ -3,4 +3,5 @@ export { MemoryRepository } from './memory.js';
 export { HandlerRegistry } from './registry.js';
 export { enumDict, enumDictKeys } from './metadata.js';
 export * from './model.js';
+export { SqliteDynamicTableWriter, PersistPostInterceptor, } from './persist.js';
 export { registerBuiltinAssignments, OperatorAssignmentHandler, FormFieldAssigneeHandler, DeptLeaderAssignmentHandler, DeptMainLeaderAssignmentHandler, ApplicantDeptLeaderAssignmentHandler, ApplicantDeptMainLeaderAssignmentHandler, TaskRoleAssigneeHandler, HANDLER_OPERATOR_ASSIGNMENT, HANDLER_FORM_FIELD_ASSIGNEE, HANDLER_DEPT_LEADER, HANDLER_DEPT_MAIN_LEADER, HANDLER_APPLICANT_DEPT_LEADER, HANDLER_APPLICANT_DEPT_MAIN_LEADER, HANDLER_TASK_ROLE_ASSIGNEE, } from './builtin.js';

package/dist/persist.d.ts

@@ -0,0 +1,72 @@
+import { DatabaseSync } from 'node:sqlite';
+import { type ProcessInstance, type ProcessDefine, type FlowNode } from './model.js';
+import type { FlowInterceptor } from './extensions.js';
+/**
+ * 动态表写入组件接口——引擎无关，四语言契约一致（Java/Go/Python/Node）
+ *
+ * 用法：给「表名 + 字段 Map」安全写入任意业务表（列过滤 / 参数化 INSERT /
+ * 幂等 / 系统字段）。不依赖工作流引擎。
+ */
+export interface DynamicTableWriter {
+    /** 按目标表过滤列（表结构探测），返回表内实际存在的列 */
+    filterColumns(tableName: string, columns: string[]): string[] | Promise<string[]>;
+    /** 参数化 INSERT（按列过滤结果落库），返回生成主键 */
+    insert(tableName: string, data: Record<string, unknown>): unknown | Promise<unknown>;
+    /** 幂等检查：指定业务键（如 process_instance_id）是否已存在 */
+    exists(tableName: string, bizKey: string, bizKeyValue: unknown): boolean | Promise<boolean>;
+    /** 按配置列名填充系统字段（未配置的列跳过） */
+    fillSystemFields(data: Record<string, unknown>, isInsert: boolean): void;
+}
+/**
+ * 动态表写入器默认实现（node:sqlite DatabaseSync）。
+ *
+ * 注意：node:sqlite 是实验特性（Node 22.5+，无需外部依赖）。
+ * MySQL/PG 集成方可自行实现 DynamicTableWriter 接口（契约见上）。
+ */
+export declare class SqliteDynamicTableWriter implements DynamicTableWriter {
+    private db;
+    private cache;
+    /** 系统字段列名（null/undefined 禁用） */
+    createTimeColumn?: string | null;
+    createUserColumn?: string | null;
+    updateTimeColumn?: string | null;
+    updateUserColumn?: string | null;
+    isDeletedColumn?: string | null;
+    /** 用户列默认值（issues/19）：优先取 data 中已注入的 apply_user_id=流程 operator，
+     *  否则用此配置值，缺省 "system"——多数框架业务表 create_user/update_user 为 BIGINT 存 userId */
+    defaultUserValue: unknown;
+    constructor(db: DatabaseSync);
+    private tableColumns;
+    filterColumns(tableName: string, columns: string[]): string[];
+    insert(tableName: string, data: Record<string, unknown>): unknown;
+    exists(tableName: string, bizKey: string, bizKeyValue: unknown): boolean;
+    fillSystemFields(data: Record<string, unknown>, isInsert: boolean): void;
+    /** 默认用户值（issues/19）：优先取 data 中已注入的 apply_user_id
+     * （拦截器场景 = 流程 operator，BIGINT 用户列表开箱即用），否则回落配置默认值 */
+    private resolveDefaultUser;
+}
+/** 流程定义加载器（用于解析 relTableName / 流程 name），通常透传仓库 findDefineById */
+export type DefineLoader = (defineId: number) => Promise<ProcessDefine | null>;
+/**
+ * 工作流业务数据入库适配拦截器——流程结束同意后，f_ 表单数据写入业务表。
+ *
+ * 语义（spec 契约，四语言一致）：
+ * - 时机：结束节点执行后 + 实例 Done + submitType=AGREE（不同意/退回不入库）
+ * - 字段：实例 Variables 中 f_ 前缀字段，去前缀
+ * - 表名：流程定义 content 顶层 relTableName，缺省回落流程 name
+ * - 系统字段：writer 通用字段 + 流程上下文（process_instance_id / apply_user_id /
+ *   apply_dept_id，蛇形列名约定）
+ * - 幂等：bizKey = process_instance_id（先查后插，跨请求有效）
+ * - 静默跳过：非结束节点 / 非同意 / 未配置表名 / writer 未注入
+ * - 表不存在 = 配置错误 → 显性抛错（快速失败）
+ */
+export declare class PersistPostInterceptor implements FlowInterceptor {
+    private writer;
+    private loader;
+    order: number;
+    fieldPrefix: string;
+    constructor(writer: DynamicTableWriter | null, loader: DefineLoader | null);
+    preHandle(_node: FlowNode, _inst: ProcessInstance): Promise<boolean>;
+    postHandle(node: FlowNode, inst: ProcessInstance): Promise<void>;
+    private resolveTableName;
+}

package/dist/persist.js

@@ -0,0 +1,197 @@
+import { KeySubmitType, KeyDeptID } from './engine.js';
+import { TypeEnd, InstanceState, SubmitType } from './model.js';
+// ─── 默认实现：node:sqlite（内置零依赖） ──────────────────────────────────────
+const TABLE_NAME_RE = /^[A-Za-z0-9_]+$/;
+function nowText() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/** 表名安全校验：非空、合法字符、拒绝 sys_ 前缀 */
+function checkTableName(tableName) {
+    if (!tableName)
+        throw new Error('persist: table name is empty');
+    if (tableName.startsWith('sys_'))
+        throw new Error(`persist: table ${tableName} with sys_ prefix is not allowed`);
+    if (!TABLE_NAME_RE.test(tableName))
+        throw new Error(`persist: table ${tableName} contains illegal characters`);
+}
+/**
+ * 动态表写入器默认实现（node:sqlite DatabaseSync）。
+ *
+ * 注意：node:sqlite 是实验特性（Node 22.5+，无需外部依赖）。
+ * MySQL/PG 集成方可自行实现 DynamicTableWriter 接口（契约见上）。
+ */
+export class SqliteDynamicTableWriter {
+    db;
+    cache = new Map();
+    /** 系统字段列名（null/undefined 禁用） */
+    createTimeColumn = 'create_time';
+    createUserColumn = 'create_user';
+    updateTimeColumn = 'update_time';
+    updateUserColumn = 'update_user';
+    isDeletedColumn = 'is_deleted';
+    /** 用户列默认值（issues/19）：优先取 data 中已注入的 apply_user_id=流程 operator，
+     *  否则用此配置值，缺省 "system"——多数框架业务表 create_user/update_user 为 BIGINT 存 userId */
+    defaultUserValue = 'system';
+    constructor(db) {
+        this.db = db;
+    }
+    tableColumns(tableName) {
+        const cached = this.cache.get(tableName);
+        if (cached)
+            return cached;
+        // PRAGMA 不支持占位符——表名已过安全校验
+        const rows = this.db.prepare(`PRAGMA table_info(${tableName})`).all();
+        if (rows.length === 0)
+            throw new Error(`persist: table ${tableName} not found`);
+        const cols = rows.map(r => r.name.toUpperCase());
+        this.cache.set(tableName, cols);
+        return cols;
+    }
+    filterColumns(tableName, columns) {
+        checkTableName(tableName);
+        const set = new Set(this.tableColumns(tableName));
+        return columns.filter(c => set.has(c.toUpperCase()));
+    }
+    insert(tableName, data) {
+        checkTableName(tableName);
+        const cols = this.tableColumns(tableName);
+        const names = [];
+        const values = [];
+        // 保持插入顺序稳定（对象键无序，按表列顺序取）
+        for (const col of cols) {
+            if (Object.prototype.hasOwnProperty.call(data, col)) {
+                names.push(col);
+                values.push(data[col]);
+            }
+            else {
+                const key = Object.keys(data).find(k => k.toUpperCase() === col);
+                if (key !== undefined) {
+                    names.push(col);
+                    values.push(data[key]);
+                }
+            }
+        }
+        if (names.length === 0)
+            throw new Error(`persist: no matching columns for ${tableName}`);
+        const placeholders = names.map(() => '?').join(',');
+        const stmt = this.db.prepare(`INSERT INTO ${tableName} (${names.join(',')}) VALUES (${placeholders})`);
+        const res = stmt.run(...values);
+        return res.lastInsertRowid;
+    }
+    exists(tableName, bizKey, bizKeyValue) {
+        checkTableName(tableName);
+        this.tableColumns(tableName); // 表不存在提前报错
+        const row = this.db.prepare(`SELECT COUNT(1) AS c FROM ${tableName} WHERE ${bizKey} = ?`).get(bizKeyValue);
+        return Number(row?.c ?? 0) > 0;
+    }
+    fillSystemFields(data, isInsert) {
+        const now = nowText();
+        if (isInsert) {
+            if (this.createTimeColumn)
+                data[this.createTimeColumn] ??= now;
+            if (this.createUserColumn)
+                data[this.createUserColumn] ??= this.resolveDefaultUser(data);
+            if (this.updateTimeColumn)
+                data[this.updateTimeColumn] ??= now;
+            if (this.updateUserColumn)
+                data[this.updateUserColumn] ??= this.resolveDefaultUser(data);
+            if (this.isDeletedColumn)
+                data[this.isDeletedColumn] ??= 0;
+        }
+        else {
+            if (this.updateTimeColumn)
+                data[this.updateTimeColumn] = now;
+            if (this.updateUserColumn)
+                data[this.updateUserColumn] ??= this.resolveDefaultUser(data);
+        }
+    }
+    /** 默认用户值（issues/19）：优先取 data 中已注入的 apply_user_id
+     * （拦截器场景 = 流程 operator，BIGINT 用户列表开箱即用），否则回落配置默认值 */
+    resolveDefaultUser(data) {
+        return data['apply_user_id'] ?? this.defaultUserValue;
+    }
+}
+/**
+ * 工作流业务数据入库适配拦截器——流程结束同意后，f_ 表单数据写入业务表。
+ *
+ * 语义（spec 契约，四语言一致）：
+ * - 时机：结束节点执行后 + 实例 Done + submitType=AGREE（不同意/退回不入库）
+ * - 字段：实例 Variables 中 f_ 前缀字段，去前缀
+ * - 表名：流程定义 content 顶层 relTableName，缺省回落流程 name
+ * - 系统字段：writer 通用字段 + 流程上下文（process_instance_id / apply_user_id /
+ *   apply_dept_id，蛇形列名约定）
+ * - 幂等：bizKey = process_instance_id（先查后插，跨请求有效）
+ * - 静默跳过：非结束节点 / 非同意 / 未配置表名 / writer 未注入
+ * - 表不存在 = 配置错误 → 显性抛错（快速失败）
+ */
+export class PersistPostInterceptor {
+    writer;
+    loader;
+    order = 0;
+    fieldPrefix = 'f_';
+    constructor(writer, loader) {
+        this.writer = writer;
+        this.loader = loader;
+    }
+    async preHandle(_node, _inst) {
+        return true;
+    }
+    async postHandle(node, inst) {
+        if (!this.writer || !this.loader)
+            return; // 未注入：静默跳过
+        // 时机：仅结束节点 + 流程正常完成（Done）+ 同意
+        if (!node || node.type !== TypeEnd)
+            return;
+        if (!inst || inst.state !== InstanceState.Done)
+            return;
+        const submitType = Number(inst.variables[KeySubmitType]);
+        if (submitType !== SubmitType.Agree)
+            return;
+        // 同链重复触发防护（issues/19）：最后任务节点与结束节点都会触发后置拦截器，
+        // 同一执行链（共享 inst.variables）只插一次。标记写入时实例已完成持久化
+        // （引擎 executeNode 先 updateInstance 后触发拦截器，repo 存副本）不会落库；
+        // exists 保留作为跨请求/重启的幂等兜底（先查后插语义不变）。
+        const chainKey = `__persist_executed_${inst.id}`;
+        if (inst.variables[chainKey] === true)
+            return;
+        inst.variables[chainKey] = true;
+        // 表名：流程定义顶层 relTableName，缺省回落流程 name
+        const tableName = await this.resolveTableName(inst);
+        if (!tableName)
+            return; // 未配置：静默跳过
+        // 幂等：以 process_instance_id 为键，先查后插
+        if (await this.writer.exists(tableName, 'process_instance_id', inst.id))
+            return;
+        // 提取 f_ 前缀字段（去前缀）
+        const prefix = this.fieldPrefix || 'f_';
+        const data = {};
+        for (const [k, v] of Object.entries(inst.variables)) {
+            if (k.startsWith(prefix) && k.length > prefix.length)
+                data[k.slice(prefix.length)] = v;
+        }
+        // 流程上下文字段（蛇形列名约定，与 writer 系统字段一致）
+        data['process_instance_id'] ??= inst.id;
+        data['apply_user_id'] ??= inst.operator;
+        data['apply_dept_id'] ??= inst.variables[KeyDeptID] ?? null;
+        // 通用系统字段（writer 按配置列填充）
+        this.writer.fillSystemFields(data, true);
+        await this.writer.insert(tableName, data);
+    }
+    async resolveTableName(inst) {
+        const define = await this.loader(inst.defineId);
+        if (!define)
+            return '';
+        const content = typeof define.content === 'string' ? define.content : new TextDecoder().decode(define.content);
+        let meta;
+        try {
+            meta = JSON.parse(content);
+        }
+        catch {
+            return '';
+        }
+        const tableName = (meta.relTableName ?? '').trim();
+        return tableName || (meta.name ?? '').trim(); // 缺省回落流程 name
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mldong/jeeflow",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "description": "jeeflow workflow engine — Node.js / TypeScript implementation",
   "type": "module",
   "main": "./dist/index.js",