@mldong/jeeflow 1.0.0 → 1.2.0

package/README.md

@@ -1,55 +1,58 @@
-# jeeflow · Node.js / TypeScript
-
-[jeeflow](https://jeeflow-doc.mldong.com) 引擎规范的 **TypeScript 实现**。仅依赖 `node:*` 标准库，零外部依赖（引擎核心）。
-
-```bash
-npm install jeeflow   # 等发布到 npm 后
-```
-
-## 快速开始
-
-```ts
-import { EngineImpl, MemoryRepository } from 'jeeflow'
-
-const repo = new MemoryRepository()
-const engine = new EngineImpl(repo)
-
-const def = {
-  id: 1, name: 'leave', displayName: '请假审批',
-  content: JSON.stringify({ nodes: [...], edges: [...] })
-}
-repo.addDefine(def)
-
-const inst = await engine.startProcessInstanceById(def.id, '张三')
-const tasks = await repo.findDoingTasks(inst.id)
-await engine.executeProcessTask(tasks[0].id, 'leader')
-```
-
-## 运行演示
-
-```bash
-git clone https://github.com/mldong/jeeflow-node
-cd jeeflow-node
-npm install
-npm run demo     # http://localhost:8082
-```
-
-## 目录
-
-| 路径 | 说明 |
-|------|------|
-| `src/engine.ts` | 引擎核心 |
-| `src/model.ts` | 域类型 |
-| `src/spi.ts` | SPI 接口 |
-| `src/memory.ts` | 内存仓储 |
-| `src/jdbc/` | JDBC 多库实现（shared 核心 + mysql/postgres 适配器） |
-| `demo/main.ts` | Express 演示 |
-| `__tests__/` | 9 项合规测试 |
-
-## 节点支持
-
-对齐 [SPEC.md](https://jeeflow-doc.mldong.com) v1.0——与 Java/Go 版一致。
-
-## License
-
-Apache-2.0
+# jeeflow · Node.js / TypeScript
+
+[jeeflow](https://jeeflow-doc.mldong.com) 引擎规范的 **TypeScript 实现**。仅依赖 `node:*` 标准库，零外部依赖（引擎核心）。
+
+> **v1.1.0**：新增管理扩展（流程设计/历史/委托 + `ProcessExtRepository`）与统一门面
+> `JeeflowFacade.flow(action, args)`；assignee 变量解析与 `flow.auto`/`flow.admin` 系统代执行对齐 boot2/boot3。
+
+```bash
+npm install @mldong/jeeflow   # 等发布到 npm 后
+```
+
+## 快速开始
+
+```ts
+import { EngineImpl, MemoryRepository } from '@mldong/jeeflow'
+
+const repo = new MemoryRepository()
+const engine = new EngineImpl(repo)
+
+const def = {
+  id: 1, name: 'leave', displayName: '请假审批',
+  content: JSON.stringify({ nodes: [...], edges: [...] })
+}
+repo.addDefine(def)
+
+const inst = await engine.startProcessInstanceById(def.id, '张三')
+const tasks = await repo.findDoingTasks(inst.id)
+await engine.executeProcessTask(tasks[0].id, 'leader')
+```
+
+## 运行演示
+
+```bash
+git clone https://github.com/mldong/jeeflow-node
+cd jeeflow-node
+npm install
+npm run demo     # http://localhost:8082
+```
+
+## 目录
+
+| 路径 | 说明 |
+|------|------|
+| `src/engine.ts` | 引擎核心 |
+| `src/model.ts` | 域类型 |
+| `src/spi.ts` | SPI 接口 |
+| `src/memory.ts` | 内存仓储 |
+| `src/jdbc/` | JDBC 多库实现（shared 核心 + mysql/postgres 适配器） |
+| `demo/main.ts` | Express 演示 |
+| `__tests__/` | 9 项合规测试 |
+
+## 节点支持
+
+对齐 [SPEC.md](https://jeeflow-doc.mldong.com) v1.0——与 Java/Go 版一致。
+
+## License
+
+Apache-2.0

package/dist/engine.d.ts

@@ -10,6 +10,9 @@ export declare const KeyDeptID = "u_deptId";
 export declare const KeyDeptName = "u_deptName";
 export declare const KeyPostID = "u_postId";
 export declare const KeyPostName = "u_postName";
+export declare const KeyNextNodeOperator = "tf_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>;

package/dist/engine.js

@@ -8,6 +8,11 @@ export const KeyDeptID = 'u_deptId';
 export const KeyDeptName = 'u_deptName';
 export const KeyPostID = 'u_postId';
 export const KeyPostName = 'u_postName';
+// v1.0.1：下一节点处理人（对齐 boot3 tf_nextNodeOperator）
+export const KeyNextNodeOperator = 'tf_nextNodeOperator';
+// v1.0.1：系统代执行 / 超级管理员（对齐 boot3 FlowConst）
+export const KeyAutoExecute = 'flow.auto';
+export const KeyAdminID = 'flow.admin';
 export class EngineImpl {
     repo;
     userProv;
@@ -74,6 +79,9 @@ export class EngineImpl {
         // 聚合根：完成任务（子实体状态转换 + 实例变量合并）
         inst.completeTask(task, operator, vars, now);
         await this.repo.updateTask(task);
+        // v1.0.1：updateInstance 级联持久化依赖聚合内任务副本为最新状态，
+        // completeTask 改的是外部任务对象，需同步回聚合根
+        syncTaskToAggregate(inst, task);
         await this.fireEvent({ type: EventType.TaskComplete, instanceId: inst.id, taskId: task.id, nodeId: task.taskName, operator });
         const def = await this.repo.findDefineById(inst.defineId);
         const flow = JSON.parse(typeof def.content === 'string' ? def.content : new TextDecoder().decode(def.content));
@@ -132,6 +140,8 @@ export class EngineImpl {
         // 子实体：完成任务
         task.finish(operator, task.variables, now);
         await this.repo.updateTask(task);
+        // v1.0.1：同步回聚合根，避免 updateInstance 级联把任务写回旧状态
+        syncTaskToAggregate(inst, task);
         // 聚合根：驳回
         inst.reject(now);
         await this.repo.updateInstance(inst);
@@ -286,8 +296,8 @@ export class EngineImpl {
             }
         }
     }
-    async createTask(node, inst, operator, _vars) {
-        const actors = await this.resolveActors(node, inst);
+    async createTask(node, inst, operator, vars) {
+        const actors = await this.resolveActors(node, inst, vars);
         if (!actors.length)
             return;
         const performType = parseInt(String(node.properties?.performType ?? '0'));
@@ -316,9 +326,13 @@ export class EngineImpl {
                     return;
             }
         }
-        await this.repo.saveTask(inst.createTask(this.nextId(), node.id, node.text.value, actors[0], operator, form, now));
+        // 普通任务：一个任务承载全部参与者（对齐 boot3 createTask + addTaskActor，多参与者任一可办）
+        const nt = inst.createTask(this.nextId(), node.id, node.text.value, actors[0], operator, form, now);
+        if (actors.length > 1)
+            nt.actorIds = actors;
+        await this.repo.saveTask(nt);
     }
-    async resolveActors(node, inst) {
+    async resolveActors(node, inst, vars) {
         // 1a. Registry 按名称解析（推荐）
         if (this.registry) {
             const handlerName = node.properties?.assignmentHandler ?? '';
@@ -335,21 +349,56 @@ export class EngineImpl {
             if (Array.isArray(result) && result.length > 0)
                 return result;
         }
-        // 2. 固定指派 assignee（boot2 约定："applicant" → 解析为流程发起人）
+        // 2. 动态指定下一节点处理人优先（v1.0.1：对齐 boot3 tf_nextNodeOperator）
+        const nextOp = vars[KeyNextNodeOperator];
+        if (nextOp != null) {
+            if (typeof nextOp === 'string')
+                return nextOp.split(',').map(s => s.trim()).filter(Boolean);
+            if (Array.isArray(nextOp))
+                return nextOp.map(String);
+            return [String(nextOp)];
+        }
+        // 3. 固定指派 assignee——token 即变量 key，能替换就换，换不了就是字面量（v1.0.1 对齐 boot3 args.get(token, token)）
         const assignee = node.properties?.assignee;
         if (assignee) {
-            const actors = assignee.split(',').map(s => s.trim()).filter(Boolean);
-            return actors.map(a => (a === 'applicant' ? inst.operator : a));
+            const actors = [];
+            for (const raw of assignee.split(',')) {
+                let token = raw.trim();
+                if (!token)
+                    continue;
+                // mldong 契约特殊值：applicant → 流程发起人
+                if (token.includes('applicant'))
+                    token = token.replace('applicant', inst.operator);
+                if (token in vars) {
+                    const val = vars[token];
+                    if (Array.isArray(val))
+                        actors.push(...val.map(String));
+                    else
+                        actors.push(String(val));
+                }
+                else {
+                    actors.push(token);
+                }
+            }
+            return actors;
         }
         return [];
     }
     isAllowed(task, operator) {
+        // v1.0.1：系统代执行（flow.auto）/超级管理员（flow.admin）放行（对齐 boot3 isAllowed）
+        if (operator && (operator.toLowerCase() === KeyAutoExecute || operator.toLowerCase() === KeyAdminID)) {
+            return true;
+        }
         // 子实体：actorIds 权限判断
         return task.isAllowed(operator);
     }
     async addUserInfo(operator, vars) {
         if (!this.userProv)
             return;
+        // v1.0.1：系统代执行（flow.auto）/超级管理员（flow.admin）非真实用户，跳过注入（对齐 boot3）
+        if (operator && (operator.toLowerCase() === KeyAutoExecute || operator.toLowerCase() === KeyAdminID)) {
+            return;
+        }
         const u = await this.userProv.getUser(operator);
         if (!u)
             return;
@@ -389,6 +438,16 @@ function getCsState(vars, nodeId) {
     const lc = parseInt(String(vars[`loopCounter_${nodeId}`] ?? '0'));
     return [actors, lc];
 }
+// syncTaskToAggregate 把外部任务对象的最新状态同步回聚合根任务副本
+// （v1.0.1：updateInstance 级联持久化依赖聚合内任务副本为最新状态）
+function syncTaskToAggregate(inst, task) {
+    for (let i = 0; i < inst.tasks.length; i++) {
+        if (inst.tasks[i].id === task.id) {
+            inst.tasks[i] = task;
+            return;
+        }
+    }
+}
 function isTruthy(v) {
     if (typeof v === 'boolean')
         return v;

package/dist/facade.d.ts

@@ -0,0 +1,38 @@
+import type { ProcessExtRepository, ProcessRepository } from './spi.js';
+import type { EngineImpl } from './engine.js';
+export type UserSearch = (query: Record<string, any>) => Promise<[Record<string, any>[], number]> | [Record<string, any>[], number];
+export declare class JeeflowFacade {
+    private readonly engine;
+    private readonly repo;
+    private readonly extRepo?;
+    private userSearch?;
+    constructor(engine: EngineImpl, repo: ProcessRepository, extRepo?: ProcessExtRepository | undefined);
+    setUserSearch(fn: UserSearch): this;
+    flow(action: string, args?: Record<string, any>): Promise<Record<string, any>>;
+    private dispatch;
+    private startAndExecute;
+    private deploy;
+    private saveDeployedDefine;
+    private redeploy;
+    private withdraw;
+    private execute;
+    private designPage;
+    private designDetail;
+    private designSave;
+    private surrogatePage;
+    private surrogateSave;
+    private getLastByName;
+    private highLight;
+    private collectPath;
+    private approvalRecord;
+    private getAssigneeTextData;
+    private createCCInstance;
+    private updateCCStatus;
+    private taskDetail;
+    private jumpAbleTaskNameList;
+    private candidatePage;
+    private nextTaskCandidates;
+    private taskAddActor;
+    private taskLatest;
+    private ext;
+}