@mldong/jeeflow 1.7.0 → 1.8.0

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { TypeStart, TypeEnd, TypeTask, TypeDecision, TypeFork, TypeJoin, TypeCustom, ProcessInstance, TaskState, } from './model.js';
+import { TypeStart, TypeEnd, TypeTask, TypeDecision, TypeFork, TypeJoin, TypeCustom, ProcessInstance, TaskState, SubmitType, } from './model.js';
 import { EventType } from './extensions.js';
 export const KeySubmitType = 'submitType';
 export const KeyBusinessNo = 'BUSINESS_NO';
@@ -97,6 +97,9 @@ export class EngineImpl {
         await this.repo.updateInstance(inst);
         const curNode = findNode(flow, task.taskName);
         if (curNode) {
+            // 1.8.0：任务完成节点自身的后置拦截器（SYNC 同步演进——任务节点推进更新状态/字段）。
+            // createTask 不再触发（引擎语义修正），此处为完成任务节点的唯一触发点
+            await this.firePost(curNode, inst);
             const ct = curNode.properties?.countersignType;
             if (ct === 'SEQUENTIAL') {
                 const doing = await this.repo.findDoingTasks(inst.id);
@@ -209,13 +212,16 @@ export class EngineImpl {
         return { task, inst };
     }
     async executeNode(flow, inst, node, operator, vars) {
+        // 任务创建（对齐 Java CreateTaskHandler：不触发节点拦截器——创建任务 ≠ 节点执行完成；
+        // 任务完成的拦截器由 executeProcessTask 显式触发，1.8.0 SYNC 同步演进）
+        if (node.type === TypeTask || node.type === TypeCustom) {
+            await this.createTask(node, inst, operator, vars);
+            return;
+        }
         if (!(await this.firePre(node, inst)))
             return;
         try {
             switch (node.type) {
-                case TypeTask:
-                case TypeCustom:
-                    return this.createTask(node, inst, operator, vars);
                 case TypeDecision:
                     return this.evaluateDecision(flow, inst, node, operator, vars);
                 case TypeFork:
@@ -229,12 +235,20 @@ export class EngineImpl {
                             await this.executeNode(flow, inst, n, operator, vars);
                     return;
                 }
-                case TypeEnd:
-                    inst.finish(new Date());
+                case TypeEnd: {
+                    // 对齐 Java EndProcessHandler：submitType=REJECT → reject，否则 finish
+                    const submitType = inst.variables[KeySubmitType];
+                    if (submitType != null && Number(submitType) === SubmitType.Reject) {
+                        inst.reject(new Date());
+                    }
+                    else {
+                        inst.finish(new Date());
+                    }
                     inst.variables = vars;
                     await this.repo.updateInstance(inst);
                     await this.fireEvent({ type: EventType.ProcessFinish, instanceId: inst.id, operator });
                     return;
+                }
             }
         }
         finally {

package/dist/meta.d.ts

@@ -50,10 +50,17 @@ export declare class MetaTableWriter implements DynamicTableWriter {
     constructor(base: DynamicTableWriter, provider: IDynamicMetaProvider);
     filterColumns(tableName: string, columns: string[]): string[] | Promise<string[]>;
     insert(tableName: string, data: Record<string, unknown>): unknown;
+    /** 按元数据 storageType 组装 SET 列（SYNC 同步演进，issues/24）——
+     *  NORMAL/JSON/EXPAND 参与更新；ONE2ONE/ONE2MANY 子表不参与中途更新
+     *  （任务推进只更新主表行状态，子表数据变动走重新提交）；未消费字段直通。 */
+    update(tableName: string, data: Record<string, unknown>, whereColumn: string, whereValue: unknown): number | Promise<number>;
     exists(tableName: string, bizKey: string, bizKeyValue: unknown): boolean | Promise<boolean>;
     fillSystemFields(data: Record<string, unknown>, isInsert: boolean): void;
     private expandInto;
     private insertSubTable;
+    /** 子表单行插入（issues/24）：继承主表 apply_user_id（拦截器场景=流程 operator），
+     *  子表单显式同名字段优先（??=）——fillSystemFields 的用户列默认值可解析到 operator，
+     *  避免 BIGINT create_user/update_user 列回落 "system" 严格模式报错 */
     private insertSubRow;
 }
 /** 业务表查询器——按列等值查询原始行（与写入器职责分离） */

package/dist/meta.js

@@ -117,12 +117,45 @@ export class MetaTableWriter {
         let pk = this.base.insert(tableName, row); // 主表插入（自增/生成器返回主键）
         if (pk === undefined || pk === null)
             pk = findRowValue(row, pkOf(meta));
-        // 子表递归插入（外键=主表主键）
+        // 子表递归插入（外键=主表主键；继承主表 apply_user_id，issues/24）
         for (const [name, v] of subData) {
-            this.insertSubTable(meta, findField(meta, name), v, pk);
+            this.insertSubTable(meta, findField(meta, name), v, pk, data);
         }
         return pk;
     }
+    /** 按元数据 storageType 组装 SET 列（SYNC 同步演进，issues/24）——
+     *  NORMAL/JSON/EXPAND 参与更新；ONE2ONE/ONE2MANY 子表不参与中途更新
+     *  （任务推进只更新主表行状态，子表数据变动走重新提交）；未消费字段直通。 */
+    update(tableName, data, whereColumn, whereValue) {
+        const meta = this.provider.loadTableMeta(tableName);
+        if (!meta)
+            return this.base.update(tableName, data, whereColumn, whereValue); // 无元数据：回落基础 writer
+        const row = {};
+        for (const f of meta.fields) {
+            const v = data[f.name];
+            if (v === undefined || v === null)
+                continue;
+            const st = f.storageType ?? StorageType.Normal;
+            if (st === StorageType.Json) {
+                row[columnOf(f)] = JSON.stringify(v);
+            }
+            else if (st === StorageType.Expand) {
+                this.expandInto(f, v, row);
+            }
+            else if (st === StorageType.One2One || st === StorageType.One2Many) {
+                continue; // 子表不参与中途更新
+            }
+            else {
+                row[columnOf(f)] = v;
+            }
+        }
+        // 未消费字段（流程上下文/状态字段等）直通基础 writer
+        for (const [k, v] of Object.entries(data)) {
+            if (!findField(meta, k))
+                row[k] ??= v;
+        }
+        return this.base.update(tableName, row, whereColumn, whereValue);
+    }
     exists(tableName, bizKey, bizKeyValue) {
         return this.base.exists(tableName, bizKey, bizKeyValue);
     }
@@ -138,25 +171,31 @@ export class MetaTableWriter {
                 row[col] = obj[sub];
         }
     }
-    insertSubTable(parentMeta, f, v, parentPk) {
+    insertSubTable(parentMeta, f, v, parentPk, parentData) {
         if (parentPk === undefined || parentPk === null) {
             throw new Error(`persist: parent primary key missing, cannot insert sub table ${f.name}`);
         }
         const fk = f.foreignKey || pkOf(parentMeta);
         const st = f.storageType ?? StorageType.Normal;
         if (st === StorageType.One2One && typeof v === 'object' && v !== null) {
-            this.insertSubRow(f, v, fk, parentPk);
+            this.insertSubRow(f, v, fk, parentPk, parentData);
         }
         else if (st === StorageType.One2Many && Array.isArray(v)) {
             for (const item of v) {
                 if (typeof item === 'object' && item !== null) {
-                    this.insertSubRow(f, item, fk, parentPk);
+                    this.insertSubRow(f, item, fk, parentPk, parentData);
                 }
             }
         }
     }
-    insertSubRow(f, subData, fk, parentPk) {
+    /** 子表单行插入（issues/24）：继承主表 apply_user_id（拦截器场景=流程 operator），
+     *  子表单显式同名字段优先（??=）——fillSystemFields 的用户列默认值可解析到 operator，
+     *  避免 BIGINT create_user/update_user 列回落 "system" 严格模式报错 */
+    insertSubRow(f, subData, fk, parentPk, parentData) {
         const row = { ...subData, [fk]: parentPk };
+        if (parentData['apply_user_id'] !== undefined) {
+            row['apply_user_id'] ??= parentData['apply_user_id'];
+        }
         this.insert(f.targetTable, row); // 递归走子表自身元数据
     }
 }
@@ -224,9 +263,10 @@ export class MetaTableReader {
                 result[f.name] = v;
             }
         }
-        // 未在元数据中的列带出（key 统一小写）
+        // 未在元数据中的列带出（key 统一小写）；
+        // EXPAND 展开列（挂在某字段 expandFields 映射里，对象形式已带出）不重复平铺（issues/24）
         for (const [k, v] of Object.entries(row)) {
-            if (!findFieldByColumn(meta, k))
+            if (!findFieldByColumn(meta, k) && !isExpandColumn(meta, k))
                 result[k.toLowerCase()] ??= v;
         }
         return result;
@@ -266,3 +306,13 @@ export function findRowValue(row, columnName) {
     }
     return undefined;
 }
+/** 列是否为某字段的 EXPAND 展开列（issues/24：已消费，不重复平铺带出） */
+function isExpandColumn(meta, column) {
+    for (const f of meta.fields) {
+        for (const col of Object.values(f.expandFields ?? {})) {
+            if (col.toLowerCase() === (column ?? '').toLowerCase())
+                return true;
+        }
+    }
+    return false;
+}

package/dist/persist.d.ts

@@ -12,6 +12,9 @@ export interface DynamicTableWriter {
     filterColumns(tableName: string, columns: string[]): string[] | Promise<string[]>;
     /** 参数化 INSERT（按列过滤结果落库），返回生成主键 */
     insert(tableName: string, data: Record<string, unknown>): unknown | Promise<unknown>;
+    /** 参数化 UPDATE（按列过滤结果组装 SET；条件列排除，防注入），返回受影响行数
+     * （SYNC 同步演进，issues/24） */
+    update(tableName: string, data: Record<string, unknown>, whereColumn: string, whereValue: unknown): number | Promise<number>;
     /** 幂等检查：指定业务键（如 process_instance_id）是否已存在 */
     exists(tableName: string, bizKey: string, bizKeyValue: unknown): boolean | Promise<boolean>;
     /** 按配置列名填充系统字段（未配置的列跳过） */
@@ -49,33 +52,58 @@ export declare class SqliteDynamicTableWriter implements DynamicTableWriter {
     /** 在 data 中找匹配指定表列的 key（宽松模式驼峰 key 匹配下划线列） */
     private findDataKey;
     exists(tableName: string, bizKey: string, bizKeyValue: unknown): boolean;
+    /** 参数化 UPDATE（SYNC 同步演进，issues/24）：列过滤（宽松匹配）+ 条件列排除 +
+     *  参数化 SET，返回受影响行数。对齐 Java JdbcDynamicTableWriter.update。 */
+    update(tableName: string, data: Record<string, unknown>, whereColumn: string, whereValue: unknown): number;
     fillSystemFields(data: Record<string, unknown>, isInsert: boolean): void;
     /** 默认用户值（issues/19）：优先取 data 中已注入的 apply_user_id
      * （拦截器场景 = 流程 operator，BIGINT 用户列表开箱即用），否则回落配置默认值 */
     private resolveDefaultUser;
 }
-/** 流程定义加载器（用于解析 relTableName / 流程 name），通常透传仓库 findDefineById */
+/** 流程定义加载器（用于解析 relTableName / persistMode / 流程 name），通常透传仓库 findDefineById */
 export type DefineLoader = (defineId: number) => Promise<ProcessDefine | null>;
+/** 持久化模式（流程定义顶层 persistMode，缺省 ARCHIVE） */
+export declare const PersistModeArchive = "ARCHIVE";
+export declare const PersistModeSync = "SYNC";
+/** 字段权限值（任务节点 properties.field 的 PERMISSION_{字段名}，vben5-wf 机制） */
+export declare const PermReadOnly = 1;
+export declare const PermEdit = 2;
+export declare const PermHidden = 3;
 /**
- * 工作流业务数据入库适配拦截器——流程结束同意后，f_ 表单数据写入业务表。
+ * 工作流业务数据入库适配拦截器——按流程定义顶层 persistMode 分派：
  *
- * 语义（spec 契约，四语言一致）：
- * - 时机：结束节点执行后 + 实例 Done + submitType=AGREE（不同意/退回不入库）
- * - 字段：实例 Variables 中 f_ 前缀字段，去前缀
- * - 表名：流程定义 content 顶层 relTableName，缺省回落流程 name
- * - 系统字段：writer 通用字段 + 流程上下文（process_instance_id / apply_user_id /
- *   apply_dept_id，蛇形列名约定）
- * - 幂等：bizKey = process_instance_id（先查后插，跨请求有效）
- * - 静默跳过：非结束节点 / 非同意 / 未配置表名 / writer 未注入
- * - 表不存在 = 配置错误 → 显性抛错（快速失败）
+ * - ARCHIVE（缺省）：流程结束同意后，f_ 表单数据写入业务表（一次落库）
+ * - SYNC（1.8.0，issues/24 同步演进）：提交申请即入库（start 节点 INSERT 全量），
+ *   任务节点推进 UPDATE（f_ 按节点字段权限过滤 + tf_ 冗余 + 状态字段=DOING），
+ *   结束节点定稿 UPDATE（最终状态 FINISHED/REJECT）——不管成功失败都入库
+ *
+ * 对标 Java PersistPostInterceptor（1.8.0）。
  */
 export declare class PersistPostInterceptor implements FlowInterceptor {
     private writer;
     private loader;
     order: number;
     fieldPrefix: string;
+    taskFieldPrefix: string;
     constructor(writer: DynamicTableWriter | null, loader: DefineLoader | null);
     preHandle(_node: FlowNode, _inst: ProcessInstance): Promise<boolean>;
     postHandle(node: FlowNode, inst: ProcessInstance): Promise<void>;
-    private resolveTableName;
+    private handleArchive;
+    private handleSync;
+    private resolveDefine;
+    /** 同链重复触发防护（issues/19，1.8.0 节点级）：同一执行链中**每个节点**触发一次
+     * （任务推进更新 + 结束定稿是不同节点，都要生效），同节点不重复；exists 兜底跨请求。 */
+    private markChain;
+    /** 提取字段：f_ 去前缀（SYNC 下按字段权限过滤——只读/隐藏不更新；
+     *  includeFormFields=false 时不带出，用于非任务节点定稿避免覆盖只读限制）；
+     *  tf_ 去前缀冗余（有列则写，列过滤由 writer 做） */
+    private extractFields;
+    /** 任务节点字段权限（node.properties.field 的 PERMISSION_x；缺省 null=全部可编辑） */
+    private resolveFieldPermission;
+    /** 字段可编辑判定：无声明或 EDIT(2) 可更新；READ_ONLY(1)/HIDDEN(3) 不更新 */
+    private isEditable;
+    /** 状态字段写入：优先 {节点ID}_{状态码} 列，无则 {节点ID} 列（列探测过滤） */
+    private putStateField;
+    /** 流程上下文字段（蛇形列名约定，与 writer 系统字段一致） */
+    private fillContext;
 }

package/dist/persist.js

@@ -1,5 +1,5 @@
 import { KeySubmitType, KeyDeptID } from './engine.js';
-import { TypeEnd, InstanceState, SubmitType } from './model.js';
+import { TypeEnd, TypeTask, TypeCustom, InstanceState, SubmitType } from './model.js';
 // ─── 默认实现：node:sqlite（内置零依赖） ──────────────────────────────────────
 const TABLE_NAME_RE = /^[A-Za-z0-9_]+$/;
 /** 列名归一（issues/20）：转小写 + 去下划线（companyName / company_name / COMPANY_NAME 等价） */
@@ -128,6 +128,30 @@ export class SqliteDynamicTableWriter {
         const row = this.db.prepare(`SELECT COUNT(1) AS c FROM ${tableName} WHERE ${bizKey} = ?`).get(bizKeyValue);
         return Number(row?.c ?? 0) > 0;
     }
+    /** 参数化 UPDATE（SYNC 同步演进，issues/24）：列过滤（宽松匹配）+ 条件列排除 +
+     *  参数化 SET，返回受影响行数。对齐 Java JdbcDynamicTableWriter.update。 */
+    update(tableName, data, whereColumn, whereValue) {
+        checkTableName(tableName);
+        if (!whereColumn)
+            throw new Error(`persist: update ${tableName} requires where column`);
+        const cols = this.tableColumns(tableName);
+        const sets = [];
+        const values = [];
+        for (const m of cols) {
+            if (normalizeColumn(m.name) === normalizeColumn(whereColumn))
+                continue; // 条件列不参与 SET
+            const key = this.findDataKey(data, m.name);
+            if (key) {
+                sets.push(`${m.name} = ?`);
+                values.push(data[key]);
+            }
+        }
+        if (sets.length === 0)
+            return 0; // 无更新列（如结束节点仅状态探测未命中）
+        values.push(whereValue);
+        const res = this.db.prepare(`UPDATE ${tableName} SET ${sets.join(',')} WHERE ${whereColumn} = ?`).run(...values);
+        return Number(res.changes ?? 0);
+    }
     fillSystemFields(data, isInsert) {
         const now = nowText();
         if (isInsert) {
@@ -155,24 +179,29 @@ export class SqliteDynamicTableWriter {
         return data['apply_user_id'] ?? this.defaultUserValue;
     }
 }
+/** 持久化模式（流程定义顶层 persistMode，缺省 ARCHIVE） */
+export const PersistModeArchive = 'ARCHIVE'; // 结束归档（现状）：流程结束同意后落库
+export const PersistModeSync = 'SYNC'; // 同步演进：发起 INSERT → 任务节点 UPDATE → 结束定稿
+/** 字段权限值（任务节点 properties.field 的 PERMISSION_{字段名}，vben5-wf 机制） */
+export const PermReadOnly = 1; // 只读：不更新
+export const PermEdit = 2; // 可编辑：更新
+export const PermHidden = 3; // 隐藏：不更新
 /**
- * 工作流业务数据入库适配拦截器——流程结束同意后，f_ 表单数据写入业务表。
+ * 工作流业务数据入库适配拦截器——按流程定义顶层 persistMode 分派：
+ *
+ * - ARCHIVE（缺省）：流程结束同意后，f_ 表单数据写入业务表（一次落库）
+ * - SYNC（1.8.0，issues/24 同步演进）：提交申请即入库（start 节点 INSERT 全量），
+ *   任务节点推进 UPDATE（f_ 按节点字段权限过滤 + tf_ 冗余 + 状态字段=DOING），
+ *   结束节点定稿 UPDATE（最终状态 FINISHED/REJECT）——不管成功失败都入库
  *
- * 语义（spec 契约，四语言一致）：
- * - 时机：结束节点执行后 + 实例 Done + submitType=AGREE（不同意/退回不入库）
- * - 字段：实例 Variables 中 f_ 前缀字段，去前缀
- * - 表名：流程定义 content 顶层 relTableName，缺省回落流程 name
- * - 系统字段：writer 通用字段 + 流程上下文（process_instance_id / apply_user_id /
- *   apply_dept_id，蛇形列名约定）
- * - 幂等：bizKey = process_instance_id（先查后插，跨请求有效）
- * - 静默跳过：非结束节点 / 非同意 / 未配置表名 / writer 未注入
- * - 表不存在 = 配置错误 → 显性抛错（快速失败）
+ * 对标 Java PersistPostInterceptor（1.8.0）。
  */
 export class PersistPostInterceptor {
     writer;
     loader;
     order = 0;
     fieldPrefix = 'f_';
+    taskFieldPrefix = 'tf_';
     constructor(writer, loader) {
         this.writer = writer;
         this.loader = loader;
@@ -183,57 +212,146 @@ export class PersistPostInterceptor {
     async postHandle(node, inst) {
         if (!this.writer || !this.loader)
             return; // 未注入：静默跳过
+        if (!node || !inst)
+            return;
+        const { tableName, persistMode } = await this.resolveDefine(inst);
+        if (!tableName)
+            return; // 未配置：静默跳过
+        if (persistMode.toUpperCase() === PersistModeSync) {
+            await this.handleSync(node, inst, tableName);
+            return;
+        }
+        await this.handleArchive(node, inst, tableName);
+    }
+    // ─── ARCHIVE（现状：结束同意归档） ──────────────────────────────────────────
+    async handleArchive(node, inst, tableName) {
+        const writer = this.writer;
+        if (!writer)
+            return;
         // 时机：仅结束节点 + 流程正常完成（Done）+ 同意
-        if (!node || node.type !== TypeEnd)
+        if (node.type !== TypeEnd)
             return;
-        if (!inst || inst.state !== InstanceState.Done)
+        if (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)
+        if (!this.markChain(node, inst))
             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))
+        // 幂等：以 process_instance_id 为键，先查后插。
+        // 表不存在等探测失败是配置错误，必须显性暴露（与 Java/Python 抛异常一致）
+        if (await writer.exists(tableName, 'process_instance_id', inst.id))
+            return;
+        const data = this.extractFields(inst, null, false, true); // 只 f_ 全量
+        this.fillContext(data, inst);
+        writer.fillSystemFields(data, true);
+        await writer.insert(tableName, data);
+    }
+    // ─── SYNC（1.8.0 同步演进：发起入库 → 节点推进 → 结束定稿） ──────────────────
+    async handleSync(node, inst, tableName) {
+        const writer = this.writer;
+        if (!writer)
+            return;
+        if (!this.markChain(node, inst))
+            return; // 同链同节点不重复（节点级，issues/19 演进）
+        const exists = await writer.exists(tableName, 'process_instance_id', inst.id);
+        // 任务节点（TypeTask/TypeCustom）才更新业务字段：f_ 按节点字段权限过滤；
+        // 结束/网关等非任务节点只定稿状态，避免全量覆盖任务节点的只读/隐藏限制
+        const isTask = node.type === TypeTask || node.type === TypeCustom;
+        const fieldPerm = isTask ? this.resolveFieldPermission(node) : null;
+        const data = this.extractFields(inst, fieldPerm, !exists || isTask, !exists || isTask);
+        // 状态字段：优先 {节点ID}_{状态码} 列，无则 {节点ID} 列。
+        // 任务节点写 DOING(10)——任务推进状态；结束节点写实例最终状态（FINISHED/REJECT）
+        let stateCode = Number(inst.state);
+        if (isTask)
+            stateCode = InstanceState.Doing;
+        this.putStateField(writer, tableName, data, node.id, stateCode);
+        this.fillContext(data, inst);
+        if (!exists) {
+            writer.fillSystemFields(data, true);
+            await writer.insert(tableName, data);
             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);
+        writer.fillSystemFields(data, false); // 只填 update 组
+        await writer.update(tableName, data, 'process_instance_id', inst.id);
     }
-    async resolveTableName(inst) {
+    // ─── 公共 ───────────────────────────────────────────────────────────────────
+    async resolveDefine(inst) {
         const define = await this.loader(inst.defineId);
         if (!define)
-            return '';
+            return { tableName: '', persistMode: '' };
         const content = typeof define.content === 'string' ? define.content : new TextDecoder().decode(define.content);
         let meta;
         try {
             meta = JSON.parse(content);
         }
         catch {
-            return '';
+            return { tableName: '', persistMode: '' };
         }
         const tableName = (meta.relTableName ?? '').trim();
-        return tableName || (meta.name ?? '').trim(); // 缺省回落流程 name
+        return {
+            tableName: tableName || (meta.name ?? '').trim(), // 缺省回落流程 name
+            persistMode: (meta.persistMode ?? '').trim(),
+        };
+    }
+    /** 同链重复触发防护（issues/19，1.8.0 节点级）：同一执行链中**每个节点**触发一次
+     * （任务推进更新 + 结束定稿是不同节点，都要生效），同节点不重复；exists 兜底跨请求。 */
+    markChain(node, inst) {
+        const chainKey = `__persist_executed_${inst.id}_${node.id}`;
+        if (inst.variables[chainKey] === true)
+            return false;
+        inst.variables[chainKey] = true;
+        return true;
+    }
+    /** 提取字段：f_ 去前缀（SYNC 下按字段权限过滤——只读/隐藏不更新；
+     *  includeFormFields=false 时不带出，用于非任务节点定稿避免覆盖只读限制）；
+     *  tf_ 去前缀冗余（有列则写，列过滤由 writer 做） */
+    extractFields(inst, fieldPerm, includeTaskFields, includeFormFields) {
+        const prefix = this.fieldPrefix || 'f_';
+        const taskPrefix = this.taskFieldPrefix || 'tf_';
+        const data = {};
+        for (const [k, v] of Object.entries(inst.variables)) {
+            if (includeFormFields && k.startsWith(prefix) && k.length > prefix.length) {
+                const name = k.slice(prefix.length);
+                if (!this.isEditable(fieldPerm, name))
+                    continue;
+                data[name] = v;
+            }
+            else if (includeTaskFields && k.startsWith(taskPrefix) && k.length > taskPrefix.length) {
+                data[k.slice(taskPrefix.length)] = v;
+            }
+        }
+        return data;
+    }
+    /** 任务节点字段权限（node.properties.field 的 PERMISSION_x；缺省 null=全部可编辑） */
+    resolveFieldPermission(node) {
+        const field = node.properties?.field;
+        if (field && typeof field === 'object' && Object.keys(field).length > 0) {
+            return field;
+        }
+        return null;
+    }
+    /** 字段可编辑判定：无声明或 EDIT(2) 可更新；READ_ONLY(1)/HIDDEN(3) 不更新 */
+    isEditable(fieldPerm, fieldName) {
+        if (!fieldPerm)
+            return true;
+        const perm = fieldPerm[`PERMISSION_${fieldName}`];
+        if (perm == null)
+            return true;
+        return Number(perm) === PermEdit;
+    }
+    /** 状态字段写入：优先 {节点ID}_{状态码} 列，无则 {节点ID} 列（列探测过滤） */
+    putStateField(writer, tableName, data, nodeId, stateCode) {
+        if (!nodeId)
+            return;
+        const kept = writer.filterColumns(tableName, [`${nodeId}_${stateCode}`, nodeId]);
+        if (Array.isArray(kept) && kept.length > 0)
+            data[kept[0]] = stateCode;
+    }
+    /** 流程上下文字段（蛇形列名约定，与 writer 系统字段一致） */
+    fillContext(data, inst) {
+        data['process_instance_id'] ??= inst.id;
+        data['apply_user_id'] ??= inst.operator;
+        data['apply_dept_id'] ??= inst.variables[KeyDeptID] ?? null;
     }
 }

package/package.json

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