diff --git a/src/modeler/candidateExpression.test.ts b/src/modeler/candidateExpression.test.ts new file mode 100644 index 0000000..d9f3449 --- /dev/null +++ b/src/modeler/candidateExpression.test.ts @@ -0,0 +1,202 @@ +import { describe, it, expect } from 'vitest'; +import { SYNTHETIC_BPMN } from './moddle/fixtures/synthetic-full-surface.bpmn'; +import { + parseCandidateExpression, + buildCandidateExpression, + type UserPropertyItem, +} from './candidateExpression'; + +// ── 真实形态锚定 ──────────────────────────────────────────────────────────── +// 不手抄表达式:直接从 T1.1 逐字对照「总包合同交底」写就的 synthetic-full-surface +// fixture 里,运行时抽出 activiti:candidateUsers / activiti:collection 的属性值, +// 做 XML 实体解码("→")得到 businessObject 属性值层的真实表达式。这样测试 +// 与「真实形态的唯一真相」绑定,fixture 改则测试自动跟随,杜绝逐字漂移。 +function xmlDecode(s: string): string { + return s + .replace(/"/g, '"') + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/&/g, '&'); +} +function extractAttr(attr: string): string { + const m = SYNTHETIC_BPMN.match(new RegExp(attr + '="([^"]*)"')); + if (!m) throw new Error('fixture 缺属性 ' + attr); + return xmlDecode(m[1]); +} + +// activiti:candidateUsers,单实例办理人,type=position,content 尾部 4 个 CHAR 补白空格, +// 外层 meta 含非空 taskSuccessService(真实服务钩子)。 +const REAL_CANDIDATE = extractAttr('activiti:candidateUsers'); +// activiti:collection,多实例(会签)办理人,type=projectRoleType,content 为逗号分隔的 +// 11 个布尔维度串,外层 meta 全部为空/false。 +const REAL_MULTI = extractAttr('activiti:collection'); + +describe('parseCandidateExpression — 真实形态解析', () => { + it('解析真实 candidate 表达式(全角【】,识别为 candidate 变体)', () => { + const r = parseCandidateExpression(REAL_CANDIDATE); + expect(r).not.toBeNull(); + expect(r!.variant).toBe('candidate'); + expect(r!.items).toHaveLength(1); + expect(r!.items[0]).toMatchObject({ + type: 'position', + isCandidate: true, + isSendMail: false, + isSendPhone: false, + isSendMessage: false, + }); + }); + + it('content 尾部 CHAR 补白空格原样保留(不 trim)', () => { + const r = parseCandidateExpression(REAL_CANDIDATE); + // 32 位十六进制 id + 4 个尾部空格 + expect(r!.items[0].content).toBe('402881343cd50391013d62ccd0c20f7d '); + expect(r!.items[0].content).toHaveLength(36); + }); + + it('multiInstance 前缀变体 multiInstanceUsersHandler.getUsers 同套解析', () => { + const r = parseCandidateExpression(REAL_MULTI); + expect(r).not.toBeNull(); + expect(r!.variant).toBe('multiInstance'); + expect(r!.items[0].type).toBe('projectRoleType'); + }); + + it('content 含逗号分隔多值原样保留', () => { + const r = parseCandidateExpression(REAL_MULTI); + expect(r!.items[0].content).toBe( + 'true,false,false,false,false,false,false,false,false,false,false', + ); + }); +}); + +describe('buildCandidateExpression — 与引擎口径逐字往返', () => { + it('candidate 真实表达式 round-trip 逐字一致(全角【】+前后缀逐字+meta 不丢)', () => { + const r = parseCandidateExpression(REAL_CANDIDATE)!; + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toBe(REAL_CANDIDATE); + }); + + it('multiInstance 真实表达式 round-trip 逐字一致', () => { + const r = parseCandidateExpression(REAL_MULTI)!; + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toBe(REAL_MULTI); + }); + + it('外层 meta(messageTemplate/taskSuccessService/isSkip* 等)往返一字不丢', () => { + const r = parseCandidateExpression(REAL_CANDIDATE)!; + // 真实服务钩子:侧板只改 items 时,taskSuccessService 等业务字段必须原样带回, + // 否则重新部署会打掉已部署流程的任务后置服务。 + expect(r.meta).toMatchObject({ + messageTemplate: '', + taskSuccessService: 'PM_CONTRACTUALREGISTER_UPDATEPROJECTSTATUS', + isSkipInitiator: false, + isNoUserSkip: false, + isSkipBeforeTask: true, + }); + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toContain( + 'PM_CONTRACTUALREGISTER_UPDATEPROJECTSTATUS', + ); + }); + + it('构建输出前缀/后缀逐字对齐 BasePropertiesConverter 常量', () => { + const r = parseCandidateExpression(REAL_CANDIDATE)!; + const built = buildCandidateExpression(r.items, r.variant, r.meta); + expect(built.startsWith("${candidateUsersHandler.getCandidateUsers(execution,'")).toBe(true); + expect(built.endsWith("')}")).toBe(true); + const rm = parseCandidateExpression(REAL_MULTI)!; + const builtM = buildCandidateExpression(rm.items, rm.variant, rm.meta); + expect(builtM.startsWith("${multiInstanceUsersHandler.getUsers(execution,'")).toBe(true); + }); +}); + +describe('各 type 往返不丢字段(真实结构派生:同一真实外壳,仅换 type/content)', () => { + // 用真实 candidate 外壳(REAL_CANDIDATE 的 meta 与 item 键集),仅替换 type/content, + // 覆盖 §0 其余 type。结构逐字来自真实形态,值取真实业务样例。 + function reshape(type: string, content: string): string { + const r = parseCandidateExpression(REAL_CANDIDATE)!; + const item: UserPropertyItem = { ...r.items[0], type, content }; + return buildCandidateExpression([item], 'candidate', r.meta); + } + + it('scriptUser(content=${APPLYUSERS},真实会签办理人形态)往返不丢', () => { + const expr = reshape('scriptUser', '${APPLYUSERS}'); + const r = parseCandidateExpression(expr)!; + expect(r.items[0]).toMatchObject({ type: 'scriptUser', content: '${APPLYUSERS}' }); + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toBe(expr); + }); + + it('depart 往返不丢', () => { + const expr = reshape('depart', '402881343cd50391013d62ccd0c20f7d'); + const r = parseCandidateExpression(expr)!; + expect(r.items[0].type).toBe('depart'); + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toBe(expr); + }); + + it('beforeTaskLeader 往返不丢', () => { + const expr = reshape('beforeTaskLeader', ''); + const r = parseCandidateExpression(expr)!; + expect(r.items[0].type).toBe('beforeTaskLeader'); + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toBe(expr); + }); +}); + +describe('isSendMessage 可选字段', () => { + it('含 isSendMessage 往返保留', () => { + const r = parseCandidateExpression(REAL_CANDIDATE)!; + expect(r.items[0].isSendMessage).toBe(false); + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toBe(REAL_CANDIDATE); + }); + + it('缺 isSendMessage 的旧数据变体:parse 不填充,build 不凭空添加', () => { + // 引擎 BasePropertiesConverter:62-67 对 isCandidate/isSendMail/isSendPhone 无 null 守卫、 + // 唯 isSendMessage 有(:63),故存在无 isSendMessage 的合法历史数据。此变体无 meta。 + const NO_MSG = + "${candidateUsersHandler.getCandidateUsers(execution,'【\"items\":[【\"type\":\"user\",\"content\":\"u1,u2\",\"isCandidate\":true,\"isSendMail\":false,\"isSendPhone\":false】]】')}"; + const r = parseCandidateExpression(NO_MSG)!; + expect(r.items[0].isSendMessage).toBeUndefined(); + expect('isSendMessage' in r.items[0]).toBe(false); + expect(Object.keys(r.meta)).toHaveLength(0); + expect(buildCandidateExpression(r.items, r.variant, r.meta)).toBe(NO_MSG); + }); +}); + +describe('半角输入兼容 + build 恒全角', () => { + it('半角{}输入可解析,build 输出恒全角【】,回到真实全角形态', () => { + const halfWidth = REAL_CANDIDATE.split('【').join('{').split('】').join('}'); + expect(halfWidth).not.toBe(REAL_CANDIDATE); // 确认输入确是半角 + const r = parseCandidateExpression(halfWidth); + expect(r).not.toBeNull(); + expect(r!.items[0].type).toBe('position'); + // build 输出恒全角 → 等于真实全角原文 + expect(buildCandidateExpression(r!.items, r!.variant, r!.meta)).toBe(REAL_CANDIDATE); + }); +}); + +describe('非法/空输入返回 null 不抛', () => { + it('undefined → null', () => { + expect(parseCandidateExpression(undefined)).toBeNull(); + }); + + it('空串 → null', () => { + expect(parseCandidateExpression('')).toBeNull(); + }); + + it('缺前缀(非办理人表达式)→ null', () => { + expect(parseCandidateExpression('${someOtherExpr(execution)}')).toBeNull(); + }); + + it('有前缀但内容坏 JSON → null 不抛', () => { + const bad = + "${candidateUsersHandler.getCandidateUsers(execution,'【not a valid json】')}"; + expect(() => parseCandidateExpression(bad)).not.toThrow(); + expect(parseCandidateExpression(bad)).toBeNull(); + }); + + it('有前缀但缺后缀 → null', () => { + const noSuffix = "${candidateUsersHandler.getCandidateUsers(execution,'【\"items\":[]】"; + expect(parseCandidateExpression(noSuffix)).toBeNull(); + }); + + it('JSON 合法但无 items 数组 → null', () => { + const noItems = + "${candidateUsersHandler.getCandidateUsers(execution,'【\"foo\":1】')}"; + expect(parseCandidateExpression(noItems)).toBeNull(); + }); +}); diff --git a/src/modeler/candidateExpression.ts b/src/modeler/candidateExpression.ts new file mode 100644 index 0000000..fcdc824 --- /dev/null +++ b/src/modeler/candidateExpression.ts @@ -0,0 +1,114 @@ +// 办理人 / 会签(多实例)办理人表达式的编解码器(纯函数)。 +// +// 处理的是 bpmn-js businessObject **属性值层**的表达式(XML 实体已解码:真引号、全角【】), +// 不是 XML 源码层(")。引擎侧唯一真相: +// - 前后缀常量逐字对齐 com.dsasp.server.wf.bean.BasePropertiesConverter:34-35 +// CANDIDATESERVICE / MULTIINSTANCESERVICE(见下 PREFIX 常量)。 +// - 存储态的对象花括号一律写作**全角【】**(方括号 [] 半角),运行期由 +// CandidateUsersHandler:54 以 `.replace("【","{").replace("】","}")`(全局字面替换) +// 还原为合法 JSON 再交 Jackson 解析。本编解码器 build 输出恒全角、parse 兼容全角/半角。 +// - 外层对象结构:{"items":[{...}],"messageTemplate","taskSuccessService", +// "isSkipInitiator","isNoUserSkip","isSkipBeforeTask"}。引擎运行期候选人解析 +// (convertToUserProperties)只读 items,但 taskSuccessService 等是任务后置服务钩子等 +// 运行期业务字段——侧板只改 items 时必须原样带回(meta),否则重新部署会打掉这些字段。 +// +// 逐字往返约定:content 不含花括号(与引擎的全局替换同约定),故 JSON.stringify 产出的 +// 结构性 {} 全局换成全角是安全的;content 里的逗号分隔多值与 CHAR 尾部补白空格原样保留。 + +const CANDIDATE_PREFIX = "${candidateUsersHandler.getCandidateUsers(execution,'"; +const MULTI_PREFIX = "${multiInstanceUsersHandler.getUsers(execution,'"; +const SUFFIX = "')}"; + +export type CandidateVariant = 'candidate' | 'multiInstance'; + +/** 单个办理人项。字段名逐字对齐 BasePropertiesConverter 常量(:21-27)。 */ +export interface UserPropertyItem { + type: string; + content: string; + isCandidate?: boolean; + isSendMail?: boolean; + isSendPhone?: boolean; + isSendMessage?: boolean; +} + +export interface ParsedCandidateExpression { + items: UserPropertyItem[]; + variant: CandidateVariant; + /** items 之外的外层字段(messageTemplate/taskSuccessService/isSkip* 等),原样保留以逐字往返。 */ + meta: Record; +} + +function fullToHalf(s: string): string { + return s.split('【').join('{').split('】').join('}'); +} + +function halfToFull(s: string): string { + return s.split('{').join('【').split('}').join('】'); +} + +/** 按固定规范键序重建 item,只输出存在的键(不凭空增删),保证逐字确定性。 */ +function normalizeItem(it: UserPropertyItem): UserPropertyItem { + const o = {} as UserPropertyItem; + o.type = it.type; + o.content = it.content; + if (it.isCandidate !== undefined) o.isCandidate = it.isCandidate; + if (it.isSendMail !== undefined) o.isSendMail = it.isSendMail; + if (it.isSendPhone !== undefined) o.isSendPhone = it.isSendPhone; + if (it.isSendMessage !== undefined) o.isSendMessage = it.isSendMessage; + return o; +} + +/** + * 解析办理人/会签表达式。识别 candidate / multiInstance 两种前缀,内容段全角【】→{} 后 JSON.parse。 + * 非办理人表达式、缺后缀、坏 JSON、无 items 数组、undefined/空串一律返回 null 不抛。 + */ +export function parseCandidateExpression( + expr: string | undefined | null, +): ParsedCandidateExpression | null { + if (typeof expr !== 'string' || expr.length === 0) return null; + + let variant: CandidateVariant; + let prefix: string; + if (expr.startsWith(CANDIDATE_PREFIX)) { + variant = 'candidate'; + prefix = CANDIDATE_PREFIX; + } else if (expr.startsWith(MULTI_PREFIX)) { + variant = 'multiInstance'; + prefix = MULTI_PREFIX; + } else { + return null; + } + if (!expr.endsWith(SUFFIX)) return null; + + const content = expr.slice(prefix.length, expr.length - SUFFIX.length); + let obj: unknown; + try { + obj = JSON.parse(fullToHalf(content)); + } catch { + return null; + } + if (obj === null || typeof obj !== 'object') return null; + const record = obj as Record; + if (!Array.isArray(record.items)) return null; + + const items = (record.items as UserPropertyItem[]).map(normalizeItem); + const meta: Record = { ...record }; + delete meta.items; + + return { items, variant, meta }; +} + +/** + * 构建办理人/会签表达式:重建外层对象 {items, ...meta} → JSON.stringify(紧凑无空白)→ + * 结构性 {} 换成全角【】(方括号保持半角)→ 套前后缀。round-trip 与真实表达式逐字一致。 + */ +export function buildCandidateExpression( + items: UserPropertyItem[], + variant: CandidateVariant, + meta?: Record, +): string { + const prefix = variant === 'multiInstance' ? MULTI_PREFIX : CANDIDATE_PREFIX; + const outer = { items: items.map(normalizeItem), ...(meta ?? {}) }; + const content = halfToFull(JSON.stringify(outer)); + return prefix + content + SUFFIX; +}