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>
This commit is contained in:
2026-07-02 11:36:53 +08:00
parent 6dc9075648
commit 11632b4801
3 changed files with 340 additions and 21 deletions

View File

@@ -8,12 +8,22 @@
// CandidateUsersHandler:54 以 `.replace("【","{").replace("】","}")`(全局字面替换)
// 还原为合法 JSON 再交 Jackson 解析。本编解码器 build 输出恒全角、parse 兼容全角/半角。
// - 外层对象结构:{"items":[{...}],"messageTemplate","taskSuccessService",
// "isSkipInitiator","isNoUserSkip","isSkipBeforeTask"}。引擎运行期候选人解析
// (convertToUserProperties)只读 items,但 taskSuccessService 等是任务后置服务钩子等
// 运行期业务字段——侧板只改 items 时必须原样带回(meta),否则重新部署会打掉这些字段。
// "isSkipInitiator","isNoUserSkip","isSkipBeforeTask"}(语料实测 meta 键集有多种子集)。
// 引擎运行期候选人解析(convertToUserProperties)只读 items,但 taskSuccessService 等是
// 任务后置服务钩子等运行期业务字段——侧板只改 items 时必须原样带回(meta),否则重新部署
// 会打掉这些字段。
// - 字符串叶子值(content/messageTemplate 等)的转义逐字对齐原版 stringToJson
// (BasePropertiesConverter.java:235-280):`'`→‘(U+2018)、`"`→“(U+201C)、
// `{`→【、`}`→】,反斜杠与控制字符走标准 JSON 转义。build 对新值应用此契约,防用户输入
// 含 `'`(截断外层 JUEL 单引号字面量)或 `"`(截断内层 JSON)导致部署后表达式解析即断。
//
// 逐字往返约定:content 不含花括号(与引擎的全局替换同约定),故 JSON.stringify 产出的
// 结构性 {} 全局换成全角是安全的;content 里的逗号分隔多值与 CHAR 尾部补白空格原样保留。
// 逐字往返口径(全量 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,'";
@@ -38,6 +48,10 @@ export interface ParsedCandidateExpression {
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('}');
}
@@ -46,21 +60,31 @@ 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;
/**
* 字符串叶子值转义,逐字对齐原版 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 数组、undefined/空串一律返回 null 不抛。
* 非办理人表达式、缺后缀、坏 JSON、无 items 数组、items 元素非对象或 type 非字符串、
* undefined/空串一律返回 null 不抛。
*/
export function parseCandidateExpression(
expr: string | undefined | null,
@@ -91,7 +115,15 @@ export function parseCandidateExpression(
const record = obj as Record<string, unknown>;
if (!Array.isArray(record.items)) return null;
const items = (record.items as UserPropertyItem[]).map(normalizeItem);
// 形状守卫:元素必须是普通对象且 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;
@@ -99,8 +131,9 @@ export function parseCandidateExpression(
}
/**
* 构建办理人/会签表达式:重建外层对象 {items, ...meta} → JSON.stringify(紧凑无空白)→
* 结构性 {} 换成全角【】(方括号保持半角)→ 套前后缀。round-trip 与真实表达式逐字一致。
* 构建办理人/会签表达式:重建外层对象 {items, ...meta} → JSON.stringify(紧凑无空白,replacer
* 对字符串叶子应用 stringToJson 引号映射)→ 结构性 {} 换成全角【】(方括号保持半角)→ 套前后缀。
* round-trip 与真实表达式逐字一致(半角 content 变体除外,见文件头运行期等价说明)。
*/
export function buildCandidateExpression(
items: UserPropertyItem[],
@@ -108,7 +141,12 @@ export function buildCandidateExpression(
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;
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;
}