@mldong/jeeflow 1.8.3 → 1.8.5

package/README.md

@@ -18,7 +18,7 @@ const repo = new MemoryRepository()
 const engine = new EngineImpl(repo)
 
 const def = {
-  id: 1, name: 'leave', displayName: '请假审批',
+  id: '1', name: 'leave', displayName: '请假审批',
   content: JSON.stringify({ nodes: [...], edges: [...] })
 }
 repo.addDefine(def)
@@ -28,6 +28,28 @@ const tasks = await repo.findDoingTasks(inst.id)
 await engine.executeProcessTask(tasks[0].id, 'leader')
 ```
 
+> ⚠️ **id 全程 string（issue 38 E9）**：引擎内部与 API 契约的 id（流程定义/实例/任务/设计）一律为**字符串**。
+> Java 雪花 id（>2^53）超出 JS 安全整数，`Number()` 转换必丢精度；字符串可无损承载，保证四语言同库共享流程。
+
+## JDBC（MySQL/PostgreSQL）
+
+```ts
+import mysql from 'mysql2/promise'
+import { JdbcRepository, TsIDGenerator, MysqlAdapter } from '@mldong/jeeflow/jdbc'
+
+// ⚠️ 必须配置 bigNumberStrings（issue 38 E9）：BIGINT 列以 string 返回，
+// 否则 mysql2 默认转 number，Java 雪花 id（>2^53）在驱动层就已丢精度
+const pool = mysql.createPool({
+  host: 'localhost', user: 'root', password: '***', database: 'wf',
+  supportBigNumbers: true,
+  bigNumberStrings: true,
+})
+const repo = new JdbcRepository(new MysqlAdapter(pool), new TsIDGenerator())
+```
+
+- MySQL 连接池必须带 `supportBigNumbers: true, bigNumberStrings: true`；PostgreSQL 的 int8 默认即字符串，无此要求
+- 引擎侧已做驱动兜底：`rowId()` 把驱动返回的 number/string 统一归一化为 string，未开 `bigNumberStrings` 时小 id（Node 自建）仍可用
+
 ## 运行演示
 
 ```bash

package/dist/engine.d.ts

