@mldong/jeeflow 1.8.22 → 1.8.25

package/dist/engine.d.ts

@@ -1,6 +1,6 @@
 import { ProcessInstance } from './model.js';
 import type { ProcessRepository, UserProvider, IDGenerator, ExpressionEvaluator } from './spi.js';
-import { type EngineExtensions } from './extensions.js';
+import { type EngineExtensions, type ProcessEvent } from './extensions.js';
 import { HandlerRegistry } from './registry.js';
 export declare const KeySubmitType = "submitType";
 export declare const KeyBusinessNo = "BUSINESS_NO";
@@ -23,6 +23,7 @@ export interface Engine {
     executeAndJumpToFirstTaskNode(taskId: string, operator: string, args?: Record<string, any>): Promise<ProcessInstance>;
 }
 export declare class EngineImpl implements Engine {
+    #private;
     private repo;
     private userProv?;
     private idGen?;
@@ -43,7 +44,7 @@ export declare class EngineImpl implements Engine {
     /** 表达式求值（v1.5.0，门面 highLight 决策分支过滤用） */
     evalExpr(expr: string, vars: Record<string, any>): Promise<any>;
     private firePost;
-    private fireEvent;
+    fireEvent(evt: ProcessEvent): Promise<void>;
     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>;

package/dist/engine.js

@@ -97,10 +97,23 @@ export class EngineImpl {
             await ic.postHandle(node, inst);
     }
     async fireEvent(evt) {
+        // 公开事件发布入口（issues/102 CC_CREATE）：facade 层 CC 实例创建后逐抄送人 fire；
+        // 无监听器（ext/listeners 为空）时零副作用，与上一版逐字节一致
+        await this.#fireEvent(evt);
+    }
+    async #fireEvent(evt) {
         if (!this.ext?.listeners)
             return;
-        for (const l of this.ext.listeners)
-            await l(evt);
+        // 兜底语义（issues/104 P2 统一口径）：单监听器异常只记录不传播——
+        // 不得影响引擎主流程，也不得中断后续监听器（对齐 PHP per-listener catch）
+        for (const l of this.ext.listeners) {
+            try {
+                await l(evt);
+            }
+            catch (e) {
+                console.error(`[jeeflow] process event listener error: type=${evt.type} instanceId=${evt.instanceId}`, e);
+            }
+        }
     }
     // ─── Start ─────────────────────────────────────────────────────────────────
     async startProcessInstanceById(defineId, operator, args = {}) {
@@ -155,6 +168,8 @@ export class EngineImpl {
                             [`operatorList_${curNode.id}`]: actors,
                         };
                         await this.repo.saveTask(nt);
+                        // TASK_CREATE：顺序会签推进新任务落库后 fire（对齐 Java CreateTaskHandler / Rust）
+                        await this.fireEvent({ type: EventType.TaskCreate, instanceId: inst.id, taskId: nt.id, nodeId: curNode.id, operator });
                         return (await this.repo.findInstanceById(inst.id));
                     }
                 }
@@ -340,8 +355,11 @@ export class EngineImpl {
             switch (ct) {
                 case 'PARALLEL':
                 case '':
-                    for (const actor of actors)
-                        await this.repo.saveTask(inst.createTask(this.nextId(), node.id, node.text.value, actor, operator, form, now, 1));
+                    for (const actor of actors) {
+                        const nt = inst.createTask(this.nextId(), node.id, node.text.value, actor, operator, form, now, 1);
+                        await this.repo.saveTask(nt);
+                        await this.fireEvent({ type: EventType.TaskCreate, instanceId: inst.id, taskId: nt.id, nodeId: node.id, operator });
+                    }
                     return;
                 case 'SEQUENTIAL': {
                     const nt = inst.createTask(this.nextId(), node.id, node.text.value, actors[0], operator, form, now, 1);
@@ -351,11 +369,15 @@ export class EngineImpl {
                         [`operatorList_${node.id}`]: actors,
                     };
                     await this.repo.saveTask(nt);
+                    await this.fireEvent({ type: EventType.TaskCreate, instanceId: inst.id, taskId: nt.id, nodeId: node.id, operator });
                     return;
                 }
                 default:
-                    for (const actor of actors)
-                        await this.repo.saveTask(inst.createTask(this.nextId(), node.id, node.text.value, actor, operator, form, now, 1));
+                    for (const actor of actors) {
+                        const nt = inst.createTask(this.nextId(), node.id, node.text.value, actor, operator, form, now, 1);
+                        await this.repo.saveTask(nt);
+                        await this.fireEvent({ type: EventType.TaskCreate, instanceId: inst.id, taskId: nt.id, nodeId: node.id, operator });
+                    }
                     return;
             }
         }
