feat(modeler): 办理人/会签表达式编解码器(与 BasePropertiesConverter 逐字对齐)

纯前端纯函数 codec,parse/build 处理 businessObject 属性值层的办理人表达式。
前后缀常量逐字对齐 BasePropertiesConverter:34-35(candidate/multiInstance 两变体);
内容段全角【】↔{} 双向映射(build 恒全角,parse 兼容半角);外层 meta
(messageTemplate/taskSuccessService/isSkip* 等运行期业务字段)原样保留,侧板只改
items 也逐字往返不丢。content 逗号多值与 CHAR 尾部补白空格原样保留。

TDD:先红后绿。测试运行时从 synthetic-full-surface fixture 抽真实表达式锚定逐字形态。
20 例(真实 candidate/multiInstance 往返逐字 / 尾部空格保留 / 各 type 不丢字段 /
isSendMessage 可选往返 / 半角输入兼容 build 恒全角 / 非法输入返 null 不抛)全绿;
modeler 全量 32 例绿;tsc -b 干净。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-02 11:16:51 +08:00
parent dffd1f32ef
commit 3dfb90f59b
2 changed files with 316 additions and 0 deletions

View File

@@ -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 实体解码(&quot;→")得到 businessObject 属性值层的真实表达式。这样测试
// 与「真实形态的唯一真相」绑定,fixture 改则测试自动跟随,杜绝逐字漂移。
function xmlDecode(s: string): string {
return s
.replace(/&quot;/g, '"')
.replace(/&lt;/g, '<')
.replace(/&gt;/g, '>')
.replace(/&amp;/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();
});
});

View File

@@ -0,0 +1,114 @@
// 办理人 / 会签(多实例)办理人表达式的编解码器(纯函数)。
//
// 处理的是 bpmn-js businessObject **属性值层**的表达式(XML 实体已解码:真引号、全角【】),
// 不是 XML 源码层(&quot;)。引擎侧唯一真相:
// - 前后缀常量逐字对齐 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<string, unknown>;
}
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<string, unknown>;
if (!Array.isArray(record.items)) return null;
const items = (record.items as UserPropertyItem[]).map(normalizeItem);
const meta: Record<string, unknown> = { ...record };
delete meta.items;
return { items, variant, meta };
}
/**
* 构建办理人/会签表达式:重建外层对象 {items, ...meta} → JSON.stringify(紧凑无空白)→
* 结构性 {} 换成全角【】(方括号保持半角)→ 套前后缀。round-trip 与真实表达式逐字一致。
*/
export function buildCandidateExpression(
items: UserPropertyItem[],
variant: CandidateVariant,
meta?: Record<string, unknown>,
): 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;
}