@@ -15,11 +15,11 @@ export declare const KeyProcessStartNextNodeOperator = "f_nextNodeOperator";
 export declare const KeyAutoExecute = "flow.auto";
 export declare const KeyAdminID = "flow.admin";
 export interface Engine {
-    startProcessInstanceById(defineId: number, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
-    executeProcessTask(taskId: number, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
-    executeAndJumpToEnd(taskId: number, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
-    executeAndJumpTask(taskId: number, operator: string, args: Record<string, any>, targetTaskName?: string): Promise<ProcessInstance>;
-    executeAndJumpToFirstTaskNode(taskId: number, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
+    startProcessInstanceById(defineId: string, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
+    executeProcessTask(taskId: string, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
+    executeAndJumpToEnd(taskId: string, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
+    executeAndJumpTask(taskId: string, operator: string, args: Record<string, any>, targetTaskName?: string): Promise<ProcessInstance>;
+    executeAndJumpToFirstTaskNode(taskId: string, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
 }
 export declare class EngineImpl implements Engine {
     private repo;
@@ -31,16 +31,21 @@ export declare class EngineImpl implements Engine {
     constructor(repo: ProcessRepository, userProv?: UserProvider | undefined, idGen?: IDGenerator | undefined, exprEval?: ExpressionEvaluator | undefined);
     setExtensions(ext: EngineExtensions): void;
     setRegistry(reg: HandlerRegistry): void;
+    private interceptorCache;
+    /** 定义级拦截器解析（issue 34，对齐 Java 模型级 postInterceptors）：
+     *  流程定义顶层 postInterceptors 声明 → 按名从 interceptorRegistry 取（未声明该流程不触发）；
+     *  未声明 → 回落引擎级列表（向后兼容）。结果按 defineId 缓存。 */
+    private resolveInterceptors;
     private firePre;
     /** 表达式求值（v1.5.0，门面 highLight 决策分支过滤用） */
     evalExpr(expr: string, vars: Record<string, any>): Promise<any>;
     private firePost;
     private fireEvent;
-    startProcessInstanceById(defineId: number, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
-    executeProcessTask(taskId: number, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
-    executeAndJumpToEnd(taskId: number, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
-    executeAndJumpTask(taskId: number, operator: string, args?: Record<string, any>, targetTaskName?: string): Promise<ProcessInstance>;
-    executeAndJumpToFirstTaskNode(taskId: number, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
+    startProcessInstanceById(defineId: string, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
+    executeProcessTask(taskId: string, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
+    executeAndJumpToEnd(taskId: string, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
+    executeAndJumpTask(taskId: string, operator: string, args?: Record<string, any>, targetTaskName?: string): Promise<ProcessInstance>;
+    executeAndJumpToFirstTaskNode(taskId: string, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
     private loadAndCheck;
     private executeNode;
     private evaluateDecision;

package/dist/engine.js

@@ -28,12 +28,50 @@ export class EngineImpl {
         this.idGen = idGen;
         this.exprEval = exprEval;
     }
-    setExtensions(ext) { this.ext = ext; }
+    setExtensions(ext) {
+        this.ext = ext;
+        this.interceptorCache = new Map();
+    }
     setRegistry(reg) { this.registry = reg; }
+    interceptorCache = new Map();
+    /** 定义级拦截器解析（issue 34，对齐 Java 模型级 postInterceptors）：
+     *  流程定义顶层 postInterceptors 声明 → 按名从 interceptorRegistry 取（未声明该流程不触发）；
+     *  未声明 → 回落引擎级列表（向后兼容）。结果按 defineId 缓存。 */
+    async resolveInterceptors(inst) {
+        if (!this.ext)
+            return [];
+        const defineId = inst.defineId;
+        if (defineId == null)
+            return this.ext.interceptors ?? [];
+        const cached = this.interceptorCache.get(defineId);
+        if (cached)
+            return cached;
+        let list = this.ext.interceptors ?? [];
+        try {
+            const def = await this.repo.findDefineById(defineId);
+            if (def) {
+                const content = typeof def.content === 'string' ? def.content : new TextDecoder().decode(def.content);
+                const meta = JSON.parse(content);
+                const declared = String(meta.postInterceptors ?? '').trim();
+                if (declared) {
+                    list = [];
+                    for (const name of declared.split(',').map(n => n.trim())) {
+                        const ic = this.ext.interceptorRegistry?.[name];
+                        if (name && ic)
+                            list.push(ic);
+                    }
+                }
+            }
+        }
+        catch { /* 解析失败回落引擎级 */ }
+        this.interceptorCache.set(defineId, list);
+        return list;
+    }
     async firePre(node, inst) {
-        if (!this.ext?.interceptors)
+        if (!this.ext?.interceptors && !this.ext?.interceptorRegistry)
             return true;
-        for (const ic of this.ext.interceptors.sort((a, b) => a.order - b.order))
+        const list = await this.resolveInterceptors(inst);
+        for (const ic of [...list].sort((a, b) => a.order - b.order))
             if (!(await ic.preHandle(node, inst)))
                 return false;
         return true;
@@ -45,9 +83,9 @@ export class EngineImpl {
         return this.exprEval.eval(expr, vars);
     }
     async firePost(node, inst) {
-        if (!this.ext?.interceptors)
+        if (!this.ext?.interceptors && !this.ext?.interceptorRegistry)
             return;
-        for (const ic of this.ext.interceptors)
+        for (const ic of await this.resolveInterceptors(inst))
             await ic.postHandle(node, inst);
     }
     async fireEvent(evt) {
@@ -435,7 +473,7 @@ export class EngineImpl {
     nextId() {
         if (this.idGen)
             return this.idGen.nextId();
-        return Date.now() * 1000 + Math.floor(Math.random() * 1000);
+        return String(Date.now() * 1000 + Math.floor(Math.random() * 1000));
     }
 }
 // ─── Pure Functions ──────────────────────────────────────────────────────────

package/dist/extensions.d.ts

@@ -26,14 +26,16 @@ export declare enum EventType {
 }
 export interface ProcessEvent {
     type: EventType;
-    instanceId: number;
-    taskId?: number;
+    instanceId: string;
+    taskId?: string;
     nodeId?: string;
     operator: string;
 }
 export type ProcessEventListener = (event: ProcessEvent) => void | Promise<void>;
 export interface EngineExtensions {
     interceptors?: FlowInterceptor[];
+    /** 定义级拦截器注册表（issue 34）：名字 → 实例；流程定义顶层 postInterceptors 按名解析 */
+    interceptorRegistry?: Record<string, FlowInterceptor>;
     assignmentHandler?: AssignmentHandler;
     decisionHandler?: DecisionHandler;
     listeners?: ProcessEventListener[];

package/dist/facade.d.ts

@@ -7,7 +7,12 @@ export declare class JeeflowFacade {
     private readonly extRepo?;
     private userSearch?;
     private orgProv?;
+    private metaReader?;
     constructor(engine: EngineImpl, repo: ProcessRepository, extRepo?: ProcessExtRepository | undefined);
+    /** 注入业务数据读取器（issue 30）：需有 readByProcessInstance(tableName, processInstanceId) */
+    setMetaReader(reader: {
+        readByProcessInstance(tableName: string, processInstanceId: unknown): unknown;
+    }): this;
     setUserSearch(fn: UserSearch): this;
     setOrgProvider(orgProv: OrgUserProvider): this;
     flow(action: string, args?: Record<string, any>): Promise<Record<string, any>>;
@@ -23,6 +28,16 @@ export declare class JeeflowFacade {
     private designUpdate;
     /** 更新流程设计定义（设计稿保存，issues/08）：content 快照入库 + 同步基本信息 + 置未部署 */
     private designUpdateDefine;
+    /** 删除设计稿（issues/28：兼容 {ids} 批量与单 {id}） */
+    private designRemove;
+    /** 删除定义（issues/28：兼容 {ids} 批量与单 {id}） */
+    private defineRemove;
+    /** 启用/停用（issues/28：兼容 {ids, opType} 批量；opType/state 二选一） */
+    private defineUpAndDown;
+    /** 按类型分组列出流程设计（issue 30，对齐 Java issues/28）：不依赖框架字典 */
+    private designListByType;
+    /** 按流程实例回显业务数据（issue 30，对齐 Java issues/28）：metaReader 注入式，未注入清晰报错 */
+    private bizData;
     /** 重新部署流程定义（issues/08）：替换最新定义内容 + 置已部署（对齐 boot3 redeploy） */
     private designRedeploy;
     private designDetail;

package/dist/facade.js

@@ -19,11 +19,17 @@ export class JeeflowFacade {
     extRepo;
     userSearch;
     orgProv;
+    metaReader;
     constructor(engine, repo, extRepo) {
         this.engine = engine;
         this.repo = repo;
         this.extRepo = extRepo;
     }
+    /** 注入业务数据读取器（issue 30）：需有 readByProcessInstance(tableName, processInstanceId) */
+    setMetaReader(reader) {
+        this.metaReader = reader;
+        return this;
+    }
     // 注入用户搜索钩子（candidatePage 无模型候选时的用户分页搜索）
     setUserSearch(fn) {
         this.userSearch = fn;
@@ -60,9 +66,9 @@ export class JeeflowFacade {
             case 'processDefine/redeploy':
                 return this.redeploy(args);
             case 'processDefine/remove':
-                return this.repo.removeDefine(toId(args.id));
+                return this.defineRemove(args);
             case 'processDefine/upAndDown':
-                return this.repo.updateDefineState(toId(args.id), toInt(args.state));
+                return this.defineUpAndDown(args);
             case 'processInstance/page':
                 return this.instancePage(args);
             case 'processInstance/detail':
@@ -86,7 +92,11 @@ export class JeeflowFacade {
             case 'processDesign/updateDefine':
                 return this.designUpdateDefine(args);
             case 'processDesign/remove':
-                return this.ext().removeDesign(toId(args.id));
+                return this.designRemove(args);
+            case 'processDesign/listByType':
+                return this.designListByType(args);
+            case 'processInstance/bizData':
+                return this.bizData(args);
             case 'processSurrogate/page':
                 return this.surrogatePage(args);
             case 'processSurrogate/save':
@@ -187,7 +197,7 @@ export class JeeflowFacade {
             version = (latest.version ?? 0) + 1;
         const operator = String(args.operator ?? 'system');
         const def = {
-            id: 0, name, displayName: flow.displayName ?? '', type: flow.type ?? 'approval',
+            id: '', name, displayName: flow.displayName ?? '', type: flow.type ?? 'approval',
             state: 1, content, version, createTime: new Date(), createUser: operator,
             updateTime: new Date(), updateUser: operator,
         };
@@ -292,14 +302,24 @@ export class JeeflowFacade {
         const design = await ext.findDesignById(designId);
         if (!design)
             throw new Error('流程设计不存在');
-        if (args.content == null)
-            throw new Error('content 缺失');
-        const content = toStr(args.content);
+        // issues/31：兼容 boot3 顶层 JSON（无 content 字段）——非保留字段序列化为内容快照
+        let content = args.content;
+        if (content == null) {
+            const copy = {};
+            for (const [k, v] of Object.entries(args)) {
+                if (k !== 'processDesignId' && k !== 'operator')
+                    copy[k] = v;
+            }
+            if (Object.keys(copy).length === 0)
+                throw new Error('content 缺失');
+            content = JSON.stringify(copy);
+        }
+        content = toStr(content);
         // 与最新一条相同则不重复入库（对齐 boot3 updateDefine）
         const hisList = await ext.listDesignHis(designId);
         if (hisList.length === 0 || toStr(hisList[0].content) !== content) {
             await ext.saveDesignHis({
-                id: 0, processDesignId: designId, content,
+                id: '', processDesignId: designId, content,
                 createTime: new Date(), createUser: String(args.operator ?? 'system'),
             });
         }
@@ -319,6 +339,93 @@ export class JeeflowFacade {
         await ext.updateDesign(design);
         return {};
     }
+    /** 删除设计稿（issues/28：兼容 {ids} 批量与单 {id}） */
+    async designRemove(args) {
+        const ext = this.ext();
+        if (Array.isArray(args.ids)) {
+            for (const id of args.ids)
+                await ext.removeDesign(toId(id));
+        }
+        else {
+            await ext.removeDesign(toId(args.id));
+        }
+        return {};
+    }
+    /** 删除定义（issues/28：兼容 {ids} 批量与单 {id}） */
+    async defineRemove(args) {
+        if (Array.isArray(args.ids)) {
+            for (const id of args.ids)
+                await this.repo.removeDefine(toId(id));
+        }
+        else {
+            await this.repo.removeDefine(toId(args.id));
+        }
+        return {};
+    }
+    /** 启用/停用（issues/28：兼容 {ids, opType} 批量；opType/state 二选一） */
+    async defineUpAndDown(args) {
+        const state = toInt(args.opType ?? args.state);
+        if (Array.isArray(args.ids)) {
+            for (const id of args.ids)
+                await this.repo.updateDefineState(toId(id), state);
+        }
+        else {
+            await this.repo.updateDefineState(toId(args.id), state);
+        }
+        return {};
+    }
+    /** 按类型分组列出流程设计（issue 30，对齐 Java issues/28）：不依赖框架字典 */
+    async designListByType(args) {
+        const ext = this.ext();
+        const pageNum = args.pageNum != null ? toInt(args.pageNum) : 1;
+        const pageSize = args.pageSize != null ? toInt(args.pageSize) : 10000;
+        const [rows] = await ext.pageDesigns(pageNum, pageSize, []);
+        // 每 name 最新 define（version 最大）
+        const { rows: defRows } = await this.repo.pageDefines(1, 10000, []);
+        const latestByName = new Map();
+        for (const r of defRows) {
+            const prev = latestByName.get(r.name);
+            if (!prev || r.version > prev.version)
+                latestByName.set(r.name, r);
+        }
+        const groups = {};
+        for (const d of rows) {
+            const key = d.type || '';
+            (groups[key] ??= []).push({
+                processDesignId: d.id,
+                name: d.name,
+                displayName: d.displayName,
+                icon: d.icon,
+                remark: d.remark,
+                processDefineId: latestByName.get(d.name)?.id ?? null,
+                processDefineState: latestByName.get(d.name)?.state ?? null,
+                jsonObject: this.parseGraph((await ext.listDesignHis(d.id))[0]?.content ?? ''),
+            });
+        }
+        return groups;
+    }
+    /** 按流程实例回显业务数据（issue 30，对齐 Java issues/28）：metaReader 注入式，未注入清晰报错 */
+    async bizData(args) {
+        const instanceId = toId(args.processInstanceId ?? args.id);
+        const inst = await this.repo.findInstanceById(instanceId);
+        if (!inst)
+            throw new Error('流程实例不存在');
+        const def = await this.repo.findDefineById(inst.defineId);
+        if (!def)
+            throw new Error('流程定义不存在');
+        const content = typeof def.content === 'string' ? def.content : new TextDecoder().decode(def.content);
+        let tableName = null;
+        try {
+            const meta = JSON.parse(content);
+            tableName = String(meta.relTableName ?? '').trim() || String(meta.name ?? '').trim() || null;
+        }
+        catch { /* ignore */ }
+        if (!tableName)
+            throw new Error('流程定义未配置 relTableName');
+        if (!this.metaReader)
+            throw new Error('业务数据读取器未注册（facade.setMetaReader(MetaTableReader(...))，需引入 jeeflow.meta）');
+        return this.metaReader.readByProcessInstance(tableName, instanceId);
+    }
     /** 重新部署流程定义（issues/08）：替换最新定义内容 + 置已部署（对齐 boot3 redeploy） */
     async designRedeploy(args) {
         const ext = this.ext();
@@ -394,11 +501,11 @@ export class JeeflowFacade {
     async designSave(args) {
         const ext = this.ext();
         const operator = String(args.operator ?? 'user1');
-        const designId = args.id != null ? toId(args.id) : 0;
+        const designId = args.id != null ? toId(args.id) : '';
         let design;
         if (!designId) {
             design = {
-                id: 0, name: String(args.name ?? ''), displayName: String(args.displayName ?? ''),
+                id: '', name: String(args.name ?? ''), displayName: String(args.displayName ?? ''),
                 type: String(args.type ?? 'approval'), icon: String(args.icon ?? ''),
                 isDeployed: 0, remark: String(args.remark ?? ''),
                 createTime: new Date(), createUser: operator,
@@ -428,7 +535,7 @@ export class JeeflowFacade {
         // 内容快照（设计稿内容存历史表）
         if (args.content != null) {
             await ext.saveDesignHis({
-                id: 0, processDesignId: design.id, content: String(args.content),
+                id: '', processDesignId: design.id, content: String(args.content),
                 createTime: new Date(), createUser: operator,
             });
         }
@@ -443,11 +550,11 @@ export class JeeflowFacade {
     async surrogateSave(args) {
         const ext = this.ext();
         const operator = String(args.operator ?? 'user1');
-        const surrogateId = args.id != null ? toId(args.id) : 0;
+        const surrogateId = args.id != null ? toId(args.id) : '';
         let surrogate;
         if (!surrogateId) {
             surrogate = {
-                id: 0, operator, // 授权人 = 操作人
+                id: '', operator, // 授权人 = 操作人
                 surrogate: String(args.surrogate ?? ''), processName: String(args.processName ?? ''),
                 enabled: toInt(args.enabled ?? 1),
                 createTime: new Date(), createUser: operator,
@@ -972,10 +1079,14 @@ function toStr(v) {
     return String(v);
 }
 function toId(v) {
-    const n = Number(v);
-    if (!Number.isFinite(n) || n <= 0)
+    // issue 38 E9：id 全程 string 承载——Java 雪花 id（>2^53）经 Number() 必丢精度。
+    // 数字输入（JS 安全整数内）转字符串；字符串输入原样保留（含超长雪花 id）。
+    if (v == null)
         throw new Error('id 缺失或非法');
-    return n;
+    const s = String(v).trim();
+    if (!/^\d+$/.test(s) || s === '0')
+        throw new Error('id 缺失或非法');
+    return s;
 }
 function toStringList2(v) {
     if (Array.isArray(v))

package/dist/index.d.ts

@@ -6,3 +6,6 @@ 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';
+export { JeeflowFacade } from './facade.js';
+export type { EngineExtensions, FlowInterceptor, ProcessEventListener, ProcessEvent, AssignmentHandler, DecisionHandler } from './extensions.js';
+export { JdbcProcessExtRepository } from './jdbc/ext.js';

package/dist/index.js

@@ -5,3 +5,6 @@ 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';
+// issues/35：包导出面补齐——门面/扩展类型/扩展仓储（集成方组装完整引擎链）
+export { JeeflowFacade } from './facade.js';
+export { JdbcProcessExtRepository } from './jdbc/ext.js';

package/dist/jdbc/ext.d.ts

@@ -9,21 +9,21 @@ export declare class JdbcProcessExtRepository implements ProcessExtRepository {
     private c;
     private done;
     private static DESIGN_COLS;
-    findDesignById(id: number): Promise<ProcessDesign | null>;
+    findDesignById(id: string): Promise<ProcessDesign | null>;
     saveDesign(d: ProcessDesign): Promise<void>;
     updateDesign(d: ProcessDesign): Promise<void>;
-    removeDesign(id: number): Promise<void>;
+    removeDesign(id: string): Promise<void>;
     pageDesigns(pageNum?: number, pageSize?: number, filters?: Record<string, any>, conditions?: QueryCondition[]): Promise<[ProcessDesign[], number]>;
     private buildExtWhere;
     private static readonly DESIGN_WHITELIST;
     private static readonly SURROGATE_WHITELIST;
     saveDesignHis(his: ProcessDesignHis): Promise<void>;
-    listDesignHis(designId: number): Promise<ProcessDesignHis[]>;
+    listDesignHis(designId: string): Promise<ProcessDesignHis[]>;
     private static SURROGATE_COLS;
-    findSurrogateById(id: number): Promise<ProcessSurrogate | null>;
+    findSurrogateById(id: string): Promise<ProcessSurrogate | null>;
     saveSurrogate(s: ProcessSurrogate): Promise<void>;
     updateSurrogate(s: ProcessSurrogate): Promise<void>;
-    removeSurrogate(id: number): Promise<void>;
+    removeSurrogate(id: string): Promise<void>;
     pageSurrogates(pageNum?: number, pageSize?: number, filters?: Record<string, any>, conditions?: QueryCondition[]): Promise<[ProcessSurrogate[], number]>;
     getSurrogate(operator: string, processName: string, at?: Date): Promise<ProcessSurrogate | null>;
     private querySurrogate;

package/dist/jdbc/ext.js

@@ -2,7 +2,7 @@
 //
 // 与 shared.ts 同一套 SqlAdapter / 占位符约定；分页为单表简单过滤（filters 字段名 EQ）。
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { TsIDGenerator } from './shared.js';
+import { TsIDGenerator, rowId } from './shared.js';
 const txStore = new AsyncLocalStorage();
 export class JdbcProcessExtRepository {
     adapter;
@@ -174,9 +174,9 @@ export class JdbcProcessExtRepository {
         try {
             const rows = await conn.fetchAll(this.sql('SELECT id, process_design_id, content, create_time, create_user FROM wf_process_design_his WHERE process_design_id = ? ORDER BY id DESC'), [designId]);
             return rows.map(r => ({
-                id: r.id, processDesignId: r.process_design_id,
+                id: rowId(r.id), processDesignId: rowId(r.process_design_id),
                 content: r.content ? Buffer.from(r.content).toString('utf8') : '',
-                createTime: r.create_time, createUser: r.create_user,
+                createTime: r.create_time, createUser: rowId(r.create_user),
             }));
         }
         finally {
@@ -300,18 +300,18 @@ export class JdbcProcessExtRepository {
     // ── 行映射 ───────────────────────────────────────────────────────────────
     mapDesign(row) {
         return {
-            id: row.id, name: row.name, displayName: row.display_name, type: row.type,
+            id: rowId(row.id), name: row.name, displayName: row.display_name, type: row.type,
             icon: row.icon, isDeployed: row.is_deployed, remark: row.remark,
-            createTime: row.create_time, createUser: row.create_user,
-            updateTime: row.update_time, updateUser: row.update_user,
+            createTime: row.create_time, createUser: rowId(row.create_user),
+            updateTime: row.update_time, updateUser: rowId(row.update_user),
         };
     }
     mapSurrogate(row) {
         return {
-            id: row.id, processName: row.process_name, operator: row.operator, surrogate: row.surrogate,
+            id: rowId(row.id), processName: row.process_name, operator: row.operator, surrogate: row.surrogate,
             startTime: row.start_time, endTime: row.end_time, enabled: row.enabled,
-            createTime: row.create_time, createUser: row.create_user,
-            updateTime: row.update_time, updateUser: row.update_user,
+            createTime: row.create_time, createUser: rowId(row.create_user),
+            updateTime: row.update_time, updateUser: rowId(row.update_user),
         };
     }
 }

package/dist/jdbc/shared.d.ts

@@ -1,11 +1,15 @@
 import { ProcessInstance, ProcessTask, type ProcessDefine, type CcInstanceRow, type DefineRow, type InstanceRow, type TaskRow } from '../model.js';
 import type { IDGenerator, ProcessRepository, QueryCondition } from '../spi.js';
-/** 默认 ID 生成器：时间戳毫秒 + 同毫秒递增序号（对齐 Java nextId 默认实现） */
+/** 默认 ID 生成器：时间戳毫秒 + 同毫秒递增序号（对齐 Java nextId 默认实现）——
+ *  issue 38 E9：返回 string（数字值在 2^53 内精确，转字符串统一承载） */
 export declare class TsIDGenerator implements IDGenerator {
     private last;
     private seq;
-    nextId(): number;
+    nextId(): string;
 }
+/** 行 id 归一化（issue 38 E9）：mysql2 可能返回 number（默认）或 string（bigNumberStrings），
+ *  统一转 string，保证引擎内部 id 全字符串、跨驱动一致 */
+export declare function rowId(v: any): string;
 /** 适配器返回的连接包装——最小接口 */
 export interface SqlConnection {
     execute(sql: string, args: any[]): Promise<void>;
@@ -35,34 +39,34 @@ export declare class JdbcRepository implements ProcessRepository {
     private c;
     /** 归还非事务连接（事务连接由 withTx 统一释放） */
     private done;
-    findDefineById(id: number): Promise<ProcessDefine | null>;
+    findDefineById(id: string): Promise<ProcessDefine | null>;
     saveDefine(define: ProcessDefine): Promise<void>;
     updateDefine(define: ProcessDefine): Promise<void>;
-    updateDefineState(defineId: number, state: number): Promise<void>;
-    removeDefine(defineId: number): Promise<void>;
+    updateDefineState(defineId: string, state: number): Promise<void>;
+    removeDefine(defineId: string): Promise<void>;
     findDefineByName(name: string): Promise<ProcessDefine | null>;
     private static INSTANCE_COLS;
-    findInstanceById(id: number): Promise<ProcessInstance | null>;
+    findInstanceById(id: string): Promise<ProcessInstance | null>;
     saveInstance(inst: ProcessInstance): Promise<void>;
     updateInstance(inst: ProcessInstance): Promise<void>;
     private static TASK_COLS;
-    findTaskById(taskId: number): Promise<ProcessTask | null>;
+    findTaskById(taskId: string): Promise<ProcessTask | null>;
     saveTask(task: ProcessTask): Promise<void>;
     updateTask(task: ProcessTask): Promise<void>;
     /** 用指定连接更新任务（实例级联时与实例更新同连接） */
     private updateTaskWithConn;
     private findTasksByState;
-    findDoingTasks(instanceId: number, taskNames?: string[]): Promise<ProcessTask[]>;
-    findDoneTasks(instanceId: number, taskNames?: string[]): Promise<ProcessTask[]>;
-    findHistoryTasks(instanceId: number): Promise<ProcessTask[]>;
+    findDoingTasks(instanceId: string, taskNames?: string[]): Promise<ProcessTask[]>;
+    findDoneTasks(instanceId: string, taskNames?: string[]): Promise<ProcessTask[]>;
+    findHistoryTasks(instanceId: string): Promise<ProcessTask[]>;
     private mapTask;
     private replaceTaskActors;
     private insertTaskActors;
-    findTaskActors(taskId: number): Promise<string[]>;
-    addTaskActor(taskId: number, actors: string[]): Promise<void>;
-    removeTaskActor(taskId: number, actors: string[]): Promise<void>;
-    createCcInstance(instanceId: number, creator: string, ...actorIds: string[]): Promise<void>;
-    updateCcStatus(instanceId: number, actorId: string): Promise<void>;
+    findTaskActors(taskId: string): Promise<string[]>;
+    addTaskActor(taskId: string, actors: string[]): Promise<void>;
+    removeTaskActor(taskId: string, actors: string[]): Promise<void>;
+    createCcInstance(instanceId: string, creator: string, ...actorIds: string[]): Promise<void>;
+    updateCcStatus(instanceId: string, actorId: string): Promise<void>;
     pageDefines(pageNum: number, pageSize: number, conditions?: QueryCondition[]): Promise<{
         rows: DefineRow[];
         total: number;

package/dist/jdbc/shared.js

@@ -37,7 +37,8 @@ const DEFINE_WHITELIST = new Set([
 ]);
 // 当前异步上下文绑定的事务连接
 const txStore = new AsyncLocalStorage();
-/** 默认 ID 生成器：时间戳毫秒 + 同毫秒递增序号（对齐 Java nextId 默认实现） */
+/** 默认 ID 生成器：时间戳毫秒 + 同毫秒递增序号（对齐 Java nextId 默认实现）——
+ *  issue 38 E9：返回 string（数字值在 2^53 内精确，转字符串统一承载） */
 export class TsIDGenerator {
     last = 0;
     seq = 0;
@@ -50,9 +51,14 @@ export class TsIDGenerator {
             this.last = now;
             this.seq = 0;
         }
-        return now * 1000 + this.seq;
+        return String(now * 1000 + this.seq);
     }
 }
+/** 行 id 归一化（issue 38 E9）：mysql2 可能返回 number（默认）或 string（bigNumberStrings），
+ *  统一转 string，保证引擎内部 id 全字符串、跨驱动一致 */
+export function rowId(v) {
+    return v == null ? '' : String(v);
+}
 /** 把核心 SQL 的统一 `?` 占位符转换为适配器风格 */
 export function convertPlaceholder(sql, style) {
     if (style === '$n') {
@@ -115,8 +121,8 @@ export class JdbcRepository {
                 id: row.id, name: row.name, displayName: row.display_name, type: row.type,
                 state: row.state,
                 content: row.content ? Buffer.from(row.content).toString('utf8') : '',
-                version: row.version, createTime: row.create_time, createUser: row.create_user,
-                updateTime: row.update_time, updateUser: row.update_user,
+                version: row.version, createTime: row.create_time, createUser: rowId(row.create_user),
+                updateTime: row.update_time, updateUser: rowId(row.update_user),
             };
         }
         finally {
@@ -180,11 +186,11 @@ export class JdbcRepository {
             if (!row)
                 return null;
             return {
-                id: row.id, name: row.name, displayName: row.display_name, type: row.type,
+                id: rowId(row.id), name: row.name, displayName: row.display_name, type: row.type,
                 state: row.state,
                 content: row.content ? Buffer.from(row.content).toString('utf8') : '',
-                version: row.version, createTime: row.create_time, createUser: row.create_user,
-                updateTime: row.update_time, updateUser: row.update_user,
+                version: row.version, createTime: row.create_time, createUser: rowId(row.create_user),
+                updateTime: row.update_time, updateUser: rowId(row.update_user),
             };
         }
         finally {
@@ -201,11 +207,12 @@ export class JdbcRepository {
             if (!row)
                 return null;
             const inst = new ProcessInstance({
-                id: row.id, parentId: row.parent_id, defineId: row.process_define_id,
+                id: rowId(row.id), parentId: row.parent_id != null ? rowId(row.parent_id) : undefined,
+                defineId: rowId(row.process_define_id),
                 state: row.state, parentNodeName: row.parent_node_name, businessNo: row.business_no,
                 operator: row.operator, expireTime: row.expire_time,
-                createTime: row.create_time, createUser: row.create_user,
-                updateTime: row.update_time, updateUser: row.update_user,
+                createTime: row.create_time, createUser: rowId(row.create_user),
+                updateTime: row.update_time, updateUser: rowId(row.update_user),
                 tasks: [],
             });
             inst.variables = row.variable ? JSON.parse(row.variable) : {};
@@ -318,7 +325,7 @@ export class JdbcRepository {
                 for (const t of tasks)
                     t.actorIds = [];
                 for (const r of actorRows) {
-                    const t = tasks.find(x => x.id === r.process_task_id);
+                    const t = tasks.find(x => x.id === rowId(r.process_task_id));
                     if (t)
                         t.actorIds.push(r.actor_id);
                 }
@@ -340,12 +347,13 @@ export class JdbcRepository {
     }
     mapTask(row) {
         const task = new ProcessTask({
-            id: row.id, processInstanceId: row.process_instance_id, taskName: row.task_name,
+            id: rowId(row.id), processInstanceId: rowId(row.process_instance_id), taskName: row.task_name,
             displayName: row.display_name, taskType: row.task_type, performType: row.perform_type,
             taskState: row.task_state, actorId: row.operator, finishTime: row.finish_time,
-            expireTime: row.expire_time, formKey: row.form_key, parentTaskId: row.task_parent_id,
-            createTime: row.create_time, createUser: row.create_user,
-            updateTime: row.update_time, updateUser: row.update_user,
+            expireTime: row.expire_time, formKey: row.form_key,
+            parentTaskId: row.task_parent_id != null ? rowId(row.task_parent_id) : undefined,
+            createTime: row.create_time, createUser: rowId(row.create_user),
+            updateTime: row.update_time, updateUser: rowId(row.update_user),
         });
         task.variables = row.variable ? JSON.parse(row.variable) : {};
         task.actorIds = [];
@@ -435,10 +443,10 @@ export class JdbcRepository {
                 where + ' ORDER BY t.id DESC LIMIT ? OFFSET ?'), [...cond.params, pageSize, (pageNum - 1) * pageSize]);
             return {
                 rows: rows.map(r => ({
-                    id: Number(r.id), name: r.name, displayName: r.display_name, type: r.type,
+                    id: rowId(r.id), name: r.name, displayName: r.display_name, type: r.type,
                     state: Number(r.state), version: Number(r.version),
-                    createTime: r.create_time, createUser: r.create_user ?? '',
-                    updateTime: r.update_time, updateUser: r.update_user ?? '',
+                    createTime: r.create_time, createUser: rowId(r.create_user),
+                    updateTime: r.update_time, updateUser: rowId(r.update_user),
                 })),
                 total,
             };
@@ -504,12 +512,12 @@ export class JdbcRepository {
             catch { /* 忽略坏 JSON */ }
         }
         return {
-            id: Number(r.id), parentId: r.parent_id != null ? Number(r.parent_id) : undefined,
-            defineId: Number(r.process_define_id), state: r.state,
+            id: rowId(r.id), parentId: r.parent_id != null ? rowId(r.parent_id) : undefined,
+            defineId: rowId(r.process_define_id), state: r.state,
             parentNodeName: r.parent_node_name ?? '', businessNo: r.business_no ?? '', operator: r.operator ?? '',
             expireTime: r.expire_time ?? undefined, variables,
-            createTime: r.create_time, createUser: r.create_user ?? '',
-            updateTime: r.update_time, updateUser: r.update_user ?? '',
+            createTime: r.create_time, createUser: rowId(r.create_user),
+            updateTime: r.update_time, updateUser: rowId(r.update_user),
             defineName: r.name ?? '', defineDisplayName: r.display_name ?? '',
             defineVersion: Number(r.version ?? 0),
         };
@@ -583,13 +591,13 @@ export class JdbcRepository {
             catch { /* 忽略坏 JSON */ }
         }
         return {
-            id: Number(r.id), processInstanceId: Number(r.process_instance_id), taskName: r.task_name,
+            id: rowId(r.id), processInstanceId: rowId(r.process_instance_id), taskName: r.task_name,
             displayName: r.display_name, taskType: Number(r.task_type), performType: Number(r.perform_type),
             taskState: r.task_state, operator: r.operator ?? '', finishTime: r.finish_time ?? undefined,
             expireTime: r.expire_time ?? undefined, formKey: r.form_key ?? '',
-            taskParentId: r.task_parent_id != null ? Number(r.task_parent_id) : undefined,
-            variables, createTime: r.create_time, createUser: r.create_user ?? '',
-            updateTime: r.update_time, updateUser: r.update_user ?? '',
+            taskParentId: r.task_parent_id != null ? rowId(r.task_parent_id) : undefined,
+            variables, createTime: r.create_time, createUser: rowId(r.create_user),
+            updateTime: r.update_time, updateUser: rowId(r.update_user),
             processDefineName: r.name ?? '', processDefineDisplayName: r.display_name ?? '',
             defineVersion: Number(r.process_define_version ?? 0),
             instanceVariable: r.instance_variable ?? '', instanceCreateTime: r.instance_create_time,
@@ -628,12 +636,12 @@ export class JdbcRepository {
             catch { /* 忽略坏 JSON */ }
         }
         return {
-            id: Number(r.id), parentId: r.parent_id != null ? Number(r.parent_id) : undefined,
-            defineId: Number(r.process_define_id), state: r.state,
+            id: rowId(r.id), parentId: r.parent_id != null ? rowId(r.parent_id) : undefined,
+            defineId: rowId(r.process_define_id), state: r.state,
             parentNodeName: r.parent_node_name ?? '', businessNo: r.business_no ?? '', operator: r.operator ?? '',
             expireTime: r.expire_time ?? undefined, variables,
-            createTime: r.create_time, createUser: r.create_user ?? '',
-            updateTime: r.update_time, updateUser: r.update_user ?? '',
+            createTime: r.create_time, createUser: rowId(r.create_user),
+            updateTime: r.update_time, updateUser: rowId(r.update_user),
             defineName: r.name ?? '', defineDisplayName: r.display_name ?? '',
             defineVersion: Number(r.version ?? 0),
         };

package/dist/memory-ext.d.ts

@@ -5,17 +5,17 @@ export declare class MemoryExtRepository implements ProcessExtRepository {
     private designHis;
     private surrogates;
     private seq;
-    findDesignById(id: number): Promise<ProcessDesign | null>;
+    findDesignById(id: string): Promise<ProcessDesign | null>;
     saveDesign(d: ProcessDesign): Promise<void>;
     updateDesign(d: ProcessDesign): Promise<void>;
-    removeDesign(id: number): Promise<void>;
+    removeDesign(id: string): Promise<void>;
     pageDesigns(_pageNum?: number, _pageSize?: number, _filters?: Record<string, any>, conditions?: QueryCondition[]): Promise<[ProcessDesign[], number]>;
     saveDesignHis(his: ProcessDesignHis): Promise<void>;
-    listDesignHis(designId: number): Promise<ProcessDesignHis[]>;
-    findSurrogateById(id: number): Promise<ProcessSurrogate | null>;
+    listDesignHis(designId: string): Promise<ProcessDesignHis[]>;
+    findSurrogateById(id: string): Promise<ProcessSurrogate | null>;
     saveSurrogate(s: ProcessSurrogate): Promise<void>;
     updateSurrogate(s: ProcessSurrogate): Promise<void>;
-    removeSurrogate(id: number): Promise<void>;
+    removeSurrogate(id: string): Promise<void>;
     pageSurrogates(_pageNum?: number, _pageSize?: number, filters?: Record<string, any>, conditions?: QueryCondition[]): Promise<[ProcessSurrogate[], number]>;
     getSurrogate(operator: string, processName: string, at?: Date): Promise<ProcessSurrogate | null>;
 }

package/dist/memory-ext.js

@@ -28,7 +28,7 @@ export class MemoryExtRepository {
     async findDesignById(id) { return this.designs.get(id) ?? null; }
     async saveDesign(d) {
         if (!d.id)
-            d.id = this.seq++;
+            d.id = String(this.seq++);
         const now = new Date();
         if (!d.createTime)
             d.createTime = now;
@@ -51,7 +51,7 @@ export class MemoryExtRepository {
     // ── 设计历史 ──
     async saveDesignHis(his) {
         if (!his.id)
-            his.id = this.seq++;
+            his.id = String(this.seq++);
         if (!his.createTime)
             his.createTime = new Date();
         const list = this.designHis.get(his.processDesignId) ?? [];
@@ -65,7 +65,7 @@ export class MemoryExtRepository {
     async findSurrogateById(id) { return this.surrogates.get(id) ?? null; }
     async saveSurrogate(s) {
         if (!s.id)
-            s.id = this.seq++;
+            s.id = String(this.seq++);
         const now = new Date();
         if (!s.createTime)
             s.createTime = now;

package/dist/memory.d.ts

@@ -13,26 +13,26 @@ export declare class MemoryRepository implements ProcessRepository {
     private ccInstances;
     private seq;
     addDefine(def: ProcessDefine): void;
-    findDefineById(id: number): Promise<ProcessDefine | null>;
+    findDefineById(id: string): Promise<ProcessDefine | null>;
     findDefineByName(name: string): Promise<ProcessDefine | null>;
     saveDefine(def: ProcessDefine): Promise<void>;
     updateDefine(def: ProcessDefine): Promise<void>;
-    updateDefineState(defineId: number, state: number): Promise<void>;
-    removeDefine(defineId: number): Promise<void>;
+    updateDefineState(defineId: string, state: number): Promise<void>;
+    removeDefine(defineId: string): Promise<void>;
     saveInstance(inst: ProcessInstance): Promise<void>;
     updateInstance(inst: ProcessInstance): Promise<void>;
-    findInstanceById(id: number): Promise<ProcessInstance | null>;
-    findTaskById(id: number): Promise<ProcessTask | null>;
+    findInstanceById(id: string): Promise<ProcessInstance | null>;
+    findTaskById(id: string): Promise<ProcessTask | null>;
     saveTask(task: ProcessTask): Promise<void>;
     updateTask(task: ProcessTask): Promise<void>;
-    findDoingTasks(instanceId: number, taskNames?: string[]): Promise<ProcessTask[]>;
-    findDoneTasks(instanceId: number, _taskNames?: string[]): Promise<ProcessTask[]>;
-    findHistoryTasks(instanceId: number): Promise<ProcessTask[]>;
-    findTaskActors(taskId: number): Promise<string[]>;
-    addTaskActor(taskId: number, actors: string[]): Promise<void>;
-    removeTaskActor(taskId: number, actors: string[]): Promise<void>;
-    createCcInstance(instanceId: number, _creator: string, ...actorIds: string[]): Promise<void>;
-    updateCcStatus(_instanceId: number, _actorId: string): Promise<void>;
+    findDoingTasks(instanceId: string, taskNames?: string[]): Promise<ProcessTask[]>;
+    findDoneTasks(instanceId: string, _taskNames?: string[]): Promise<ProcessTask[]>;
+    findHistoryTasks(instanceId: string): Promise<ProcessTask[]>;
+    findTaskActors(taskId: string): Promise<string[]>;
+    addTaskActor(taskId: string, actors: string[]): Promise<void>;
+    removeTaskActor(taskId: string, actors: string[]): Promise<void>;
+    createCcInstance(instanceId: string, _creator: string, ...actorIds: string[]): Promise<void>;
+    updateCcStatus(_instanceId: string, _actorId: string): Promise<void>;
     pageDefines(pageNum?: number, pageSize?: number, conditions?: QueryCondition[]): Promise<{
         rows: DefineRow[];
         total: number;

package/dist/memory.js

@@ -101,7 +101,7 @@ export class MemoryRepository {
     seq = 1;
     addDefine(def) {
         if (!def.id)
-            def.id = this.seq++;
+            def.id = String(this.seq++);
         this.defines.set(def.id, def);
     }
     async findDefineById(id) { return this.defines.get(id) ?? null; }
@@ -109,7 +109,8 @@ export class MemoryRepository {
     async findDefineByName(name) {
         let latest = null;
         for (const d of this.defines.values()) {
-            if (d.name === name && (!latest || d.id > latest.id))
+            // BigInt 比较：id 为 string（issue 38 E9），大整数数字比较不可靠
+            if (d.name === name && (!latest || BigInt(d.id) > BigInt(latest.id)))
                 latest = d;
         }
         return latest;
@@ -117,7 +118,7 @@ export class MemoryRepository {
     // ── 定义写操作（v1.0.1，对齐 SPI）──
     async saveDefine(def) {
         if (!def.id)
-            def.id = this.seq++;
+            def.id = String(this.seq++);
         this.defines.set(def.id, def);
     }
     async updateDefine(def) {
@@ -133,7 +134,7 @@ export class MemoryRepository {
     }
     async saveInstance(inst) {
         if (!inst.id)
-            inst.id = this.seq++;
+            inst.id = String(this.seq++);
         const cp = cloneInstance(inst);
         cp.tasks = [];
         this.instances.set(inst.id, cp);
@@ -178,7 +179,7 @@ export class MemoryRepository {
     }
     async saveTask(task) {
         if (!task.id)
-            task.id = this.seq++;
+            task.id = String(this.seq++);
         const cp = cloneTask(task);
         cp.actorIds = [];
         this.tasks.set(task.id, cp);

package/dist/model.d.ts

@@ -32,7 +32,7 @@ export declare const TypeFork = "snaker:fork";
 export declare const TypeJoin = "snaker:join";
 export declare const TypeCustom = "snaker:custom";
 export interface ProcessDefine {
-    id: number;
+    id: string;
     name: string;
     displayName: string;
     type: string;
@@ -45,7 +45,7 @@ export interface ProcessDefine {
     updateUser: string;
 }
 export interface ProcessDesign {
-    id: number;
+    id: string;
     name: string;
     displayName: string;
     type: string;
@@ -58,14 +58,14 @@ export interface ProcessDesign {
     updateUser: string;
 }
 export interface ProcessDesignHis {
-    id: number;
-    processDesignId: number;
+    id: string;
+    processDesignId: string;
     content: Uint8Array | string;
     createTime: Date;
     createUser: string;
 }
 export interface ProcessSurrogate {
-    id: number;
+    id: string;
     processName?: string;
     operator: string;
     surrogate: string;
@@ -128,9 +128,9 @@ export declare enum CountersignType {
 }
 export declare const BusinessNoKey = "BUSINESS_NO";
 export declare class ProcessInstance {
-    id: number;
-    parentId?: number;
-    defineId: number;
+    id: string;
+    parentId?: string;
+    defineId: string;
     state: InstanceState;
     parentNodeName: string;
     businessNo: string;
@@ -144,7 +144,7 @@ export declare class ProcessInstance {
     updateUser: string;
     constructor(data: any);
     /** 工厂——创建流程实例 */
-    static create(id: number, defineId: number, operator: string, vars: Record<string, any>, now: Date): ProcessInstance;
+    static create(id: string, defineId: string, operator: string, vars: Record<string, any>, now: Date): ProcessInstance;
     /** 完成任务（子实体状态转换 + 实例变量合并） */
     completeTask(task: ProcessTask, operator: string, vars: Record<string, any>, now: Date): void;
     /** 废弃单个任务 */
@@ -164,11 +164,11 @@ export declare class ProcessInstance {
     /** 所有任务是否都已完成（join 合并判断） */
     isAllTasksFinished(): boolean;
     /** 创建任务（子实体工厂） */
-    createTask(id: number, taskName: string, displayName: string, actor: string, operator: string, formKey: string, now: Date): ProcessTask;
+    createTask(id: string, taskName: string, displayName: string, actor: string, operator: string, formKey: string, now: Date): ProcessTask;
 }
 export declare class ProcessTask {
-    id: number;
-    processInstanceId: number;
+    id: string;
+    processInstanceId: string;
     taskName: string;
     displayName: string;
     taskType: number;
@@ -179,7 +179,7 @@ export declare class ProcessTask {
     finishTime?: Date;
     expireTime?: Date;
     formKey: string;
-    parentTaskId?: number;
+    parentTaskId?: string;
     variables: Record<string, any>;
     createTime: Date;
     createUser: string;
@@ -208,9 +208,9 @@ export interface UserInfo {
     postName?: string;
 }
 export interface CcInstanceRow {
-    id: number;
-    parentId?: number;
-    defineId: number;
+    id: string;
+    parentId?: string;
+    defineId: string;
     state: InstanceState;
     parentNodeName: string;
     businessNo: string;
@@ -226,7 +226,7 @@ export interface CcInstanceRow {
     defineVersion: number;
 }
 export interface DefineRow {
-    id: number;
+    id: string;
     name: string;
     displayName: string;
     type: string;
@@ -238,9 +238,9 @@ export interface DefineRow {
     updateUser: string;
 }
 export interface InstanceRow {
-    id: number;
-    parentId?: number;
-    defineId: number;
+    id: string;
+    parentId?: string;
+    defineId: string;
     state: InstanceState;
     parentNodeName: string;
     businessNo: string;
@@ -256,8 +256,8 @@ export interface InstanceRow {
     defineVersion: number;
 }
 export interface TaskRow {
-    id: number;
-    processInstanceId: number;
+    id: string;
+    processInstanceId: string;
     taskName: string;
     displayName: string;
     taskType: number;
@@ -267,7 +267,7 @@ export interface TaskRow {
     finishTime?: Date;
     expireTime?: Date;
     formKey: string;
-    taskParentId?: number;
+    taskParentId?: string;
     variables: Record<string, any>;
     createTime: Date;
     createUser: string;

package/dist/persist.d.ts

@@ -61,7 +61,7 @@ export declare class SqliteDynamicTableWriter implements DynamicTableWriter {
     private resolveDefaultUser;
 }
 /** 流程定义加载器（用于解析 relTableName / persistMode / 流程 name），通常透传仓库 findDefineById */
-export type DefineLoader = (defineId: number) => Promise<ProcessDefine | null>;
+export type DefineLoader = (defineId: string) => Promise<ProcessDefine | null>;
 /** 持久化模式（流程定义顶层 persistMode，缺省 ARCHIVE） */
 export declare const PersistModeArchive = "ARCHIVE";
 export declare const PersistModeSync = "SYNC";

package/dist/spi.d.ts

@@ -5,26 +5,26 @@ export interface QueryCondition {
     value: any;
 }
 export interface ProcessRepository {
-    findDefineById(id: number): Promise<ProcessDefine | null>;
+    findDefineById(id: string): Promise<ProcessDefine | null>;
     findDefineByName(name: string): Promise<ProcessDefine | null>;
     saveDefine(define: ProcessDefine): Promise<void>;
     updateDefine(define: ProcessDefine): Promise<void>;
-    updateDefineState(defineId: number, state: number): Promise<void>;
-    removeDefine(defineId: number): Promise<void>;
-    findInstanceById(id: number): Promise<ProcessInstance | null>;
+    updateDefineState(defineId: string, state: number): Promise<void>;
+    removeDefine(defineId: string): Promise<void>;
+    findInstanceById(id: string): Promise<ProcessInstance | null>;
     saveInstance(inst: ProcessInstance): Promise<void>;
     updateInstance(inst: ProcessInstance): Promise<void>;
-    findTaskById(taskId: number): Promise<ProcessTask | null>;
+    findTaskById(taskId: string): Promise<ProcessTask | null>;
     saveTask(task: ProcessTask): Promise<void>;
     updateTask(task: ProcessTask): Promise<void>;
-    findDoingTasks(instanceId: number, taskNames?: string[]): Promise<ProcessTask[]>;
-    findDoneTasks(instanceId: number, taskNames?: string[]): Promise<ProcessTask[]>;
-    findHistoryTasks(instanceId: number): Promise<ProcessTask[]>;
-    findTaskActors(taskId: number): Promise<string[]>;
-    addTaskActor(taskId: number, actors: string[]): Promise<void>;
-    removeTaskActor(taskId: number, actors: string[]): Promise<void>;
-    createCcInstance(instanceId: number, creator: string, ...actorIds: string[]): Promise<void>;
-    updateCcStatus(instanceId: number, actorId: string): Promise<void>;
+    findDoingTasks(instanceId: string, taskNames?: string[]): Promise<ProcessTask[]>;
+    findDoneTasks(instanceId: string, taskNames?: string[]): Promise<ProcessTask[]>;
+    findHistoryTasks(instanceId: string): Promise<ProcessTask[]>;
+    findTaskActors(taskId: string): Promise<string[]>;
+    addTaskActor(taskId: string, actors: string[]): Promise<void>;
+    removeTaskActor(taskId: string, actors: string[]): Promise<void>;
+    createCcInstance(instanceId: string, creator: string, ...actorIds: string[]): Promise<void>;
+    updateCcStatus(instanceId: string, actorId: string): Promise<void>;
     pageCcInstances(pageNum: number, pageSize: number, actorId: string, conditions?: QueryCondition[]): Promise<{
         rows: CcInstanceRow[];
         total: number;
@@ -58,23 +58,23 @@ export interface OrgUserProvider {
     findByRole(roleCode: string): Promise<string[]>;
 }
 export interface IDGenerator {
-    nextId(): number;
+    nextId(): string;
 }
 export interface ExpressionEvaluator {
     eval(expr: string, vars: Record<string, any>): Promise<any>;
 }
 export interface ProcessExtRepository {
-    findDesignById(id: number): Promise<ProcessDesign | null>;
+    findDesignById(id: string): Promise<ProcessDesign | null>;
     saveDesign(d: ProcessDesign): Promise<void>;
     updateDesign(d: ProcessDesign): Promise<void>;
-    removeDesign(id: number): Promise<void>;
+    removeDesign(id: string): Promise<void>;
     pageDesigns(pageNum?: number, pageSize?: number, filters?: Record<string, any>, conditions?: QueryCondition[]): Promise<[ProcessDesign[], number]>;
     saveDesignHis(his: ProcessDesignHis): Promise<void>;
-    listDesignHis(designId: number): Promise<ProcessDesignHis[]>;
-    findSurrogateById(id: number): Promise<ProcessSurrogate | null>;
+    listDesignHis(designId: string): Promise<ProcessDesignHis[]>;
+    findSurrogateById(id: string): Promise<ProcessSurrogate | null>;
     saveSurrogate(s: ProcessSurrogate): Promise<void>;
     updateSurrogate(s: ProcessSurrogate): Promise<void>;
-    removeSurrogate(id: number): Promise<void>;
+    removeSurrogate(id: string): Promise<void>;
     pageSurrogates(pageNum?: number, pageSize?: number, filters?: Record<string, any>, conditions?: QueryCondition[]): Promise<[ProcessSurrogate[], number]>;
     getSurrogate(operator: string, processName: string, at?: Date): Promise<ProcessSurrogate | null>;
 }

package/package.json

@@ -1,47 +1,48 @@
-{
-  "name": "@mldong/jeeflow",
-  "version": "1.8.3",
-  "description": "jeeflow workflow engine — Node.js / TypeScript implementation",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": "./dist/index.js",
-    "./engine": "./dist/engine.js",
-    "./model": "./dist/model.js",
-    "./spi": "./dist/spi.js",
-    "./memory": "./dist/memory.js",
-    "./jdbc": "./dist/jdbc/index.js",
-    "./mysql": "./dist/jdbc/mysql.js",
-    "./postgres": "./dist/jdbc/postgres.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "node --import tsx __tests__/spec.test.ts",
-    "demo": "node --import tsx demo/main.ts",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "workflow",
-    "engine",
-    "jeeflow",
-    "typescript"
-  ],
-  "license": "Apache-2.0",
-  "devDependencies": {
-    "@types/express": "^4.17.25",
-    "@types/pg": "^8.20.3",
-    "express": "^4.22.2",
-    "tsx": "^4.19.0",
-    "typescript": "^5.5.0"
-  },
-  "optionalDependencies": {
-    "mysql2": "^3.11.0",
-    "pg": "^8.13.0"
-  },
-  "files": [
-    "dist",
-    "LICENSE",
-    "README.md"
-  ]
-}
+{
+  "name": "@mldong/jeeflow",
+  "version": "1.8.5",
+  "description": "jeeflow workflow engine — Node.js / TypeScript implementation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./engine": "./dist/engine.js",
+    "./model": "./dist/model.js",
+    "./spi": "./dist/spi.js",
+    "./memory": "./dist/memory.js",
+    "./jdbc": "./dist/jdbc/index.js",
+    "./mysql": "./dist/jdbc/mysql.js",
+    "./postgres": "./dist/jdbc/postgres.js",
+    "./jdbc/ext": "./dist/jdbc/ext.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx __tests__/spec.test.ts",
+    "demo": "node --import tsx demo/main.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "workflow",
+    "engine",
+    "jeeflow",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/express": "^4.17.25",
+    "@types/pg": "^8.20.3",
+    "express": "^4.22.2",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  },
+  "optionalDependencies": {
+    "mysql2": "^3.11.0",
+    "pg": "^8.13.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ]
+}