@@ -363,6 +385,7 @@ export class EngineImpl {
         if (actors.length > 1)
             nt.actorIds = actors;
         await this.repo.saveTask(nt);
+        await this.fireEvent({ type: EventType.TaskCreate, instanceId: inst.id, taskId: nt.id, nodeId: node.id, operator });
     }
     // ─── Helpers ───────────────────────────────────────────────────────────────
     async loadAndCheck(taskId, operator) {
@@ -489,8 +512,12 @@ export class EngineImpl {
         if (isCountersign(node.properties?.performType) && ct) {
             switch (ct) {
                 case 'PARALLEL':
-                    for (const actor of actors)
-                        await this.repo.saveTask(inst.createTask(this.nextId(), node.id, node.text.value, actor, operator, form, now, 1));
+                    for (const actor of actors) {
+                        const nt = inst.createTask(this.nextId(), node.id, node.text.value, actor, operator, form, now, 1);
+                        await this.repo.saveTask(nt);
+                        // TASK_CREATE：任务落库后逐个 fire（会签多任务逐个，对齐 Java CreateTaskHandler）
+                        await this.fireEvent({ type: EventType.TaskCreate, instanceId: inst.id, taskId: nt.id, nodeId: node.id, operator });
+                    }
                     return;
                 case 'SEQUENTIAL': {
                     // 顺序会签任务也是会签任务（issues/57 E29 修正：仅普通分支默认 0）
@@ -501,11 +528,15 @@ export class EngineImpl {
                         [`operatorList_${node.id}`]: actors,
                     };
                     await this.repo.saveTask(nt);
+                    await this.fireEvent({ type: EventType.TaskCreate, instanceId: inst.id, taskId: nt.id, nodeId: node.id, operator });
                     return;
                 }
                 default:
-                    for (const actor of actors)
-                        await this.repo.saveTask(inst.createTask(this.nextId(), node.id, node.text.value, actor, operator, form, now, 1));
+                    for (const actor of actors) {
+                        const nt = inst.createTask(this.nextId(), node.id, node.text.value, actor, operator, form, now, 1);
+                        await this.repo.saveTask(nt);
+                        await this.fireEvent({ type: EventType.TaskCreate, instanceId: inst.id, taskId: nt.id, nodeId: node.id, operator });
+                    }
                     return;
             }
         }
@@ -514,6 +545,7 @@ export class EngineImpl {
         if (actors.length > 1)
             nt.actorIds = actors;
         await this.repo.saveTask(nt);
+        await this.fireEvent({ type: EventType.TaskCreate, instanceId: inst.id, taskId: nt.id, nodeId: node.id, operator });
     }
     async resolveActors(node, inst, operator, vars) {
         // 1a. Registry 按名称解析（推荐）

package/dist/extensions.d.ts

@@ -22,7 +22,8 @@ export declare enum EventType {
     ProcessFinish = 1,
     ProcessReject = 2,
     TaskCreate = 3,
-    TaskComplete = 4
+    TaskComplete = 4,
+    CcCreate = 5
 }
 export interface ProcessEvent {
     type: EventType;
@@ -30,6 +31,8 @@ export interface ProcessEvent {
     taskId?: string;
     nodeId?: string;
     operator: string;
+    /** 抄送人 id 直传事件体，监听器免反查 cc 表（issues/102；对齐 Java ccActorId / Go CcActorID） */
+    ccActorId?: string;
 }
 export type ProcessEventListener = (event: ProcessEvent) => void | Promise<void>;
 export interface EngineExtensions {

package/dist/extensions.js

@@ -5,4 +5,7 @@ export var EventType;
     EventType[EventType["ProcessReject"] = 2] = "ProcessReject";
     EventType[EventType["TaskCreate"] = 3] = "TaskCreate";
     EventType[EventType["TaskComplete"] = 4] = "TaskComplete";
+    // issues/102：抄送知会（对齐 Java CC_CREATE / Go EventCCCreate / Python CC_CREATE / PHP CC_CREATE；
+    // 4 号位是活码 TaskComplete，0/1/2/3/4 不重排——码值契约 Go/Node=5）
+    EventType[EventType["CcCreate"] = 5] = "CcCreate";
 })(EventType || (EventType = {}));

package/dist/facade.d.ts

@@ -87,4 +87,11 @@ export declare class JeeflowFacade {
     private doneList;
     /** 定义 content 解析为 LogicFlow JSON（issues/05 jsonObject） */
     private parseGraph;
+    private static readonly DEFAULT_STATE_IN;
+    private static readonly DEFAULT_STATS_LIMIT;
+    private static readonly VALID_GRANULARITY;
+    private static readonly VALID_DIMENSION;
+    private statsOverview;
+    private statsTrend;
+    private statsGroup;
 }

package/dist/facade.js

@@ -5,6 +5,7 @@
 // （code=0 成功 / 99999999 失败）。操作人约定：args.operator 显式传入。
 import { TaskState, } from './model.js';
 import { KeyNextNodeOperator, KeyProcessStartNextNodeOperator, isCountersign } from './engine.js';
+import { EventType } from './extensions.js';
 // submitType 枚举（对齐 boot3）
 const SUBMIT_APPLY = 0;
 const SUBMIT_AGREE = 1;
@@ -132,6 +133,12 @@ export class JeeflowFacade {
                 return this.taskAddActor(args);
             case 'processTask/latest':
                 return this.taskLatest(args);
+            case 'processInstance/stats/overview':
+                return this.statsOverview(args);
+            case 'processInstance/stats/trend':
+                return this.statsTrend(args);
+            case 'processInstance/stats/group':
+                return this.statsGroup(args);
             default:
                 throw new Error(`未知 action: ${action}`);
         }
@@ -153,6 +160,11 @@ export class JeeflowFacade {
                 ? flowArgs.f_ccActors.split(',').map((x) => x.trim()).filter(Boolean) : [];
         if (ccList.length > 0) {
             await this.repo.createCcInstance(inst.id, operator, ...ccList);
+            // issues/102：CC 实例落库后逐抄送人 fire CcCreate（ccActorId 直传事件体，
+            // 对齐 Go startAndExecute / Python _startAndExecute；监听器据此落抄送知会 NOTICE）
+            for (const actor of ccList) {
+                await this.engine.fireEvent({ type: EventType.CcCreate, instanceId: inst.id, operator, ccActorId: actor });
+            }
         }
         // startAndExecute：自动完成申请节点（assignee="applicant" → 发起人）
         const doing = await this.repo.findDoingTasks(inst.id);
@@ -807,6 +819,10 @@ export class JeeflowFacade {
         if (actors.length === 0)
             throw new Error('actorIds 缺失');
         await this.repo.createCcInstance(instanceId, operator, ...actors);
+        // issues/102：手动 CC 与发起路径同语义——逐抄送人 fire CcCreate
+        for (const actor of actors) {
+            await this.engine.fireEvent({ type: EventType.CcCreate, instanceId, operator, ccActorId: actor });
+        }
     }
     async updateCCStatus(args) {
         const instanceId = toId(args.processInstanceId);
@@ -1091,6 +1107,197 @@ export class JeeflowFacade {
             return undefined;
         }
     }
+    // ── 统计（v1.8.25，issues/103） ──────────────────────────────────────────
+    static DEFAULT_STATE_IN = [10, 20, 30, 40, 45, 50];
+    static DEFAULT_STATS_LIMIT = 10;
+    static VALID_GRANULARITY = new Set(['hour', 'day', 'week', 'month']);
+    static VALID_DIMENSION = new Set([
+        'state', 'define', 'category', 'approver', 'applicant',
+        'node', 'stuckNode', 'stuckApprover', 'durationBucket',
+    ]);
+    async statsOverview(args) {
+        const start = parseSurrogateTime(args.start);
+        const end = parseSurrogateTime(args.end);
+        const stateIn = args.stateIn?.length ? args.stateIn.map(Number) : JeeflowFacade.DEFAULT_STATE_IN;
+        const insts = await this.repo.queryInstancesForStats(stateIn, start, end);
+        const total = insts.length;
+        const inProgress = insts.filter(r => r.state === 10).length;
+        const completed = insts.filter(r => r.state === 20).length;
+        const withdrawn = insts.filter(r => r.state === 30).length;
+        const rejected = insts.filter(r => r.state === 45).length;
+        const suspended = insts.filter(r => r.state === 50).length;
+        const now = new Date();
+        const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+        const todayEnd = new Date(todayStart.getTime() + 86400000);
+        // E：todayNew 恒按服务器当日、不过滤 state / 不受 stateIn 影响（对齐内置线 countTodayNew）
+        const todayInsts = await this.repo.queryInstancesForStats(null, todayStart, todayEnd);
+        const todayNew = todayInsts.length;
+        const [pending, overdue] = await this.repo.statsPendingAndOverdueCount();
+        const avgDur = await this.repo.statsAvgCompletedDurationSeconds(start, end);
+        const [csTotal, csCount, onTime, onTimeDenom] = await this.repo.statsCompletedTaskAggregate();
+        const countersignRate = csTotal > 0 ? statsRound4(csCount / csTotal) : 0;
+        const onTimeRate = onTimeDenom > 0 ? statsRound4(onTime / onTimeDenom) : 0;
+        const rejectRate = statsRound4(rejected / Math.max(1, completed + rejected));
+        return {
+            total, inProgress, completed, rejected, withdrawn, suspended,
+            todayNew, avgDurationSeconds: avgDur,
+            rejectRate, pendingTaskCount: pending,
+            overdueTaskCount: overdue, countersignRate, onTimeRate,
+        };
+    }
+    async statsTrend(args) {
+        const granularity = String(args.granularity ?? '');
+        if (!JeeflowFacade.VALID_GRANULARITY.has(granularity)) {
+            throw new Error(`不支持的 granularity: ${granularity}`);
+        }
+        const start = parseSurrogateTime(args.start);
+        const end = parseSurrogateTime(args.end);
+        // C：start/end 必填（对齐内置线 20010012 缺参语义），不静默回退不限时间
+        if (!start || !end) {
+            throw new Error('trend 缺少必填参数：start/end/granularity');
+        }
+        // 实例侧无 state 过滤（对齐内置线 countInstanceStartedByBucket）
+        const insts = await this.repo.queryInstancesForStats(null, start, end);
+        const doneTasks = await this.repo.queryTasksForStats(20 /* TaskState.Done */, start, end);
+        const buckets = statsEnumerateBuckets(start, end, granularity);
+        const startedMap = new Map();
+        for (const r of insts) {
+            const ct = parseSurrogateTime(r.createTime);
+            if (ct) {
+                const bk = statsBucketKey(ct, granularity);
+                startedMap.set(bk, (startedMap.get(bk) ?? 0) + 1);
+            }
+        }
+        const finishedMap = new Map();
+        for (const r of doneTasks) {
+            const ft = parseSurrogateTime(r.finishTime);
+            if (ft) {
+                const bk = statsBucketKey(ft, granularity);
+                finishedMap.set(bk, (finishedMap.get(bk) ?? 0) + 1);
+            }
+        }
+        const series = buckets.map(b => ({
+            bucket: b, started: startedMap.get(b) ?? 0, finished: finishedMap.get(b) ?? 0,
+        }));
+        // A：data 本体为裸数组（去掉 {granularity, series} 包装，对齐契约 spec 06 §4.2 / 内置线）
+        return series;
+    }
+    async statsGroup(args) {
+        const dimension = String(args.dimension ?? '');
+        if (!JeeflowFacade.VALID_DIMENSION.has(dimension)) {
+            throw new Error(`不支持的 dimension: ${dimension}`);
+        }
+        const start = parseSurrogateTime(args.start);
+        const end = parseSurrogateTime(args.end);
+        const limit = args.limit ? Number(args.limit) : JeeflowFacade.DEFAULT_STATS_LIMIT;
+        let rows;
+        if (dimension === 'define') {
+            const raw = await this.repo.statsDefineGroup(start, end, limit);
+            rows = raw.map(r => ({ key: r.key, label: r.label ?? null, count: r.count, avgDurationSeconds: r.avgDurationSeconds ?? null }));
+        }
+        else if (dimension === 'state') {
+            // 无 state 过滤（对齐内置线 groupByDimension：仅按时间限定，契约 group 无 stateIn 入参）
+            const insts = await this.repo.queryInstancesForStats(null, start, end);
+            const grouped = new Map();
+            for (const r of insts) {
+                const k = String(r.state);
+                grouped.set(k, (grouped.get(k) ?? 0) + 1);
+            }
+            const entries = [...grouped.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit);
+            rows = entries.map(([k, c]) => ({ key: k, label: null, count: c, avgDurationSeconds: null }));
+        }
+        else if (dimension === 'category') {
+            const insts = await this.repo.queryInstancesForStats(null, start, end);
+            const defineTypes = new Map();
+            for (const r of insts) {
+                if (!defineTypes.has(r.defineId)) {
+                    const def = await this.repo.findDefineById(r.defineId);
+                    defineTypes.set(r.defineId, def?.type ?? '');
+                }
+            }
+            const grouped = new Map();
+            for (const r of insts) {
+                const tp = defineTypes.get(r.defineId) ?? '';
+                grouped.set(tp, (grouped.get(tp) ?? 0) + 1);
+            }
+            const entries = [...grouped.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit);
+            rows = entries.map(([k, c]) => ({ key: k, label: null, count: c, avgDurationSeconds: null }));
+        }
+        else if (dimension === 'approver') {
+            const tasks = await this.repo.queryTasksForStats(20, start, end);
+            const grouped = new Map();
+            for (const r of tasks) {
+                if (!r.operator)
+                    continue;
+                grouped.set(r.operator, (grouped.get(r.operator) ?? 0) + 1);
+            }
+            const entries = [...grouped.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit);
+            rows = entries.map(([k, c]) => ({ key: k, label: null, count: c, avgDurationSeconds: null }));
+        }
+        else if (dimension === 'applicant') {
+            const insts = await this.repo.queryInstancesForStats(null, start, end);
+            const grouped = new Map();
+            for (const r of insts) {
+                if (!r.operator)
+                    continue;
+                grouped.set(r.operator, (grouped.get(r.operator) ?? 0) + 1);
+            }
+            const entries = [...grouped.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit);
+            rows = entries.map(([k, c]) => ({ key: k, label: null, count: c, avgDurationSeconds: null }));
+        }
+        else if (dimension === 'node') {
+            const tasks = await this.repo.queryTasksForStats(20, start, end);
+            const nodeAgg = new Map();
+            for (const r of tasks) {
+                if (!r.displayName)
+                    continue;
+                let dur = 0;
+                const ft = parseSurrogateTime(r.finishTime);
+                const ct = parseSurrogateTime(r.createTime);
+                if (ft && ct)
+                    dur = Math.floor((ft.getTime() - ct.getTime()) / 1000);
+                const agg = nodeAgg.get(r.displayName) ?? { count: 0, totalDur: 0 };
+                agg.count++;
+                agg.totalDur += dur;
+                nodeAgg.set(r.displayName, agg);
+            }
+            const entries = [...nodeAgg.entries()].sort((a, b) => b[1].count - a[1].count).slice(0, limit);
+            rows = entries.map(([name, agg]) => ({
+                key: name, label: null, count: agg.count,
+                avgDurationSeconds: agg.count > 0 ? Math.round(agg.totalDur / agg.count) : null,
+            }));
+        }
+        else if (dimension === 'stuckNode') {
+            const raw = await this.repo.statsStuckNodeGroup(limit);
+            rows = raw.map(r => ({ key: r.key, label: r.label ?? null, count: r.count, avgDurationSeconds: r.avgDurationSeconds ?? null }));
+        }
+        else if (dimension === 'stuckApprover') {
+            const raw = await this.repo.statsStuckApproverGroup(limit);
+            rows = raw.map(r => ({ key: r.key, label: r.label ?? null, count: r.count, avgDurationSeconds: r.avgDurationSeconds ?? null }));
+        }
+        else if (dimension === 'durationBucket') {
+            const durations = await this.repo.statsCompletedInstanceDurations(start, end);
+            let sameDay = 0, d1to3 = 0, d3to7 = 0, over7d = 0;
+            for (const dur of durations) {
+                if (dur < 86400)
+                    sameDay++;
+                else if (dur < 259200)
+                    d1to3++;
+                else if (dur < 604800)
+                    d3to7++;
+                else
+                    over7d++;
+            }
+            const keys = ['sameDay', '1to3d', '3to7d', 'over7d'];
+            const counts = [sameDay, d1to3, d3to7, over7d];
+            rows = keys.map((k, i) => ({ key: k, label: null, count: counts[i], avgDurationSeconds: null }));
+        }
+        else {
+            rows = [];
+        }
+        // A：data 本体为裸数组（去掉 {dimension, rows} 包装，对齐契约 spec 06 §4.2 / 内置线）
+        return rows;
+    }
 }
 // ── 行转 Map（issues/05-2 列表字段契约 + 05-3 时间格式）─────────────────────
 /** issues/15：取 vars 中 prefix 前缀字段，输出「带前缀 + 去前缀副本」（对齐 boot3 getFormData） */
@@ -1304,3 +1511,82 @@ function pageData(pageNum, pageSize, total, rows) {
         totalPage = Math.ceil(total / ps);
     return { pageNum: pn, pageSize: ps, recordCount: total, totalPage, rows };
 }
+// ═══ 统计辅助（v1.8.25，issues/103） ═══
+function statsRound4(v) {
+    return Math.round(v * 10000) / 10000;
+}
+function statsWeekKey(d) {
+    const iso = isoWeek(d);
+    return `${iso[0]}-W${String(iso[1]).padStart(2, '0')}`;
+}
+function isoWeek(d) {
+    const date = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+    const dayNum = date.getUTCDay() || 7;
+    date.setUTCDate(date.getUTCDate() + 4 - dayNum);
+    const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
+    const weekNo = Math.ceil((((date.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
+    return [date.getUTCFullYear(), weekNo];
+}
+function statsEnumerateBuckets(start, end, granularity) {
+    const now = new Date();
+    const s = start ?? new Date(now.getTime() - 30 * 86400000);
+    const e = end ?? now;
+    const buckets = [];
+    if (granularity === 'hour') {
+        const cursor = new Date(s.getFullYear(), s.getMonth(), s.getDate(), s.getHours(), 0, 0);
+        while (cursor <= e) {
+            buckets.push(formatHour(cursor));
+            cursor.setHours(cursor.getHours() + 1);
+        }
+    }
+    else if (granularity === 'day') {
+        const cursor = new Date(s.getFullYear(), s.getMonth(), s.getDate());
+        const endDay = new Date(e.getFullYear(), e.getMonth(), e.getDate());
+        while (cursor <= endDay) {
+            buckets.push(formatDay(cursor));
+            cursor.setDate(cursor.getDate() + 1);
+        }
+    }
+    else if (granularity === 'week') {
+        const cursor = new Date(s.getFullYear(), s.getMonth(), s.getDate());
+        const weekday = cursor.getDay() || 7;
+        cursor.setDate(cursor.getDate() - (weekday - 1));
+        const endDay = new Date(e.getFullYear(), e.getMonth(), e.getDate());
+        while (cursor <= endDay) {
+            buckets.push(statsWeekKey(cursor));
+            cursor.setDate(cursor.getDate() + 7);
+        }
+    }
+    else if (granularity === 'month') {
+        let year = s.getFullYear();
+        let month = s.getMonth();
+        const endYear = e.getFullYear();
+        const endMonth = e.getMonth();
+        while (year < endYear || (year === endYear && month <= endMonth)) {
+            buckets.push(`${year}-${String(month + 1).padStart(2, '0')}`);
+            month++;
+            if (month > 11) {
+                month = 0;
+                year++;
+            }
+        }
+    }
+    return buckets;
+}
+function statsBucketKey(d, granularity) {
+    if (granularity === 'hour')
+        return formatHour(d);
+    if (granularity === 'day')
+        return formatDay(d);
+    if (granularity === 'week')
+        return statsWeekKey(d);
+    if (granularity === 'month')
+        return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+    return '';
+}
+function formatHour(d) {
+    return `${formatDay(d)} ${String(d.getHours()).padStart(2, '0')}:00`;
+}
+function formatDay(d) {
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}

package/dist/jdbc/shared.d.ts

@@ -1,5 +1,5 @@
 import { ProcessInstance, ProcessTask, type ProcessDefine, type CcInstanceRow, type DefineRow, type InstanceRow, type TaskRow } from '../model.js';
-import type { IDGenerator, ProcessRepository, QueryCondition } from '../spi.js';
+import type { IDGenerator, ProcessRepository, QueryCondition, InstanceStatsRow, TaskStatsRow } from '../spi.js';
 /** 默认 ID 生成器：时间戳毫秒 + 同毫秒递增序号（对齐 Java nextId 默认实现）——
  *  issue 38 E9：返回 string（数字值在 2^53 内精确，转字符串统一承载） */
 export declare class TsIDGenerator implements IDGenerator {
@@ -95,4 +95,13 @@ export declare class JdbcRepository implements ProcessRepository {
         total: number;
     }>;
     private mapCcRow;
+    queryInstancesForStats(stateIn?: number[] | null, start?: Date | null, end?: Date | null): Promise<InstanceStatsRow[]>;
+    queryTasksForStats(taskState?: number, start?: Date | null, end?: Date | null): Promise<TaskStatsRow[]>;
+    statsPendingAndOverdueCount(): Promise<[number, number]>;
+    statsCompletedTaskAggregate(): Promise<[number, number, number, number]>;
+    statsAvgCompletedDurationSeconds(start?: Date | null, end?: Date | null): Promise<number>;
+    statsDefineGroup(start?: Date | null, end?: Date | null, limit?: number): Promise<Record<string, any>[]>;
+    statsStuckNodeGroup(limit?: number): Promise<Record<string, any>[]>;
+    statsStuckApproverGroup(limit?: number): Promise<Record<string, any>[]>;
+    statsCompletedInstanceDurations(start?: Date | null, end?: Date | null): Promise<number[]>;
 }

package/dist/jdbc/shared.js

@@ -648,4 +648,208 @@ export class JdbcRepository {
             defineVersion: Number(r.version ?? 0),
         };
     }
+    // ── Stats（issues/103：统计接口契约） ─────────────────────────────────────
+    async queryInstancesForStats(stateIn, start, end) {
+        // stateIn 空 = 无 state 过滤（对齐内置线：仅 overview 六计数用 stateIn）
+        let sql = 'SELECT process_define_id, state, operator, create_time FROM wf_process_instance WHERE 1=1';
+        const args = [];
+        if (stateIn && stateIn.length) {
+            sql += ` AND state IN (${repeatPh(stateIn.length)})`;
+            args.push(...stateIn);
+        }
+        if (start) {
+            sql += ' AND create_time >= ?';
+            args.push(start);
+        }
+        if (end) {
+            sql += ' AND create_time < DATE_ADD(?, INTERVAL 1 SECOND)';
+            args.push(end);
+        }
+        sql += ' ORDER BY create_time';
+        const conn = await this.c();
+        try {
+            const rows = await conn.fetchAll(this.sql(sql), args);
+            return rows.map((r) => ({
+                defineId: rowId(r.process_define_id), state: r.state,
+                operator: r.operator ?? '', createTime: r.create_time,
+            }));
+        }
+        finally {
+            await this.done(conn);
+        }
+    }
+    async queryTasksForStats(taskState, start, end) {
+        let sql = 'SELECT operator, display_name, perform_type, create_time, finish_time, expire_time FROM wf_process_task WHERE 1=1';
+        const args = [];
+        if (taskState != null) {
+            sql += ' AND task_state = ?';
+            args.push(taskState);
+        }
+        if (start) {
+            sql += ' AND finish_time >= ?';
+            args.push(start);
+        }
+        if (end) {
+            sql += ' AND finish_time < DATE_ADD(?, INTERVAL 1 SECOND)';
+            args.push(end);
+        }
+        const conn = await this.c();
+        try {
+            const rows = await conn.fetchAll(this.sql(sql), args);
+            return rows.map((r) => ({
+                operator: r.operator ?? '', displayName: r.display_name ?? '',
+                performType: r.perform_type ?? 0, createTime: r.create_time,
+                finishTime: r.finish_time, expireTime: r.expire_time,
+            }));
+        }
+        finally {
+            await this.done(conn);
+        }
+    }
+    async statsPendingAndOverdueCount() {
+        const conn = await this.c();
+        try {
+            const r1 = await conn.fetchOne(this.sql('SELECT COUNT(*) FROM wf_process_task WHERE task_state = 10'), []);
+            const pending = r1 ? Number(Object.values(r1)[0] ?? 0) : 0;
+            const now = new Date();
+            const r2 = await conn.fetchOne(this.sql('SELECT COUNT(*) FROM wf_process_task WHERE task_state = 10 AND expire_time IS NOT NULL AND expire_time < ?'), [now]);
+            const overdue = r2 ? Number(Object.values(r2)[0] ?? 0) : 0;
+            return [pending, overdue];
+        }
+        finally {
+            await this.done(conn);
+        }
+    }
+    async statsCompletedTaskAggregate() {
+        const conn = await this.c();
+        try {
+            const r = await conn.fetchOne(this.sql('SELECT COUNT(*) AS total, ' +
+                'SUM(CASE WHEN perform_type = 1 THEN 1 ELSE 0 END) AS countersign, ' +
+                'SUM(CASE WHEN expire_time IS NOT NULL AND finish_time IS NOT NULL AND finish_time <= expire_time THEN 1 ELSE 0 END) AS on_time, ' +
+                'SUM(CASE WHEN expire_time IS NOT NULL THEN 1 ELSE 0 END) AS on_time_denom ' +
+                'FROM wf_process_task WHERE task_state = 20'), []);
+            if (!r)
+                return [0, 0, 0, 0];
+            return [
+                Number(r.total ?? 0),
+                Number(r.countersign ?? 0),
+                Number(r.on_time ?? 0),
+                Number(r.on_time_denom ?? 0),
+            ];
+        }
+        finally {
+            await this.done(conn);
+        }
+    }
+    async statsAvgCompletedDurationSeconds(start, end) {
+        let sql = `SELECT COALESCE(ROUND(AVG(
+        TIMESTAMPDIFF(SECOND, i.create_time, (
+          SELECT MAX(t.finish_time) FROM wf_process_task t WHERE t.process_instance_id = i.id AND t.finish_time IS NOT NULL
+        ))
+      )), 0) AS avg_sec FROM wf_process_instance i WHERE i.state = 20`;
+        const args = [];
+        if (start) {
+            sql += ' AND i.create_time >= ?';
+            args.push(start);
+        }
+        if (end) {
+            sql += ' AND i.create_time < DATE_ADD(?, INTERVAL 1 SECOND)';
+            args.push(end);
+        }
+        const conn = await this.c();
+        try {
+            const r = await conn.fetchOne(this.sql(sql), args);
+            if (!r)
+                return 0;
+            return Number(Object.values(r)[0] ?? 0);
+        }
+        finally {
+            await this.done(conn);
+        }
+    }
+    async statsDefineGroup(start, end, limit = 10) {
+        // 对齐内置线 mapper：count 全实例（无 state 过滤）、inner join define、
+        // avg 仅对 state=20 且有 finish 的实例聚合（MAX(task.finish_time) - create_time）
+        let sql = 'SELECT pd.name, pd.display_name, COUNT(*) AS cnt, ' +
+            'ROUND(AVG(CASE WHEN i.state = 20 AND sub.maxft IS NOT NULL ' +
+            'THEN TIMESTAMPDIFF(SECOND, i.create_time, sub.maxft) END)) AS avg_dur ' +
+            'FROM wf_process_instance i ' +
+            'JOIN wf_process_define pd ON i.process_define_id = pd.id ' +
+            'LEFT JOIN (SELECT process_instance_id, MAX(finish_time) AS maxft ' +
+            'FROM wf_process_task GROUP BY process_instance_id) sub ' +
+            'ON sub.process_instance_id = i.id ' +
+            'WHERE 1=1';
+        const args = [];
+        if (start) {
+            sql += ' AND i.create_time >= ?';
+            args.push(start);
+        }
+        if (end) {
+            sql += ' AND i.create_time < DATE_ADD(?, INTERVAL 1 SECOND)';
+            args.push(end);
+        }
+        sql += ' GROUP BY pd.id, pd.name, pd.display_name ORDER BY cnt DESC LIMIT ?';
+        args.push(limit);
+        const conn = await this.c();
+        try {
+            const rows = await conn.fetchAll(this.sql(sql), args);
+            return rows.map((r) => ({
+                key: r.name ?? null, label: r.display_name ?? null,
+                count: Number(r.cnt ?? 0),
+                avgDurationSeconds: r.avg_dur != null ? Math.round(Number(r.avg_dur)) : null,
+            }));
+        }
+        finally {
+            await this.done(conn);
+        }
+    }
+    async statsStuckNodeGroup(limit = 10) {
+        const conn = await this.c();
+        try {
+            const rows = await conn.fetchAll(this.sql('SELECT display_name, COUNT(*) AS cnt FROM wf_process_task ' +
+                'WHERE task_state = 10 GROUP BY display_name ORDER BY cnt DESC LIMIT ?'), [limit]);
+            return rows.map((r) => ({
+                key: r.display_name ?? '', label: null, count: Number(r.cnt ?? 0), avgDurationSeconds: null,
+            }));
+        }
+        finally {
+            await this.done(conn);
+        }
+    }
+    async statsStuckApproverGroup(limit = 10) {
+        const conn = await this.c();
+        try {
+            const rows = await conn.fetchAll(this.sql('SELECT ta.actor_id, COUNT(DISTINCT t.id) AS cnt FROM wf_process_task_actor ta ' +
+                'INNER JOIN wf_process_task t ON ta.process_task_id = t.id ' +
+                'WHERE t.task_state = 10 GROUP BY ta.actor_id ORDER BY cnt DESC LIMIT ?'), [limit]);
+            return rows.map((r) => ({
+                key: rowId(r.actor_id), label: null, count: Number(r.cnt ?? 0), avgDurationSeconds: null,
+            }));
+        }
+        finally {
+            await this.done(conn);
+        }
+    }
+    async statsCompletedInstanceDurations(start, end) {
+        let sql = `SELECT TIMESTAMPDIFF(SECOND, i.create_time, (
+        SELECT MAX(t.finish_time) FROM wf_process_task t WHERE t.process_instance_id = i.id AND t.finish_time IS NOT NULL
+      )) AS dur FROM wf_process_instance i WHERE i.state = 20`;
+        const args = [];
+        if (start) {
+            sql += ' AND i.create_time >= ?';
+            args.push(start);
+        }
+        if (end) {
+            sql += ' AND i.create_time < DATE_ADD(?, INTERVAL 1 SECOND)';
+            args.push(end);
+        }
+        const conn = await this.c();
+        try {
+            const rows = await conn.fetchAll(this.sql(sql), args);
+            return rows.map((r) => Number(r.dur)).filter((v) => v != null && !isNaN(v));
+        }
+        finally {
+            await this.done(conn);
+        }
+    }
 }

package/dist/memory.d.ts

@@ -57,4 +57,37 @@ export declare class MemoryRepository implements ProcessRepository {
     allDefines(): ProcessDefine[];
     allInstances(): ProcessInstance[];
     allTasks(): ProcessTask[];
+    private toDt;
+    queryInstancesForStats(stateIn?: number[] | null, start?: Date | null, end?: Date | null): Promise<{
+        defineId: string;
+        state: number;
+        operator: string;
+        createTime: Date | string | null;
+    }[]>;
+    queryTasksForStats(taskState?: number, start?: Date | null, end?: Date | null): Promise<{
+        operator: string;
+        displayName: string;
+        performType: number;
+        createTime: Date | string | null;
+        finishTime: Date | string | null;
+        expireTime: Date | string | null;
+    }[]>;
+    statsPendingAndOverdueCount(): Promise<[number, number]>;
+    statsCompletedTaskAggregate(): Promise<[number, number, number, number]>;
+    statsAvgCompletedDurationSeconds(start?: Date | null, end?: Date | null): Promise<number>;
+    statsDefineGroup(start?: Date | null, end?: Date | null, limit?: number): Promise<{
+        key: string;
+        label: string | null;
+        count: number;
+        avgDurationSeconds: number | null;
+    }[]>;
+    statsStuckNodeGroup(limit?: number): Promise<{
+        key: string;
+        count: number;
+    }[]>;
+    statsStuckApproverGroup(limit?: number): Promise<{
+        key: string;
+        count: number;
+    }[]>;
+    statsCompletedInstanceDurations(start?: Date | null, end?: Date | null): Promise<number[]>;
 }

package/dist/memory.js

@@ -144,13 +144,13 @@ export class MemoryRepository {
         cp.tasks = [];
         this.instances.set(inst.id, cp);
         // v1.0.1：级联保存聚合根内任务状态变更
-        for (const t of inst.tasks) {
+        for (const t of (inst.tasks ?? [])) {
             if (!t.id)
                 continue;
             const tc = cloneTask(t);
             tc.actorIds = [];
             this.tasks.set(t.id, tc);
-            if (t.actorIds.length)
+            if (t.actorIds?.length)
                 this.actors.set(t.id, [...t.actorIds]);
         }
     }
@@ -183,14 +183,14 @@ export class MemoryRepository {
         const cp = cloneTask(task);
         cp.actorIds = [];
         this.tasks.set(task.id, cp);
-        if (task.actorIds.length)
+        if (task.actorIds?.length)
             this.actors.set(task.id, [...task.actorIds]);
     }
     async updateTask(task) {
         const cp = cloneTask(task);
         cp.actorIds = [];
         this.tasks.set(task.id, cp);
-        if (task.actorIds.length)
+        if (task.actorIds?.length)
             this.actors.set(task.id, [...task.actorIds]);
     }
     async findDoingTasks(instanceId, taskNames) {
@@ -375,4 +375,198 @@ export class MemoryRepository {
             return cp;
         });
     }
+    // ── 统计（v1.8.25，issues/103） ──────────────────────────────────────────
+    toDt(v) {
+        if (v == null)
+            return undefined;
+        if (v instanceof Date)
+            return isNaN(v.getTime()) ? undefined : v;
+        const d = new Date(String(v).replace(' ', 'T'));
+        return isNaN(d.getTime()) ? undefined : d;
+    }
+    async queryInstancesForStats(stateIn, start, end) {
+        const sd = this.toDt(start);
+        const ed = this.toDt(end);
+        const rows = [];
+        for (const inst of this.instances.values()) {
+            const sv = Number(inst.state);
+            // stateIn 空 = 无 state 过滤（对齐内置线：仅 overview 六计数用 stateIn）
+            if (stateIn && stateIn.length && !stateIn.includes(sv))
+                continue;
+            const ct = this.toDt(inst.createTime);
+            if (sd && ct && ct < sd)
+                continue;
+            if (ed && ct && ct > ed)
+                continue;
+            rows.push({ defineId: String(inst.defineId), state: sv, operator: inst.operator ?? '', createTime: inst.createTime ?? null });
+        }
+        return rows;
+    }
+    async queryTasksForStats(taskState, start, end) {
+        const sd = this.toDt(start);
+        const ed = this.toDt(end);
+        const rows = [];
+        for (const t of this.tasks.values()) {
+            if (taskState != null && Number(t.taskState) !== taskState)
+                continue;
+            const ft = this.toDt(t.finishTime);
+            if (sd && ft && ft < sd)
+                continue;
+            if (ed && ft && ft > ed)
+                continue;
+            rows.push({
+                operator: t.actorId ?? '', displayName: t.displayName ?? '',
+                performType: t.performType ?? 0,
+                createTime: t.createTime ?? null, finishTime: t.finishTime ?? null, expireTime: t.expireTime ?? null,
+            });
+        }
+        return rows;
+    }
+    async statsPendingAndOverdueCount() {
+        const now = new Date();
+        let pending = 0, overdue = 0;
+        for (const t of this.tasks.values()) {
+            if (Number(t.taskState) !== TaskState.Doing)
+                continue;
+            pending++;
+            const exp = this.toDt(t.expireTime);
+            if (exp && exp < now)
+                overdue++;
+        }
+        return [pending, overdue];
+    }
+    async statsCompletedTaskAggregate() {
+        let total = 0, countersign = 0, onTime = 0, onTimeDenom = 0;
+        for (const t of this.tasks.values()) {
+            if (Number(t.taskState) !== TaskState.Done)
+                continue;
+            total++;
+            if (t.performType === 1)
+                countersign++;
+            const ft = this.toDt(t.finishTime);
+            const exp = this.toDt(t.expireTime);
+            if (exp != null) {
+                onTimeDenom++;
+                if (ft && ft <= exp)
+                    onTime++;
+            }
+        }
+        return [total, countersign, onTime, onTimeDenom];
+    }
+    async statsAvgCompletedDurationSeconds(start, end) {
+        const sd = this.toDt(start);
+        const ed = this.toDt(end);
+        let totalSec = 0, count = 0;
+        for (const inst of this.instances.values()) {
+            if (Number(inst.state) !== 20)
+                continue;
+            const ct = this.toDt(inst.createTime);
+            if (sd && ct && ct < sd)
+                continue;
+            if (ed && ct && ct > ed)
+                continue;
+            let maxFt;
+            for (const t of this.tasks.values()) {
+                if (t.processInstanceId !== inst.id)
+                    continue;
+                const ft = this.toDt(t.finishTime);
+                if (ft && (!maxFt || ft > maxFt))
+                    maxFt = ft;
+            }
+            if (maxFt && ct) {
+                totalSec += Math.floor((maxFt.getTime() - ct.getTime()) / 1000);
+                count++;
+            }
+        }
+        return count > 0 ? Math.floor(totalSec / count) : 0;
+    }
+    async statsDefineGroup(start, end, limit = 10) {
+        const sd = this.toDt(start);
+        const ed = this.toDt(end);
+        const grouped = new Map();
+        for (const inst of this.instances.values()) {
+            const ct = this.toDt(inst.createTime);
+            if (sd && ct && ct < sd)
+                continue;
+            if (ed && ct && ct > ed)
+                continue;
+            const did = String(inst.defineId);
+            if (!grouped.has(did)) {
+                const defn = this.defines.get(did);
+                grouped.set(did, { key: defn?.name ?? '', label: defn?.displayName ?? null, count: 0, totalDur: 0, durCount: 0 });
+            }
+            const g = grouped.get(did);
+            g.count++;
+            if (Number(inst.state) === 20) {
+                let maxFt;
+                for (const t of this.tasks.values()) {
+                    if (t.processInstanceId !== inst.id)
+                        continue;
+                    const ft = this.toDt(t.finishTime);
+                    if (ft && (!maxFt || ft > maxFt))
+                        maxFt = ft;
+                }
+                if (maxFt && ct) {
+                    g.totalDur += Math.floor((maxFt.getTime() - ct.getTime()) / 1000);
+                    g.durCount++;
+                }
+            }
+        }
+        const entries = [...grouped.values()].sort((a, b) => b.count - a.count).slice(0, limit);
+        return entries.map(e => ({ key: e.key, label: e.label, count: e.count, avgDurationSeconds: e.durCount > 0 ? Math.floor(e.totalDur / e.durCount) : null }));
+    }
+    async statsStuckNodeGroup(limit = 10) {
+        const grouped = new Map();
+        for (const t of this.tasks.values()) {
+            if (Number(t.taskState) !== TaskState.Doing)
+                continue;
+            const dn = t.displayName;
+            if (!dn)
+                continue;
+            grouped.set(dn, (grouped.get(dn) ?? 0) + 1);
+        }
+        const entries = [...grouped.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit);
+        return entries.map(([k, c]) => ({ key: k, count: c }));
+    }
+    async statsStuckApproverGroup(limit = 10) {
+        const grouped = new Map();
+        for (const t of this.tasks.values()) {
+            if (Number(t.taskState) !== TaskState.Doing)
+                continue;
+            const actors = this.actors.get(t.id) ?? [];
+            for (const aid of actors) {
+                if (!aid)
+                    continue;
+                grouped.set(aid, (grouped.get(aid) ?? 0) + 1);
+            }
+        }
+        const entries = [...grouped.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit);
+        return entries.map(([k, c]) => ({ key: k, count: c }));
+    }
+    async statsCompletedInstanceDurations(start, end) {
+        const sd = this.toDt(start);
+        const ed = this.toDt(end);
+        const durations = [];
+        for (const inst of this.instances.values()) {
+            if (Number(inst.state) !== 20)
+                continue;
+            const ct = this.toDt(inst.createTime);
+            if (sd && ct && ct < sd)
+                continue;
+            if (ed && ct && ct > ed)
+                continue;
+            let maxFt;
+            for (const t of this.tasks.values()) {
+                if (t.processInstanceId !== inst.id)
+                    continue;
+                const ft = this.toDt(t.finishTime);
+                if (ft && (!maxFt || ft > maxFt))
+                    maxFt = ft;
+            }
+            if (maxFt && ct) {
+                durations.push(Math.floor((maxFt.getTime() - ct.getTime()) / 1000));
+            }
+        }
+        return durations;
+    }
 }

package/dist/model.js

@@ -212,7 +212,7 @@ export class ProcessTask {
 // ─── Clone Helpers（保留 class 原型）────────────────────────────────────────────
 export function cloneInstance(inst) {
     return Object.assign(Object.create(ProcessInstance.prototype), inst, {
-        tasks: inst.tasks.map(cloneTask),
+        tasks: (inst.tasks ?? []).map(cloneTask),
     });
 }
 export function cloneTask(task) {

package/dist/spi.d.ts

@@ -4,6 +4,20 @@ export interface QueryCondition {
     operator: string;
     value: any;
 }
+export interface InstanceStatsRow {
+    defineId: string;
+    state: number;
+    operator: string;
+    createTime: Date | string | null;
+}
+export interface TaskStatsRow {
+    operator: string;
+    displayName: string;
+    performType: number;
+    createTime: Date | string | null;
+    finishTime: Date | string | null;
+    expireTime: Date | string | null;
+}
 export interface ProcessRepository {
     findDefineById(id: string): Promise<ProcessDefine | null>;
     findDefineByName(name: string): Promise<ProcessDefine | null>;
@@ -45,6 +59,15 @@ export interface ProcessRepository {
         rows: TaskRow[];
         total: number;
     }>;
+    queryInstancesForStats(stateIn?: number[] | null, start?: Date | null, end?: Date | null): Promise<InstanceStatsRow[]>;
+    queryTasksForStats(taskState?: number, start?: Date | null, end?: Date | null): Promise<TaskStatsRow[]>;
+    statsPendingAndOverdueCount(): Promise<[number, number]>;
+    statsCompletedTaskAggregate(): Promise<[number, number, number, number]>;
+    statsAvgCompletedDurationSeconds(start?: Date | null, end?: Date | null): Promise<number>;
+    statsDefineGroup(start?: Date | null, end?: Date | null, limit?: number): Promise<Record<string, any>[]>;
+    statsStuckNodeGroup(limit?: number): Promise<Record<string, any>[]>;
+    statsStuckApproverGroup(limit?: number): Promise<Record<string, any>[]>;
+    statsCompletedInstanceDurations(start?: Date | null, end?: Date | null): Promise<number[]>;
 }
 export interface UserProvider {
     getUser(userId: string): Promise<UserInfo | null>;

package/package.json

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