@mldong/jeeflow 1.6.6 → 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

@@ -0,0 +1,85 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { DynamicTableWriter } from './persist.js';
+/** 字段存储类型（对齐 mldong dev_schema_field 1-5 语义） */
+export declare enum StorageType {
+    Normal = 1,// 直写列
+    Expand = 2,// 对象展开为多列（expandFields 定义子字段列映射）
+    Json = 3,// 对象/数组序列化为 JSON 串写列
+    One2One = 4,// 子表单条（外键=主表主键，同事务）
+    One2Many = 5
+}
+/** 解析 storageType：支持名称（"EXPAND"）与数字（2，mldong 语义） */
+export declare function parseStorageType(v: unknown): StorageType;
+/** 字段元数据——表单字段 → 存储语义映射 */
+export interface FieldMeta {
+    name: string;
+    columnName?: string;
+    storageType?: StorageType;
+    expandFields?: Record<string, string>;
+    targetTable?: string;
+    foreignKey?: string;
+}
+/** 表元数据——一张业务表的字段存储规范 */
+export interface TableMeta {
+    tableName: string;
+    primaryKey?: string;
+    fields: FieldMeta[];
+}
+export declare function columnOf(f: FieldMeta): string;
+export declare function pkOf(m: TableMeta): string;
+export declare function findField(m: TableMeta, name: string): FieldMeta | undefined;
+export declare function findFieldByColumn(m: TableMeta, columnName: string): FieldMeta | undefined;
+/** 驼峰转下划线（companyName → company_name） */
+export declare function toUnderline(name: string): string;
+/** 元数据提供者 SPI——集成方只实现这一件事；未定义返回 null（回落表结构探测） */
+export interface IDynamicMetaProvider {
+    loadTableMeta(tableName: string): TableMeta | null;
+}
+/** 内置 JSON 配置加载器——从目录加载（文件名 = 表名，如 biz_leave.json） */
+export declare class JsonMetaProvider implements IDynamicMetaProvider {
+    private dir;
+    private cache;
+    constructor(dir: string);
+    loadTableMeta(tableName: string): TableMeta | null;
+}
+/** 元数据驱动的动态写入器——按 TableMeta.storageType 语义执行插入；
+ *  无元数据时完全委托基础 writer（回落现状，零破坏）。读侧由 MetaTableReader 提供。 */
+export declare class MetaTableWriter implements DynamicTableWriter {
+    private base;
+    private provider;
+    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;
+}
+/** 业务表查询器——按列等值查询原始行（与写入器职责分离） */
+export declare class JdbcTableReader {
+    private db;
+    constructor(db: DatabaseSync);
+    queryFirst(tableName: string, whereColumn: string, value: unknown): Record<string, unknown> | null;
+    queryList(tableName: string, whereColumn: string, value: unknown, limit: number): Record<string, unknown>[];
+}
+/** 元数据驱动的动态读取器——按流程实例回显业务数据。
+ *  边界（不做）：通用条件分页 / 动态条件语法 / 数据权限 / 排序。 */
+export declare class MetaTableReader {
+    private reader;
+    private provider;
+    constructor(reader: JdbcTableReader, provider: IDynamicMetaProvider);
+    readByProcessInstance(tableName: string, processInstanceId: unknown): Record<string, unknown> | null;
+    assemble(meta: TableMeta, row: Record<string, unknown>): Record<string, unknown>;
+    private expandFrom;
+    private readSubTable;
+}
+/** 按列名取值（宽松：忽略大小写） */
+export declare function findRowValue(row: Record<string, unknown>, columnName: string): unknown;

package/dist/meta.js

