From 22d81114628ecfb475d16af0bf1fc65e8838db9d Mon Sep 17 00:00:00 2001 From: ssw Date: Tue, 28 Jul 2026 17:35:08 +0800 Subject: [PATCH] feat(workflow): approver expr resolution with reason (Task 5, webapi hardening) --- src/commands/workflow/_approver_resolve.ts | 86 ++++++++++++++++++++ src/commands/workflow/_semantic_lint.ts | 23 ++++-- tests/unit/workflow_approver_resolve.test.ts | 43 ++++++++++ 3 files changed, 147 insertions(+), 5 deletions(-) create mode 100644 src/commands/workflow/_approver_resolve.ts create mode 100644 tests/unit/workflow_approver_resolve.test.ts diff --git a/src/commands/workflow/_approver_resolve.ts b/src/commands/workflow/_approver_resolve.ts new file mode 100644 index 0000000..42c0545 --- /dev/null +++ b/src/commands/workflow/_approver_resolve.ts @@ -0,0 +1,86 @@ +/** + * workflow 审批人变量解析 (webapi hardening) + * + * 镜像 web 端 FlowApproverSelect + ssw-common build-workflow 的 candidateResolver. + * + * 设计原则: + * - 解析 BPMN userTask assignee 表达式, 返回候选人列表 + 失败原因 (reason). + * - 失败原因显式化, 方便 _semantic_lint.ts 阻断坏 BPMN 进后端 Flowable 部署. + * - 不直接调 JnpfClient, 接受 webapi 容器 (resolveApproverExpr 是纯函数, 易于测试 + 复用). + * + * 支持的表达式: + * - `role:` → 调用 webapi.getUserListByRole(enCode) + * - `${deptManager}` → 调用 webapi.getDeptManager() (web 端发起人部门主管) + * - `${currentUser}` → 调用 webapi.getCurrentUser() (运行时上下文) + * - 显式 id (u\d+|v\d+) → 视为单候选人占位 (不解析, 视为合法) + * + * 保留关键字 (reserved keyword, 不允许作为审批人): + * - `initiator` / `any` / `starter` / `currentUser` 直接使用 (≠ ${currentUser} 表达式) + * 这些关键字在 BPMN flowable 引擎层有特殊语义, dacli 不应混淆 (避免双重解析). + */ + +export interface ResolveCtx { + /** webapi 容器 (测试时可注入 mock). */ + webapi: any +} + +export interface ResolveResult { + candidates: Array<{ id: string; name: string }> + reason?: 'no users in dept' | 'no such role' | 'unknown expression' | 'reserved keyword' | 'api error' +} + +/** 不允许直接当作 assignee 表达式使用的关键字. */ +const RESERVED = new Set(['initiator', 'any', 'starter', 'currentUser']) + +/** + * 解析 BPMN userTask assignee 表达式. + * + * @param expr 原始 assignee 表达式 (e.g. "role:finance", "${deptManager}", "initiator") + * @param ctx 解析上下文, 注入 webapi mock (测试) 或真实 webapi (生产) + * @returns 候选人列表 + 失败原因 (失败时 candidates=[] 且 reason 有值) + */ +export async function resolveApproverExpr(expr: string, ctx: ResolveCtx): Promise { + const e = (expr ?? '').trim() + if (!e) { + return { candidates: [], reason: 'unknown expression' } + } + + // 保留关键字 (initiator / any / starter / currentUser 字面量) + if (RESERVED.has(e)) { + return { candidates: [], reason: 'reserved keyword' } + } + + // role:xxx — 角色 enCode + const roleMatch = /^role:(.+)$/.exec(e) + if (roleMatch) { + const list = (await ctx.webapi?.getUserListByRole?.(roleMatch[1])) ?? [] + return list.length ? { candidates: list } : { candidates: [], reason: 'no such role' } + } + + // ${var} — 运行时变量 + const varMatch = /^\$\{(.+)\}$/.exec(e) + if (varMatch) { + const name = varMatch[1].trim() + if (name === 'deptManager') { + const list = (await ctx.webapi?.getDeptManager?.()) ?? [] + return list.length ? { candidates: list } : { candidates: [], reason: 'no users in dept' } + } + if (name === 'currentUser') { + const me = await ctx.webapi?.getCurrentUser?.() + if (me && (me.id || me.userId)) { + const id = String(me.id ?? me.userId) + const name2 = String(me.realName ?? me.userName ?? me.account ?? id) + return { candidates: [{ id, name: name2 }] } + } + return { candidates: [], reason: 'no users in dept' } + } + return { candidates: [], reason: 'unknown expression' } + } + + // 显式 id (u\d+ 或 v\d+, JNPF userId / Vben v-id 风格) — 视为单候选人占位 + if (/^[uv]\d+$/.test(e)) { + return { candidates: [{ id: e, name: e }] } + } + + return { candidates: [], reason: 'unknown expression' } +} \ No newline at end of file diff --git a/src/commands/workflow/_semantic_lint.ts b/src/commands/workflow/_semantic_lint.ts index ec3e989..2367e1b 100644 --- a/src/commands/workflow/_semantic_lint.ts +++ b/src/commands/workflow/_semantic_lint.ts @@ -21,6 +21,7 @@ */ import { BpmnModdle } from 'bpmn-moddle' +import { resolveApproverExpr } from './_approver_resolve.ts' export interface SemanticDiagnostic { nodeId: string @@ -34,8 +35,10 @@ export interface SemanticResult { } export interface ResolverCtx { - /** 解析 ${var} 表达式到候选人列表. T5 会替换为真实的 resolveApproverExpr. */ - candidateResolver: (assigneeExpr: string) => Array<{ id: string; name: string }> + /** webapi 容器 (T5 接入). 优先使用, 解析失败时返回 reason. */ + webapi?: any + /** 旧版 fallback (T4 阶段使用). 仅 webapi 缺失时启用, 兼容老调用点. */ + candidateResolver?: (assigneeExpr: string) => Array<{ id: string; name: string }> } /** @@ -114,10 +117,20 @@ export async function semanticLint(xml: string, ctx: ResolverCtx): Promise = [] + let reason: string | undefined + if (ctx.webapi) { + const r = await resolveApproverExpr(assignee, { webapi: ctx.webapi }) + resolved = r.candidates + reason = r.reason + } else if (ctx.candidateResolver) { + // 向后兼容: T4 阶段调用点只传 candidateResolver + resolved = ctx.candidateResolver(assignee) || [] + if (resolved.length === 0) reason = 'no candidate' + } if (resolved.length === 0) { - errors.push(`userTask ${ut.id}: assignee ${assignee} unresolved (no candidate)`) - diagnostics.push({ nodeId: ut.id, message: `unresolved: ${assignee}` }) + errors.push(`userTask ${ut.id}: assignee ${assignee} unresolved (${reason ?? 'no candidate'})`) + diagnostics.push({ nodeId: ut.id, message: `unresolved: ${assignee}${reason ? ` (${reason})` : ''}` }) } } } diff --git a/tests/unit/workflow_approver_resolve.test.ts b/tests/unit/workflow_approver_resolve.test.ts new file mode 100644 index 0000000..1846f0c --- /dev/null +++ b/tests/unit/workflow_approver_resolve.test.ts @@ -0,0 +1,43 @@ +/** + * workflow approver expr resolve tests (Task 5 — webapi hardening) + * + * 镜像 web 端 FlowApproverSelect + ssw-common build-workflow 的 candidateResolver. + * 4 场景: + * 1. 显式 `role:finance` 解析 + * 2. 变量 `${deptManager}` 解析为空 → reason=no users in dept + * 3. unknown expression → reason=unknown expression + * 4. `initiator` / `any` 不允许作为审批人 → reason=reserved keyword + * + * 与 _semantic_lint.ts 集成 (T5): + * - ResolverCtx 扩展: 支持 webapi, 保留 candidateResolver fallback + * - semanticLint 在解析 ${var} 时, 用 resolveApproverExpr 替代 ctx.candidateResolver 直接调用 + */ +import { describe, expect, it, vi } from 'vitest' +import { resolveApproverExpr } from '../../src/commands/workflow/_approver_resolve.ts' + +describe('workflow approver resolve (Task 5)', () => { + it('显式 role:finance → 解析', async () => { + const webapi = { getUserListByRole: vi.fn().mockResolvedValue([{ id: 'u1', name: 'Alice' }]) } + const r = await resolveApproverExpr('role:finance', { webapi }) + expect(r.candidates).toEqual([{ id: 'u1', name: 'Alice' }]) + expect(r.reason).toBeUndefined() + }) + + it('变量 ${deptManager} 解析为空 → reason=no users in dept', async () => { + const webapi = { getDeptManager: vi.fn().mockResolvedValue([]) } + const r = await resolveApproverExpr('${deptManager}', { webapi }) + expect(r.candidates).toEqual([]) + expect(r.reason).toBe('no users in dept') + }) + + it('unknown expression → reason=unknown expression', async () => { + const r = await resolveApproverExpr('${mystery}', { webapi: {} as any }) + expect(r.candidates).toEqual([]) + expect(r.reason).toBe('unknown expression') + }) + + it('initiator/any 不允许作为审批人 → reason=reserved keyword', async () => { + const r = await resolveApproverExpr('initiator', { webapi: {} as any }) + expect(r.reason).toBe('reserved keyword') + }) +}) \ No newline at end of file