feat(workflow): approver expr resolution with reason (Task 5, webapi hardening)

This commit is contained in:
ssw committed 2026-07-28 17:35:08 +08:00
1 parent 6341768f9f
commit 22d8111462
3 files changed
+147 -5

No files matched your search

@@ -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:<enCode>` → 调用 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<ResolveResult> {
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' }
}
+18 -5
View File
@@ -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<Seman
// 3b. assignee 是 ${var} 表达式, 尝试解析
if (assignee && /\$\{.+\}/.test(assignee)) {
const resolved = ctx.candidateResolver(assignee) || []
let resolved: Array<{ id: string; name: string }> = []
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})` : ''}` })
}
}
}
@@ -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')
})
})