@@ -0,0 +1,318 @@
+// ═══ 元数据驱动的动态写入/读取规范（issues/23）— 与 Java/Go/Python 契约一致 ═══
+/** 字段存储类型（对齐 mldong dev_schema_field 1-5 语义） */
+export var StorageType;
+(function (StorageType) {
+    StorageType[StorageType["Normal"] = 1] = "Normal";
+    StorageType[StorageType["Expand"] = 2] = "Expand";
+    StorageType[StorageType["Json"] = 3] = "Json";
+    StorageType[StorageType["One2One"] = 4] = "One2One";
+    StorageType[StorageType["One2Many"] = 5] = "One2Many";
+})(StorageType || (StorageType = {}));
+/** 解析 storageType：支持名称（"EXPAND"）与数字（2，mldong 语义） */
+export function parseStorageType(v) {
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string')
+        return StorageType[v] ?? StorageType.Normal;
+    return StorageType.Normal;
+}
+export function columnOf(f) {
+    return f.columnName || toUnderline(f.name);
+}
+export function pkOf(m) {
+    return m.primaryKey || 'id';
+}
+export function findField(m, name) {
+    return m.fields.find(f => f.name.toLowerCase() === name.toLowerCase());
+}
+export function findFieldByColumn(m, columnName) {
+    return m.fields.find(f => columnOf(f).toLowerCase() === columnName.toLowerCase());
+}
+/** 驼峰转下划线（companyName → company_name） */
+export function toUnderline(name) {
+    return name.replace(/([A-Z])/g, (c, _, i) => (i > 0 ? '_' : '') + c.toLowerCase());
+}
+/** 内置 JSON 配置加载器——从目录加载（文件名 = 表名，如 biz_leave.json） */
+export class JsonMetaProvider {
+    dir;
+    cache = new Map();
+    constructor(dir) {
+        this.dir = dir;
+    }
+    loadTableMeta(tableName) {
+        if (this.cache.has(tableName))
+            return this.cache.get(tableName);
+        const data = readFileSyncSafe(`${this.dir}/${tableName}.json`);
+        if (data === null)
+            return null;
+        const raw = JSON.parse(data);
+        const meta = {
+            tableName: raw.tableName ?? tableName,
+            primaryKey: raw.primaryKey ?? 'id',
+            fields: (raw.fields ?? []).map((f) => ({
+                name: f.name,
+                columnName: f.columnName,
+                storageType: parseStorageType(f.storageType ?? 1),
+                expandFields: f.expandFields,
+                targetTable: f.targetTable,
+                foreignKey: f.foreignKey,
+            })),
+        };
+        this.cache.set(tableName, meta);
+        return meta;
+    }
+}
+import { readFileSync } from 'node:fs';
+function readFileSyncSafe(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+// ═══ MetaTableWriter（写，纯写职责） ═══════════════════════════════════════════
+/** 元数据驱动的动态写入器——按 TableMeta.storageType 语义执行插入；
+ *  无元数据时完全委托基础 writer（回落现状，零破坏）。读侧由 MetaTableReader 提供。 */
+export class MetaTableWriter {
+    base;
+    provider;
+    constructor(base, provider) {
+        this.base = base;
+        this.provider = provider;
+    }
+    filterColumns(tableName, columns) {
+        return this.base.filterColumns(tableName, columns);
+    }
+    insert(tableName, data) {
+        const meta = this.provider.loadTableMeta(tableName);
+        if (!meta)
+            return this.base.insert(tableName, data); // 无元数据：回落现状
+        const subData = new Map();
+        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) {
+                subData.set(f.name, v);
+            }
+            else {
+                row[columnOf(f)] = v;
+            }
+        }
+        // 未消费字段（流程上下文 process_instance_id 等）直通基础 writer
+        for (const [k, v] of Object.entries(data)) {
+            if (!findField(meta, k))
+                row[k] ??= v;
+        }
+        this.base.fillSystemFields(row, true);
+        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, 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);
+    }
+    fillSystemFields(data, isInsert) {
+        this.base.fillSystemFields(data, isInsert);
+    }
+    expandInto(f, v, row) {
+        if (typeof v !== 'object' || v === null)
+            return;
+        const obj = v;
+        for (const [sub, col] of Object.entries(f.expandFields ?? {})) {
+            if (obj[sub] !== undefined && obj[sub] !== null)
+                row[col] = obj[sub];
+        }
+    }
+    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, 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, parentData);
+                }
+            }
+        }
+    }
+    /** 子表单行插入（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); // 递归走子表自身元数据
+    }
+}
+// ═══ JdbcTableReader（读侧底层） ═══════════════════════════════════════════════
+/** 业务表查询器——按列等值查询原始行（与写入器职责分离） */
+export class JdbcTableReader {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    queryFirst(tableName, whereColumn, value) {
+        const rows = this.queryList(tableName, whereColumn, value, 1);
+        return rows.length > 0 ? rows[0] : null;
+    }
+    queryList(tableName, whereColumn, value, limit) {
+        const sql = `SELECT * FROM ${tableName} WHERE ${whereColumn} = ?${limit > 0 ? ` LIMIT ${limit}` : ''}`;
+        return this.db.prepare(sql).all(value);
+    }
+}
+// ═══ MetaTableReader（读，流程回显最小闭环） ═══════════════════════════════════
+/** 元数据驱动的动态读取器——按流程实例回显业务数据。
+ *  边界（不做）：通用条件分页 / 动态条件语法 / 数据权限 / 排序。 */
+export class MetaTableReader {
+    reader;
+    provider;
+    constructor(reader, provider) {
+        this.reader = reader;
+        this.provider = provider;
+    }
+    readByProcessInstance(tableName, processInstanceId) {
+        const row = this.reader.queryFirst(tableName, 'process_instance_id', processInstanceId);
+        if (!row)
+            return null;
+        const meta = this.provider.loadTableMeta(tableName);
+        if (!meta)
+            return row; // 无元数据：原样返回（列名→值）
+        return this.assemble(meta, row);
+    }
+    assemble(meta, row) {
+        const result = {};
+        for (const f of meta.fields) {
+            const v = findRowValue(row, columnOf(f));
+            const st = f.storageType ?? StorageType.Normal;
+            if (st === StorageType.Json) {
+                if (v !== undefined && v !== null) {
+                    try {
+                        result[f.name] = JSON.parse(String(v));
+                    }
+                    catch {
+                        result[f.name] = v;
+                    }
+                }
+            }
+            else if (st === StorageType.Expand) {
+                const obj = this.expandFrom(row, f);
+                if (Object.keys(obj).length > 0)
+                    result[f.name] = obj;
+            }
+            else if (st === StorageType.One2One || st === StorageType.One2Many) {
+                const sub = this.readSubTable(meta, f, row);
+                if (sub !== undefined && sub !== null)
+                    result[f.name] = sub;
+            }
+            else if (v !== undefined && v !== null) {
+                result[f.name] = v;
+            }
+        }
+        // 未在元数据中的列带出（key 统一小写）；
+        // EXPAND 展开列（挂在某字段 expandFields 映射里，对象形式已带出）不重复平铺（issues/24）
+        for (const [k, v] of Object.entries(row)) {
+            if (!findFieldByColumn(meta, k) && !isExpandColumn(meta, k))
+                result[k.toLowerCase()] ??= v;
+        }
+        return result;
+    }
+    expandFrom(row, f) {
+        const obj = {};
+        for (const [sub, col] of Object.entries(f.expandFields ?? {})) {
+            const v = findRowValue(row, col);
+            if (v !== undefined && v !== null)
+                obj[sub] = v;
+        }
+        return obj;
+    }
+    readSubTable(parentMeta, f, row) {
+        const parentPk = findRowValue(row, pkOf(parentMeta));
+        if (parentPk === undefined || parentPk === null)
+            return null;
+        const fk = f.foreignKey || pkOf(parentMeta);
+        const subMeta = this.provider.loadTableMeta(f.targetTable);
+        const st = f.storageType ?? StorageType.Normal;
+        if (st === StorageType.One2One) {
+            const sub = this.reader.queryFirst(f.targetTable, fk, parentPk);
+            if (!sub)
+                return null;
+            return subMeta ? this.assemble(subMeta, sub) : sub;
+        }
+        // ONE2MANY
+        const subs = this.reader.queryList(f.targetTable, fk, parentPk, 0);
+        return subs.map(sub => (subMeta ? this.assemble(subMeta, sub) : sub));
+    }
+}
+/** 按列名取值（宽松：忽略大小写） */
+export function findRowValue(row, columnName) {
+    for (const [k, v] of Object.entries(row)) {
+        if (k.toLowerCase() === columnName.toLowerCase())
+            return v;
+    }
+    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.6.6",
+  "version": "1.8.0",
   "description": "jeeflow workflow engine — Node.js / TypeScript implementation",
   "type": "module",
   "main": "./dist/index.js",