diff --git a/flowable-service/src/main/java/com/eip4/flowservice/api/BpmnIdSanitizer.java b/flowable-service/src/main/java/com/eip4/flowservice/api/BpmnIdSanitizer.java
new file mode 100644
index 0000000..0d9d59e
--- /dev/null
+++ b/flowable-service/src/main/java/com/eip4/flowservice/api/BpmnIdSanitizer.java
@@ -0,0 +1,125 @@
+package com.eip4.flowservice.api;
+
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.Map;
+import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * BPMN id 净化/还原(可逆双射)。
+ *
+ *
迁移的 1512 个真实流程里,1445 个的 process id 就是中文(如「总包合同交底」),BPMN 常把中文用作
+ * process/diagram/节点 id。bpmn-js / moddle 的 NCName 校验拒非 ASCII id → 整图无法渲染,且 moddle-xml
+ * 在 import 前就会拒中文 id。{@link #sanitize} 把非法(非 ASCII NCName)id 及其全部引用一致重写为安全
+ * ASCII id(稳定哈希),保存原→净化映射;{@link #restore} 依映射逆向还原——发布存量流程时把中文原 key
+ * 原样写回引擎,保证 process key 不变(D7 硬需求)。
+ *
+ * 双射保证:同一文档内两个不同中文 id 若哈希相同(Java String.hashCode 存在碰撞),基名冲突时
+ * 追加 {@code -2}/{@code -3} 序号;生成的净化 id 亦不与文档内既有合法 id 冲突。故净化后引用不串、restore
+ * 可精确逆向。非碰撞场景下净化输出与历史实现({@code "n"+hex(hashCode)})逐字节一致,保住查看器回归。
+ *
+ * restore 前缀安全:还原一律复用 {@link #ID_ATTR} 正则逐个属性值精确匹配,绝不裸 {@code String.replace}
+ * 子串替换——否则净化 id {@code n1} 会误伤前缀相同的 {@code n1x}。映射外的 id(如设计器新增的 ASCII 节点)原样保留。
+ */
+final class BpmnIdSanitizer {
+
+ private BpmnIdSanitizer() {
+ }
+
+ /** id/引用类属性(值须为合法 NCName);name/value 等展示属性不在内,避免改坏中文节点名。 */
+ static final Pattern ID_ATTR = Pattern.compile(
+ "\\b(id|bpmnElement|sourceRef|targetRef|attachedToRef|processRef|default)\\s*=\\s*\"([^\"]+)\"");
+
+ /** 净化结果:{@code xml}=净化后 XML;{@code idMap}=原 id→净化 id(双射,供 {@link #restore} 逆向)。 */
+ record Result(String xml, Map idMap) {
+ }
+
+ /**
+ * 把 BPMN 里非法(非 ASCII NCName)的 id 及其全部引用一致重写为安全 ASCII id。
+ * 只重写 id/引用类属性,name 等展示属性不动。返回净化 XML 与「原 id→净化 id」映射。
+ */
+ static Result sanitize(String xml) {
+ if (xml == null || xml.isEmpty()) {
+ return new Result(xml, Map.of());
+ }
+ // 先登记文档内所有合法 id,占位保证生成的净化 id 不与既有合法 id 冲突(双射 + restore 安全)。
+ Set used = new LinkedHashSet<>();
+ Matcher scanLegal = ID_ATTR.matcher(xml);
+ while (scanLegal.find()) {
+ String val = scanLegal.group(2);
+ if (isValidNcName(val)) {
+ used.add(val);
+ }
+ }
+ // 收集非法 id → 唯一净化 id;基名冲突(含 hash 碰撞)时追加 -2/-3… 保双射。
+ Map map = new LinkedHashMap<>();
+ Matcher scan = ID_ATTR.matcher(xml);
+ while (scan.find()) {
+ String val = scan.group(2);
+ if (!isValidNcName(val) && !map.containsKey(val)) {
+ String base = "n" + Integer.toHexString(val.hashCode() & 0x7fffffff);
+ String safe = base;
+ int seq = 2;
+ while (used.contains(safe)) {
+ safe = base + "-" + seq++;
+ }
+ map.put(val, safe);
+ used.add(safe);
+ }
+ }
+ if (map.isEmpty()) {
+ return new Result(xml, Map.of());
+ }
+ return new Result(rewrite(xml, map), map);
+ }
+
+ /**
+ * 依 {@code idMap}(原→净化)逆向还原:把净化 id 精确写回原 id。映射外的 id(如新增 ASCII 节点)原样保留。
+ * 逐个属性值精确匹配(复用 {@link #ID_ATTR}),前缀安全。
+ */
+ static String restore(String xml, Map idMap) {
+ if (xml == null || xml.isEmpty() || idMap == null || idMap.isEmpty()) {
+ return xml;
+ }
+ Map inverse = new LinkedHashMap<>();
+ for (Map.Entry e : idMap.entrySet()) {
+ inverse.put(e.getValue(), e.getKey());
+ }
+ return rewrite(xml, inverse);
+ }
+
+ /** 逐个 id/引用类属性值按 {@code map} 精确替换(命中才换,未命中原样)。前缀安全:只锚定完整属性值。 */
+ private static String rewrite(String xml, Map map) {
+ Matcher rw = ID_ATTR.matcher(xml);
+ StringBuilder sb = new StringBuilder();
+ while (rw.find()) {
+ String attr = rw.group(1);
+ String val = rw.group(2);
+ String repl = map.getOrDefault(val, val);
+ rw.appendReplacement(sb, Matcher.quoteReplacement(attr + "=\"" + repl + "\""));
+ }
+ rw.appendTail(sb);
+ return sb.toString();
+ }
+
+ /** ASCII NCName:首字符字母/下划线,其余字母/数字/下划线/连字符/点;非 ASCII(中文等)视为非法。 */
+ private static boolean isValidNcName(String s) {
+ if (s == null || s.isEmpty()) {
+ return false;
+ }
+ char c0 = s.charAt(0);
+ if (!((c0 >= 'A' && c0 <= 'Z') || (c0 >= 'a' && c0 <= 'z') || c0 == '_')) {
+ return false;
+ }
+ for (int i = 1; i < s.length(); i++) {
+ char c = s.charAt(i);
+ if (!((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9')
+ || c == '_' || c == '-' || c == '.')) {
+ return false;
+ }
+ }
+ return true;
+ }
+}
diff --git a/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessDiagramController.java b/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessDiagramController.java
index 1022e99..8749cd6 100644
--- a/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessDiagramController.java
+++ b/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessDiagramController.java
@@ -109,63 +109,16 @@ public class ProcessDiagramController {
return ResponseEntity.ok(resp);
}
- /** id/引用类属性(需为合法 NCName;name/value 等展示属性不在内,避免改坏中文节点名)。 */
- private static final java.util.regex.Pattern ID_ATTR = java.util.regex.Pattern.compile(
- "\\b(id|bpmnElement|sourceRef|targetRef|attachedToRef|processRef|default)\\s*=\\s*\"([^\"]+)\"");
-
/**
- * 把 BPMN 里非法(非 ASCII NCName)的 id 及其全部引用一致重写为安全 ASCII id(稳定哈希),
- * 使 bpmn-js 能解析渲染。只重写 id/引用类属性,name 等展示属性不动。同步重映射 active/finished 节点 id。
+ * 把 BPMN 里非法(非 ASCII NCName)的 id 及其全部引用一致重写为安全 ASCII id,使 bpmn-js 能解析渲染,
+ * 并同步重映射 active/finished 节点 id。净化算法委托 {@link BpmnIdSanitizer}(含可逆映射与 hash 碰撞消解)。
*/
static String sanitizeBpmnIds(String xml, List active, List finished) {
- if (xml == null || xml.isEmpty()) {
- return xml;
- }
- // 1. 收集所有非法 id 值 → 安全 id 映射
- java.util.Map map = new java.util.LinkedHashMap<>();
- java.util.regex.Matcher scan = ID_ATTR.matcher(xml);
- while (scan.find()) {
- String val = scan.group(2);
- if (!isValidNcName(val) && !map.containsKey(val)) {
- map.put(val, "n" + Integer.toHexString(val.hashCode() & 0x7fffffff));
- }
- }
- if (map.isEmpty()) {
- return xml;
- }
- // 2. 仅重写 id/引用类属性(appendReplacement 精确,不误伤 name=)
- java.util.regex.Matcher rw = ID_ATTR.matcher(xml);
- StringBuilder sb = new StringBuilder();
- while (rw.find()) {
- String attr = rw.group(1);
- String val = rw.group(2);
- String repl = map.getOrDefault(val, val);
- rw.appendReplacement(sb, java.util.regex.Matcher.quoteReplacement(attr + "=\"" + repl + "\""));
- }
- rw.appendTail(sb);
- // 3. 同步重映射返回的当前/历史节点 id
+ BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml);
+ Map map = r.idMap();
active.replaceAll(id -> map.getOrDefault(id, id));
finished.replaceAll(id -> map.getOrDefault(id, id));
- return sb.toString();
- }
-
- /** ASCII NCName:首字符字母/下划线,其余字母/数字/下划线/连字符/点;非 ASCII(中文等)视为非法。 */
- private static boolean isValidNcName(String s) {
- if (s == null || s.isEmpty()) {
- return false;
- }
- char c0 = s.charAt(0);
- if (!((c0 >= 'A' && c0 <= 'Z') || (c0 >= 'a' && c0 <= 'z') || c0 == '_')) {
- return false;
- }
- for (int i = 1; i < s.length(); i++) {
- char c = s.charAt(i);
- if (!((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9')
- || c == '_' || c == '-' || c == '.')) {
- return false;
- }
- }
- return true;
+ return r.xml();
}
/** 读流程定义 BPMN XML(getProcessModel 返回部署的 BPMN 资源流)。读失败返回 null(前端降级)。 */
diff --git a/flowable-service/src/test/java/com/eip4/flowservice/api/BpmnIdSanitizerTest.java b/flowable-service/src/test/java/com/eip4/flowservice/api/BpmnIdSanitizerTest.java
new file mode 100644
index 0000000..2f309fd
--- /dev/null
+++ b/flowable-service/src/test/java/com/eip4/flowservice/api/BpmnIdSanitizerTest.java
@@ -0,0 +1,163 @@
+package com.eip4.flowservice.api;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * BpmnIdSanitizer 可逆双射单测:净化(中文 id→安全 ASCII)与还原(restore)严格互逆,
+ * 覆盖 hash 碰撞消解、restore 前缀安全、合法 id 不动、混合场景。
+ *
+ * 非碰撞净化输出须与 ProcessDiagramController 旧实现逐字节一致(由既有 ProcessDiagramControllerTest 兜底),
+ * 本类聚焦「可逆」这一新增契约。
+ */
+class BpmnIdSanitizerTest {
+
+ /** 中文 process id + processRef/sourceRef/targetRef/default/attachedToRef 全引用面净化→restore 须逐字节还原。 */
+ @Test
+ void 净化后还原_逐字节等于原文() {
+ String xml = """
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ """;
+
+ BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml);
+
+ // 中文 id 不再出现在 id/引用类属性中;name 展示属性照旧保留中文
+ assertThat(r.xml()).doesNotContain("id=\"总包合同交底\"");
+ assertThat(r.xml()).doesNotContain("processRef=\"总包合同交底\"");
+ assertThat(r.xml()).doesNotContain("attachedToRef=\"审批\"");
+ assertThat(r.xml()).contains("name=\"总包合同交底\"");
+ assertThat(r.xml()).contains("name=\"审批人\"");
+ // idMap 覆盖全部 5 个中文 id(合法 ASCII id 不入 map)
+ assertThat(r.idMap()).containsOnlyKeys("总包合同交底", "审批", "超时", "回退", "通过");
+
+ // restore 逐字节还原
+ assertThat(BpmnIdSanitizer.restore(r.xml(), r.idMap())).isEqualTo(xml);
+ }
+
+ /**
+ * hash 碰撞消解:Java String.hashCode 下 "中Aa" 与 "中BB" 撞哈希('A'*31+'a' == 'B'*31+'B' == 2112),
+ * 二者又都是非法 NCName(含中文)→ 旧实现会撞成同一净化 id(非双射)。sanitize 须给两者不同净化 id,restore 仍完整还原。
+ */
+ @Test
+ void 撞哈希两中文id_净化后仍双射可逆() {
+ // 前置自证:确实撞哈希
+ assertThat("中Aa".hashCode()).isEqualTo("中BB".hashCode());
+
+ String xml = """
+
+
+
+
+
+
+ """;
+
+ BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml);
+
+ String s1 = r.idMap().get("中Aa");
+ String s2 = r.idMap().get("中BB");
+ // 双射:两净化 id 互不相同(否则 sourceRef/targetRef 引用会串)
+ assertThat(s1).isNotNull();
+ assertThat(s2).isNotNull();
+ assertThat(s1).isNotEqualTo(s2);
+ // 碰撞消解序号:其一为基名,另一为基名 +"-2"
+ assertThat(s1 + "|" + s2).containsPattern("-2");
+ // 净化后中文 id 消失
+ assertThat(r.xml()).doesNotContain("中Aa");
+ assertThat(r.xml()).doesNotContain("中BB");
+ // restore 逐字节还原(引用不串)
+ assertThat(BpmnIdSanitizer.restore(r.xml(), r.idMap())).isEqualTo(xml);
+ }
+
+ /**
+ * restore 前缀安全:idMap 同时含净化 id "n1" 与 "n1x"(后者以前者为前缀)。
+ * 裸 String.replace("n1",..) 会把 "n1x" 误伤成 "x";必须锚定完整属性值精确匹配。
+ */
+ @Test
+ void restore前缀安全_n1不误伤n1x() {
+ Map idMap = new LinkedHashMap<>();
+ idMap.put("原A", "n1");
+ idMap.put("原B", "n1x");
+ String xml = "";
+
+ String out = BpmnIdSanitizer.restore(xml, idMap);
+
+ assertThat(out).isEqualTo("");
+ assertThat(out).doesNotContain("原Ax"); // 无前缀误伤
+ assertThat(out).doesNotContain("n1x");
+ assertThat(out).doesNotContain("n1\"");
+ }
+
+ /** 全合法 NCName id:不改写,idMap 为空,restore 无副作用。 */
+ @Test
+ void 合法NCName_id不改写_映射为空() {
+ String xml = ""
+ + "";
+
+ BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml);
+
+ assertThat(r.idMap()).isEmpty();
+ assertThat(r.xml()).isEqualTo(xml);
+ // 空 idMap 的 restore 原样返回
+ assertThat(BpmnIdSanitizer.restore(xml, r.idMap())).isEqualTo(xml);
+ }
+
+ /** 混合:部分中文部分合法,只映射中文者;合法 id 原样保留;restore 还原。 */
+ @Test
+ void 混合_只映射中文id_合法id原样保留() {
+ String xml = ""
+ + "";
+
+ BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml);
+
+ assertThat(r.idMap()).containsOnlyKeys("审批流程");
+ assertThat(r.xml()).contains("id=\"legalTask\"");
+ assertThat(r.xml()).contains("targetRef=\"legalTask\"");
+ assertThat(r.xml()).doesNotContain("审批流程");
+ assertThat(BpmnIdSanitizer.restore(r.xml(), r.idMap())).isEqualTo(xml);
+ }
+
+ /** restore 只回写映射内 id;净化后新增的 ASCII 节点 id(不在 idMap)原样保留。 */
+ @Test
+ void restore只回写映射内id_新增ascii_id保留() {
+ Map idMap = new LinkedHashMap<>();
+ idMap.put("审批", "n5");
+ // n9 是设计器新增节点,不在 idMap → restore 不得改动
+ String xml = ""
+ + "";
+
+ String out = BpmnIdSanitizer.restore(xml, idMap);
+
+ assertThat(out).isEqualTo(""
+ + "");
+ }
+
+ /** null/空 XML 防御:不抛,idMap 为空。 */
+ @Test
+ void 空xml不抛_映射为空() {
+ assertThat(BpmnIdSanitizer.sanitize(null).idMap()).isEmpty();
+ assertThat(BpmnIdSanitizer.sanitize("").idMap()).isEmpty();
+ assertThat(BpmnIdSanitizer.restore(null, Map.of())).isNull();
+ assertThat(BpmnIdSanitizer.restore("", Map.of())).isEqualTo("");
+ }
+}