From 732655e776a31ff3ad54f4d99ca9567aedd97bb0 Mon Sep 17 00:00:00 2001 From: zhengwr Date: Thu, 2 Jul 2026 14:52:03 +0800 Subject: [PATCH] =?UTF-8?q?fix(gateway):=20=E8=AF=AD=E4=B9=89=E9=97=A8?= =?UTF-8?q?=E6=94=B6=E5=8F=A3=E2=80=94=E2=80=94type=E7=99=BD=E5=90=8D?= =?UTF-8?q?=E5=8D=95=E5=AF=B9=E9=BD=90WfTypes(=E9=98=B2=E8=AF=AF=E6=8B=92?= =?UTF-8?q?=E5=AD=98=E9=87=8F)+=E9=80=8F=E4=BC=A0=E4=B8=8B=E6=B8=B8?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E5=8C=96errors+TOCTOU=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 评审 T3.2 收口(2 Important + 2 Minor): - I-1(功能回归):ModelSemanticValidator.TYPE_WHITELIST 10 种→16 种,对齐 flowable-service WfTypes 配置类型 + OrgDirectoryJdbc 运行期分派(权威源,非 BasePropertiesConverter,注释已改)。 psql 窄查询实证:缺失 6 种里 initiatorDepartManager(24 文档)/fixedDimension(12 文档)在真实 candidateUsers 有非零命中,旧白名单会 422 误拒这些存量流程(载入→编辑无关节点→发布)。 网关不依赖 flowable-service 故复刻常量并注同步提醒。 - I-2(UX):FlowRemoteException 加 responseBody;FlowableClient.execute 携带下游原始体; FlowGatewayExceptionHandler.onRemote 解析并把下游 errors 数组并入网关响应顶层——发布下游 422 的引擎结构校验 errors[{activityId,problem,defaultDescription}] 现能到前端,与网关语义 422 顶层 errors 契约统一(前端 T3.3 同一渲染)。非发布路径纯文本体照旧不加 errors 键(无回归)。 - I-3(TOCTOU):deploy 端点加「已接受风险」javadoc(超管低频+窄窗+非安全洞,v1 不做 content-hash 409)。 - 补测 M-1(flowable: 前缀 candidateUsers 按本地名匹配同校验)+ M-2(新增 4 种 type 放行,锁 I-1)+ I-2 客户端携带体/handler 并入顶层 errors 两用例。 测试:语义 19(+2)、审计 3、客户端 24(+1)、控制器 30(+1)。全 reactor mvn clean install 退出码 0, 零 <<< FAILURE,ArchitectureRulesTest 6/6。 Co-Authored-By: Claude Fable 5 --- .../aggregate/ModelSemanticValidator.java | 13 ++++-- .../client/FlowRemoteException.java | 16 +++++++ .../flowgateway/client/FlowableClient.java | 6 ++- .../web/FlowGatewayExceptionHandler.java | 45 ++++++++++++++++--- .../web/ProcessModelerController.java | 8 ++++ .../flowgateway/FlowableClientTest.java | 24 ++++++++++ .../ModelSemanticValidatorTest.java | 27 +++++++++++ .../ProcessModelerControllerTest.java | 20 +++++++++ 8 files changed, 148 insertions(+), 11 deletions(-) diff --git a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/aggregate/ModelSemanticValidator.java b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/aggregate/ModelSemanticValidator.java index eeaaed1..19eb437 100644 --- a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/aggregate/ModelSemanticValidator.java +++ b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/aggregate/ModelSemanticValidator.java @@ -62,10 +62,17 @@ public class ModelSemanticValidator { private static final String MULTI_PREFIX = "${multiInstanceUsersHandler.getUsers(execution,'"; private static final String SUFFIX = "')}"; - /** 办理人/会签项合法 type(§0 实测 10 种,逐字对齐 BasePropertiesConverter)。 */ + /** + * 办理人/会签项合法 type。权威集 = flowable-service {@code WfTypes} 的 16 个配置类型 + {@code OrgDirectoryJdbc} + * 运行期分派(非 BasePropertiesConverter——它只 setType,不做白名单)。网关不依赖 flowable-service 故此处复刻 + * 常量值;WfTypes 新增类型时两处必须同步。此前只列 10 种会 422 误拒含 {@code initiatorDepartManager} + * (实测 24 文档)/{@code fixedDimension}(12 文档)等运行期完全支持的存量流程(from-procdef 载入→编辑无关节点→发布)。 + */ static final Set TYPE_WHITELIST = Set.of( - "user", "depart", "position", "formSpecifiedDimension", "initiator", - "sameToTask", "beforeTaskLeader", "beforeTaskDepartManager", "scriptUser", "projectRoleType"); + "user", "roles", "depart", "position", "initiator", + "initiatorDepartManager", "initiatorLeader", "initiatorSubordinate", "initiatorDepart", + "sameToTask", "beforeTaskLeader", "beforeTaskDepartManager", + "fixedDimension", "formSpecifiedDimension", "projectRoleType", "scriptUser"); /** 会签完成条件三预设(与 Eip4Panel.tsx:60-77 逐字一致):全票 / 过半 / 指定数。 */ private static final Pattern COMPLETION_ALL = diff --git a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/client/FlowRemoteException.java b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/client/FlowRemoteException.java index 5b09778..46a8ba6 100644 --- a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/client/FlowRemoteException.java +++ b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/client/FlowRemoteException.java @@ -8,17 +8,33 @@ import org.springframework.http.HttpStatusCode; *

