Files
eip4-web/src/modeler/candidateExpression.ts
zhengwr 11632b4801 fix(modeler): codec 评审收口——stringToJson引号映射+半角content变体+item未知键透传+形状守卫
评审者跑全库 4794 条真实表达式往返对照原版序列化器,四项收口:
- I-1 build 补 stringToJson 引号契约(BasePropertiesConverter.java:235-280):字符串叶子值
  '→‘、"→“(经 JSON.stringify replacer,{}→【】由 halfToFull、\\与控制字符由 stringify 覆盖)。
  否则用户输入含 ' 截断外层 JUEL 单引号字面量 / 含 " 截断内层 JSON,部署后表达式解析即断。
  语料 ‘/“ 均 0 命中→对存量为 no-op,不破逐字往返。
- I-2 头注释纠偏:「content 不含花括号」被 20 条真实 ${users}(半角)证伪;改为事实——
  4774/4794 逐字,20 条半角 content 变体 build 归一为全角,引擎 :54 全局【→{ 还原后运行期等价。
- M-1 item 未知键 known-first 重排+按原序透传(与 meta 全量保留对称,不静默丢未来扩展键)。
- M-2 items 元素形状守卫:元素非对象或 type 非字符串→整体返 null 不抛。

加分:tools/codec-corpus-sweep.mjs(照 modeler-fidelity-sweep 风格,内联镜像 codec 跑全语料):
1512 文档 / 4794 表达式 → 逐字 4774 + 引擎运行期等价 20 + 解析失败 0 + 硬不匹配 0(门禁绿)。

测试 29 例(原 20 + 引号映射/幂等/meta 引号/半角变体运行期等价/未知键透传/形状守卫 9 例);
modeler 全量 66 例绿;tsc -b 干净。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 11:36:53 +08:00

153 lines
6.9 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 办理人 / 会签(多实例)办理人表达式的编解码器(纯函数)。
//
// 处理的是 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"}(语料实测 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<string, unknown>;
}
/** 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<string, unknown>): Record<string, unknown> {
const o: Record<string, unknown> = {};
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<string, unknown>;
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<string, unknown>).type !== 'string') return null;
}
const items = (record.items as Record<string, unknown>[]).map(
reorderItem,
) as unknown as UserPropertyItem[];
const meta: Record<string, unknown> = { ...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, unknown>,
): string {
const prefix = variant === 'multiInstance' ? MULTI_PREFIX : CANDIDATE_PREFIX;
const outer = {
items: items.map((it) => reorderItem(it as unknown as Record<string, unknown>)),
...(meta ?? {}),
};
const json = JSON.stringify(outer, (_key, value) =>
typeof value === 'string' ? escapeLeaf(value) : value,
);
return prefix + halfToFull(json) + SUFFIX;
}