feat(embed): 新增办件进度嵌入页签发端点与免签数据端点

src/main/java/com/yunhai/flowcenter/controller/oapi/OapiFlowController.java

@@ -25,6 +25,7 @@ import java.util.List;
  * - POST /oapi/flow/instance/{instanceId}/withdraw?schId=&submitterId= → data=null（提交人复核后撤回）
  * - GET  /oapi/flow/progress?instanceId=|bizType=&bizId=&schId=        → data={status,steps:[…]}
  * - GET  /oapi/flow/diagram/url?instanceId=|flowGuid=&mode=&schId=     → data={imgUrl,expiresIn}
+ * - GET  /oapi/flow/embed/url?instanceId=|bizType=&bizId=&mode=&schId= → data={pageUrl,expiresIn}
  * - POST /oapi/flow/callback/reg?schId=                  → data={secret}
  * 应用内审批（2026-09 第三步，原"刻意不提供审批动作"立场由该方案修订：登录身份由调用方
  * 应用按其 CAS 会话保证并以 operatorId 传入，本端按任务办理人逐字复核，审计链不断）：
@@ -89,6 +90,20 @@ public class OapiFlowController {
         return flowService.diagramUrl(schId, instanceId, flowGuid, mode);
     }
 
+    /**
+     * 办件进度嵌入页换址（iframe 场景，token 模式与换图同构）：pageUrl 为 flow-center 前端
+     * 绝对地址，子应用直接放 {@code <iframe src>}。用户级可见性（本人/办理人/管理员）由
+     * 子应用后端在调本端点前完成——oapi 层只认 schId，应用签名不替代"谁能看"。
+     */
+    @GetMapping("/embed/url")
+    public OapiModels.EmbedUrlVo embedUrl(@RequestParam(value = "instanceId", required = false) Long instanceId,
+                                          @RequestParam(value = "bizType", required = false) String bizType,
+                                          @RequestParam(value = "bizId", required = false) String bizId,
+                                          @RequestParam(value = "mode", required = false) String mode,
+                                          @RequestParam("schId") Long schId) {
+        return flowService.embedUrl(schId, instanceId, bizType, bizId, mode);
+    }
+
     /**
      * 撤回（提交人本人；仅尚无任务被办理时）。submitterId 由业务应用按其办件归属传入，
      * 本端与办件提交人复核——应用签名不替代"谁在撤"的身份证明。

src/main/java/com/yunhai/flowcenter/controller/open/OpenEmbedController.java

@@ -0,0 +1,64 @@
+package com.yunhai.flowcenter.controller.open;
+
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.model.FlowModels;
+import com.yunhai.flowcenter.repository.FlwInstanceRepository;
+import com.yunhai.flowcenter.service.DiagramTokenService;
+import com.yunhai.flowcenter.service.FlowQueryService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 免签嵌入页数据端点（/open/flow/embed/**，与图片流 /open/flow/diagram/img 同纪律）。
+ * <p>
+ * {@code <iframe src>} 进不了 /api（CAS）也进不了 /oapi（app-sign）：免签资格由 10 分钟
+ * 短时 token 承担（与换图共用 DiagramTokenService 同一 token 池，token 由 app-sign 的
+ * GET /oapi/flow/embed/url 签发）。token 分发点之外，本端点不接受任何业务参数直接定位——
+ * 免签面收窄到"只认 token"，定位与可见性全在签发侧（OapiFlowService.embedUrl）完成。
+ * 出参复用管理面办件详情 InstanceDetail 整体（viewerId=null，本人待办字段自然为空），
+ * 不新造 VO——嵌入页信息量与管理面一致，单点维护。
+ */
+@RestController
+@RequestMapping("/open/flow/embed")
+@RequiredArgsConstructor
+public class OpenEmbedController {
+
+    private final DiagramTokenService tokenService;
+    private final FlowQueryService flowQueryService;
+    private final FlwInstanceRepository instanceRepository;
+
+    @GetMapping("/data")
+    public ResponseEntity<?> embedData(@RequestParam(value = "token", required = false) String token) {
+        DiagramTokenService.TokenEntry entry = tokenService.resolve(token);
+        if (entry == null) {
+            return notFound("链接已过期，请重新打开");
+        }
+        // 办件口径收窄：defId 口径的换图 token（flowGuid 预览）没有办件，不在此消费
+        if (entry.getInstanceId() == null) {
+            return notFound("链接已过期，请重新打开");
+        }
+        // token 已收 schId，出数据前再二次比对防漂移（同图片流口径，token 无法跨校探数据）
+        FlwInstance instance = instanceRepository.findById(entry.getInstanceId()).orElse(null);
+        if (instance == null || !entry.getSchId().equals(instance.getSchId())) {
+            return notFound("办件不存在");
+        }
+        FlowModels.InstanceDetail detail =
+                flowQueryService.detail(entry.getSchId(), entry.getInstanceId(), null);
+        return ResponseEntity.ok()
+                .cacheControl(org.springframework.http.CacheControl.noStore())
+                .body(detail);
+    }
+
+    private ResponseEntity<String> notFound(String msg) {
+        // 显式 UTF-8：text/plain 缺 charset 时浏览器/客户端按 ISO-8859-1 解码中文必乱码
+        return ResponseEntity.status(HttpStatus.NOT_FOUND)
+                .contentType(new MediaType("text", "plain", java.nio.charset.StandardCharsets.UTF_8))
+                .body(msg);
+    }
+}

