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,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;
}