与 {@link FlowServiceUnavailableException} 区分:那个是"引擎进程不可达"(→ 503); * 这个是"引擎在线但拒绝了这次操作"(原状态码透传给调用方,保留 Flowable 语义, * 如挂起拒办 409、参数错 400)。 + * + *

responseBody(可空):携带下游原始响应体,供 {@code FlowGatewayExceptionHandler} 透传结构化错误 + * ——如流程发布下游 422 的 {@code {errors:[{activityId,problem,defaultDescription}]}}(引擎 ProcessValidator 结构校验) + * 需并入网关响应,与网关语义校验 422 的顶层 {@code errors} 契约统一(T3.2 评审 I-2:此前只留状态码丢体, + * 结构化错误到不了前端)。旧两参构造(无体)保留,非发布路径不受影响。 */ public class FlowRemoteException extends RuntimeException { private final HttpStatusCode status; + private final String responseBody; public FlowRemoteException(HttpStatusCode status, String message) { + this(status, message, null); + } + + public FlowRemoteException(HttpStatusCode status, String message, String responseBody) { super(message); this.status = status; + this.responseBody = responseBody; } public HttpStatusCode getStatus() { return status; } + + /** 下游原始响应体(可空);供 handler 解析并透传结构化 errors。 */ + public String getResponseBody() { + return responseBody; + } } diff --git a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/client/FlowableClient.java b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/client/FlowableClient.java index 23487cf..ab4c392 100644 --- a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/client/FlowableClient.java +++ b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/client/FlowableClient.java @@ -490,10 +490,12 @@ public class FlowableClient { sleepBackoff(); } } catch (RestClientResponseException e) { - // 业务级:引擎在线但返回 4xx/5xx(如挂起拒办 409)——透传原状态码,绝不重试 + // 业务级:引擎在线但返回 4xx/5xx(如挂起拒办 409)——透传原状态码,绝不重试。 + // 携带原始响应体:发布下游 422 的结构化 errors(activityId/problem) 交 handler 并入网关响应(评审 I-2)。 HttpStatusCode status = e.getStatusCode(); log.debug("flowable-service {}调用返回业务状态 {}: {}", op, status, e.getMessage()); - throw new FlowRemoteException(status, "flowable-service " + op + "返回 " + status.value()); + throw new FlowRemoteException(status, "flowable-service " + op + "返回 " + status.value(), + e.getResponseBodyAsString()); } } // 重试耗尽仍连不上 —— 熔断降级为 503 语义 diff --git a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/web/FlowGatewayExceptionHandler.java b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/web/FlowGatewayExceptionHandler.java index 521b88d..938f2f8 100644 --- a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/web/FlowGatewayExceptionHandler.java +++ b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/web/FlowGatewayExceptionHandler.java @@ -1,7 +1,10 @@ package com.eip4.platform.flowgateway.web; +import java.util.LinkedHashMap; import java.util.Map; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.ExceptionHandler; @@ -9,6 +12,8 @@ import org.springframework.web.bind.annotation.RestControllerAdvice; import com.eip4.platform.flowgateway.client.FlowRemoteException; import com.eip4.platform.flowgateway.client.FlowServiceUnavailableException; +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; /** * 流程网关异常 → 干净 HTTP 语义(只管本网关 client 抛出的两类异常,不拦其他)。 @@ -17,12 +22,17 @@ import com.eip4.platform.flowgateway.client.FlowServiceUnavailableException; *

  • {@link FlowServiceUnavailableException}(引擎进程不可达,重试耗尽)→ 503 * Service Unavailable —— 待办聚合在引擎宕机/网络分区时返回明确的服务不可用语义,而非 500 堆栈。
  • *
  • {@link FlowRemoteException}(引擎在线但拒绝,如挂起拒办 409)→ 透传原状态码, - * 保留 Flowable 语义。
  • + * 保留 Flowable 语义;若下游响应体带结构化 {@code errors} 数组(如发布 422 的引擎结构校验错误 + * {@code [{activityId,problem,defaultDescription}]}),并入网关响应顶层 {@code errors}, + * 与网关语义校验 422 的顶层 {@code errors} 契约统一(评审 I-2)。 * */ @RestControllerAdvice(basePackages = "com.eip4.platform.flowgateway") public class FlowGatewayExceptionHandler { + private static final Logger log = LoggerFactory.getLogger(FlowGatewayExceptionHandler.class); + private static final ObjectMapper MAPPER = new ObjectMapper(); + @ExceptionHandler(FlowServiceUnavailableException.class) public ResponseEntity> onUnavailable(FlowServiceUnavailableException e) { return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE) @@ -34,10 +44,33 @@ public class FlowGatewayExceptionHandler { @ExceptionHandler(FlowRemoteException.class) public ResponseEntity> onRemote(FlowRemoteException e) { - return ResponseEntity.status(e.getStatus()) - .body(Map.of( - "status", e.getStatus().value(), - "error", "FLOW_REMOTE_ERROR", - "message", e.getMessage())); + Map body = new LinkedHashMap<>(); + body.put("status", e.getStatus().value()); + body.put("error", "FLOW_REMOTE_ERROR"); + body.put("message", e.getMessage()); + Object errors = extractErrors(e.getResponseBody()); + if (errors != null) { + body.put("errors", errors); + } + return ResponseEntity.status(e.getStatus()).body(body); + } + + /** + * 从下游原始响应体抽结构化 {@code errors} 数组(非空才返回)。下游体非 JSON / 无 errors / 空数组 → null + * (回原 FLOW_REMOTE_ERROR 信封,不加 errors 键)。防御性:解析失败静默降级,不让异常翻译再抛异常。 + */ + private static Object extractErrors(String responseBody) { + if (responseBody == null || responseBody.isBlank()) { + return null; + } + try { + JsonNode errors = MAPPER.readTree(responseBody).get("errors"); + if (errors != null && errors.isArray() && !errors.isEmpty()) { + return MAPPER.convertValue(errors, Object.class); + } + } catch (Exception ex) { + log.debug("下游响应体非 JSON 或无 errors,回原信封: {}", ex.toString()); + } + return null; } } diff --git a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/web/ProcessModelerController.java b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/web/ProcessModelerController.java index 486c5e9..2e1eb3c 100644 --- a/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/web/ProcessModelerController.java +++ b/platform-flow-gateway/src/main/java/com/eip4/platform/flowgateway/web/ProcessModelerController.java @@ -169,6 +169,14 @@ public class ProcessModelerController { // ---------------------------------------------------------------- 发布门(T3.2) + /** + * TOCTOU 已接受风险(评审 I-3):本端点先 {@link FlowableClient#getModel} 读草稿源做语义校验,再由下游 + * deploy 重新读 editorSource 部署——两次读之间存在并发 PUT 改写草稿的窗口(校验的是旧内容、部署的是新内容)。 + * v1 接受该风险,不做 content-hash 乐观锁 409:①发布是超管手动、低频、通常单人操作,并发改写窗口极窄; + * ②非安全洞(超管门已限定调用者,下游 deploy 仍过引擎 ProcessValidator 结构校验兜底);③content-hash 409 + * 对 v1 过重(需前端拿版本号回传+冲突重试 UI)。与 {@link FlowableClient} 幂等段同风格声明,v2 有多人协同编辑 + * 需求再引入乐观锁。 + */ @Operation(summary = "发布草稿为流程定义(超管 + 语义校验门 + 审计)", description = "超管门 → 取草稿源 XML(FlowableClient.getModel)→ EIP4 语义校验" + "(ModelSemanticValidator:办理人/会签内嵌 JSON items 非空+type 白名单、formKey 存在于 view_wftemplate、" diff --git a/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/FlowableClientTest.java b/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/FlowableClientTest.java index 3508e17..8a5f799 100644 --- a/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/FlowableClientTest.java +++ b/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/FlowableClientTest.java @@ -469,6 +469,30 @@ class FlowableClientTest { server.verify(); } + @Test + void 发布_下游422结构化errors体被FlowRemoteException携带_不丢弃() { + // 评审 I-2:execute 曾只留状态码丢响应体,引擎结构校验 errors 到不了前端。现携带原始体供 handler 透传。 + FlowGatewayProperties p = props(); + RestClient.Builder builder = RestClient.builder().baseUrl(p.getBaseUrl()); + MockRestServiceServer server = MockRestServiceServer.bindTo(builder).build(); + String engineBody = "{\"status\":1,\"msg\":\"流程校验未通过\",\"errors\":" + + "[{\"activityId\":\"t1\",\"problem\":\"flowable-noOutgoingSeq\",\"defaultDescription\":\"节点未连出边\"}]}"; + server.expect(ExpectedCount.once(), requestTo("http://localhost:8089/api/flow/models/m1/deploy")) + .andExpect(method(HttpMethod.POST)) + .andRespond(withStatus(HttpStatus.UNPROCESSABLE_ENTITY) + .body(engineBody).contentType(MediaType.APPLICATION_JSON)); + FlowableClient client = new FlowableClient(builder.build(), p); + + assertThatThrownBy(() -> client.deployModel("m1")) + .isInstanceOf(FlowRemoteException.class) + .satisfies(e -> { + FlowRemoteException fre = (FlowRemoteException) e; + assertThat(fre.getStatus().value()).isEqualTo(422); + assertThat(fre.getResponseBody()).contains("activityId").contains("节点未连出边"); + }); + server.verify(); + } + @Test void 发布影响_GET_models_id_impact_透传下游结果() { FlowGatewayProperties p = props(); diff --git a/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/ModelSemanticValidatorTest.java b/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/ModelSemanticValidatorTest.java index 4926b8c..7bcbac3 100644 --- a/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/ModelSemanticValidatorTest.java +++ b/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/ModelSemanticValidatorTest.java @@ -107,6 +107,33 @@ class ModelSemanticValidatorTest { assertThat(validator.validate(xml)).isEmpty(); } + @Test + void M1_flowable前缀candidateUsers_按本地名匹配同样校验() { + // 语料有 flowable 命名空间文档(3docs);按本地名匹配,flowable:candidateUsers 与 activiti: 同样被校验。 + String xml = "" + + "" + + "" + + "" + + ""; + List errors = validator.validate(xml); + assertThat(errors).hasSize(1); + assertThat(errors.get(0)).contains("flowable节点").contains("bogusType"); + } + + @Test + void M2_新增4种type放行_锁I1白名单对齐WfTypes() { + // roles/initiatorLeader/initiatorDepartManager/fixedDimension:WfTypes 配置类型、OrgDirectoryJdbc 运行期支持, + // 但旧 10 种白名单缺失。实测 initiatorDepartManager(24 文档)/fixedDimension(12 文档)真存量命中→曾会 422 误拒。 + for (String type : new String[]{"roles", "initiatorLeader", "initiatorDepartManager", "fixedDimension", + "initiatorSubordinate", "initiatorDepart"}) { + String xml = bpmn(userTaskWithCandidate("节点", + candidateExpr("[{\"type\":\"" + type + "\",\"content\":\"x\"}]"))); + assertThat(validator.validate(xml)).as("type=%s 应放行", type).isEmpty(); + } + } + // ---------------------------------------------------------------- 办理人 JSON 错误 @Test diff --git a/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/ProcessModelerControllerTest.java b/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/ProcessModelerControllerTest.java index 92d8aa3..34c0be0 100644 --- a/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/ProcessModelerControllerTest.java +++ b/platform-flow-gateway/src/test/java/com/eip4/platform/flowgateway/ProcessModelerControllerTest.java @@ -472,4 +472,24 @@ class ProcessModelerControllerTest { verify(flowableClient, never()).deployModel(anyString()); } + + @Test + void 胶水_发布_语义过但下游引擎422结构化errors经handler并入顶层() throws Exception { + // I-2:语义门放行 → 转发 deploy → 下游引擎 ProcessValidator 结构校验 422(对象式 errors) → handler 并入网关响应。 + // 两条 422 契约统一:顶层 errors(语义=字符串数组 / 引擎=对象数组),前端 T3.3 同一渲染。 + when(flowableClient.getModel("m1")) + .thenReturn(Map.of("found", true, "bpmnXml", "")); + when(semanticValidator.validate("")).thenReturn(List.of()); // 语义过 + String engineBody = "{\"status\":1,\"msg\":\"流程校验未通过\",\"errors\":" + + "[{\"activityId\":\"t1\",\"problem\":\"noOutgoing\",\"defaultDescription\":\"节点未连出边\"}]}"; + when(flowableClient.deployModel("m1")).thenThrow( + new FlowRemoteException(HttpStatus.UNPROCESSABLE_ENTITY, + "flowable-service 发布草稿返回 422", engineBody)); + + glueMvc().perform(post("/api/workflow/models/{id}/deploy", "m1")) + .andExpect(status().isUnprocessableEntity()) + .andExpect(jsonPath("$.error").value("FLOW_REMOTE_ERROR")) + .andExpect(jsonPath("$.errors[0].activityId").value("t1")) + .andExpect(jsonPath("$.errors[0].defaultDescription").value("节点未连出边")); + } }