src/main/java/com/yunhai/flowcenter/model/OapiModels.java

@@ -146,6 +146,15 @@ public final class OapiModels {
         private long expiresIn;
     }
 
+    /** 办件进度嵌入页换址响应（pageUrl 可直接放 <iframe src>，SDK FlowEmbedUrl 同构） */
+    @Data
+    public static class EmbedUrlVo {
+        /** 嵌入页绝对地址（flow-center 前端基址 + hash 路由 + 短时 token） */
+        private String pageUrl;
+        /** 相对 token 有效期（秒） */
+        private long expiresIn;
+    }
+
     /** 待办任务行（tasks/todo 元素）：审批列表页数据源，带办件定位与快照 */
     @Data
     public static class TodoTaskVo {

src/main/java/com/yunhai/flowcenter/service/OapiFlowService.java

@@ -61,6 +61,14 @@ public class OapiFlowService {
     @Value("${flow-center.submitter-school-check.enabled:true}")
     private boolean submitterCheckEnabled;
 
+    /**
+     * 办件进度嵌入页前端基址（flow-center 自身的对外前端地址，本方案新增的第一个前端地址配置：
+     * 此前 UserMsg jumpPath 均为裸相对路径由接收方解析）。未配置即调签发 → fail-fast 业务异常，
+     * 与 callback-url 同纪律——宁可不发也不发一个打不开的地址。
+     */
+    @Value("${flow-center.embed.front-url:}")
+    private String embedFrontUrl;
+
     private final FlwDefRepository defRepository;
     private final FlwInstanceRepository instanceRepository;
     private final FlwTaskRepository taskRepository;
@@ -324,6 +332,43 @@ public class OapiFlowService {
         return vo;
     }
 
+    /**
+     * 办件进度嵌入页换址（token 模式，与换图同构）：同一 token 两处消费——嵌入页数据
+     * /open/flow/embed/data 与流程图 /open/flow/diagram/img 均免签认领该 token。定位二选一：
+     * instanceId（与办件直接复核）/ bizType+bizId（对账口径，办件不存在与 progress 同文案）。
+     * 用户级可见性（本人/办理人/管理员）由子应用后端在调本端点前完成——oapi 层只认 schId。
+     */
+    public OapiModels.EmbedUrlVo embedUrl(Long schId, Long instanceId, String bizType, String bizId, String mode) {
+        // 配置缺失优先于办件定位：fail-fast 纪律要的是"无论如何都不发打不开的地址"
+        if (embedFrontUrl == null || embedFrontUrl.trim().isEmpty()) {
+            throw new BizException(ErrorCode.INTERNAL_SERVER_ERROR, "嵌入页地址未配置：flow-center.embed.front-url");
+        }
+        Long resolvedInstanceId;
+        if (instanceId != null) {
+            resolvedInstanceId = requireInstance(schId, instanceId).getId();
+        } else {
+            if (bizType == null || bizId == null) {
+                throw new BizException(ErrorCode.PARAM_ERROR, "缺少必要参数：instanceId 或 bizType/bizId");
+            }
+            OapiModels.InstanceVo vo = instanceByBiz(schId, bizType, bizId);
+            if (vo == null) {
+                throw new BizException(ErrorCode.PARAM_ERROR, "办件不存在或不可见");
+            }
+            resolvedInstanceId = vo.getInstanceId();
+        }
+        // mode 与 DiagramTokenService 内部缺省同值（"auto"），URL 里显式带上仅为前端展示冗余
+        String normMode = mode == null || mode.trim().isEmpty() ? "auto" : mode.trim();
+        String token = tokenService.issue(schId, resolvedInstanceId, null, normMode);
+        String base = embedFrontUrl.trim();
+        if (!base.endsWith("/")) {
+            base = base + "/";
+        }
+        OapiModels.EmbedUrlVo out = new OapiModels.EmbedUrlVo();
+        out.setPageUrl(base + "#/embed/instance?token=" + token + "&mode=" + normMode);
+        out.setExpiresIn(DiagramTokenService.TTL_MS / 1000);
+        return out;
+    }
+
     /** 进度/换图共用的办件定位（schId 收敛在次） */
     private FlwInstance requireInstance(Long schId, Long instanceId) {
         FlwInstance instance = instanceRepository.findById(instanceId)

src/main/resources/application.yml

@@ -112,6 +112,14 @@ flow-center:
     #     FLOWCENTER_USERMSG_ENABLED=true FLOWCENTER_USERMSG_BASEURL=http://localhost:8080 mvn -o spring-boot:run
     enabled: false
     # base-url: http://localhost:8080
+  # 办件进度嵌入页（iframe 免签嵌入）：flow-center 自身前端的对外基址，签发 /oapi/flow/embed/url
+  # 时拼 pageUrl 用（{front-url}#/embed/instance?token=…）。本应用此前从不需要自己的前端地址
+  # （UserMsg jumpPath 是裸相对路径由接收方解析），此为本方案新增的第一个前端地址配置。
+  # 本地 vite dev 实际端口 8088（见 local-debug/embed-c0-facts.md，卡册假设的 5173 不符）；
+  # 生产形如 https://<base域>/flow-center/front/，由 projman 平台设置登记注入。未配置时签发端点
+  # fail-fast 业务异常（与 callback-url 同纪律），不发出打不开的地址。
+  embed:
+    front-url: http://localhost:8088
 
 logging:
   level:

src/test/java/com/yunhai/flowcenter/oapi/OapiFlowContractIT.java

@@ -3,11 +3,15 @@ package com.yunhai.flowcenter.oapi;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.service.DiagramTokenService;
+import com.yunhai.flowcenter.service.OapiFlowService;
 import com.yunhai.flowcenter.support.FlowTestSupport;
 import com.yunhai.flowcenter.support.OapiSignedClient;
+import com.yunhai.platform.apistd.BizException;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.boot.test.context.TestConfiguration;
 import org.springframework.boot.web.server.LocalServerPort;
@@ -15,12 +19,14 @@ import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Primary;
 import org.springframework.http.ResponseEntity;
 import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.util.ReflectionTestUtils;
 
 import java.util.List;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
@@ -41,6 +47,16 @@ class OapiFlowContractIT extends FlowTestSupport {
     @Autowired
     private ObjectMapper objectMapper;
 
+    @Autowired
+    private OapiFlowService flowService;
+
+    @Autowired
+    private DiagramTokenService tokenService;
+
+    /** 签发端点拼 pageUrl 用的前端基址（application.yml 实配值，断言前缀不硬编码端口） */
+    @Value("${flow-center.embed.front-url}")
+    private String embedFrontUrl;
+
     private OapiSignedClient client;
 
     @TestConfiguration
@@ -244,6 +260,100 @@ class OapiFlowContractIT extends FlowTestSupport {
         assertEquals(10, instanceRepository.findById(instanceId).get().getStatus());
     }
 
+    // ===== 办件进度嵌入页（token 模式，与换图同构）：embed/url 签发 + /open/flow/embed/data 消费 =====
+
+    /** 嵌入换址契约：签名强制 / pageUrl 形态 / bizType 定位 / 办件不存在业务码 / 未配置 fail-fast */
+    @Test
+    void embedUrl_contract() {
+        assertEquals(401, client.getRaw("/oapi/flow/embed/url?schId=1&instanceId=1").getStatusCodeValue());
+
+        mapDept("ybb", 101, "甲");
+        FlwDef def = saveAndPublishDef("t30", "嵌入页", linearDef("ybb", "审核"));
+        Long instanceId = unwrap(client.post("/oapi/flow/apply?schId=1", "{"
+                + "\"flowGuid\":\"" + def.getFlowGuid() + "\","
+                + "\"bizType\":\"notice\",\"bizId\":\"em-1\",\"bizTitle\":\"嵌入办件\","
+                + "\"submitterId\":201,\"submitterName\":\"张三\"}", JsonNode.class).getBody())
+                .get("instanceId").asLong();
+
+        // instanceId 直取：pageUrl=前端基址 + hash 路由 + 短时 token，expiresIn 与换图 TTL 同源
+        JsonNode byInstance = unwrap(client.get(
+                "/oapi/flow/embed/url?schId=1&instanceId=" + instanceId, JsonNode.class).getBody());
+        String pageUrl = byInstance.get("pageUrl").asText();
+        assertTrue(pageUrl.startsWith(embedFrontUrl), "pageUrl 须以配置的前端基址开头：" + pageUrl);
+        assertTrue(pageUrl.contains("#/embed/instance?token="), "pageUrl 须为嵌入页 hash 深链：" + pageUrl);
+        assertFalse(extractToken(pageUrl).isEmpty(), "token 不可为空");
+        assertEquals("&mode=auto", pageUrl.substring(pageUrl.length() - "&mode=auto".length()));
+        assertEquals(600, byInstance.get("expiresIn").asLong());
+
+        // bizType+bizId 定位：与 instanceId 口径指向同一办件
+        JsonNode byBiz = unwrap(client.get(
+                "/oapi/flow/embed/url?schId=1&bizType=notice&bizId=em-1", JsonNode.class).getBody());
+        assertTrue(byBiz.get("pageUrl").asText().contains("#/embed/instance?token="));
+
+        // 办件不存在 → 业务码拒绝（与 progress 同口径，不 404 不 500）
+        ResponseEntity<JsonNode> miss = client.get(
+                "/oapi/flow/embed/url?schId=1&bizType=notice&bizId=none", JsonNode.class);
+        assertNotEquals(0, miss.getBody().get("code").asInt(), "办件不存在应业务码拒绝");
+    }
+
+    /** 未配置 front-url → fail-fast 业务异常（非 NPE/空串地址） */
+    @Test
+    void embedUrl_frontUrlUnconfigured_failFast() {
+        Object origin = ReflectionTestUtils.getField(flowService, "embedFrontUrl");
+        try {
+            ReflectionTestUtils.setField(flowService, "embedFrontUrl", " ");
+            BizException ex = assertThrows(BizException.class,
+                    () -> flowService.embedUrl(1L, 1L, null, null, null));
+            assertTrue(ex.getMessage().contains("嵌入页地址未配置"), "文案须指向配置键：" + ex.getMessage());
+        } finally {
+            ReflectionTestUtils.setField(flowService, "embedFrontUrl", origin);
+        }
+    }
+
+    /** 免签数据端点：无/伪造 token 404；命中 200 + detail 全字段 + no-store；跨校 token 404 */
+    @Test
+    void embedData_tokenGated() throws Exception {
+        mapDept("ybb", 101, "甲");
+        FlwDef def = saveAndPublishDef("t31", "嵌入数据", linearDef("ybb", "审核"));
+        Long instanceId = unwrap(client.post("/oapi/flow/apply?schId=1", "{"
+                + "\"flowGuid\":\"" + def.getFlowGuid() + "\","
+                + "\"bizType\":\"notice\",\"bizId\":\"em-2\",\"bizTitle\":\"数据办件\","
+                + "\"submitterId\":201,\"submitterName\":\"张三\"}", JsonNode.class).getBody())
+                .get("instanceId").asLong();
+
+        // 免签面：缺 token / 伪造 token 均 404 文本（不 401，不诱导探测）
+        assertEquals(404, client.getRaw("/open/flow/embed/data").getStatusCodeValue());
+        ResponseEntity<String> forged = client.getRaw("/open/flow/embed/data?token=forged0000000000");
+        assertEquals(404, forged.getStatusCodeValue());
+        assertEquals("链接已过期，请重新打开", forged.getBody());
+
+        // 命中：顶层即 InstanceDetail（ResponseEntity 不进信封），trace/bizTitle 全字段可见
+        String token = extractToken(unwrap(client.get(
+                "/oapi/flow/embed/url?schId=1&instanceId=" + instanceId, JsonNode.class).getBody())
+                .get("pageUrl").asText());
+        ResponseEntity<String> hit = client.getRaw("/open/flow/embed/data?token=" + token);
+        assertEquals(200, hit.getStatusCodeValue());
+        JsonNode detail = objectMapper.readTree(hit.getBody());
+        assertEquals(instanceId.longValue(), detail.get("instanceId").asLong());
+        assertEquals("数据办件", detail.get("bizTitle").asText());
+        assertNotNull(detail.get("trace"), "嵌入数据须含轨迹");
+        assertTrue(detail.get("trace").size() >= 1);
+        assertEquals("no-store", hit.getHeaders().getCacheControl());
+        // viewerId=null：本人待办字段不填充（嵌入页只读，不泄办理面板）
+        assertTrue(detail.get("myPendingTaskIds").isNull() || detail.get("myPendingTaskIds").size() == 0);
+
+        // 跨校隔离：token 内 schId 与办件归属不符 → 404（同图片流防漂移口径）
+        String crossToken = tokenService.issue(2L, instanceId, null, "auto");
+        assertEquals(404, client.getRaw("/open/flow/embed/data?token=" + crossToken).getStatusCodeValue());
+    }
+
+    /** 从 pageUrl 提取 token（#/embed/instance?token=xxx&mode=yyy） */
+    private String extractToken(String pageUrl) {
+        int from = pageUrl.indexOf("token=") + "token=".length();
+        int to = pageUrl.indexOf("&mode=");
+        return pageUrl.substring(from, to);
+    }
+
     // ===== 应用内审批（第三步）：tasks/todo + instances + approve/reject =====
 
     /** 待办分页（bizType 过滤 + 出参含 biz 定位/快照/版本）；查询不限办理人（办理才校验） */