// 办理人 / 会签(多实例)办理人表达式的编解码器(纯函数)。 // // 处理的是 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"}(语料实测 meta 键集有多种子集)。 // 引擎运行期候选人解析(convertToUserProperties)只读 items,但 taskSuccessService 等是 // 任务后置服务钩子等运行期业务字段——侧板只改 items 时必须原样带回(meta),否则重新部署 // 会打掉这些字段。 // - 字符串叶子值(content/messageTemplate 等)的转义逐字对齐原版 stringToJson // (BasePropertiesConverter.java:235-280):`'`→‘(U+2018)、`"`→“(U+201C)、 // `{`→【、`}`→】,反斜杠与控制字符走标准 JSON 转义。build 对新值应用此契约,防用户输入 // 含 `'`(截断外层 JUEL 单引号字面量)或 `"`(截断内层 JSON)导致部署后表达式解析即断。 // // 逐字往返口径(全量 1512 流 4794 条真实表达式实测,见 tools/codec-corpus-sweep.mjs): // - 4774/4794 build(parse(x))===x 逐字一致;`‘`/`“`/`\/` 在语料 0 命中,故新增引号 // 转义对存量表达式为 no-op(合法存量叶子值不含裸 ' / ",否则会截断 JUEL/JSON)。 // - 余 20 条 content 用**半角** `${users}`(scriptUser 会签变体,非 stringToJson 产物): // parse 保留原值,build 把结构性 {} 连同 content 里的半角 {} 一并规范化为全角【】。此非字节 // 逐字,但**运行期等价**——引擎 :54 对整串做全局 【→{ 还原,`$【users】` 复原为 `${users}`。 // - 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; } /** item 的规范键序;未知键在其后按原序透传(与 meta 全量保留对称,不静默丢未来扩展键)。 */ const KNOWN_ITEM_KEYS = ['type', 'content', 'isCandidate', 'isSendMail', 'isSendPhone', 'isSendMessage']; const KNOWN_ITEM_KEY_SET = new Set(KNOWN_ITEM_KEYS); function fullToHalf(s: string): string { return s.split('【').join('{').split('】').join('}'); } function halfToFull(s: string): string { return s.split('{').join('【').split('}').join('】'); } /** * 字符串叶子值转义,逐字对齐原版 stringToJson 里 JSON.stringify **未覆盖**的两处值级映射: * `'`→‘、`"`→“。(反斜杠/控制字符由 JSON.stringify 覆盖;`{`/`}`→【/】由 halfToFull 覆盖。) * 对合法存量叶子值(不含裸 ' / ")为 no-op,故不破坏逐字往返;仅对面板新输入生效。 */ function escapeLeaf(v: string): string { return v.split("'").join('‘').split('"').join('“'); } /** 按规范键序重建 item:已知键在前(存在才输出,不凭空增删),未知键按原序透传。 */ function reorderItem(src: Record): Record { const o: Record = {}; for (const k of KNOWN_ITEM_KEYS) { if (src[k] !== undefined) o[k] = src[k]; } for (const k of Object.keys(src)) { if (!KNOWN_ITEM_KEY_SET.has(k) && src[k] !== undefined) o[k] = src[k]; } return o; } /** * 解析办理人/会签表达式。识别 candidate / multiInstance 两种前缀,内容段全角【】→{} 后 JSON.parse。 * 非办理人表达式、缺后缀、坏 JSON、无 items 数组、items 元素非对象或 type 非字符串、 * 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; // 形状守卫:元素必须是普通对象且 type 为字符串,否则整体返 null(对齐「非法返 null 不抛」)。 for (const el of record.items) { if (el === null || typeof el !== 'object' || Array.isArray(el)) return null; if (typeof (el as Record).type !== 'string') return null; } const items = (record.items as Record[]).map( reorderItem, ) as unknown as UserPropertyItem[]; const meta: Record = { ...record }; delete meta.items; return { items, variant, meta }; } /** * 构建办理人/会签表达式:重建外层对象 {items, ...meta} → JSON.stringify(紧凑无空白,replacer * 对字符串叶子应用 stringToJson 引号映射)→ 结构性 {} 换成全角【】(方括号保持半角)→ 套前后缀。 * round-trip 与真实表达式逐字一致(半角 content 变体除外,见文件头运行期等价说明)。 */ export function buildCandidateExpression( items: UserPropertyItem[], variant: CandidateVariant, meta?: Record, ): string { const prefix = variant === 'multiInstance' ? MULTI_PREFIX : CANDIDATE_PREFIX; const outer = { items: items.map((it) => reorderItem(it as unknown as Record)), ...(meta ?? {}), }; const json = JSON.stringify(outer, (_key, value) => typeof value === 'string' ? escapeLeaf(value) : value, ); return prefix + halfToFull(json) + SUFFIX; }