From 57812f0edcfb67eb70f70f0a993fe11a7062e917 Mon Sep 17 00:00:00 2001
From: zhengwr
Date: Thu, 2 Jul 2026 11:15:54 +0800
Subject: [PATCH 01/11] =?UTF-8?q?feat(flow):=20=E6=B5=81=E7=A8=8B=E8=8D=89?=
=?UTF-8?q?=E7=A8=BF=20ProcessModelController(act=5Fre=5Fmodel,Model=20API?=
=?UTF-8?q?=20=E9=A6=96=E6=AC=A1=E5=90=AF=E7=94=A8)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
在线 Modeler 草稿仓:flowable 原生 Model API 存草稿于 act_re_model(全仓首次启用
Model API,表已有 143 行存量,databaseSchemaUpdate=false 不涉 DDL)。5 端点(@RequestMapping
"/api/flow"):GET /models 列表(orderByLastUpdateTime desc,时间转 ISO)、GET /models/{id}
取草稿(getModel+getModelEditorSource,不存在/源空→found:false)、POST /models 建草稿
(XML 过 BpmnXMLConverter 解析守卫,坏 XML→422 不落库)、PUT /models/{id} 更新
(不存在→404;name/metaInfo 仅当请求提供才更新,避免抹掉 eip4IdMap)、
POST /models/from-procdef 从流程定义建草稿(BpmnIdSanitizer 净化中文 id,
metaInfo={eip4IdMap,sourceProcDefId,originalKey} 供发布逆向还原)。
解析守卫就地 catch 转 422,不逸出到 FlowExceptionHandler(那里 FlowableException→400
语义不符)。from-procdef 复用本控制器自带 readProcessModel 小方法,零改动 ProcessDiagramController。
测试:ProcessModelControllerTest 11 例(列表 ISO 降序/取草稿含 metaInfo/model 不存在或
源空 found:false/建草稿合法 XML 落库/坏 XML 422 且 verify 零 saveModel/PUT 404/PUT 合法
更新 status:0/PUT 坏 XML 422/from-procdef 净化 XML 与 idMap 落 metaInfo(捕获 setMetaInfo
断言 JSON 含 eip4IdMap+中文 originalKey、捕获 editorSource 断言净化无中文 id)/procDef
不存在 found:false 不落库)。flowable-service 全模块 84 测试绿(新增 11,既有 73 零改动)。
Co-Authored-By: Claude Fable 5
---
.../api/ProcessModelController.java | 262 ++++++++++++++++
.../api/ProcessModelControllerTest.java | 281 ++++++++++++++++++
2 files changed, 543 insertions(+)
create mode 100644 flowable-service/src/main/java/com/eip4/flowservice/api/ProcessModelController.java
create mode 100644 flowable-service/src/test/java/com/eip4/flowservice/api/ProcessModelControllerTest.java
diff --git a/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessModelController.java b/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessModelController.java
new file mode 100644
index 0000000..6636dc3
--- /dev/null
+++ b/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessModelController.java
@@ -0,0 +1,262 @@
+package com.eip4.flowservice.api;
+
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.Date;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import org.flowable.bpmn.converter.BpmnXMLConverter;
+import org.flowable.common.engine.impl.util.io.StringStreamSource;
+import org.flowable.engine.RepositoryService;
+import org.flowable.engine.repository.Model;
+import org.flowable.engine.repository.ProcessDefinition;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.util.StreamUtils;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * 流程草稿 CRUD(flowable 原生 Model API 存 act_re_model,本控制器为全仓首次启用 Model API)。
+ *
+ * 在线 Modeler 的草稿仓:编辑中的 BPMN 存为 flowable Model(editorSource=BPMN XML,metaInfo=EIP4 元数据 JSON),
+ * 不进部署库;发布(T3.1)时才 restore 中文原 key + 校验门 + deploy。act_re_model 表已有 143 行存量、schema 已在,
+ * {@code databaseSchemaUpdate=false} 不涉 DDL。
+ *
+ * 写入前 XML 一律过 {@link BpmnXMLConverter} 解析守卫(validateSchema=true):坏 XML 返 422 且绝不落库。
+ * 守卫异常在本控制器就地 catch 转 422,不逸出到 {@code FlowExceptionHandler}(那里 FlowableException→400,语义不符)。
+ * {@code from-procdef} 复用「按 procDefId 读部署 BPMN」逻辑(本控制器自带 {@link #readProcessModel} 小方法,
+ * 零改动 ProcessDiagramController)→ {@link BpmnIdSanitizer#sanitize} 净化中文 id → 建草稿,
+ * 原→净化映射连同源 procDefId/原 key 写进 metaInfo,供发布逆向还原。
+ */
+@RestController
+@RequestMapping("/api/flow")
+@Tag(name = "流程草稿", description = "flowable Model API 草稿 CRUD(act_re_model)+ 从流程定义建草稿")
+public class ProcessModelController {
+
+ private static final Logger log = LoggerFactory.getLogger(ProcessModelController.class);
+
+ private final RepositoryService repositoryService;
+ private final ObjectMapper objectMapper = new ObjectMapper();
+
+ public ProcessModelController(RepositoryService repositoryService) {
+ this.repositoryService = repositoryService;
+ }
+
+ @GetMapping("/models")
+ @Operation(summary = "草稿列表",
+ description = "createModelQuery().orderByLastUpdateTime().desc() → {models:[{id,name,key,lastUpdateTime(ISO)}]}。")
+ public ResponseEntity
*
- * 写入前 XML 一律过 {@link BpmnXMLConverter} 解析守卫(validateSchema=true):坏 XML 返 422 且绝不落库。
+ *
存量隔离:本控制器建的草稿一律 {@code setCategory("eip4")},{@link #list()} 只查该分类,
+ * 库里 143 条老 shape act_re_model(旧 metaInfo + 可能悬空 editorSource)不进 Modeler 列表、避免打不开。
+ *
+ * 写入前 XML 一律过 {@link BpmnXMLConverter} 解析守卫(validateSchema=true + enableSafeBpmnXml=true,
+ * 后者关外部 DTD/实体解析,防 XXE/SSRF):坏 XML 返 422 且绝不落库;422 只回通用文案,原始解析原因仅进日志。
* 守卫异常在本控制器就地 catch 转 422,不逸出到 {@code FlowExceptionHandler}(那里 FlowableException→400,语义不符)。
* {@code from-procdef} 复用「按 procDefId 读部署 BPMN」逻辑(本控制器自带 {@link #readProcessModel} 小方法,
* 零改动 ProcessDiagramController)→ {@link BpmnIdSanitizer#sanitize} 净化中文 id → 建草稿,
* 原→净化映射连同源 procDefId/原 key 写进 metaInfo,供发布逆向还原。
+ *
+ * 鉴权:本控制器随 flowable-service 跑在裸 8089,进程本身无鉴权栈;所有写端点
+ * (POST/PUT/from-procdef)必须经 platform-flow-gateway 的超管门访问(T2.2),生产环境 8089 不对外暴露。
*/
@RestController
@RequestMapping("/api/flow")
@@ -51,6 +58,9 @@ public class ProcessModelController {
private static final Logger log = LoggerFactory.getLogger(ProcessModelController.class);
+ /** EIP4 草稿分类:建草稿时打此标,list() 只查此分类,隔离库里 143 条老 shape 存量 act_re_model。 */
+ static final String EIP4_CATEGORY = "eip4";
+
private final RepositoryService repositoryService;
private final ObjectMapper objectMapper = new ObjectMapper();
@@ -60,9 +70,11 @@ public class ProcessModelController {
@GetMapping("/models")
@Operation(summary = "草稿列表",
- description = "createModelQuery().orderByLastUpdateTime().desc() → {models:[{id,name,key,lastUpdateTime(ISO)}]}。")
+ description = "createModelQuery().modelCategory(\"eip4\").orderByLastUpdateTime().desc() → "
+ + "{models:[{id,name,key,lastUpdateTime(ISO)}]}。只列 EIP4 建的草稿,隔离存量 act_re_model。")
public ResponseEntity> list() {
List> models = repositoryService.createModelQuery()
+ .modelCategory(EIP4_CATEGORY)
.orderByLastUpdateTime().desc().list().stream()
.map(m -> {
Map row = new LinkedHashMap<>();
@@ -105,9 +117,13 @@ public class ProcessModelController {
@PostMapping("/models")
@Operation(summary = "建草稿",
- description = "body {name,key,bpmnXml,metaInfo?}。XML 先过 BpmnXMLConverter 解析守卫(坏 XML→422 不落库),"
- + "过门后 newModel+saveModel+addModelEditorSource → {modelId}。")
+ description = "body {name,key,bpmnXml,metaInfo?}。name/key 空白→422;XML 过 BpmnXMLConverter 解析守卫"
+ + "(坏 XML→422 不落库);过门后 newModel+setCategory(eip4)+saveModel+addModelEditorSource → {modelId}。")
public ResponseEntity> create(@RequestBody CreateModelRequest req) {
+ // key 是 T3.1 部署资源名/中文原 key 还原的依赖,name 用于列表展示:空白一律拒。
+ if (isBlank(req.name) || isBlank(req.key)) {
+ return status(HttpStatus.UNPROCESSABLE_ENTITY, "name 与 key 不能为空");
+ }
ResponseEntity> rejected = parseGuard(req.bpmnXml);
if (rejected != null) {
return rejected;
@@ -115,6 +131,7 @@ public class ProcessModelController {
Model model = repositoryService.newModel();
model.setName(req.name);
model.setKey(req.key);
+ model.setCategory(EIP4_CATEGORY);
if (req.metaInfo != null) {
model.setMetaInfo(req.metaInfo);
}
@@ -184,6 +201,7 @@ public class ProcessModelController {
Model model = repositoryService.newModel();
model.setName(def.getName());
model.setKey(def.getKey());
+ model.setCategory(EIP4_CATEGORY);
model.setMetaInfo(metaInfoJson);
repositoryService.saveModel(model);
repositoryService.addModelEditorSource(model.getId(), r.xml().getBytes(StandardCharsets.UTF_8));
@@ -195,17 +213,21 @@ public class ProcessModelController {
/**
* BPMN 解析守卫:过则返回 {@code null}(放行),坏 XML 返回 422 ResponseEntity({status:1,msg})。
* 就地 catch 一切异常,不让引擎 XMLException/FlowableException 逸出到全局 advice(那里映射成 400,语义不符)。
+ *
+ * {@code convertToBpmnModel(source, validateSchema, enableSafeBpmnXml)} 两布尔参:
+ * {@code validateSchema=true} 走 BPMN 2.0 XSD 校验(拒非法结构);
+ * {@code enableSafeBpmnXml=true} 启用 flowable 加固解析器(禁外部 DTD/参数实体/DOCTYPE),
+ * 关掉 XXE/SSRF 面——校验路径也走加固解析器,不给外部实体注入留口。
+ *
+ * 422 只回通用文案;原始解析原因(可能含内部路径/实体细节)仅进 {@code log.warn},不回显给调用方。
*/
private ResponseEntity> parseGuard(String xml) {
try {
- new BpmnXMLConverter().convertToBpmnModel(new StringStreamSource(xml), true, false);
+ new BpmnXMLConverter().convertToBpmnModel(new StringStreamSource(xml), true, true);
return null;
} catch (Exception e) {
log.warn("[流程草稿] BPMN 解析守卫拒绝: {}", e.toString());
- Map body = new LinkedHashMap<>();
- body.put("status", 1);
- body.put("msg", "BPMN 解析失败: " + e.getMessage());
- return ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY).body(body);
+ return status(HttpStatus.UNPROCESSABLE_ENTITY, "BPMN 解析失败");
}
}
@@ -240,6 +262,11 @@ public class ProcessModelController {
return d == null ? null : d.toInstant().toString();
}
+ /** null 或纯空白(含全角/半角空格)视为空白。 */
+ private static boolean isBlank(String s) {
+ return s == null || s.isBlank();
+ }
+
/** 建草稿入参。 */
public static class CreateModelRequest {
public String name;
diff --git a/flowable-service/src/test/java/com/eip4/flowservice/api/ProcessModelControllerTest.java b/flowable-service/src/test/java/com/eip4/flowservice/api/ProcessModelControllerTest.java
index 705e85b..aa5e2a2 100644
--- a/flowable-service/src/test/java/com/eip4/flowservice/api/ProcessModelControllerTest.java
+++ b/flowable-service/src/test/java/com/eip4/flowservice/api/ProcessModelControllerTest.java
@@ -64,13 +64,14 @@ class ProcessModelControllerTest {
}
@Test
- void 列表按最近更新降序返回id名key时间() throws Exception {
+ void 列表只查eip4分类并按最近更新降序返回id名key时间() throws Exception {
Model m = Mockito.mock(Model.class);
when(m.getId()).thenReturn("m1");
when(m.getName()).thenReturn("总包合同交底");
when(m.getKey()).thenReturn("总包合同交底");
when(m.getLastUpdateTime()).thenReturn(new Date(0L)); // 1970-01-01T00:00:00Z
when(repositoryService.createModelQuery()).thenReturn(modelQuery);
+ when(modelQuery.modelCategory("eip4")).thenReturn(modelQuery);
when(modelQuery.orderByLastUpdateTime()).thenReturn(modelQuery);
when(modelQuery.desc()).thenReturn(modelQuery);
when(modelQuery.list()).thenReturn(List.of(m));
@@ -81,6 +82,9 @@ class ProcessModelControllerTest {
.andExpect(jsonPath("$.models[0].name").value("总包合同交底"))
.andExpect(jsonPath("$.models[0].key").value("总包合同交底"))
.andExpect(jsonPath("$.models[0].lastUpdateTime").value("1970-01-01T00:00:00Z"));
+
+ // 列表只列 EIP4 建的草稿:隔离库里 143 条老 shape 存量 act_re_model(打不开)
+ verify(modelQuery).modelCategory("eip4");
}
@Test
@@ -137,6 +141,7 @@ class ProcessModelControllerTest {
verify(m).setName("新流程");
verify(m).setKey("newproc");
+ verify(m).setCategory("eip4"); // 建草稿打 EIP4 分类,供 list() 过滤隔离存量
verify(repositoryService).saveModel(m);
ArgumentCaptor src = ArgumentCaptor.forClass(byte[].class);
verify(repositoryService).addModelEditorSource(eq("newid"), src.capture());
@@ -144,6 +149,19 @@ class ProcessModelControllerTest {
new String(src.getValue(), StandardCharsets.UTF_8).contains(" meta = ArgumentCaptor.forClass(String.class);
verify(m).setMetaInfo(meta.capture());
@@ -262,6 +299,23 @@ class ProcessModelControllerTest {
verify(repositoryService, never()).newModel();
}
+ @Test
+ void fromProcDef_BPMN读取为空返found_false不落库() throws Exception {
+ // procDef 存在但部署 BPMN 资源读不出(getProcessModel 返 null)→ 降级 found:false,不建空草稿。
+ ProcessDefinition def = Mockito.mock(ProcessDefinition.class);
+ when(repositoryService.createProcessDefinitionQuery()).thenReturn(processDefinitionQuery);
+ when(processDefinitionQuery.processDefinitionId("def-empty")).thenReturn(processDefinitionQuery);
+ when(processDefinitionQuery.singleResult()).thenReturn(def);
+ when(repositoryService.getProcessModel("def-empty")).thenReturn(null);
+
+ mvc.perform(post("/api/flow/models/from-procdef")
+ .contentType(MediaType.APPLICATION_JSON).content("{\"procDefId\":\"def-empty\"}"))
+ .andExpect(status().isOk())
+ .andExpect(jsonPath("$.found").value(false));
+
+ verify(repositoryService, never()).newModel();
+ }
+
/** 把任意字符串编成 JSON 字符串字面量(转义引号/反斜杠/换行),用于拼请求体。 */
private static String jsonString(String s) {
StringBuilder sb = new StringBuilder("\"");
From 4abe9f8ce6e6fd1a7f6d24081617646965b2777d Mon Sep 17 00:00:00 2001
From: zhengwr
Date: Thu, 2 Jul 2026 11:48:29 +0800
Subject: [PATCH 04/11] =?UTF-8?q?docs(plan):=20=E5=9B=9E=E5=86=99=20T2.4?=
=?UTF-8?q?=20=E8=AF=84=E5=AE=A1=E2=80=94=E2=80=94T3.2=20=E8=AF=AD?=
=?UTF-8?q?=E4=B9=89=E6=A0=A1=E9=AA=8C=E5=8A=A0=20items=20=E9=9D=9E?=
=?UTF-8?q?=E7=A9=BA=E4=B8=8E=E8=87=AA=E5=AE=9A=E4=B9=89=E5=AE=8C=E6=88=90?=
=?UTF-8?q?=E6=9D=A1=E4=BB=B6=E5=8F=A3=E5=BE=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-Authored-By: Claude Fable 5
---
docs/plans/2026-07-02-在线流程Modeler-实施计划.md | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/plans/2026-07-02-在线流程Modeler-实施计划.md b/docs/plans/2026-07-02-在线流程Modeler-实施计划.md
index fcad0db..5e22e7d 100644
--- a/docs/plans/2026-07-02-在线流程Modeler-实施计划.md
+++ b/docs/plans/2026-07-02-在线流程Modeler-实施计划.md
@@ -301,6 +301,8 @@ commit:`feat(flow): 草稿发布(id还原+ProcessValidator校验门)+影响摘
### Task 3.2 网关:EIP4 语义校验 + 部署审计(Flyway V4)
+> 📌 **T2.4 评审补充**:语义校验白名单须加两条——①办理人/会签表达式的 `items` **非空**(`items:[]` 的 MI collection 运行期会炸,仅 JSON 可解析+type 白名单不够);②completionCondition 允许「三预设 或 保留的自定义 body」(T2.4 已实现自定义保留态,校验别把存量自定义条件拒了,白名单改为预设正则 ∪ 非空任意表达式加告警)。
+
**Files:**
- Create: `platform-flow-gateway/.../aggregate/ModelSemanticValidator.java` + test:解析 XML(**照 WfTemplateService.newJdkDbf :116-135 钉 JDK 解析器**,防 xerces 击穿)→ ①每个 `activiti:candidateUsers`/multiInstance collection 的内嵌 JSON 可解析且 items[].type ∈ 白名单 ②`activiti:formKey` 存在于 view_wftemplate(JdbcTemplate exists)③completionCondition 匹配预设白名单正则。返回 `List errors`。
- Create: `platform-app/src/main/resources/db/migration/V4__flow_deploy_audit.sql`(照 V3 风格):`sys_flow_deploy_audit(id bigserial pk, model_id, deployment_id, process_key, new_version int, operator varchar(64), deployed_at timestamp default now())`
From b489f3d834d8d5fd296b366644c835a965f7fb1d Mon Sep 17 00:00:00 2001
From: zhengwr
Date: Thu, 2 Jul 2026 11:48:30 +0800
Subject: [PATCH 05/11] =?UTF-8?q?feat(gateway):=20models=20=E4=BA=94?=
=?UTF-8?q?=E7=AB=AF=E7=82=B9=E8=BD=AC=E5=8F=91(requireSuperAdmin=20?=
=?UTF-8?q?=E7=BB=9F=E4=B8=80=E9=97=A8)+wftemplates=20picker=20=E6=95=B0?=
=?UTF-8?q?=E6=8D=AE=E6=BA=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
阶段 2 网关侧(对齐 flowable-service T2.1 ProcessModelController 契约):
FlowableClient +5 方法:listModels/getModel/createModel/updateModel/modelFromProcDef,
全 uri 模板变量严格编码(禁字符串拼接);RestClient 无 PUT 封装 → 照 post 补私有 put()
(uriTemplate+uriVars 严格编码);连接级重试 + 4xx/5xx 透传语义复用既有 execute。
ProcessModelerController:抽 requireSuperAdmin(principal) 私有方法(超管返 null,非超管/无身份
返 403 {status:1,msg:"仅系统管理员可用"}),既有两个 source 端点改用它(行为零变,既有 10 测试零改动);
新增五端点 GET /models、GET /models/{id}、POST /models、PUT /models/{id}、POST /models/from-procdef
全部先过门再转发 FlowableClient,返回体原样透传。
GET /api/workflow/wftemplates(同门):formKey 选择器数据源。
**information_schema 实证**:view_wftemplate 无独立名称列(仅 view_wftemplate_id CHAR + xml +
isactive + 审计列),