From 57812f0edcfb67eb70f70f0a993fe11a7062e917 Mon Sep 17 00:00:00 2001 From: zhengwr Date: Thu, 2 Jul 2026 11:15:54 +0800 Subject: [PATCH] =?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> list() { + List> models = repositoryService.createModelQuery() + .orderByLastUpdateTime().desc().list().stream() + .map(m -> { + Map row = new LinkedHashMap<>(); + row.put("id", m.getId()); + row.put("name", m.getName()); + row.put("key", m.getKey()); + row.put("lastUpdateTime", toIso(m.getLastUpdateTime())); + return row; + }) + .collect(Collectors.toList()); + Map resp = new LinkedHashMap<>(); + resp.put("models", models); + return ResponseEntity.ok(resp); + } + + @GetMapping("/models/{id}") + @Operation(summary = "取草稿", + description = "getModel + getModelEditorSource → {found,id,name,key,bpmnXml,metaInfo}。" + + "草稿不存在或编辑源为空 → {found:false}(HTTP 200,前端降级)。") + public ResponseEntity> get(@PathVariable String id) { + Map resp = new LinkedHashMap<>(); + Model model = repositoryService.getModel(id); + if (model == null) { + resp.put("found", false); + return ResponseEntity.ok(resp); + } + byte[] source = repositoryService.getModelEditorSource(id); + if (source == null) { + resp.put("found", false); + return ResponseEntity.ok(resp); + } + resp.put("found", true); + resp.put("id", model.getId()); + resp.put("name", model.getName()); + resp.put("key", model.getKey()); + resp.put("bpmnXml", new String(source, StandardCharsets.UTF_8)); + resp.put("metaInfo", model.getMetaInfo()); + return ResponseEntity.ok(resp); + } + + @PostMapping("/models") + @Operation(summary = "建草稿", + description = "body {name,key,bpmnXml,metaInfo?}。XML 先过 BpmnXMLConverter 解析守卫(坏 XML→422 不落库)," + + "过门后 newModel+saveModel+addModelEditorSource → {modelId}。") + public ResponseEntity> create(@RequestBody CreateModelRequest req) { + ResponseEntity> rejected = parseGuard(req.bpmnXml); + if (rejected != null) { + return rejected; + } + Model model = repositoryService.newModel(); + model.setName(req.name); + model.setKey(req.key); + if (req.metaInfo != null) { + model.setMetaInfo(req.metaInfo); + } + repositoryService.saveModel(model); + repositoryService.addModelEditorSource(model.getId(), req.bpmnXml.getBytes(StandardCharsets.UTF_8)); + Map resp = new LinkedHashMap<>(); + resp.put("modelId", model.getId()); + return ResponseEntity.ok(resp); + } + + @PutMapping("/models/{id}") + @Operation(summary = "更新草稿", + description = "草稿不存在→404;更新 name/metaInfo(仅当请求提供,避免覆盖 eip4IdMap)与 editorSource(XML 同守卫 422) → {status:0}。") + public ResponseEntity> update(@PathVariable String id, @RequestBody UpdateModelRequest req) { + Model model = repositoryService.getModel(id); + if (model == null) { + return status(HttpStatus.NOT_FOUND, "草稿不存在: " + id); + } + ResponseEntity> rejected = parseGuard(req.bpmnXml); + if (rejected != null) { + return rejected; + } + if (req.name != null) { + model.setName(req.name); + } + // metaInfo 仅当请求显式提供时更新:草稿存 eip4IdMap 于 metaInfo,普通保存不重发 metaInfo 时不能抹掉它。 + if (req.metaInfo != null) { + model.setMetaInfo(req.metaInfo); + } + repositoryService.saveModel(model); + repositoryService.addModelEditorSource(id, req.bpmnXml.getBytes(StandardCharsets.UTF_8)); + Map resp = new LinkedHashMap<>(); + resp.put("status", 0); + return ResponseEntity.ok(resp); + } + + @PostMapping("/models/from-procdef") + @Operation(summary = "从流程定义建草稿", + description = "body {procDefId}。读部署 BPMN → BpmnIdSanitizer.sanitize 净化中文 id → 建草稿" + + "(name/key=procDef,editorSource=净化 XML,metaInfo={eip4IdMap,sourceProcDefId,originalKey}) → {modelId}。" + + "procDef 不存在或 BPMN 空 → {found:false}(HTTP 200,前端降级)。") + public ResponseEntity> fromProcDef(@RequestBody FromProcDefRequest req) { + ProcessDefinition def = repositoryService.createProcessDefinitionQuery() + .processDefinitionId(req.procDefId).singleResult(); + if (def == null) { + return found(false); + } + String bpmnXml = readProcessModel(req.procDefId); + if (bpmnXml == null || bpmnXml.isBlank()) { + return found(false); + } + BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(bpmnXml); + + Map meta = new LinkedHashMap<>(); + meta.put("eip4IdMap", r.idMap()); + meta.put("sourceProcDefId", req.procDefId); + meta.put("originalKey", def.getKey()); + String metaInfoJson; + try { + metaInfoJson = objectMapper.writeValueAsString(meta); + } catch (Exception e) { + // 纯 Map 序列化理论上不会失败;防御性 500 + log.error("[流程草稿] metaInfo 序列化失败 procDefId={}", req.procDefId, e); + return status(HttpStatus.INTERNAL_SERVER_ERROR, "metaInfo 序列化失败"); + } + + Model model = repositoryService.newModel(); + model.setName(def.getName()); + model.setKey(def.getKey()); + model.setMetaInfo(metaInfoJson); + repositoryService.saveModel(model); + repositoryService.addModelEditorSource(model.getId(), r.xml().getBytes(StandardCharsets.UTF_8)); + Map resp = new LinkedHashMap<>(); + resp.put("modelId", model.getId()); + return ResponseEntity.ok(resp); + } + + /** + * BPMN 解析守卫:过则返回 {@code null}(放行),坏 XML 返回 422 ResponseEntity({status:1,msg})。 + * 就地 catch 一切异常,不让引擎 XMLException/FlowableException 逸出到全局 advice(那里映射成 400,语义不符)。 + */ + private ResponseEntity> parseGuard(String xml) { + try { + new BpmnXMLConverter().convertToBpmnModel(new StringStreamSource(xml), true, false); + 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); + } + } + + /** 读流程定义部署 BPMN XML(getProcessModel 返回资源流)。读失败/为空返回 null(前端降级)。 */ + private String readProcessModel(String procDefId) { + try (InputStream is = repositoryService.getProcessModel(procDefId)) { + if (is == null) { + return null; + } + return StreamUtils.copyToString(is, StandardCharsets.UTF_8); + } catch (Exception e) { + log.warn("[流程草稿] 读取 BPMN 失败 procDefId={}: {}", procDefId, e.toString()); + return null; + } + } + + private static ResponseEntity> found(boolean value) { + Map resp = new LinkedHashMap<>(); + resp.put("found", value); + return ResponseEntity.ok(resp); + } + + private static ResponseEntity> status(HttpStatus httpStatus, String msg) { + Map body = new LinkedHashMap<>(); + body.put("status", 1); + body.put("msg", msg); + return ResponseEntity.status(httpStatus).body(body); + } + + /** {@link Date} → ISO-8601 UTC 字符串(如 {@code 1970-01-01T00:00:00Z});null 原样透传。 */ + private static String toIso(Date d) { + return d == null ? null : d.toInstant().toString(); + } + + /** 建草稿入参。 */ + public static class CreateModelRequest { + public String name; + public String key; + public String bpmnXml; + public String metaInfo; + } + + /** 更新草稿入参(editorSource 走 bpmnXml;name/metaInfo 为 null 表示不改)。 */ + public static class UpdateModelRequest { + public String name; + public String bpmnXml; + public String metaInfo; + } + + /** 从流程定义建草稿入参。 */ + public static class FromProcDefRequest { + public String procDefId; + } +} 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 new file mode 100644 index 0000000..705e85b --- /dev/null +++ b/flowable-service/src/test/java/com/eip4/flowservice/api/ProcessModelControllerTest.java @@ -0,0 +1,281 @@ +package com.eip4.flowservice.api; + +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; + +import java.io.ByteArrayInputStream; +import java.nio.charset.StandardCharsets; +import java.util.Date; +import java.util.List; + +import org.flowable.engine.RepositoryService; +import org.flowable.engine.repository.Model; +import org.flowable.engine.repository.ModelQuery; +import org.flowable.engine.repository.ProcessDefinition; +import org.flowable.engine.repository.ProcessDefinitionQuery; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.ArgumentCaptor; +import org.mockito.Mock; +import org.mockito.Mockito; +import org.mockito.junit.jupiter.MockitoExtension; +import org.springframework.http.MediaType; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.test.web.servlet.setup.MockMvcBuilders; + +/** + * 流程草稿 CRUD 端点薄层单测:mock RepositoryService + Model API(newModel/saveModel/addModelEditorSource/ + * getModelEditorSource/createModelQuery),验证列表/取草稿/建草稿(坏 XML 不落库)/PUT 404/from-procdef + * 净化 XML 与 idMap 落 metaInfo。standaloneSetup 不挂 FlowExceptionHandler——422/404 由控制器本地 ResponseEntity + * 显式产出(不经引擎异常映射)。 + */ +@ExtendWith(MockitoExtension.class) +class ProcessModelControllerTest { + + @Mock RepositoryService repositoryService; + @Mock ModelQuery modelQuery; + @Mock ProcessDefinitionQuery processDefinitionQuery; + + MockMvc mvc; + + // 最小 schema 合法 BPMN(default ns=BPMN20 MODEL),供 convertToBpmnModel(validateSchema=true) 过门。 + private static final String VALID_BPMN = "" + + "" + + "" + + "" + + "" + + "" + + ""; + + @BeforeEach + void setUp() { + ProcessModelController controller = new ProcessModelController(repositoryService); + mvc = MockMvcBuilders.standaloneSetup(controller).build(); + } + + @Test + void 列表按最近更新降序返回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.orderByLastUpdateTime()).thenReturn(modelQuery); + when(modelQuery.desc()).thenReturn(modelQuery); + when(modelQuery.list()).thenReturn(List.of(m)); + + mvc.perform(get("/api/flow/models")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.models[0].id").value("m1")) + .andExpect(jsonPath("$.models[0].name").value("总包合同交底")) + .andExpect(jsonPath("$.models[0].key").value("总包合同交底")) + .andExpect(jsonPath("$.models[0].lastUpdateTime").value("1970-01-01T00:00:00Z")); + } + + @Test + void 取草稿返回XML与metaInfo() throws Exception { + Model m = Mockito.mock(Model.class); + when(m.getId()).thenReturn("m1"); + when(m.getName()).thenReturn("总包合同交底"); + when(m.getKey()).thenReturn("总包合同交底"); + when(m.getMetaInfo()).thenReturn("{\"eip4IdMap\":{\"总包合同交底\":\"n1\"}}"); + when(repositoryService.getModel("m1")).thenReturn(m); + when(repositoryService.getModelEditorSource("m1")) + .thenReturn("".getBytes(StandardCharsets.UTF_8)); + + mvc.perform(get("/api/flow/models/m1")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.found").value(true)) + .andExpect(jsonPath("$.id").value("m1")) + .andExpect(jsonPath("$.key").value("总包合同交底")) + .andExpect(jsonPath("$.bpmnXml").value("")) + .andExpect(jsonPath("$.metaInfo").value("{\"eip4IdMap\":{\"总包合同交底\":\"n1\"}}")); + } + + @Test + void 取草稿_model不存在返found_false() throws Exception { + when(repositoryService.getModel("nope")).thenReturn(null); + + mvc.perform(get("/api/flow/models/nope")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.found").value(false)); + } + + @Test + void 取草稿_editorSource为空返found_false() throws Exception { + Model m = Mockito.mock(Model.class); + when(repositoryService.getModel("m2")).thenReturn(m); + when(repositoryService.getModelEditorSource("m2")).thenReturn(null); + + mvc.perform(get("/api/flow/models/m2")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.found").value(false)); + } + + @Test + void 建草稿_合法XML落库返modelId() throws Exception { + Model m = Mockito.mock(Model.class); + when(m.getId()).thenReturn("newid"); + when(repositoryService.newModel()).thenReturn(m); + + String body = "{\"name\":\"新流程\",\"key\":\"newproc\",\"bpmnXml\":" + + jsonString(VALID_BPMN) + ",\"metaInfo\":\"{}\"}"; + mvc.perform(post("/api/flow/models").contentType(MediaType.APPLICATION_JSON).content(body)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.modelId").value("newid")); + + verify(m).setName("新流程"); + verify(m).setKey("newproc"); + verify(repositoryService).saveModel(m); + ArgumentCaptor src = ArgumentCaptor.forClass(byte[].class); + verify(repositoryService).addModelEditorSource(eq("newid"), src.capture()); + org.junit.jupiter.api.Assertions.assertTrue( + new String(src.getValue(), StandardCharsets.UTF_8).contains("" + + "" + + "" + + ""; + when(repositoryService.getProcessModel("def-1")) + .thenReturn(new ByteArrayInputStream(xml.getBytes(StandardCharsets.UTF_8))); + + Model m = Mockito.mock(Model.class); + when(m.getId()).thenReturn("draft-1"); + when(repositoryService.newModel()).thenReturn(m); + + String body = "{\"procDefId\":\"def-1\"}"; + mvc.perform(post("/api/flow/models/from-procdef").contentType(MediaType.APPLICATION_JSON).content(body)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.modelId").value("draft-1")); + + verify(m).setName("总包合同交底"); + verify(m).setKey("总包合同交底"); + // metaInfo:JSON 含 eip4IdMap + sourceProcDefId + 中文 originalKey + ArgumentCaptor meta = ArgumentCaptor.forClass(String.class); + verify(m).setMetaInfo(meta.capture()); + String metaJson = meta.getValue(); + org.junit.jupiter.api.Assertions.assertTrue(metaJson.contains("eip4IdMap"), metaJson); + org.junit.jupiter.api.Assertions.assertTrue(metaJson.contains("\"sourceProcDefId\":\"def-1\""), metaJson); + org.junit.jupiter.api.Assertions.assertTrue(metaJson.contains("\"originalKey\":\"总包合同交底\""), metaJson); + org.junit.jupiter.api.Assertions.assertTrue(metaJson.contains("总包合同交底"), metaJson); // idMap 键含中文原 id + // editorSource:净化后 XML 不再含中文 id(id/ref 属性),name 保留中文 + ArgumentCaptor src = ArgumentCaptor.forClass(byte[].class); + verify(repositoryService).addModelEditorSource(eq("draft-1"), src.capture()); + String savedXml = new String(src.getValue(), StandardCharsets.UTF_8); + org.junit.jupiter.api.Assertions.assertFalse(savedXml.contains("id=\"总包合同交底\""), savedXml); + org.junit.jupiter.api.Assertions.assertFalse(savedXml.contains("sourceRef=\"总包合同交底\""), savedXml); + org.junit.jupiter.api.Assertions.assertTrue(savedXml.contains("name=\"总包合同交底\""), savedXml); + } + + @Test + void fromProcDef_procDef不存在返found_false不落库() throws Exception { + when(repositoryService.createProcessDefinitionQuery()).thenReturn(processDefinitionQuery); + when(processDefinitionQuery.processDefinitionId("nope")).thenReturn(processDefinitionQuery); + when(processDefinitionQuery.singleResult()).thenReturn(null); + + mvc.perform(post("/api/flow/models/from-procdef") + .contentType(MediaType.APPLICATION_JSON).content("{\"procDefId\":\"nope\"}")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.found").value(false)); + + verify(repositoryService, never()).newModel(); + } + + /** 把任意字符串编成 JSON 字符串字面量(转义引号/反斜杠/换行),用于拼请求体。 */ + private static String jsonString(String s) { + StringBuilder sb = new StringBuilder("\""); + for (int i = 0; i < s.length(); i++) { + char c = s.charAt(i); + switch (c) { + case '"' -> sb.append("\\\""); + case '\\' -> sb.append("\\\\"); + case '\n' -> sb.append("\\n"); + case '\r' -> sb.append("\\r"); + case '\t' -> sb.append("\\t"); + default -> sb.append(c); + } + } + return sb.append("\"").toString(); + } +}