feat: 提交流程中心后端代码

Spring Boot 流程引擎服务：流程定义/实例/任务、审批人解析、
回调分发、oapi 接口及单元测试。
保留远程 .gitea/workflows/build.yml 与 docker/Dockerfile，
新增 .gitignore 排除 target/ 构建产物。

src/main/java/com/yunhai/flowcenter/FlowCenterApplication.java

@@ -0,0 +1,20 @@
+package com.yunhai.flowcenter;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.scheduling.annotation.EnableScheduling;
+
+/**
+ * 流程中心（V2.0 拆分后独立应用，原 svhall 短名改名 flow-center）：
+ * 纯流程引擎——流程定义/引擎/任务/办件实例/回调分发；不做表单（自定义表单归办事大厅 svc-hall）。
+ * 两种消费方均以"托管模式"接入：代发起（biz uk 幂等）→ 审批 → X-Flw-* 事件回调 → 业务方镜像状态机；
+ * 对账拉取兜底（《流程中心M1开工说明.md》§1）。
+ */
+@EnableScheduling
+@SpringBootApplication
+public class FlowCenterApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(FlowCenterApplication.class, args);
+    }
+}

src/main/java/com/yunhai/flowcenter/callback/CallbackDispatcher.java

@@ -0,0 +1,165 @@
+package com.yunhai.flowcenter.callback;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.flowcenter.engine.FlowEvent;
+import com.yunhai.flowcenter.entity.FlwCallbackLog;
+import com.yunhai.flowcenter.entity.FlwCallbackReg;
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.repository.FlwCallbackLogRepository;
+import com.yunhai.flowcenter.repository.FlwCallbackRegRepository;
+import com.yunhai.flowcenter.repository.FlwDefRepository;
+import com.yunhai.flowcenter.repository.FlwInstanceRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.event.TransactionPhase;
+import org.springframework.transaction.event.TransactionalEventListener;
+
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+/**
+ * 回调分发器（概览 §8.4 可靠性设计）：引擎 AFTER_COMMIT 事件 → 匹配 flw_callback_reg
+ * （flowGuid + 订阅事件）→ 落 flw_callback_log(status=0) → 异步首推。
+ * 落库成功即视为主业务完成，推送失败不影响审批（异步解耦是特性）。
+ * @Scheduled(fixedDelay=30s) 扫 (status=0, next_retry_time<=now) 重推；死信留管理端手工重推。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class CallbackDispatcher {
+
+    private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+
+    private final FlwInstanceRepository instanceRepository;
+    private final FlwDefRepository defRepository;
+    private final FlwCallbackRegRepository regRepository;
+    private final FlwCallbackLogRepository logRepository;
+    private final CallbackLogStore logStore;
+    private final CallbackPushService pushService;
+    private final CallbackProperties properties;
+    private final ObjectMapper objectMapper;
+
+    private volatile ExecutorService pushExecutor;
+
+    private ExecutorService executor() {
+        if (pushExecutor == null) {
+            synchronized (this) {
+                if (pushExecutor == null) {
+                    pushExecutor = Executors.newFixedThreadPool(Math.max(1, properties.getPushPoolSize()));
+                }
+            }
+        }
+        return pushExecutor;
+    }
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true)
+    public void onFlowEvent(FlowEvent event) {
+        // URGE 仅站内信通道，不进回调事件流（概览 §8.3 事件枚举固定六种）
+        if (event.getType() == FlowEvent.Type.URGE) {
+            return;
+        }
+        try {
+            dispatch(event);
+        } catch (Exception e) {
+            // 分发失败只影响回调（对账兜底会追平），绝不能反噬引擎主流程
+            log.error("[flow-center] 回调分发异常：instance={} event={} {}",
+                    event.getInstanceId(), event.getType().getCode(), e.toString(), e);
+        }
+    }
+
+    private void dispatch(FlowEvent event) {
+        FlwInstance instance = instanceRepository.findById(event.getInstanceId()).orElse(null);
+        if (instance == null) {
+            return;
+        }
+        FlwDef def = defRepository.findById(instance.getDefId()).orElse(null);
+        if (def == null) {
+            return;
+        }
+        String eventCode = event.getType().getCode();
+        List<FlwCallbackReg> regs = regRepository.findBySchIdAndFlowGuidAndStatus(
+                instance.getSchId(), def.getFlowGuid(), 0);
+        for (FlwCallbackReg reg : regs) {
+            if (!subscribed(reg.getEventTypes(), eventCode)) {
+                continue;
+            }
+            persistAndPush(reg, instance, def, event);
+        }
+    }
+
+    private void persistAndPush(FlwCallbackReg reg, FlwInstance instance, FlwDef def, FlowEvent event) {
+        try {
+            String eventId = UUID.randomUUID().toString().replace("-", "").toLowerCase();
+            Map<String, Object> payload = new HashMap<>();
+            payload.put("eventId", eventId);
+            payload.put("event", event.getType().getCode());
+            payload.put("schId", instance.getSchId());
+            payload.put("flowGuid", def.getFlowGuid());
+            payload.put("instanceId", instance.getId());
+            payload.put("instanceVersion", instance.getVersion());
+            payload.put("bizType", instance.getBizType());
+            payload.put("bizId", instance.getBizId());
+            payload.put("bizTitle", instance.getBizTitle());
+            payload.put("occurredTime", LocalDateTime.now().format(TIME));
+            Map<String, Object> data = new HashMap<>();
+            if (event.getData() != null) {
+                data.putAll(event.getData());
+            }
+            payload.put("data", data);
+            String payloadJson = objectMapper.writeValueAsString(payload);
+
+            FlwCallbackLog callbackLog = new FlwCallbackLog();
+            callbackLog.setSchId(instance.getSchId());
+            callbackLog.setRegId(reg.getId());
+            callbackLog.setEventId(eventId);
+            callbackLog.setEvent(event.getType().getCode());
+            callbackLog.setInstanceId(instance.getId());
+            callbackLog.setBizType(instance.getBizType());
+            callbackLog.setBizId(instance.getBizId());
+            callbackLog.setPayloadJson(payloadJson);
+            callbackLog.setStatus(FlwEnums.CallbackLogStatus.PENDING.getCode());
+            callbackLog.setRetryCount(0);
+            callbackLog.setNextRetryTime(LocalDateTime.now());
+            // REQUIRES_NEW 落库（afterCommit 阶段原事务已完结，REQUIRED 会挂空事务）
+            Long logId = logStore.persist(callbackLog);
+            // 异步首推：失败由退避重试接手（1m 起）
+            executor().submit(() -> pushService.pushAsync(logId));
+        } catch (Exception e) {
+            log.error("[flow-center] 回调日志落库失败（对账兜底会追平）：instance={} event={} {}",
+                    instance.getId(), event.getType().getCode(), e.toString(), e);
+        }
+    }
+
+    /** 重推扫描（fixedDelay 串行防重入；推拉结合里 Webhook 永远只是加速器） */
+    @Scheduled(fixedDelay = 30_000)
+    public void scanRetry() {
+        List<FlwCallbackLog> due = logRepository.findTop50ByStatusAndNextRetryTimeLessThanEqualOrderByNextRetryTimeAsc(
+                FlwEnums.CallbackLogStatus.PENDING.getCode(), LocalDateTime.now());
+        for (FlwCallbackLog callbackLog : due) {
+            executor().submit(() -> pushService.pushAsync(callbackLog.getId()));
+        }
+    }
+
+    /** 订阅匹配：空=全部；逗号分隔事件码包含即命中 */
+    private static boolean subscribed(String eventTypes, String eventCode) {
+        if (eventTypes == null || eventTypes.trim().isEmpty()) {
+            return true;
+        }
+        for (String t : eventTypes.split(",")) {
+            if (eventCode.equals(t.trim())) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

src/main/java/com/yunhai/flowcenter/callback/CallbackLogStore.java

@@ -0,0 +1,27 @@
+package com.yunhai.flowcenter.callback;
+
+import com.yunhai.flowcenter.entity.FlwCallbackLog;
+import com.yunhai.flowcenter.repository.FlwCallbackLogRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * 回调日志落库（独立 bean 保证 REQUIRES_NEW 生效）：AFTER_COMMIT 监听阶段原事务已提交
+ * 但事务资源仍挂在线程上，REQUIRED 会"加入"已完结事务并抛 no transaction is in progress——
+ * 必须显式开新事务写日志。落库成功即视为主业务完成，推送失败不影响审批。
+ */
+@Service
+@RequiredArgsConstructor
+public class CallbackLogStore {
+
+    private final FlwCallbackLogRepository logRepository;
+
+    /** @return 落库后的日志行 id */
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public Long persist(FlwCallbackLog callbackLog) {
+        FlwCallbackLog saved = logRepository.saveAndFlush(callbackLog);
+        return saved.getId();
+    }
+}

src/main/java/com/yunhai/flowcenter/callback/CallbackProperties.java

@@ -0,0 +1,38 @@
+package com.yunhai.flowcenter.callback;
+
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * 回调推送配置（application.yml flow-center.callback.*）。
+ */
+@Data
+@Component
+@ConfigurationProperties(prefix = "flow-center.callback")
+public class CallbackProperties {
+
+    /** 推送线程池大小（概览 §8.4：单机小并发 5） */
+    private int pushPoolSize = 5;
+
+    /**
+     * 退避序列（分钟）：1m→5m→30m→2h→6h；越过序列后按 {@link #capBackoffMinutes} 封顶持续重试，
+     * 不自动死信（持续重试语义：消费方恢复即自动追平，消费方免对账）。
+     */
+    private List<Long> retryBackoffMinutes = Arrays.asList(1L, 5L, 30L, 120L, 360L);
+
+    /**
+     * 挂起告警阈值：retryCount 首次等于该值时 UserMsg 告警恰一次（retryCount 单调递增保证）。
+     * 默认 6 = 越过退避表（5 项）后的第一次失败。
+     */
+    private int hangAlertRetries = 6;
+
+    /** 越过退避表后的封顶重试间隔（分钟），默认 60 */
+    private long capBackoffMinutes = 60;
+
+    /** 告警接收人（本校管理员 userId，逗号分隔；空=不告警只记日志）——挂起告警与死信告警共用 */
+    private String alertUserIds = "";
+}

src/main/java/com/yunhai/flowcenter/callback/CallbackPushService.java

@@ -0,0 +1,243 @@
+package com.yunhai.flowcenter.callback;
+
+import com.yunhai.flowcenter.entity.FlwCallbackLog;
+import com.yunhai.flowcenter.entity.FlwCallbackReg;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.repository.FlwCallbackLogRepository;
+import com.yunhai.flowcenter.repository.FlwCallbackRegRepository;
+import com.yunhai.flowcenter.notify.UserMsgClient;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpMethod;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
+import org.springframework.stereotype.Service;
+import org.springframework.web.client.RestTemplate;
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.charset.StandardCharsets;
+import java.time.LocalDateTime;
+import java.util.Base64;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * 回调推送执行（概览 §8.4 协议）：POST callback_url + X-Flw-* 四头
+ * （Signature = Base64(HmacSHA256(secret, timestamp + "." + nonce + "." + body))）。
+ * 2xx 即成功（不解析响应体）；失败按退避序列排下次重试，越过序列后封顶 cap-backoff-minutes
+ * <b>持续重试不终止</b>（T1.1：消费方只承诺"瞬时失败回 5xx"，恢复后自动追平，消费方免对账）；
+ * 挂起（retryCount 首达 hang-alert-retries）时 UserMsg 告警恰一次；
+ * 死信（status=2）仅两个入口——注册停用、管理端手工标记，重试次数永不自动触发。
+ * 推送一律在新事务里落库（AFTER_COMMIT 监听器/调度线程均无外层事务）。
+ * 推送本身与落库解耦：payload_json 是完整快照，可重放。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class CallbackPushService {
+
+    private static final Set<Long> IN_FLIGHT = new HashSet<>();
+
+    private final FlwCallbackLogRepository logRepository;
+    private final FlwCallbackRegRepository regRepository;
+    private final CallbackProperties properties;
+    private final UserMsgClient userMsgClient;
+
+    /** 推送指定日志行（幂等入口：成功/终态/在途跳过） */
+    public void pushAsync(Long logId) {
+        synchronized (IN_FLIGHT) {
+            if (!IN_FLIGHT.add(logId)) {
+                return;
+            }
+        }
+        try {
+            doPush(logId);
+        } finally {
+            synchronized (IN_FLIGHT) {
+                IN_FLIGHT.remove(logId);
+            }
+        }
+    }
+
+    private void doPush(Long logId) {
+        FlwCallbackLog callbackLog = logRepository.findById(logId).orElse(null);
+        if (callbackLog == null
+                || callbackLog.getStatus() != FlwEnums.CallbackLogStatus.PENDING.getCode()) {
+            return;
+        }
+        FlwCallbackReg reg = regRepository.findById(callbackLog.getRegId()).orElse(null);
+        if (reg == null || reg.getStatus() != 0) {
+            // 注册已停用：保留日志待查，不再推送（置死信便于管理端一次性清理）
+            markDead(callbackLog, "registration disabled");
+            return;
+        }
+        String body = callbackLog.getPayloadJson();
+        String ts = String.valueOf(System.currentTimeMillis());
+        String nonce = UUID.randomUUID().toString().replace("-", "").substring(0, 16);
+        try {
+            HttpHeaders headers = new HttpHeaders();
+            headers.setContentType(MediaType.APPLICATION_JSON);
+            headers.set("X-Flw-EventId", callbackLog.getEventId());
+            headers.set("X-Flw-Timestamp", ts);
+            headers.set("X-Flw-Nonce", nonce);
+            headers.set("X-Flw-Signature", sign(reg.getSecret(), ts, nonce, body));
+            RestTemplate template = rawTemplate();
+            ResponseEntity<String> resp = template.exchange(reg.getCallbackUrl(), HttpMethod.POST,
+                    new HttpEntity<>(body, headers), String.class);
+            int status = resp.getStatusCodeValue();
+            if (status >= 200 && status < 300) {
+                markSuccess(callbackLog, status);
+            } else {
+                markRetryOrFail(callbackLog, "HTTP " + status, String.valueOf(status));
+            }
+        } catch (Exception e) {
+            markRetryOrFail(callbackLog, rootMessage(e), null);
+        }
+    }
+
+    private void markSuccess(FlwCallbackLog callbackLog, int httpStatus) {
+        callbackLog.setStatus(FlwEnums.CallbackLogStatus.SUCCESS.getCode());
+        callbackLog.setRetryCount(callbackLog.getRetryCount() == null ? 0 : callbackLog.getRetryCount());
+        callbackLog.setLastHttpStatus(String.valueOf(httpStatus));
+        callbackLog.setLastError(null);
+        callbackLog.setPushTime(LocalDateTime.now());
+        saveQuietly(callbackLog);
+        log.debug("[flow-center] 回调推送成功：eventId={} http={}", callbackLog.getEventId(), httpStatus);
+    }
+
+    /**
+     * 失败落定（持续重试语义）：越过退避表后按 {@link CallbackProperties#getCapBackoffMinutes()}
+     * 封顶继续排期，<b>绝不自动死信</b>；retryCount 首次等于挂起阈值时告警恰一次。
+     */
+    private void markRetryOrFail(FlwCallbackLog callbackLog, String error, String httpStatus) {
+        int retryCount = (callbackLog.getRetryCount() == null ? 0 : callbackLog.getRetryCount()) + 1;
+        callbackLog.setRetryCount(retryCount);
+        callbackLog.setLastHttpStatus(httpStatus);
+        callbackLog.setLastError(truncate(error));
+        java.util.List<Long> backoff = properties.getRetryBackoffMinutes();
+        long backoffMinutes = retryCount <= backoff.size()
+                ? backoff.get(retryCount - 1)
+                : Math.max(1, properties.getCapBackoffMinutes());
+        callbackLog.setStatus(FlwEnums.CallbackLogStatus.PENDING.getCode());
+        callbackLog.setNextRetryTime(LocalDateTime.now().plusMinutes(backoffMinutes));
+        saveQuietly(callbackLog);
+        log.warn("[flow-center] 回调推送失败（第 {} 次重试，{} 分钟后）：eventId={} {}",
+                retryCount, backoffMinutes, callbackLog.getEventId(), error);
+        // 挂起告警恰一次：retryCount 每失败 +1 单调递增，等于阈值的时机只有一次；
+        // msgNo("hang:"+eventId) 幂等双保险（管理端 rePush 重置 retryCount 后再挂起可再告警，属人工重启语义）
+        if (retryCount == properties.getHangAlertRetries()) {
+            alertHung(callbackLog, error, backoffMinutes);
+        }
+    }
+
+    /** 挂起告警本校管理员（持续重试越过退避表=消费方疑似停机；UserMsg 不可达只记日志，不影响重试） */
+    private void alertHung(FlwCallbackLog callbackLog, String error, long capMinutes) {
+        java.util.List<Integer> userIds = parseAlertUserIds();
+        if (userIds.isEmpty()) {
+            return;
+        }
+        try {
+            userMsgClient.sendUserMsg(callbackLog.getSchId().intValue(), userIds, 1,
+                    "flow.hung", String.valueOf(callbackLog.getInstanceId()),
+                    "回调挂起告警",
+                    "办件 " + callbackLog.getInstanceId() + " 事件 " + callbackLog.getEvent()
+                            + " 推送连续失败 " + callbackLog.getRetryCount() + " 次，已转入持续重试（封顶 "
+                            + capMinutes + " 分钟/次）。消费方恢复后将自动追平，无需人工干预；"
+                            + "如确认该事件已无意义，请在管理端标记死信。最近错误：" + truncate(error),
+                    null, "hang:" + callbackLog.getEventId(), null);
+        } catch (Exception e) {
+            log.warn("[flow-center] 挂起告警发送失败：eventId={} {}", callbackLog.getEventId(), e.toString());
+        }
+    }
+
+    /**
+     * 标记死信（public：管理端手工标记的唯一执行入口；重试路径已不再自动调用）。
+     * 仍被注册停用场景使用（doPush：注册已停用即无意义重试，置死信便于管理端清理）。
+     */
+    public void markDead(FlwCallbackLog callbackLog, String error) {
+        callbackLog.setStatus(FlwEnums.CallbackLogStatus.DEAD.getCode());
+        callbackLog.setLastError(truncate(error));
+        saveQuietly(callbackLog);
+        log.error("[flow-center] 回调推送进入死信：eventId={} biz={}/{} error={}",
+                callbackLog.getEventId(), callbackLog.getBizType(), callbackLog.getBizId(), error);
+        alertDead(callbackLog, error);
+    }
+
+    private java.util.List<Integer> parseAlertUserIds() {
+        java.util.List<Integer> userIds = new java.util.ArrayList<>();
+        String alertUserIds = properties.getAlertUserIds();
+        if (alertUserIds == null || alertUserIds.trim().isEmpty()) {
+            return userIds;
+        }
+        for (String s : alertUserIds.split(",")) {
+            if (!s.trim().isEmpty()) {
+                userIds.add(Integer.valueOf(s.trim()));
+            }
+        }
+        return userIds;
+    }
+
+    /** 死信告警本校管理员（配置 alertUserIds；UserMsg 不可达只记日志，不影响死信落定） */
+    private void alertDead(FlwCallbackLog callbackLog, String error) {
+        java.util.List<Integer> userIds = parseAlertUserIds();
+        if (userIds.isEmpty()) {
+            return;
+        }
+        try {
+            userMsgClient.sendUserMsg(callbackLog.getSchId().intValue(), userIds, 1,
+                    "flow.dead", String.valueOf(callbackLog.getInstanceId()),
+                    "回调推送死信告警",
+                    "办件 " + callbackLog.getInstanceId() + " 事件 " + callbackLog.getEvent()
+                            + " 推送失败进入死信：" + error,
+                    null, "dead:" + callbackLog.getEventId(), null);
+        } catch (Exception e) {
+            log.warn("[flow-center] 死信告警发送失败：eventId={} {}", callbackLog.getEventId(), e.toString());
+        }
+    }
+
+    private void saveQuietly(FlwCallbackLog callbackLog) {
+        try {
+            logRepository.save(callbackLog);
+        } catch (Exception e) {
+            log.error("[flow-center] 回调日志落库失败：eventId={} {}", callbackLog.getEventId(), e.toString());
+        }
+    }
+
+    private static String sign(String secret, String timestamp, String nonce, String body) {
+        try {
+            Mac mac = Mac.getInstance("HmacSHA256");
+            mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
+            byte[] raw = mac.doFinal((timestamp + "." + nonce + "." + body).getBytes(StandardCharsets.UTF_8));
+            return Base64.getEncoder().encodeToString(raw);
+        } catch (Exception e) {
+            throw new IllegalStateException("HmacSHA256 计算失败", e);
+        }
+    }
+
+    private RestTemplate rawTemplate() {
+        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
+        factory.setConnectTimeout(5000);
+        factory.setReadTimeout(10000);
+        return new RestTemplate(factory);
+    }
+
+    private static String rootMessage(Throwable e) {
+        Throwable cur = e;
+        while (cur.getCause() != null && cur.getCause() != cur) {
+            cur = cur.getCause();
+        }
+        return cur.toString();
+    }
+
+    private static String truncate(String s) {
+        if (s == null) {
+            return null;
+        }
+        return s.length() > 1000 ? s.substring(0, 1000) : s;
+    }
+}

src/main/java/com/yunhai/flowcenter/common/FlowCenterAuditListener.java

@@ -0,0 +1,41 @@
+package com.yunhai.flowcenter.common;
+
+import com.yunhai.flowcenter.entity.BaseEntity;
+import com.yunhai.platform.auth.LoginUser;
+import com.yunhai.platform.auth.UserContextHolder;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+import javax.persistence.PrePersist;
+import javax.persistence.PreUpdate;
+import java.time.LocalDateTime;
+
+/**
+ * 审计字段自动填充（CmsAuditListener/SvcHallAuditListener 同款）。
+ * 账号取 ThreadLocal 中的 CAS 会话用户；定时任务/回调推送等无会话场景为 null。
+ */
+@Slf4j
+@Component
+public class FlowCenterAuditListener {
+
+    @PrePersist
+    public void prePersist(BaseEntity entity) {
+        String account = currentAccount();
+        LocalDateTime now = LocalDateTime.now();
+        entity.setCreateBy(account);
+        entity.setCreateTime(now);
+        entity.setUpdateBy(account);
+        entity.setUpdateTime(now);
+    }
+
+    @PreUpdate
+    public void preUpdate(BaseEntity entity) {
+        entity.setUpdateBy(currentAccount());
+        entity.setUpdateTime(LocalDateTime.now());
+    }
+
+    private String currentAccount() {
+        LoginUser user = UserContextHolder.get();
+        return user == null ? null : user.getLoginName();
+    }
+}

src/main/java/com/yunhai/flowcenter/config/FlowCorsConfiguration.java

@@ -0,0 +1,46 @@
+package com.yunhai.flowcenter.config;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.web.servlet.FilterRegistrationBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.Ordered;
+import org.springframework.web.cors.CorsConfiguration;
+import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
+import org.springframework.web.filter.CorsFilter;
+
+import java.util.Arrays;
+import java.util.Collections;
+
+/**
+ * 本地开发跨端口 CORS（V2.0 拍板项#2）：办事大厅 front(8087)/本应用 front(8088) 直调
+ * /api/flow/* 属跨端口请求，需带凭据的 CORS 头（CAS cookie 不隔离端口，免二次登录成立的前提）。
+ * 同主域生产无跨端口问题，配置 allowed-origins 置空即整体关闭。
+ */
+@Configuration
+public class FlowCorsConfiguration {
+
+    public FlowCorsConfiguration(
+            @Value("${flow-center.cors.allowed-origins:}") String allowedOrigins) {
+        this.allowedOrigins = allowedOrigins;
+    }
+
+    private final String allowedOrigins;
+
+    @Bean
+    public FilterRegistrationBean<CorsFilter> flowCorsFilter() {
+        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+        CorsConfiguration config = new CorsConfiguration();
+        if (allowedOrigins != null && !allowedOrigins.trim().isEmpty()) {
+            config.setAllowedOrigins(Arrays.asList(allowedOrigins.split("\\s*,\\s*")));
+            config.setAllowedMethods(Collections.singletonList("*"));
+            config.setAllowedHeaders(Collections.singletonList("*"));
+            config.setAllowCredentials(true);
+            // 只对用户面生效；/oapi/* 是应用签名调用，不经浏览器
+            source.registerCorsConfiguration("/api/**", config);
+        }
+        FilterRegistrationBean<CorsFilter> bean = new FilterRegistrationBean<>(new CorsFilter(source));
+        bean.setOrder(Ordered.HIGHEST_PRECEDENCE);
+        return bean;
+    }
+}

src/main/java/com/yunhai/flowcenter/controller/api/FlowAdminController.java

@@ -0,0 +1,201 @@
+package com.yunhai.flowcenter.controller.api;
+
+import com.yunhai.flowcenter.entity.FlwAssigneeMap;
+import com.yunhai.flowcenter.entity.FlwCallbackLog;
+import com.yunhai.flowcenter.entity.FlwCallbackReg;
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.model.FlowModels;
+import com.yunhai.flowcenter.repository.FlwInstanceRepository;
+import com.yunhai.flowcenter.service.FlowAdminGuard;
+import com.yunhai.flowcenter.service.FlowCallbackAdminService;
+import com.yunhai.flowcenter.service.FlowDefAdminService;
+import com.yunhai.flowcenter.service.FlowDiagramService;
+import com.yunhai.flowcenter.service.FlowMapAdminService;
+import com.yunhai.platform.utils.model.BasePageResult;
+import com.yunhai.platform.utils.model.BoaUser;
+import lombok.RequiredArgsConstructor;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Sort;
+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.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 管理端（/api/flow/admin/**，CAS + 管理员角色，FlowAdminGuard 校验）：
+ * 定义 JSON 编辑/发布/停用、办理人映射 CRUD（成员检索调 UserBase）、
+ * 回调注册管理/推送日志/死信重推、办件查询。
+ */
+@RestController
+@RequestMapping("/api/flow/admin")
+@RequiredArgsConstructor
+public class FlowAdminController {
+
+    private final FlowAdminGuard adminGuard;
+    private final FlowDefAdminService defAdminService;
+    private final FlowMapAdminService mapAdminService;
+    private final FlowCallbackAdminService callbackAdminService;
+    private final FlwInstanceRepository instanceRepository;
+    private final FlowDiagramService diagramService;
+
+    // ==================== 流程定义 ====================
+
+    @GetMapping("/def/list")
+    public List<FlwDef> defList(BoaUser user,
+                                @RequestParam(value = "status", required = false) Integer status) {
+        return defAdminService.list(adminGuard.requireAdmin(user, null), status);
+    }
+
+    @GetMapping("/def/get")
+    public FlwDef defGet(BoaUser user, @RequestParam("id") Long id) {
+        return defAdminService.get(adminGuard.requireAdmin(user, null), id);
+    }
+
+    /** 保存（新建草稿/编辑；已发布定义保存=升版本，flowGuid 不变；baseGuid=在指定流程线上开新版本草稿） */
+    @PostMapping("/def/save")
+    public FlwDef defSave(BoaUser user, @RequestBody Map<String, Object> body) {
+        Long schId = adminGuard.requireAdmin(user, null);
+        Long id = body.get("id") == null ? null : Long.valueOf(String.valueOf(body.get("id")));
+        return defAdminService.save(schId, id,
+                (String) body.get("code"), (String) body.get("name"),
+                (String) body.get("contentJson"), (String) body.get("baseGuid"));
+    }
+
+    @PostMapping("/def/publish/{id}")
+    public FlwDef defPublish(BoaUser user, @PathVariable("id") Long id) {
+        return defAdminService.publish(adminGuard.requireAdmin(user, null), id);
+    }
+
+    @PostMapping("/def/offline/{id}")
+    public void defOffline(BoaUser user, @PathVariable("id") Long id) {
+        defAdminService.offline(adminGuard.requireAdmin(user, null), id);
+    }
+
+    @GetMapping("/def/versions")
+    public List<FlwDef> defVersions(BoaUser user, @RequestParam("flowGuid") String flowGuid) {
+        return defAdminService.versions(adminGuard.requireAdmin(user, null), flowGuid);
+    }
+
+    /** 流程定义示意图（方案 §3.1）：requireAdmin 后按 defId 任意版本出图（草稿可预览） */
+    @GetMapping("/def/diagram")
+    public FlowModels.DiagramVo defDiagram(BoaUser user, @RequestParam("id") Long id,
+                                           @RequestParam(value = "mode", required = false) String mode) {
+        Long schId = adminGuard.requireAdmin(user, null);
+        FlwDef def = defAdminService.get(schId, id);
+        return diagramService.build(def, null, mode);
+    }
+
+    // ==================== 办理人映射 ====================
+
+    @GetMapping("/map/list")
+    public List<FlwAssigneeMap> mapList(BoaUser user,
+                                        @RequestParam(value = "deptKey", required = false) String deptKey) {
+        return mapAdminService.listByDept(adminGuard.requireAdmin(user, null), deptKey);
+    }
+
+    @PostMapping("/map/save")
+    public FlwAssigneeMap mapSave(BoaUser user, @RequestBody Map<String, Object> body) {
+        Long schId = adminGuard.requireAdmin(user, null);
+        return mapAdminService.save(schId,
+                (String) body.get("deptKey"), (String) body.get("deptName"),
+                body.get("userId") == null ? null : Integer.valueOf(String.valueOf(body.get("userId"))),
+                (String) body.get("userName"));
+    }
+
+    @PostMapping("/map/disable/{id}")
+    public void mapDisable(BoaUser user, @PathVariable("id") Long id) {
+        mapAdminService.disable(adminGuard.requireAdmin(user, null), id);
+    }
+
+    /** 成员检索（UserBase /oapi/user/byId） */
+    @GetMapping("/map/lookupUser")
+    public com.yunhai.platform.utils.model.BoaUser lookupUser(BoaUser user,
+                                                              @RequestParam("userId") Integer userId) {
+        adminGuard.requireAdmin(user, null);
+        return mapAdminService.lookupUser(userId);
+    }
+
+    // ==================== 回调注册/推送日志/死信 ====================
+
+    @GetMapping("/callback/regList")
+    public List<FlwCallbackReg> regList(BoaUser user) {
+        return callbackAdminService.listRegs(adminGuard.requireAdmin(user, null));
+    }
+
+    @PostMapping("/callback/regStatus/{id}")
+    public void regStatus(BoaUser user, @PathVariable("id") Long id,
+                          @RequestParam("enabled") boolean enabled) {
+        callbackAdminService.setRegStatus(adminGuard.requireAdmin(user, null), id, enabled);
+    }
+
+    /** secret 重置（新 secret 返回给前端展示一次） */
+    @PostMapping("/callback/resetSecret/{id}")
+    public Map<String, String> resetSecret(BoaUser user, @PathVariable("id") Long id) {
+        String secret = callbackAdminService.resetSecret(adminGuard.requireAdmin(user, null), id);
+        return java.util.Collections.singletonMap("secret", secret);
+    }
+
+    @GetMapping("/callback/logs")
+    public BasePageResult<FlwCallbackLog> logs(BoaUser user,
+                                               @RequestParam(value = "status", required = false) Integer status,
+                                               @RequestParam(value = "event", required = false) String event,
+                                               @RequestParam(value = "instanceId", required = false) Long instanceId,
+                                               @RequestParam(value = "page", required = false) Integer page,
+                                               @RequestParam(value = "size", required = false) Integer size) {
+        return callbackAdminService.pageLogs(adminGuard.requireAdmin(user, null), status, event, instanceId, page, size);
+    }
+
+    /** 挂起列表（待推且重试达阈值；持续重试中疑似消费方停机的可视入口） */
+    @GetMapping("/callback/hung")
+    public BasePageResult<FlwCallbackLog> hung(BoaUser user,
+                                               @RequestParam(value = "page", required = false) Integer page,
+                                               @RequestParam(value = "size", required = false) Integer size) {
+        return callbackAdminService.pageHung(adminGuard.requireAdmin(user, null), page, size);
+    }
+
+    /** 管理端手工标记死信（死信唯一人工入口；标记后可 rePush 复活） */
+    @PostMapping("/callback/markDead/{id}")
+    public void markDead(BoaUser user, @PathVariable("id") Long id) {
+        callbackAdminService.markDead(adminGuard.requireAdmin(user, null), id);
+    }
+
+    @GetMapping("/callback/dead")
+    public BasePageResult<FlwCallbackLog> dead(BoaUser user,
+                                               @RequestParam(value = "page", required = false) Integer page,
+                                               @RequestParam(value = "size", required = false) Integer size) {
+        return callbackAdminService.pageDead(adminGuard.requireAdmin(user, null), page, size);
+    }
+
+    @PostMapping("/callback/repush")
+    public void repush(BoaUser user, @RequestBody List<Long> logIds) {
+        callbackAdminService.rePush(adminGuard.requireAdmin(user, null), logIds);
+    }
+
+    // ==================== 办件查询 ====================
+
+    @GetMapping("/instance/page")
+    public BasePageResult<FlwInstance> instancePage(
+            BoaUser user,
+            @RequestParam(value = "status", required = false) Integer status,
+            @RequestParam(value = "keyword", required = false) String keyword,
+            @RequestParam(value = "page", required = false) Integer page,
+            @RequestParam(value = "size", required = false) Integer size) {
+        Long schId = adminGuard.requireAdmin(user, null);
+        Page<FlwInstance> p = instanceRepository.pageAdmin(schId, status, keyword,
+                PageRequest.of(page == null || page < 1 ? 0 : page - 1,
+                        size == null || size < 1 || size > 100 ? 10 : size,
+                        Sort.by(Sort.Order.desc("id"))));
+        int pi = page == null || page < 1 ? 1 : page;
+        int ps = size == null || size < 1 || size > 100 ? 10 : size;
+        return new BasePageResult<>(p.getContent(), (int) p.getTotalElements(), pi, ps,
+                p.getTotalPages(), p.hasNext());
+    }
+}

src/main/java/com/yunhai/flowcenter/controller/api/FlowBaseController.java

@@ -0,0 +1,49 @@
+package com.yunhai.flowcenter.controller.api;
+
+import com.yunhai.platform.utils.model.BoaUser;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 前端壳基础端点（对齐 UserBase BaseController 的 /api/base/* 形态）：
+ * GetUserInfo 返回当前登录人；GetUserMod 返回本地路由菜单——flow-center 是独立登录态应用，
+ * 菜单不走 UserBase app_module 下发（概览 §9.4），modId 为本应用内部约定。
+ */
+@RestController
+public class FlowBaseController {
+
+    /** 左侧菜单（本地路由，顺序即展示顺序） */
+    private static final String[][] MENUS = {
+            {"100", "工作台", "/workbench"},
+            {"101", "我的办件", "/my"},
+            {"102", "办件记录", "/admin/instances"},
+            {"103", "流程定义", "/admin/defs"},
+            {"104", "办理人映射", "/admin/maps"},
+            {"105", "回调管理", "/admin/callbacks"},
+    };
+
+    @GetMapping("/api/base/GetUserInfo")
+    public BoaUser getUserInfo(BoaUser authUserWithDept) {
+        return authUserWithDept;
+    }
+
+    @GetMapping("/api/base/GetUserMod")
+    public List<Map<String, Object>> getUserMod() {
+        List<Map<String, Object>> modList = new ArrayList<>();
+        for (String[] m : MENUS) {
+            Map<String, Object> item = new HashMap<>();
+            item.put("id", Integer.valueOf(m[0]));
+            item.put("modId", Integer.valueOf(m[0]));
+            item.put("name", m[1]);
+            item.put("page", m[2]);
+            item.put("children", new ArrayList<>());
+            modList.add(item);
+        }
+        return modList;
+    }
+}

src/main/java/com/yunhai/flowcenter/controller/api/FlowUserController.java

@@ -0,0 +1,146 @@
+package com.yunhai.flowcenter.controller.api;
+
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.entity.FlwTask;
+import com.yunhai.flowcenter.model.FlowModels;
+import com.yunhai.flowcenter.service.FlowAccessGuard;
+import com.yunhai.flowcenter.service.FlowDiagramService;
+import com.yunhai.flowcenter.service.FlowInstanceService;
+import com.yunhai.flowcenter.service.FlowQueryService;
+import com.yunhai.flowcenter.service.FlowTaskService;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.platform.utils.model.BasePageResult;
+import com.yunhai.platform.utils.model.BoaUser;
+import lombok.RequiredArgsConstructor;
+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.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Map;
+
+/**
+ * 用户面（/api/flow/**，CAS 会话）：我的办件/待办/已办/办件详情/办理/撤回/催办。
+ * 一切审批入口的收敛点（概览 §8.5 不变式 2）：业务系统内嵌页、消息跳转最终都调这套 API。
+ */
+@RestController
+@RequestMapping("/api/flow")
+@RequiredArgsConstructor
+public class FlowUserController {
+
+    private final FlowQueryService queryService;
+    private final FlowTaskService taskService;
+    private final FlowInstanceService instanceService;
+    private final FlowAccessGuard accessGuard;
+    private final FlowDiagramService diagramService;
+
+    /** 我提交的办件 */
+    @GetMapping("/my")
+    public BasePageResult<FlowModels.InstanceItem> my(BoaUser user,
+                                                      @RequestParam(value = "status", required = false) Integer status,
+                                                      @RequestParam(value = "page", required = false) Integer page,
+                                                      @RequestParam(value = "size", required = false) Integer size) {
+        return queryService.pageMy(requireSchId(user), user.getId(), status, page, size);
+    }
+
+    /** 我的待办（主路径，走 assignee 索引） */
+    @GetMapping("/todo")
+    public BasePageResult<FlowModels.TaskItem> todo(BoaUser user,
+                                                    @RequestParam(value = "page", required = false) Integer page,
+                                                    @RequestParam(value = "size", required = false) Integer size) {
+        return queryService.pageTodo(requireSchId(user), user.getId(), page, size);
+    }
+
+    /** 我的已办 */
+    @GetMapping("/done")
+    public BasePageResult<FlowModels.TaskItem> done(BoaUser user,
+                                                    @RequestParam(value = "page", required = false) Integer page,
+                                                    @RequestParam(value = "size", required = false) Integer size) {
+        return queryService.pageDone(requireSchId(user), user.getId(), page, size);
+    }
+
+    /** 办件详情（提交人/办理人/本校管理员可见） */
+    @GetMapping("/instance/{id}")
+    public FlowModels.InstanceDetail detail(BoaUser user, @PathVariable("id") Long id) {
+        FlwInstance instance = instanceService.requireInstance(requireSchId(user), id);
+        accessGuard.requireInstanceVisible(instance, user);
+        return queryService.detail(requireSchId(user), id, user.getId());
+    }
+
+    /** 任务定位办件详情（办理页 /task/{taskId} 数据源；可见性走办件详情同一守卫） */
+    @GetMapping("/task/{id}/detail")
+    public FlowModels.InstanceDetail taskDetail(BoaUser user, @PathVariable("id") Long id) {
+        Long schId = requireSchId(user);
+        FlwTask task = taskService.requireTask(schId, id);
+        FlwInstance instance = instanceService.requireInstance(schId, task.getInstanceId());
+        accessGuard.requireInstanceVisible(instance, user);
+        return queryService.detail(schId, instance.getId(), user.getId());
+    }
+
+    /** 同意（opinion 可选）——一切审批入口的收敛点 */
+    @PostMapping("/task/{id}/approve")
+    public void approve(BoaUser user, @PathVariable("id") Long id,
+                        @RequestBody(required = false) Map<String, String> body) {
+        String opinion = body == null ? null : body.get("opinion");
+        taskService.handle(requireSchId(user), id, true, opinion, user.getId());
+    }
+
+    /** 拒绝（opinion 必填） */
+    @PostMapping("/task/{id}/reject")
+    public void reject(BoaUser user, @PathVariable("id") Long id,
+                       @RequestBody(required = false) Map<String, String> body) {
+        String opinion = body == null ? null : body.get("opinion");
+        taskService.handle(requireSchId(user), id, false, opinion, user.getId());
+    }
+
+    /** 撤回（提交人；仅尚无任务被办理时） */
+    @PostMapping("/instance/{id}/withdraw")
+    public void withdraw(BoaUser user, @PathVariable("id") Long id) {
+        FlwInstance instance = instanceService.requireInstance(requireSchId(user), id);
+        if (!instance.getSubmitterId().equals(user.getId())) {
+            throw new BizException(ErrorCode.FORBIDDEN, "仅提交人本人可撤回");
+        }
+        instanceService.withdraw(requireSchId(user), id);
+    }
+
+    /** 催办（提交人/管理员；对全部待办任务各催一次，msgNo 幂等） */
+    @PostMapping("/instance/{id}/urge")
+    public void urge(BoaUser user, @PathVariable("id") Long id) {
+        instanceService.urgeInstance(requireSchId(user), id, user.getId());
+    }
+
+    /**
+     * 流程示意图（方案 §3.1）：flowGuid=最高已发布版（登录+本校）；
+     * instanceId=办件 def 快照版，可见性与办件详情同口径（requireInstanceVisible）。
+     */
+    @GetMapping("/diagram")
+    public FlowModels.DiagramVo diagram(BoaUser user,
+                                        @RequestParam(value = "flowGuid", required = false) String flowGuid,
+                                        @RequestParam(value = "instanceId", required = false) Long instanceId,
+                                        @RequestParam(value = "mode", required = false) String mode) {
+        Long schId = requireSchId(user);
+        if (flowGuid != null && !flowGuid.trim().isEmpty()) {
+            return diagramService.byGuid(schId, flowGuid.trim(), mode);
+        }
+        if (instanceId != null) {
+            FlwInstance instance = instanceService.requireInstance(schId, instanceId);
+            accessGuard.requireInstanceVisible(instance, user);
+            return diagramService.byInstance(instance, mode);
+        }
+        throw new BizException(ErrorCode.PARAM_ERROR, "缺少必要参数：flowGuid 或 instanceId");
+    }
+
+    private Long requireSchId(BoaUser user) {
+        if (user == null) {
+            throw new BizException(ErrorCode.FORBIDDEN, "未登录");
+        }
+        if (user.getCurrentRole() == null || user.getCurrentRole().getSchId() == null) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "当前身份无学校归属（区域账号无流程业务）");
+        }
+        return Long.valueOf(user.getCurrentRole().getSchId());
+    }
+}

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

@@ -0,0 +1,64 @@
+package com.yunhai.flowcenter.controller.oapi;
+
+import com.yunhai.flowcenter.model.OapiModels;
+import com.yunhai.flowcenter.service.OapiFlowService;
+import lombok.RequiredArgsConstructor;
+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.RequestBody;
+import org.springframework.web.bind.annotation.RequestAttribute;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+/**
+ * 托管接入件（/oapi/flow/**，appKey 签名强制，V2.0 Part D #5 前置 M1）。
+ * 出入参逐字对齐 svc-hall FlowCenterClient（《流程中心M1开工说明.md》§5 契约锚点）：
+ * - GET  /oapi/flow/list?schId=                          → data=[{flowGuid,name,version,nodeSummary}]
+ * - GET  /oapi/flow/{flowGuid}?schId=                    → data={flowGuid,name,version,nodeSummary}
+ * - POST /oapi/flow/apply                                → data={instanceId,duplicated}
+ * - GET  /oapi/flow/instance?bizType=&bizId=&schId=      → data={status,version,instanceId,nodeSummary,traceJson,…}
+ * - POST /oapi/flow/callback/reg?schId=                  → data={secret}
+ */
+@RestController
+@RequestMapping("/oapi/flow")
+@RequiredArgsConstructor
+public class OapiFlowController {
+
+    private final OapiFlowService flowService;
+
+    @GetMapping("/list")
+    public List<OapiModels.FlowSummaryVo> list(@RequestParam("schId") Long schId) {
+        return flowService.listFlows(schId);
+    }
+
+    @GetMapping("/{flowGuid}")
+    public OapiModels.FlowSummaryVo getFlow(@PathVariable("flowGuid") String flowGuid,
+                                            @RequestParam("schId") Long schId) {
+        return flowService.getFlow(schId, flowGuid);
+    }
+
+    @PostMapping("/apply")
+    public OapiModels.ApplyResultVo apply(@RequestParam("schId") Long schId,
+                                          @RequestBody OapiModels.ApplyBody body) {
+        return flowService.apply(schId, body);
+    }
+
+    @GetMapping("/instance")
+    public OapiModels.InstanceVo instance(@RequestParam("bizType") String bizType,
+                                          @RequestParam("bizId") String bizId,
+                                          @RequestParam("schId") Long schId) {
+        return flowService.instanceByBiz(schId, bizType, bizId);
+    }
+
+    @PostMapping("/callback/reg")
+    public OapiModels.CallbackRegResultVo registerCallback(
+            @RequestParam("schId") Long schId,
+            @RequestAttribute(value = "yh.app.auth", required = false) String appKey,
+            @RequestBody OapiModels.CallbackRegBody body) {
+        return flowService.registerCallback(schId, appKey, body);
+    }
+}

src/main/java/com/yunhai/flowcenter/engine/AssigneeRef.java

@@ -0,0 +1,12 @@
+package com.yunhai.flowcenter.engine;
+
+import lombok.Value;
+
+/**
+ * 办理人解析结果（id+姓名快照），任务创建与通知共用。
+ */
+@Value
+public class AssigneeRef {
+    Integer userId;
+    String userName;
+}

src/main/java/com/yunhai/flowcenter/engine/AssigneeResolver.java

@@ -0,0 +1,64 @@
+package com.yunhai.flowcenter.engine;
+
+import com.yunhai.flowcenter.entity.FlwAssigneeMap;
+import com.yunhai.flowcenter.repository.FlwAssigneeMapRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.openapi.client.OpenApiUserClient;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.platform.utils.model.BoaUser;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 办理人解析（概览 §六）：DEPT_KEY 查显式映射表（零跨服务依赖）；USERS 定义直配，
+ * 姓名经 UserBase /oapi/user/byId 补全（失败降级空名不阻塞）。SUBMITTER_DEPT/FORM_FIELD 二期。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class AssigneeResolver {
+
+    private final FlwAssigneeMapRepository mapRepository;
+    private final OpenApiUserClient userClient;
+
+    public List<AssigneeRef> resolve(Long schId, FlowDefModel.Node node) {
+        FlowDefModel.Assignee a = node.assignee;
+        if (a == null) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "节点缺少办理人配置：" + node.id);
+        }
+        List<AssigneeRef> refs = new ArrayList<>();
+        if (FlowDefModel.ASSIGNEE_DEPT_KEY.equals(a.type)) {
+            List<FlwAssigneeMap> maps = mapRepository.findEnabled(schId, a.deptKey);
+            for (FlwAssigneeMap m : maps) {
+                refs.add(new AssigneeRef(m.getUserId(), m.getUserName()));
+            }
+        } else if (FlowDefModel.ASSIGNEE_USERS.equals(a.type)) {
+            if (a.userIds != null) {
+                for (Integer uid : a.userIds) {
+                    refs.add(new AssigneeRef(uid, fetchName(uid)));
+                }
+            }
+        } else {
+            throw new BizException(ErrorCode.PARAM_ERROR, "一期不支持办理人类型：" + a.type);
+        }
+        if (refs.isEmpty()) {
+            throw new BizException(ErrorCode.PARAM_ERROR,
+                    "节点[" + node.id + "]无可用办理人（映射可能已被停用）");
+        }
+        return refs;
+    }
+
+    private String fetchName(Integer userId) {
+        try {
+            BoaUser user = userClient.getUserById(String.valueOf(userId));
+            return user == null ? "" : (user.getName() == null ? "" : user.getName());
+        } catch (Exception e) {
+            log.warn("[flow-center] UserBase 用户名补全失败 userId={}：{}", userId, e.getMessage());
+            return "";
+        }
+    }
+}

src/main/java/com/yunhai/flowcenter/engine/DefValidator.java

@@ -0,0 +1,184 @@
+package com.yunhai.flowcenter.engine;
+
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * 定义发布静态校验（概览 §5.2 约束）：把"任务无主/死图"拦在发布期——
+ * START/END 存在且唯一、无孤儿节点、无环、每条 DEPT_KEY 在 flw_assignee_map 有 ≥1 启用映射、
+ * 分发/汇聚节点边数约束、会签/拒绝策略取值合法。校验失败抛 BizException 带全部问题清单。
+ */
+public final class DefValidator {
+
+    private DefValidator() {
+    }
+
+    /**
+     * @param enabledDeptKeys 本校 flw_assignee_map 中启用映射的 dept_key 全集
+     */
+    public static void validate(FlowDefModel model, Set<String> enabledDeptKeys) {
+        List<String> problems = new ArrayList<>();
+
+        if (model.nodes == null || model.nodes.isEmpty()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "流程定义缺少节点");
+        }
+        // 节点 id 唯一且非空
+        Set<String> ids = new HashSet<>();
+        for (FlowDefModel.Node n : model.nodes) {
+            if (n.id == null || n.id.trim().isEmpty()) {
+                problems.add("存在空 id 节点");
+                continue;
+            }
+            if (!ids.add(n.id)) {
+                problems.add("节点 id 重复：" + n.id);
+            }
+        }
+        // START/END 唯一；类型合法
+        int starts = 0;
+        int ends = 0;
+        for (FlowDefModel.Node n : model.nodes) {
+            if (n.type == null) {
+                problems.add("节点缺少 type：" + n.id);
+                continue;
+            }
+            switch (n.type) {
+                case FlowDefModel.TYPE_START:
+                    starts++;
+                    break;
+                case FlowDefModel.TYPE_END:
+                    ends++;
+                    break;
+                case FlowDefModel.TYPE_APPROVAL:
+                    validateApproval(n, enabledDeptKeys, problems);
+                    break;
+                case FlowDefModel.TYPE_PARALLEL_SPLIT:
+                case FlowDefModel.TYPE_PARALLEL_JOIN:
+                    break;
+                default:
+                    problems.add("未知节点类型：" + n.type + "（节点 " + n.id + "）");
+            }
+        }
+        if (starts != 1) {
+            problems.add("START 节点必须存在且唯一（当前 " + starts + " 个）");
+        }
+        if (ends != 1) {
+            problems.add("END 节点必须存在且唯一（当前 " + ends + " 个）");
+        }
+        // start 属性指向 START 节点
+        FlowDefModel.Node startNode = model.node(model.start);
+        if (startNode == null || !FlowDefModel.TYPE_START.equals(startNode.type)) {
+            problems.add("start 属性必须指向 START 节点");
+        }
+        // 边引用完整 + 度约束
+        Set<String> outCount = new HashSet<>();
+        for (FlowDefModel.Edge e : model.edges) {
+            if (model.node(e.from) == null) {
+                problems.add("边引用不存在的 from 节点：" + e.from);
+            }
+            if (model.node(e.to) == null) {
+                problems.add("边引用不存在的 to 节点：" + e.to);
+            }
+        }
+        for (FlowDefModel.Node n : model.nodes) {
+            int out = model.outEdges(n.id).size();
+            int in = model.inEdges(n.id).size();
+            if (FlowDefModel.TYPE_START.equals(n.type) || FlowDefModel.TYPE_APPROVAL.equals(n.type)
+                    || FlowDefModel.TYPE_PARALLEL_JOIN.equals(n.type)) {
+                if (out != 1) {
+                    problems.add(nodeLabel(n) + " 出边必须恰为 1 条（当前 " + out + "）");
+                }
+            }
+            if (FlowDefModel.TYPE_PARALLEL_SPLIT.equals(n.type) && out < 1) {
+                problems.add(nodeLabel(n) + " 出边至少 1 条");
+            }
+            if (FlowDefModel.TYPE_END.equals(n.type) && out > 0) {
+                problems.add(nodeLabel(n) + " 不允许有出边");
+            }
+            if (FlowDefModel.TYPE_PARALLEL_JOIN.equals(n.type) && in < 1) {
+                problems.add(nodeLabel(n) + " 入边至少 1 条");
+            }
+            if (FlowDefModel.TYPE_PARALLEL_JOIN.equals(n.type) && n.waitFor != null
+                    && !FlowDefModel.COUNTERSIGN_ALL.equals(n.waitFor)) {
+                problems.add(nodeLabel(n) + " waitFor 一期仅支持 ALL");
+            }
+        }
+        // 汇聚点必须有上游分发（分支进度行由 split 创建）
+        boolean hasSplit = model.nodes.stream().anyMatch(n -> FlowDefModel.TYPE_PARALLEL_SPLIT.equals(n.type));
+        boolean hasJoin = model.nodes.stream().anyMatch(n -> FlowDefModel.TYPE_PARALLEL_JOIN.equals(n.type));
+        if (hasJoin && !hasSplit) {
+            problems.add("存在 PARALLEL_JOIN 但无 PARALLEL_SPLIT");
+        }
+        // 可达性（无孤儿）+ 无环：从 start 出发 DFS，环检测用着色
+        if (startNode != null) {
+            Set<String> visited = new HashSet<>();
+            Set<String> inStack = new HashSet<>();
+            dfs(model, startNode.id, visited, inStack, problems);
+            for (FlowDefModel.Node n : model.nodes) {
+                if (!visited.contains(n.id)) {
+                    problems.add("孤儿节点（从 start 不可达）：" + n.id);
+                }
+            }
+        }
+        // 拒绝策略取值
+        if (model.settings.rejectPolicy != null
+                && !FlowDefModel.REJECT_END_REJECTED.equals(model.settings.rejectPolicy)) {
+            problems.add("rejectPolicy 一期仅支持 END_REJECTED");
+        }
+        if (!problems.isEmpty()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "发布校验失败：" + String.join("；", problems));
+        }
+    }
+
+    private static void validateApproval(FlowDefModel.Node n, Set<String> enabledDeptKeys, List<String> problems) {
+        FlowDefModel.Assignee a = n.assignee;
+        if (a == null || a.type == null) {
+            problems.add(nodeLabel(n) + " 缺少 assignee 配置");
+            return;
+        }
+        if (FlowDefModel.ASSIGNEE_DEPT_KEY.equals(a.type)) {
+            if (a.deptKey == null || a.deptKey.trim().isEmpty()) {
+                problems.add(nodeLabel(n) + " DEPT_KEY 办理人缺少 deptKey");
+            } else if (enabledDeptKeys != null && !enabledDeptKeys.contains(a.deptKey)) {
+                problems.add(nodeLabel(n) + " 的 DEPT_KEY=" + a.deptKey + " 无启用中的办理人映射");
+            }
+        } else if (FlowDefModel.ASSIGNEE_USERS.equals(a.type)) {
+            if (a.userIds == null || a.userIds.isEmpty()) {
+                problems.add(nodeLabel(n) + " USERS 办理人缺少 userIds");
+            }
+        } else {
+            problems.add(nodeLabel(n) + " 未知办理人类型：" + a.type + "（一期支持 DEPT_KEY/USERS）");
+        }
+        if (n.countersign != null && !FlowDefModel.COUNTERSIGN_ALL.equals(n.countersign)
+                && !FlowDefModel.COUNTERSIGN_ANY.equals(n.countersign)) {
+            problems.add(nodeLabel(n) + " countersign 取值非法：" + n.countersign);
+        }
+        if (n.deadlineHours != null && n.deadlineHours <= 0) {
+            problems.add(nodeLabel(n) + " deadlineHours 必须为正整数");
+        }
+    }
+
+    private static void dfs(FlowDefModel model, String current, Set<String> visited,
+                            Set<String> inStack, List<String> problems) {
+        visited.add(current);
+        inStack.add(current);
+        for (FlowDefModel.Edge e : model.outEdges(current)) {
+            if (inStack.contains(e.to)) {
+                problems.add("流程图存在环：" + current + " → " + e.to);
+                continue;
+            }
+            if (!visited.contains(e.to)) {
+                dfs(model, e.to, visited, inStack, problems);
+            }
+        }
+        inStack.remove(current);
+    }
+
+    private static String nodeLabel(FlowDefModel.Node n) {
+        return "节点[" + n.id + (n.name == null || n.name.isEmpty() ? "" : " " + n.name) + "]";
+    }
+}

src/main/java/com/yunhai/flowcenter/engine/FlowAdvanceService.java

@@ -0,0 +1,62 @@
+package com.yunhai.flowcenter.engine;
+
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.repository.FlwDefRepository;
+import com.yunhai.flowcenter.repository.FlwInstanceRepository;
+import com.yunhai.flowcenter.repository.FlwTaskRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * 节点放行推进（AFTER_COMMIT 监听器经代理调用本 bean，REQUIRES_NEW 生效——
+ * 事务已提交后的同步监听阶段没有活动事务，@Modifying 批量语句必须有新事务承载）：
+ * 该节点待办清零且办件在途才推进；并发冲突由 flw_instance.version 乐观锁暴露，监听器层负责重试。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FlowAdvanceService {
+
+    private final FlwInstanceRepository instanceRepository;
+    private final FlwDefRepository defRepository;
+    private final FlwTaskRepository taskRepository;
+    private final FlowEngine flowEngine;
+
+    /** @return 是否实际推进了 */
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public boolean tryAdvance(Long instanceId, String nodeId) {
+        FlwInstance instance = instanceRepository.findById(instanceId).orElse(null);
+        if (instance == null
+                || instance.getStatus() != FlwEnums.InstanceStatus.APPROVING.getCode()) {
+            return false;
+        }
+        // 已推进过的节点不再放行（currentNodes 由引擎在放行时移除，乐观锁保证互斥）
+        String current = instance.getCurrentNodes();
+        boolean active = current != null && java.util.Arrays.stream(current.split(","))
+                .anyMatch(nodeId::equals);
+        if (!active) {
+            return false;
+        }
+        long pending = taskRepository.findByInstanceIdAndStatus(instanceId,
+                FlwEnums.TaskStatus.PENDING.getCode()).stream()
+                .filter(t -> nodeId.equals(t.getNodeId()))
+                .count();
+        if (pending > 0) {
+            return false;
+        }
+        FlwDef def = defRepository.findById(instance.getDefId()).orElse(null);
+        if (def == null) {
+            log.error("[flow-center] 办件定义缺失，推进中止：instance={} defId={}",
+                    instanceId, instance.getDefId());
+            return false;
+        }
+        flowEngine.continueAdvance(instance, def, nodeId);
+        instanceRepository.save(instance);
+        return true;
+    }
+}

src/main/java/com/yunhai/flowcenter/engine/FlowDefModel.java

@@ -0,0 +1,138 @@
+package com.yunhai.flowcenter.engine;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+
+import java.util.List;
+
+/**
+ * 流程定义 JSON 模型（概览 §5.1 规范，一期 5 节点）。
+ * 序列化/反序列化统一走 {@link #parse(ObjectMapper, String)}，未知属性忽略（向前兼容）。
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class FlowDefModel {
+
+    /** 节点类型（一期 5 种，二期按需扩展 NOTIFY/CONDITION） */
+    public static final String TYPE_START = "START";
+    public static final String TYPE_END = "END";
+    public static final String TYPE_APPROVAL = "APPROVAL";
+    public static final String TYPE_PARALLEL_SPLIT = "PARALLEL_SPLIT";
+    public static final String TYPE_PARALLEL_JOIN = "PARALLEL_JOIN";
+
+    /** 会签模式 */
+    public static final String COUNTERSIGN_ALL = "ALL";
+    public static final String COUNTERSIGN_ANY = "ANY";
+
+    /** 拒绝策略（一期仅 END_REJECTED） */
+    public static final String REJECT_END_REJECTED = "END_REJECTED";
+
+    /** 办理人类型（概览 §六：一期 DEPT_KEY/USERS；SUBMITTER_DEPT/FORM_FIELD 二期） */
+    public static final String ASSIGNEE_DEPT_KEY = "DEPT_KEY";
+    public static final String ASSIGNEE_USERS = "USERS";
+
+    public String code;
+    public String name;
+    public String start;
+    public List<Node> nodes;
+    public List<Edge> edges;
+    public Settings settings;
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public static class Node {
+        public String id;
+        public String type;
+        public String name;
+        public Assignee assignee;
+        /** ALL（默认）|ANY */
+        public String countersign;
+        /** PARALLEL_JOIN 汇聚条件，一期仅 ALL */
+        public String waitFor;
+        /** 办理时限小时数（自然时间，任务 arrive_time + N 小时；可空） */
+        public Integer deadlineHours;
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public static class Assignee {
+        /** DEPT_KEY | USERS */
+        public String type;
+        public String deptKey;
+        public List<Integer> userIds;
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public static class Edge {
+        public String from;
+        public String to;
+        public String name;
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public static class Settings {
+        public String rejectPolicy = REJECT_END_REJECTED;
+        public Urge urge = new Urge();
+    }
+
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public static class Urge {
+        public Boolean enabled = true;
+        public Integer intervalHours = 24;
+        public Integer maxTimes = 3;
+    }
+
+    public static FlowDefModel parse(ObjectMapper objectMapper, String json) {
+        try {
+            FlowDefModel model = objectMapper.readValue(json, FlowDefModel.class);
+            if (model == null || model.nodes == null || model.edges == null) {
+                throw new BizException(ErrorCode.PARAM_ERROR, "流程定义 JSON 缺少 nodes/edges");
+            }
+            if (model.settings == null) {
+                model.settings = new Settings();
+            }
+            return model;
+        } catch (BizException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "流程定义 JSON 不合法：" + e.getMessage());
+        }
+    }
+
+    public Node node(String nodeId) {
+        for (Node n : nodes) {
+            if (n.id != null && n.id.equals(nodeId)) {
+                return n;
+            }
+        }
+        return null;
+    }
+
+    public Node nodeById(String nodeId) {
+        Node n = node(nodeId);
+        if (n == null) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "流程定义缺少节点：" + nodeId);
+        }
+        return n;
+    }
+
+    /** 出边集合（保持定义顺序） */
+    public List<Edge> outEdges(String nodeId) {
+        java.util.List<Edge> out = new java.util.ArrayList<>();
+        for (Edge e : edges) {
+            if (nodeId != null && nodeId.equals(e.from)) {
+                out.add(e);
+            }
+        }
+        return out;
+    }
+
+    public List<Edge> inEdges(String nodeId) {
+        java.util.List<Edge> in = new java.util.ArrayList<>();
+        for (Edge e : edges) {
+            if (nodeId != null && nodeId.equals(e.to)) {
+                in.add(e);
+            }
+        }
+        return in;
+    }
+}

src/main/java/com/yunhai/flowcenter/engine/FlowEngine.java

@@ -0,0 +1,252 @@
+package com.yunhai.flowcenter.engine;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.flowcenter.entity.FlwBranch;
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.entity.FlwTask;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.repository.FlwBranchRepository;
+import com.yunhai.flowcenter.repository.FlwTaskRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.util.ArrayDeque;
+import java.util.Deque;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * 流程引擎推进核心（概览 §5.2 激活规则）：由调用方事务驱动——
+ * 发起后 startAdvance 从 START 推进；任务全同意后 continueAdvance 推进下一节点。
+ * 只做状态迁移与事件发布（AFTER_COMMIT 解耦通知/回调），不感知任何业务方。
+ *
+ * <p>推进算法（递归激活，branchKey 携带分支上下文）：START→下节点；APPROVAL→建任务等待；
+ * PARALLEL_SPLIT→逐出边建分支行并递归；PARALLEL_JOIN→标记到达、全到达才放行；END→办件完成。
+ * 拒绝/撤回的终止清理在 FlowTaskService（终点语义与任务抢占耦合）。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FlowEngine {
+
+    private final ObjectMapper objectMapper;
+    private final FlwTaskRepository taskRepository;
+    private final FlwBranchRepository branchRepository;
+    private final AssigneeResolver assigneeResolver;
+    private final ApplicationEventPublisher eventPublisher;
+
+    /** 发起后首推：从 START 激活（instance 已建好、status=10） */
+    public void startAdvance(FlwInstance instance, FlwDef def) {
+        FlowDefModel model = parseModel(def);
+        setCurrentNodes(instance, null);
+        advance(instance, model, model.start, null);
+    }
+
+    /**
+     * 某节点全部同意后的放行推进：移出活跃节点集并激活唯一出边目标。
+     * 分支上下文由 {@link #branchKeyOf} 从图上回溯推导（分支内串行链的中间节点无任务级分支标记）。
+     */
+    public void continueAdvance(FlwInstance instance, FlwDef def, String fromNodeId) {
+        FlowDefModel model = parseModel(def);
+        FlowDefModel.Node node = model.nodeById(fromNodeId);
+        List<FlowDefModel.Edge> outs = model.outEdges(fromNodeId);
+        if (outs.isEmpty()) {
+            return;
+        }
+        removeCurrentNode(instance, fromNodeId);
+        String branchKey = branchKeyOf(model, fromNodeId);
+        String next = outs.get(0).to;
+        FlowDefModel.Node nextNode = model.nodeById(next);
+        if (FlowDefModel.TYPE_PARALLEL_JOIN.equals(nextNode.type)) {
+            // 会签合并守门：标记本分支到达、全部到达才放行（直通无分支键时 JOIN 直通放行）
+            advance(instance, model, next, branchKey);
+        } else {
+            activate(instance, model, nextNode, branchKey);
+        }
+    }
+
+    /**
+     * 回溯 fromNodeId 所在分支的 branchKey（= PARALLEL_SPLIT 出边目标节点 id）：
+     * 沿入边反向走到 split，split→N 边的 N 即分支键；遇 START/PARALLEL_JOIN 边界即停
+     * （join 之后属汇聚链，branchKey 已消耗，返回 null）。
+     */
+    private String branchKeyOf(FlowDefModel model, String fromNodeId) {
+        Set<String> visited = new HashSet<>();
+        Deque<String> queue = new ArrayDeque<>();
+        queue.add(fromNodeId);
+        visited.add(fromNodeId);
+        while (!queue.isEmpty()) {
+            String cur = queue.poll();
+            for (FlowDefModel.Edge e : model.inEdges(cur)) {
+                FlowDefModel.Node from = model.node(e.from);
+                if (from == null) {
+                    continue;
+                }
+                if (FlowDefModel.TYPE_PARALLEL_SPLIT.equals(from.type)) {
+                    return e.to;
+                }
+                if (FlowDefModel.TYPE_START.equals(from.type)
+                        || FlowDefModel.TYPE_PARALLEL_JOIN.equals(from.type)
+                        || !visited.add(e.from)) {
+                    continue;
+                }
+                queue.add(e.from);
+            }
+        }
+        return null;
+    }
+
+    /** 统一激活入口：含 JOIN 的到达标记与放行判断 */
+    private void advance(FlwInstance instance, FlowDefModel model, String nodeId, String branchKey) {
+        FlowDefModel.Node node = model.nodeById(nodeId);
+        if (FlowDefModel.TYPE_PARALLEL_JOIN.equals(node.type)) {
+            if (branchKey != null) {
+                FlwBranch branch = branchRepository.findByInstanceIdAndBranchKey(instance.getId(), branchKey)
+                        .orElse(null);
+                if (branch != null) {
+                    branch.setStatus(FlwEnums.BranchStatus.ARRIVED.getCode());
+                    branchRepository.save(branch);
+                }
+            }
+            long running = branchRepository.countByInstanceIdAndStatus(
+                    instance.getId(), FlwEnums.BranchStatus.RUNNING.getCode());
+            if (running > 0) {
+                log.debug("[flow-center] JOIN {} 等待分支汇聚：instance={} remaining={}",
+                        nodeId, instance.getId(), running);
+                return;
+            }
+            List<FlowDefModel.Edge> outs = model.outEdges(nodeId);
+            if (outs.isEmpty()) {
+                return;
+            }
+            activate(instance, model, model.nodeById(outs.get(0).to), null);
+            return;
+        }
+        activate(instance, model, node, branchKey);
+    }
+
+    /** 非 JOIN 节点激活 */
+    private void activate(FlwInstance instance, FlowDefModel model, FlowDefModel.Node node, String branchKey) {
+        switch (node.type) {
+            case FlowDefModel.TYPE_START: {
+                List<FlowDefModel.Edge> outs = model.outEdges(node.id);
+                if (!outs.isEmpty()) {
+                    advance(instance, model, outs.get(0).to, branchKey);
+                }
+                break;
+            }
+            case FlowDefModel.TYPE_APPROVAL:
+                createTasks(instance, model, node);
+                addCurrentNode(instance, node.id);
+                break;
+            case FlowDefModel.TYPE_PARALLEL_SPLIT: {
+                for (FlowDefModel.Edge edge : model.outEdges(node.id)) {
+                    FlwBranch branch = new FlwBranch();
+                    branch.setInstanceId(instance.getId());
+                    branch.setBranchKey(edge.to);
+                    branch.setStatus(FlwEnums.BranchStatus.RUNNING.getCode());
+                    branchRepository.save(branch);
+                    advance(instance, model, edge.to, edge.to);
+                }
+                break;
+            }
+            case FlowDefModel.TYPE_END:
+                complete(instance);
+                break;
+            default:
+                log.warn("[flow-center] 未知节点类型 {}（节点 {}），推进中止", node.type, node.id);
+        }
+    }
+
+    /** 建任务（ALL=每人一条；ANY=每人一条、任一人办理即放行）＋ 到达事件 */
+    private void createTasks(FlwInstance instance, FlowDefModel model, FlowDefModel.Node node) {
+        List<AssigneeRef> assignees = assigneeResolver.resolve(instance.getSchId(), node);
+        LocalDateTime now = LocalDateTime.now();
+        LocalDateTime deadline = node.deadlineHours == null ? null : now.plusHours(node.deadlineHours);
+        for (AssigneeRef ref : assignees) {
+            FlwTask task = new FlwTask();
+            task.setInstanceId(instance.getId());
+            task.setSchId(instance.getSchId());
+            task.setNodeId(node.id);
+            task.setNodeName(node.name);
+            task.setAssigneeId(ref.getUserId());
+            task.setAssigneeName(ref.getUserName());
+            task.setStatus(FlwEnums.TaskStatus.PENDING.getCode());
+            task.setArriveTime(now);
+            task.setDeadline(deadline);
+            task.setUrgeCount(0);
+            taskRepository.save(task);
+            Map<String, Object> data = new HashMap<>();
+            data.put("nodeId", node.id);
+            data.put("nodeName", node.name);
+            data.put("nodeSummary", nodeSummary(model));
+            data.put("totalTasks", assignees.size());
+            data.put("doneTasks", 0);
+            eventPublisher.publishEvent(FlowEvent.of(FlowEvent.Type.TASK_CREATED,
+                    instance.getId(), task.getId(), data));
+        }
+    }
+
+    /** END 激活：办件完成、残留任务/分支失效、完成事件 */
+    private void complete(FlwInstance instance) {
+        instance.setStatus(FlwEnums.InstanceStatus.COMPLETED.getCode());
+        instance.setFinishTime(LocalDateTime.now());
+        setCurrentNodes(instance, null);
+        taskRepository.invalidatePendingByInstance(instance.getId());
+        branchRepository.invalidateRunningByInstance(instance.getId());
+        Map<String, Object> data = new HashMap<>();
+        data.put("result", "APPROVED");
+        eventPublisher.publishEvent(FlowEvent.of(FlowEvent.Type.COMPLETED, instance.getId(), null, data));
+    }
+
+    public FlowDefModel parseModel(FlwDef def) {
+        return FlowDefModel.parse(objectMapper, def.getContentJson());
+    }
+
+    /** 节点链摘要（APPROVAL 节点名串联，oapi list/detail 与回调 payload 共用） */
+    public static String nodeSummary(FlowDefModel model) {
+        StringBuilder sb = new StringBuilder();
+        for (FlowDefModel.Node n : model.nodes) {
+            if (FlowDefModel.TYPE_APPROVAL.equals(n.type)) {
+                if (sb.length() > 0) {
+                    sb.append("→");
+                }
+                sb.append(n.name == null || n.name.isEmpty() ? n.id : n.name);
+            }
+        }
+        return sb.toString();
+    }
+
+    private void addCurrentNode(FlwInstance instance, String nodeId) {
+        String cur = instance.getCurrentNodes();
+        instance.setCurrentNodes(cur == null || cur.isEmpty() ? nodeId : cur + "," + nodeId);
+    }
+
+    private void removeCurrentNode(FlwInstance instance, String nodeId) {
+        String cur = instance.getCurrentNodes();
+        if (cur == null || cur.isEmpty()) {
+            return;
+        }
+        StringBuilder sb = new StringBuilder();
+        for (String part : cur.split(",")) {
+            if (!part.equals(nodeId) && !part.isEmpty()) {
+                if (sb.length() > 0) {
+                    sb.append(",");
+                }
+                sb.append(part);
+            }
+        }
+        instance.setCurrentNodes(sb.toString());
+    }
+
+    private void setCurrentNodes(FlwInstance instance, String value) {
+        instance.setCurrentNodes(value == null ? "" : value);
+    }
+}

src/main/java/com/yunhai/flowcenter/engine/FlowEvent.java

@@ -0,0 +1,68 @@
+package com.yunhai.flowcenter.engine;
+
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * 引擎关键状态变迁事件（概览 §5.2 v1.1 增补）：事务内发布，AFTER_COMMIT 后由
+ * CallbackDispatcher（回调给业务方）与 UserMsgNotifier（通知人）消费——引擎本身不知道
+ * 也不依赖任何业务方的存在。携带 instanceId 而非实体快照：监听方在提交后按需重读（含最新 version）。
+ */
+@Getter
+@RequiredArgsConstructor
+public class FlowEvent {
+
+    public enum Type {
+        /** 代发起/重提成功（instance=10） */
+        SUBMITTED("flow.submitted"),
+        /** 任一审批任务创建（并行会签每个任务各发一条，data 带 n/m 汇总） */
+        TASK_CREATED("flow.task.created"),
+        /** 任一任务被办理（同意/拒绝各发一条，进度同步用） */
+        TASK_HANDLED("flow.task.handled"),
+        /** END 激活，instance=20 */
+        COMPLETED("flow.completed"),
+        /** END_REJECTED，instance=30 */
+        REJECTED("flow.rejected"),
+        /** 提交人撤回，instance=40 */
+        WITHDRAWN("flow.withdrawn"),
+        /** 催办（仅 UserMsg 通道，非回调事件枚举） */
+        URGE("flow.urge");
+
+        private final String code;
+
+        Type(String code) {
+            this.code = code;
+        }
+
+        public String getCode() {
+            return code;
+        }
+
+        public static Type ofCode(String code) {
+            for (Type t : values()) {
+                if (t.code.equals(code)) {
+                    return t;
+                }
+            }
+            return null;
+        }
+    }
+
+    private final Type type;
+    private final Long instanceId;
+    /** 任务事件带 taskId（SUBMITTED 等办件级事件为 null） */
+    private final Long taskId;
+    /** 事件明细（result/opinion/rejectNode/task.created 的 n/m 等），可为空 */
+    private final Map<String, Object> data;
+
+    public static FlowEvent of(Type type, Long instanceId) {
+        return new FlowEvent(type, instanceId, null, new HashMap<>());
+    }
+
+    public static FlowEvent of(Type type, Long instanceId, Long taskId, Map<String, Object> data) {
+        return new FlowEvent(type, instanceId, taskId, data == null ? new HashMap<>() : data);
+    }
+}

src/main/java/com/yunhai/flowcenter/engine/FlowNodeAdvanceListener.java

@@ -0,0 +1,45 @@
+package com.yunhai.flowcenter.engine;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.orm.ObjectOptimisticLockingFailureException;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.event.TransactionPhase;
+import org.springframework.transaction.event.TransactionalEventListener;
+
+/**
+ * 节点放行推进监听器：TASK_HANDLED 事件 AFTER_COMMIT 后在新事务里重查——
+ * 该节点待办是否清零、办件是否仍在途，全部成立才继续推进（下一节点/JOIN 合并/END）。
+ * 会签并发办理时各方提交的快照互相看不到对方未提交的办理行，事务内判断
+ * "节点是否全部办结"必假，提交后重查才是唯一可靠时机；推进串行化由办件乐观锁兜底
+ * （重试循环在监听器侧，跨 bean 调用 {@link FlowAdvanceService#tryAdvance} 保证 REQUIRES_NEW 生效）。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class FlowNodeAdvanceListener {
+
+    private final FlowAdvanceService advanceService;
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true)
+    public void onTaskHandled(FlowEvent event) {
+        if (event.getType() != FlowEvent.Type.TASK_HANDLED || event.getData() == null) {
+            return;
+        }
+        String nodeId = (String) event.getData().get("nodeId");
+        if (nodeId == null) {
+            return;
+        }
+        for (int attempt = 1; attempt <= 3; attempt++) {
+            try {
+                advanceService.tryAdvance(event.getInstanceId(), nodeId);
+                return;
+            } catch (ObjectOptimisticLockingFailureException e) {
+                log.warn("[flow-center] 推进冲突重试 {}/3：instance={} node={}",
+                        attempt, event.getInstanceId(), nodeId);
+            }
+        }
+        log.error("[flow-center] 推进重试耗尽（请人工检查）：instance={} node={}",
+                event.getInstanceId(), nodeId);
+    }
+}

src/main/java/com/yunhai/flowcenter/entity/BaseEntity.java

@@ -0,0 +1,44 @@
+package com.yunhai.flowcenter.entity;
+
+import com.yunhai.flowcenter.common.FlowCenterAuditListener;
+import lombok.Getter;
+import lombok.Setter;
+
+import javax.persistence.Column;
+import javax.persistence.EntityListeners;
+import javax.persistence.GeneratedValue;
+import javax.persistence.GenerationType;
+import javax.persistence.Id;
+import javax.persistence.MappedSuperclass;
+import java.io.Serializable;
+import java.time.LocalDateTime;
+
+/**
+ * 所有实体的公共基类：自增主键 + 审计四件套（FlowCenterAuditListener 自动填充，CmsAuditListener 同款）。
+ * 主键用 Long：flw_instance.id 即对外办件标识（svc-hall 侧 flow_instance_id 为 BIGINT，对齐）。
+ * 多租户键 sch_id 不在基类——各业务实体自带列（Notice 先例，语义不同不混入）。
+ */
+@MappedSuperclass
+@Getter
+@Setter
+@EntityListeners(FlowCenterAuditListener.class)
+public abstract class BaseEntity implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "create_by", updatable = false)
+    private String createBy;
+
+    @Column(name = "create_time", updatable = false)
+    private LocalDateTime createTime;
+
+    @Column(name = "update_by")
+    private String updateBy;
+
+    @Column(name = "update_time")
+    private LocalDateTime updateTime;
+}

src/main/java/com/yunhai/flowcenter/entity/FlwAssigneeMap.java

@@ -0,0 +1,48 @@
+package com.yunhai.flowcenter.entity;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+
+/**
+ * 办理人映射（概览 §4.7，一期显式维护）：dept_key 即流程 JSON 里 DEPT_KEY 引用的科室编码；
+ * user_name 为快照供任务列表免跨服务查名。外部托管模式复用同一张映射表——办理人解析与发起入口无关。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_assignee_map",
+        uniqueConstraints = @UniqueConstraint(name = "uk_flw_map_sch_dept_user",
+                columnNames = {"sch_id", "dept_key", "user_id"}),
+        indexes = @Index(name = "idx_flw_map_sch_dept", columnList = "sch_id, dept_key, status"))
+public class FlwAssigneeMap extends BaseEntity {
+
+    /** 租户键 */
+    @Column(name = "sch_id", nullable = false)
+    private Long schId;
+
+    /** 科室编码（流程 JSON DEPT_KEY 引用，如 ybb=医保办） */
+    @Column(name = "dept_key", nullable = false, length = 64)
+    private String deptKey;
+
+    /** 科室名快照 */
+    @Column(name = "dept_name", length = 128)
+    private String deptName;
+
+    /** 办理人 id */
+    @Column(name = "user_id", nullable = false)
+    private Integer userId;
+
+    /** 办理人姓名快照（管理端成员检索时从 UserBase 补全） */
+    @Column(name = "user_name", length = 128)
+    private String userName;
+
+    /** 0 启用 */
+    @Column(name = "status", nullable = false)
+    private Integer status = 0;
+}

src/main/java/com/yunhai/flowcenter/entity/FlwAttachment.java

@@ -0,0 +1,50 @@
+package com.yunhai.flowcenter.entity;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+
+/**
+ * 申请材料（概览 §4.6）：外部托管模式材料留在业务方（biz_snapshot 引用文件名清单），
+ * 本表仅服务显式上传场景（M1 不开发上传端点，表结构先行）。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_attachment",
+        indexes = @Index(name = "idx_flw_att_inst", columnList = "instance_id, sch_id"))
+public class FlwAttachment extends BaseEntity {
+
+    /** 归属办件 */
+    @Column(name = "instance_id", nullable = false)
+    private Long instanceId;
+
+    /** 租户键 */
+    @Column(name = "sch_id", nullable = false)
+    private Long schId;
+
+    /** 表单字段键（无表单模式为 null） */
+    @Column(name = "field_key", length = 64)
+    private String fieldKey;
+
+    @Column(name = "file_name", length = 255)
+    private String fileName;
+
+    /** 磁盘相对路径（{FILE_PATH} 下） */
+    @Column(name = "file_path", length = 500)
+    private String filePath;
+
+    /** 对外可访问 URL */
+    @Column(name = "web_url", length = 500)
+    private String webUrl;
+
+    @Column(name = "file_size")
+    private Long fileSize;
+
+    @Column(name = "mime_type", length = 128)
+    private String mimeType;
+}

src/main/java/com/yunhai/flowcenter/entity/FlwBranch.java

@@ -0,0 +1,35 @@
+package com.yunhai.flowcenter.entity;
+
+import com.yunhai.flowcenter.enums.FlwEnums;
+import lombok.Getter;
+import lombok.Setter;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+
+/**
+ * 并行分支进度（概览 §4.5）：PARALLEL_SPLIT 为每条出边建一行，到达 PARALLEL_JOIN 时
+ * 标记已到达，全部到达才放行（waitFor=ALL）；branch_key=出边目标节点 id。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_branch",
+        uniqueConstraints = @UniqueConstraint(name = "uk_flw_branch_inst_key",
+                columnNames = {"instance_id", "branch_key"}))
+public class FlwBranch extends BaseEntity {
+
+    /** 归属办件 */
+    @Column(name = "instance_id", nullable = false)
+    private Long instanceId;
+
+    /** 分支键（split 出边目标节点 id） */
+    @Column(name = "branch_key", nullable = false, length = 64)
+    private String branchKey;
+
+    /** 0 进行中 / 1 已到达汇聚点 / 2 已失效 */
+    @Column(name = "status", nullable = false)
+    private Integer status = FlwEnums.BranchStatus.RUNNING.getCode();
+}

src/main/java/com/yunhai/flowcenter/entity/FlwCallbackLog.java

@@ -0,0 +1,82 @@
+package com.yunhai.flowcenter.entity;
+
+import com.yunhai.flowcenter.enums.FlwEnums;
+import lombok.Getter;
+import lombok.Setter;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+import java.time.LocalDateTime;
+
+/**
+ * 回调推送日志 = 重试队列（概览 §4.9）：eventId 唯一（重试不变，业务方按它幂等去重）；
+ * payload_json 完整快照可重放；索引 (status, next_retry_time) 是扫描主路径。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_callback_log",
+        uniqueConstraints = @UniqueConstraint(name = "uk_flw_log_event", columnNames = "event_id"),
+        indexes = {
+                @Index(name = "idx_flw_log_scan", columnList = "status, next_retry_time"),
+                @Index(name = "idx_flw_log_inst", columnList = "instance_id")})
+public class FlwCallbackLog extends BaseEntity {
+
+    /** 租户键 */
+    @Column(name = "sch_id", nullable = false)
+    private Long schId;
+
+    /** 归属注册 */
+    @Column(name = "reg_id", nullable = false)
+    private Long regId;
+
+    /** 事件唯一键（UUID 去横线 32 位），重试不变 */
+    @Column(name = "event_id", nullable = false, length = 32)
+    private String eventId;
+
+    /** 事件类型（flow.submitted/task.created/task.handled/completed/rejected/withdrawn） */
+    @Column(name = "event", nullable = false, length = 32)
+    private String event;
+
+    /** 办件 */
+    @Column(name = "instance_id", nullable = false)
+    private Long instanceId;
+
+    /** 业务键冗余（业务方消费主键） */
+    @Column(name = "biz_type", length = 32)
+    private String bizType;
+
+    @Column(name = "biz_id", length = 64)
+    private String bizId;
+
+    /** 完整推送体快照（含签名原文，可重放） */
+    @Column(name = "payload_json", nullable = false, columnDefinition = "LONGTEXT")
+    private String payloadJson;
+
+    /** 0 待推/重试中 / 1 成功 / 2 死信 */
+    @Column(name = "status", nullable = false)
+    private Integer status = FlwEnums.CallbackLogStatus.PENDING.getCode();
+
+    /** 已重试次数 */
+    @Column(name = "retry_count", nullable = false)
+    private Integer retryCount = 0;
+
+    /** 下次推送时间 */
+    @Column(name = "next_retry_time")
+    private LocalDateTime nextRetryTime;
+
+    /** 末次 HTTP 状态（管理端排障用） */
+    @Column(name = "last_http_status", length = 32)
+    private String lastHttpStatus;
+
+    /** 末次错误 */
+    @Column(name = "last_error", length = 1000)
+    private String lastError;
+
+    /** 成功时间 */
+    @Column(name = "push_time")
+    private LocalDateTime pushTime;
+}

src/main/java/com/yunhai/flowcenter/entity/FlwCallbackReg.java

@@ -0,0 +1,52 @@
+package com.yunhai.flowcenter.entity;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+
+/**
+ * 回调注册（概览 §4.8）：同一应用同一流程一条注册；secret 注册时生成本地下发，
+ * 与应用级 appSecret 分离、粒度到流程（泄露可单独重置）。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_callback_reg",
+        uniqueConstraints = @UniqueConstraint(name = "uk_flw_reg_sch_app_flow",
+                columnNames = {"sch_id", "app_key", "flow_guid"}),
+        indexes = @Index(name = "idx_flw_reg_flow", columnList = "sch_id, flow_guid, status"))
+public class FlwCallbackReg extends BaseEntity {
+
+    /** 租户键 */
+    @Column(name = "sch_id", nullable = false)
+    private Long schId;
+
+    /** 业务方应用标识（调用方 appKey，来自验签上下文） */
+    @Column(name = "app_key", nullable = false, length = 64)
+    private String appKey;
+
+    /** 订阅的流程 */
+    @Column(name = "flow_guid", nullable = false, length = 32)
+    private String flowGuid;
+
+    /** 业务方接收端点 */
+    @Column(name = "callback_url", nullable = false, length = 500)
+    private String callbackUrl;
+
+    /** 订阅事件逗号分隔（概览 §8.3 枚举），空=全部 */
+    @Column(name = "event_types", length = 200)
+    private String eventTypes;
+
+    /** 回调签名密钥（HmacSHA256，注册时生成下发） */
+    @Column(name = "secret", nullable = false, length = 64)
+    private String secret;
+
+    /** 0 启用 / 1 停用 */
+    @Column(name = "status", nullable = false)
+    private Integer status = 0;
+}

src/main/java/com/yunhai/flowcenter/entity/FlwDef.java

@@ -0,0 +1,67 @@
+package com.yunhai.flowcenter.entity;
+
+import com.yunhai.flowcenter.enums.FlwEnums;
+import lombok.Getter;
+import lombok.Setter;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+import java.time.LocalDateTime;
+
+/**
+ * 流程定义（概览 §4.1 + V2.0 Part D #2/#3 修订）。
+ * flow_guid 绑定"这条流程线"而非某个版本：升版后业务方绑定关系零改动，新发起自动走
+ * 当前已发布最高版本；item_code/form_id 留可空列（M1 不启用，原生模式/表单二期）。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_def",
+        uniqueConstraints = @UniqueConstraint(name = "uk_flw_def_sch_code_ver",
+                columnNames = {"sch_id", "code", "version"}),
+        indexes = @Index(name = "idx_flw_def_guid", columnList = "sch_id, flow_guid, status, version"))
+public class FlwDef extends BaseEntity {
+
+    /** 租户键 */
+    @Column(name = "sch_id", nullable = false)
+    private Long schId;
+
+    /** 对外稳定流程标识：创建草稿时生成（UUID 去横线小写），同一 code 跨版本不变 */
+    @Column(name = "flow_guid", nullable = false, length = 32)
+    private String flowGuid;
+
+    /** 流程编码（本应用内部管理键） */
+    @Column(name = "code", nullable = false, length = 64)
+    private String code;
+
+    /** 流程名 */
+    @Column(name = "name", nullable = false, length = 128)
+    private String name;
+
+    /** 版本，发布后不可改，改定义=升版本 */
+    @Column(name = "version", nullable = false)
+    private Integer version;
+
+    /** 关联 CMS 事项业务键（原生模式用，M1 不启用；与外部模式的 biz_* 互斥） */
+    @Column(name = "item_code", length = 64)
+    private String itemCode;
+
+    /** 关联表单定义（外部托管模式可无表单，M1 恒 null；二期通用表单预留） */
+    @Column(name = "form_id")
+    private Long formId;
+
+    /** §5.1 流程定义 JSON */
+    @Column(name = "content_json", nullable = false, columnDefinition = "LONGTEXT")
+    private String contentJson;
+
+    /** 0 草稿 / 1 已发布 / 2 停用（停用=不可新发起，存量跑完） */
+    @Column(name = "status", nullable = false)
+    private Integer status = FlwEnums.DefStatus.DRAFT.getCode();
+
+    /** 发布时间 */
+    @Column(name = "publish_time")
+    private LocalDateTime publishTime;
+}

src/main/java/com/yunhai/flowcenter/entity/FlwInstance.java

@@ -0,0 +1,111 @@
+package com.yunhai.flowcenter.entity;
+
+import com.yunhai.flowcenter.enums.FlwEnums;
+import lombok.Getter;
+import lombok.Setter;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import javax.persistence.UniqueConstraint;
+import javax.persistence.Version;
+import java.time.LocalDateTime;
+
+/**
+ * 办件实例（概览 §4.3 + V2.0 Part D）：托管模式下业务对象留在业务方，本表只存
+ * biz_title/biz_url/biz_snapshot 快照与关联键；uk(sch_id, biz_type, biz_id) 幂等——
+ * 同一业务对象一条办件，重复代发起返回原办件；驳回/撤回后重提复用同一行（R4 重启语义）。
+ *
+ * <p>version 是乐观锁（推进串行化）兼回调 payload 的 instanceVersion（业务方按它丢弃乱序旧事件），
+ * 由 JPA @Version 在 flush 时自增。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_instance",
+        uniqueConstraints = @UniqueConstraint(name = "uk_flw_instance_biz",
+                columnNames = {"sch_id", "biz_type", "biz_id"}),
+        indexes = {
+                @Index(name = "idx_flw_inst_submitter", columnList = "sch_id, submitter_id, status"),
+                @Index(name = "idx_flw_inst_status_time", columnList = "sch_id, status, submit_time")})
+public class FlwInstance extends BaseEntity {
+
+    /** 租户键 */
+    @Column(name = "sch_id", nullable = false)
+    private Long schId;
+
+    /** 定义快照（发布版本 id；重提重启时刷新为当前已发布版本） */
+    @Column(name = "def_id", nullable = false)
+    private Long defId;
+
+    /** 定义编码快照 */
+    @Column(name = "def_code", nullable = false, length = 64)
+    private String defCode;
+
+    /** 定义版本快照 */
+    @Column(name = "def_version", nullable = false)
+    private Integer defVersion;
+
+    /** 表单提交快照（无表单托管模式为 NULL，透传存业务方 formData） */
+    @Column(name = "form_data_json", columnDefinition = "LONGTEXT")
+    private String formDataJson;
+
+    /** CMS 事项快照（原生模式，M1 不启用恒 null） */
+    @Column(name = "item_code", length = 64)
+    private String itemCode;
+
+    @Column(name = "item_title", length = 200)
+    private String itemTitle;
+
+    /** 业务类型键（外部托管模式，如 svc_item） */
+    @Column(name = "biz_type", length = 32)
+    private String bizType;
+
+    /** 业务主键（如 svc-hall applyId） */
+    @Column(name = "biz_id", length = 64)
+    private String bizId;
+
+    /** 办件标题快照：待办列表/消息/回调 payload 统一携带 */
+    @Column(name = "biz_title", length = 200)
+    private String bizTitle;
+
+    /** 业务方详情页链接：办理页"查看业务详情"跳转入口 */
+    @Column(name = "biz_url", length = 500)
+    private String bizUrl;
+
+    /** 业务摘要 JSON 快照：办理页展示用（只收摘要，不收富文本正文，概览 §十边界） */
+    @Column(name = "biz_snapshot", columnDefinition = "LONGTEXT")
+    private String bizSnapshot;
+
+    /** 提交人 id（外部模式=业务方当前登录人快照，本校校验在入口做） */
+    @Column(name = "submitter_id", nullable = false)
+    private Integer submitterId;
+
+    /** 提交人姓名快照 */
+    @Column(name = "submitter_name", nullable = false, length = 128)
+    private String submitterName;
+
+    /** 10 审批中 / 20 已完成 / 30 已拒绝 / 40 已撤回 */
+    @Column(name = "status", nullable = false)
+    private Integer status = FlwEnums.InstanceStatus.APPROVING.getCode();
+
+    /** 当前活跃节点 id 集合（冗余逗号分隔，列表页免展开） */
+    @Column(name = "current_nodes", length = 200)
+    private String currentNodes;
+
+    @Column(name = "submit_time")
+    private LocalDateTime submitTime;
+
+    @Column(name = "finish_time")
+    private LocalDateTime finishTime;
+
+    /**
+     * 乐观锁版本：推进串行化 + 回调 instanceVersion 单调递增。
+     * 注意不可初始化（=0 会让 Spring Data 判定非新实体走 merge，id 不回填）；
+     * insert 时由 Hibernate 写入 0。
+     */
+    @Version
+    @Column(name = "version", nullable = false)
+    private Integer version;
+}

src/main/java/com/yunhai/flowcenter/entity/FlwTask.java

@@ -0,0 +1,71 @@
+package com.yunhai.flowcenter.entity;
+
+import com.yunhai.flowcenter.enums.FlwEnums;
+import lombok.Getter;
+import lombok.Setter;
+
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Index;
+import javax.persistence.Table;
+import java.time.LocalDateTime;
+
+/**
+ * 审批任务（概览 §4.4）：会签 ALL 模式下每办理人一条，全部同意才放行；
+ * 办理抢占靠 UPDATE ... WHERE status=0 的原子语义（服务层用乐观锁 version 兜底并发推进）。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_task",
+        indexes = {
+                @Index(name = "idx_flw_task_inst_status", columnList = "instance_id, status"),
+                @Index(name = "idx_flw_task_assignee", columnList = "assignee_id, status, arrive_time")})
+public class FlwTask extends BaseEntity {
+
+    /** 归属办件 */
+    @Column(name = "instance_id", nullable = false)
+    private Long instanceId;
+
+    /** 租户键（冗余，待办列表主路径免 join） */
+    @Column(name = "sch_id", nullable = false)
+    private Long schId;
+
+    /** 定义节点 id（JSON 里的 node.id） */
+    @Column(name = "node_id", nullable = false, length = 64)
+    private String nodeId;
+
+    /** 节点名快照 */
+    @Column(name = "node_name", length = 128)
+    private String nodeName;
+
+    /** 办理人 id（DEPT_KEY 映射/USERS 直配解析结果） */
+    @Column(name = "assignee_id", nullable = false)
+    private Integer assigneeId;
+
+    /** 办理人姓名快照（免跨服务查名） */
+    @Column(name = "assignee_name", length = 128)
+    private String assigneeName;
+
+    /** 0 待办 / 1 同意 / 2 拒绝 / 3 失效 */
+    @Column(name = "status", nullable = false)
+    private Integer status = FlwEnums.TaskStatus.PENDING.getCode();
+
+    /** 办理意见（reject 必填，纯文本不收 HTML） */
+    @Column(name = "opinion", length = 500)
+    private String opinion;
+
+    @Column(name = "arrive_time", nullable = false)
+    private LocalDateTime arriveTime;
+
+    @Column(name = "handle_time")
+    private LocalDateTime handleTime;
+
+    /** 办理时限（一期自然时间，定义方自行折算工作日——拍板项#4） */
+    @Column(name = "deadline")
+    private LocalDateTime deadline;
+
+    /** 已催办次数 */
+    @Column(name = "urge_count", nullable = false)
+    private Integer urgeCount = 0;
+}

src/main/java/com/yunhai/flowcenter/enums/FlwEnums.java

@@ -0,0 +1,85 @@
+package com.yunhai.flowcenter.enums;
+
+/**
+ * 流程中心状态枚举（概览 §4.3/§4.4/§4.5/§4.1/§4.9 口径，一期冻结）。
+ */
+public final class FlwEnums {
+
+    private FlwEnums() {
+    }
+
+    /** 办件状态：10 审批中 / 20 已完成 / 30 已拒绝 / 40 已撤回 */
+    public enum InstanceStatus {
+        APPROVING(10), COMPLETED(20), REJECTED(30), WITHDRAWN(40);
+
+        private final int code;
+
+        InstanceStatus(int code) {
+            this.code = code;
+        }
+
+        public int getCode() {
+            return code;
+        }
+    }
+
+    /** 任务状态：0 待办 / 1 同意 / 2 拒绝 / 3 失效（拒绝/撤回/重启重提时的清理目标） */
+    public enum TaskStatus {
+        PENDING(0), APPROVED(1), REJECTED(2), INVALIDATED(3);
+
+        private final int code;
+
+        TaskStatus(int code) {
+            this.code = code;
+        }
+
+        public int getCode() {
+            return code;
+        }
+    }
+
+    /** 并行分支状态：0 进行中 / 1 已到达汇聚点 / 2 已失效 */
+    public enum BranchStatus {
+        RUNNING(0), ARRIVED(1), INVALIDATED(2);
+
+        private final int code;
+
+        BranchStatus(int code) {
+            this.code = code;
+        }
+
+        public int getCode() {
+            return code;
+        }
+    }
+
+    /** 流程定义状态：0 草稿 / 1 已发布 / 2 停用（停用=不可新发起，存量跑完） */
+    public enum DefStatus {
+        DRAFT(0), PUBLISHED(1), DISABLED(2);
+
+        private final int code;
+
+        DefStatus(int code) {
+            this.code = code;
+        }
+
+        public int getCode() {
+            return code;
+        }
+    }
+
+    /** 回调推送日志状态：0 待推/重试中 / 1 成功 / 2 死信 */
+    public enum CallbackLogStatus {
+        PENDING(0), SUCCESS(1), DEAD(2);
+
+        private final int code;
+
+        CallbackLogStatus(int code) {
+            this.code = code;
+        }
+
+        public int getCode() {
+            return code;
+        }
+    }
+}

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

@@ -0,0 +1,115 @@
+package com.yunhai.flowcenter.model;
+
+import lombok.Data;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 用户面/管理面 VO（/api/flow/**）。
+ */
+public final class FlowModels {
+
+    private FlowModels() {
+    }
+
+    /** 我的办件列表行 */
+    @Data
+    public static class InstanceItem {
+        private Long instanceId;
+        private String bizType;
+        private String bizId;
+        private String bizTitle;
+        private Integer status;
+        private String currentNodes;
+        private String submitterName;
+        private String submitTime;
+        private String finishTime;
+        private String defName;
+        private Integer defVersion;
+    }
+
+    /** 待办/已办列表行 */
+    @Data
+    public static class TaskItem {
+        private Long taskId;
+        private Long instanceId;
+        private String bizTitle;
+        private String bizType;
+        private String bizId;
+        private Integer instanceStatus;
+        private String nodeId;
+        private String nodeName;
+        private String assigneeName;
+        private Integer status;
+        private String opinion;
+        private String arriveTime;
+        private String handleTime;
+        private String deadline;
+        private Integer urgeCount;
+    }
+
+    /** 办件详情（办理页/详情页数据源） */
+    @Data
+    public static class InstanceDetail {
+        private Long instanceId;
+        private Long schId;
+        private String defCode;
+        private Integer defVersion;
+        private String bizType;
+        private String bizId;
+        private String bizTitle;
+        private String bizUrl;
+        /** 业务摘要 JSON（办理页区块渲染；无富文本正文——概览 §十边界） */
+        private String bizSnapshot;
+        private String formDataJson;
+        private Integer status;
+        private String currentNodes;
+        private Integer submitterId;
+        private String submitterName;
+        private String submitTime;
+        private String finishTime;
+        private Integer version;
+        private String nodeSummary;
+        private List<Map<String, Object>> trace;
+        private List<Map<String, Object>> branches;
+        /** 当前用户可否办理（存在本人的待办任务） */
+        private boolean myPendingTask;
+        private List<Long> myPendingTaskIds;
+    }
+
+    /** 流程示意图出参（用户面 /diagram 与管理面 /admin/def/diagram 共用，方案 §3.1） */
+    @Data
+    public static class DiagramVo {
+        private String flowGuid;
+        private Long defId;
+        private Long instanceId;
+        private String name;
+        private Integer version;
+        private Integer status;
+        /** 实际出图口径：dept｜user｜auto（后端归一化后回显） */
+        private String mode;
+        private List<NodeVo> nodes;
+        private List<EdgeVo> edges;
+    }
+
+    /** 示意图节点（label/subLabel 已按视图解析好，前端只画不解析） */
+    @Data
+    public static class NodeVo {
+        private String id;
+        private String type;
+        private String label;
+        private String subLabel;
+        private String deptKey;
+        private String assigneeType;
+        private String countersign;
+        private Integer deadlineHours;
+    }
+
+    /** 示意图连边 */
+    @Data
+    public static class EdgeVo {
+        private String from;
+        private String to;
+    }
+}

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

@@ -0,0 +1,84 @@
+package com.yunhai.flowcenter.model;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import lombok.Data;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * /oapi/flow/** 契约模型（出入参字段与 svc-hall FlowCenterClient 逐字对齐，
+ * 契约锚点：《流程中心M1开工说明.md》§5——两侧已编码，改动须双向同步）。
+ */
+public final class OapiModels {
+
+    private OapiModels() {
+    }
+
+    /** 流程摘要（list 元素 / {flowGuid} 详情） */
+    @Data
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public static class FlowSummaryVo {
+        private String flowGuid;
+        private String name;
+        private Integer version;
+        private String nodeSummary;
+    }
+
+    /** 代发起请求体（POST /oapi/flow/apply；formData 为 JSON 对象透传） */
+    @Data
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public static class ApplyBody {
+        private String flowGuid;
+        private String bizType;
+        private String bizId;
+        private String bizTitle;
+        private String bizUrl;
+        /** 业务摘要 JSON 快照（字符串或对象均可，统一落字符串） */
+        private Object bizSnapshot;
+        private Integer submitterId;
+        private String submitterName;
+        /** 表单数据对象（业务方编辑页产出，无表单模式不传） */
+        private Map<String, Object> formData;
+    }
+
+    /** 代发起响应（biz uk 幂等：重复代发起 HTTP 200 + duplicated:true 返回既有办件） */
+    @Data
+    public static class ApplyResultVo {
+        private Long instanceId;
+        private boolean duplicated;
+    }
+
+    /** 按业务键查办件响应（对账兜底；traceJson 含 assigneeId 轨迹供办理人放行判定） */
+    @Data
+    public static class InstanceVo {
+        private Long instanceId;
+        private Integer status;
+        private Integer version;
+        private String nodeSummary;
+        private String traceJson;
+        private List<Integer> assigneeIds;
+        private String currentNodes;
+        private String bizTitle;
+        private Integer submitterId;
+        private String submitterName;
+        private String submitTime;
+        private String finishTime;
+    }
+
+    /** 回调注册请求体（POST /oapi/flow/callback/reg） */
+    @Data
+    @JsonIgnoreProperties(ignoreUnknown = true)
+    public static class CallbackRegBody {
+        private String flowGuid;
+        private String callbackUrl;
+        /** 订阅事件逗号分隔，空=全部 */
+        private String eventTypes;
+    }
+
+    /** 回调注册响应（secret 注册时生成下发） */
+    @Data
+    public static class CallbackRegResultVo {
+        private String secret;
+    }
+}

src/main/java/com/yunhai/flowcenter/notify/UserMsgClient.java

@@ -0,0 +1,115 @@
+package com.yunhai.flowcenter.notify;
+
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.http.IDHttp;
+import lombok.Data;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+
+/**
+ * UserMsg 站内信客户端（概览 §七 契约，M1 手工三件套路线的<b>直达版</b>）：
+ * 经共享 IDHttp（yh-openapi 装配的出站自动签名 RestTemplate，X-App-Key/X-Timestamp/X-Signature
+ * = SignUtil.signRequest 请求级 canonical，与 svc-hall FlowCenterClient 同一套通道）直调
+ * UserMsg /oapi/msg/**。前提：UserMsg 侧 trusted-apps 白名单收本应用 appKey（本地占位 100019）；
+ * SDK（yh-usermsg-spring-boot-starter）落地后整体切换为 SDK 调用，契约不变。
+ * 发送方不阻断主业务：失败只记日志（对齐 PartyLearn 容错语义），由调用方在 AFTER_COMMIT 监听器里容错。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class UserMsgClient {
+
+    private final IDHttp http;
+
+    @Value("${flow-center.usermsg.enabled:false}")
+    private boolean enabled;
+
+    @Value("${flow-center.usermsg.base-url:http://localhost:8080}")
+    private String baseUrl;
+
+    public boolean enabled() {
+        return enabled;
+    }
+
+    /** 发送站内信（content 必填；msgNo 幂等，重发安全） */
+    public void sendUserMsg(Integer schId, List<Integer> userIds, Integer msgType, String bizType,
+                            String bizId, String title, String content, String jumpPath, String msgNo,
+                            Integer expireDays) {
+        if (!enabled || userIds == null || userIds.isEmpty()) {
+            return;
+        }
+        SendMsgRequest body = new SendMsgRequest();
+        body.setUserIds(userIds);
+        body.setMsgType(msgType);
+        body.setBizType(bizType);
+        body.setBizId(bizId);
+        body.setTitle(title);
+        body.setContent(content);
+        if (jumpPath != null) {
+            body.setJumpType(1);
+            body.setJumpPath(jumpPath);
+        }
+        body.setMsgNo(msgNo);
+        body.setSchId(schId);
+        body.setExpireDays(expireDays);
+        try {
+            http.post(trimTrailing(baseUrl) + "/oapi/msg/sendUserMsg", body, Object.class);
+        } catch (BizException e) {
+            log.warn("[flow-center] UserMsg 发送被拒：msgNo={} msg={}", msgNo, e.getMessage());
+        } catch (Exception e) {
+            log.warn("[flow-center] UserMsg 发送失败（不阻断主业务）：msgNo={} {}", msgNo, e.toString());
+        }
+    }
+
+    /** 待办角标增量（+1 到达 / -1 办结） */
+    public void todoInc(Integer schId, List<Integer> userIds, int count) {
+        if (!enabled || userIds == null || userIds.isEmpty()) {
+            return;
+        }
+        TodoCountRequest body = new TodoCountRequest();
+        body.setUserIds(userIds);
+        body.setCount(count);
+        body.setSchId(schId);
+        try {
+            http.post(trimTrailing(baseUrl) + "/oapi/msg/todo/inc", body, Object.class);
+        } catch (Exception e) {
+            log.warn("[flow-center] UserMsg 角标增量失败（不阻断主业务）：userIds={} count={} {}",
+                    userIds, count, e.toString());
+        }
+    }
+
+    private static String trimTrailing(String url) {
+        return url.endsWith("/") ? url.substring(0, url.length() - 1) : url;
+    }
+
+    /** /oapi/msg/sendUserMsg 请求体（UserMsg SendMsgRequest 同构，字段逐字对齐） */
+    @Data
+    public static class SendMsgRequest {
+        private List<Integer> userIds;
+        private String title;
+        /** 必填（UserMsg @NotBlank） */
+        private String content;
+        private String msgNo;
+        private String bizType;
+        private String bizId;
+        /** 0系统通知/1业务提醒/2审批待办 */
+        private Integer msgType;
+        /** 0无跳转/1应用内路径/2外链 */
+        private Integer jumpType;
+        private String jumpPath;
+        private Integer schId;
+        private Integer expireDays;
+    }
+
+    /** /oapi/msg/todo/inc 请求体（UserMsg TodoCountRequest 同构） */
+    @Data
+    public static class TodoCountRequest {
+        private List<Integer> userIds;
+        private Integer count;
+        private Integer schId;
+    }
+}

src/main/java/com/yunhai/flowcenter/notify/UserMsgNotifier.java

@@ -0,0 +1,142 @@
+package com.yunhai.flowcenter.notify;
+
+import com.yunhai.flowcenter.engine.FlowEvent;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.entity.FlwTask;
+import com.yunhai.flowcenter.repository.FlwInstanceRepository;
+import com.yunhai.flowcenter.repository.FlwTaskRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.event.TransactionPhase;
+import org.springframework.transaction.event.TransactionalEventListener;
+
+import java.util.Collections;
+
+/**
+ * 站内信/待办角标通知（概览 §七 契约，回调通知"业务系统"、本类通知"人"，两通道互不替代）：
+ * - 任务到达：msgType=2、bizType=flow.task、msgNo=task:{taskId}、jumpPath=/task/{taskId}、todo +1
+ * - 任务被办理：todo -1（办理人）
+ * - 完成/拒绝/撤回：msgType=1、bizType=flow.result、content 必填（结果+意见）、msgNo 带 version
+ *   （重提重启多轮终态互不幂等吞掉）
+ * - 催办：bizType=flow.urge、msgNo=urge:{taskId}:{第N次}
+ * 全部在 AFTER_COMMIT 监听器里发送，失败不阻断（UserMsgClient 内部容错）。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class UserMsgNotifier {
+
+    private final UserMsgClient userMsgClient;
+    private final FlwTaskRepository taskRepository;
+    private final FlwInstanceRepository instanceRepository;
+
+    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true)
+    public void onFlowEvent(FlowEvent event) {
+        switch (event.getType()) {
+            case TASK_CREATED:
+                notifyTaskCreated(event);
+                break;
+            case TASK_HANDLED:
+                notifyTaskHandled(event);
+                break;
+            case COMPLETED:
+            case REJECTED:
+            case WITHDRAWN:
+                notifyResult(event);
+                break;
+            case URGE:
+                notifyUrge(event);
+                break;
+            default:
+                break;
+        }
+    }
+
+    private void notifyTaskCreated(FlowEvent event) {
+        FlwTask task = taskRepository.findById(event.getTaskId()).orElse(null);
+        FlwInstance instance = instanceOf(event.getInstanceId());
+        if (task == null || instance == null) {
+            return;
+        }
+        String title = "您有新的待办：" + safe(instance.getBizTitle());
+        String content = "「" + safe(instance.getBizTitle()) + "」等待您审批"
+                + (task.getNodeName() == null ? "" : "（" + task.getNodeName() + "）");
+        userMsgClient.sendUserMsg(instance.getSchId().intValue(),
+                Collections.singletonList(task.getAssigneeId()), 2,
+                "flow.task", String.valueOf(instance.getId()), title, content,
+                "/task/" + task.getId(), "task:" + task.getId(), 30);
+        userMsgClient.todoInc(instance.getSchId().intValue(),
+                Collections.singletonList(task.getAssigneeId()), 1);
+    }
+
+    private void notifyTaskHandled(FlowEvent event) {
+        FlwTask task = taskRepository.findById(event.getTaskId()).orElse(null);
+        FlwInstance instance = instanceOf(event.getInstanceId());
+        if (task == null || instance == null) {
+            return;
+        }
+        userMsgClient.todoInc(instance.getSchId().intValue(),
+                Collections.singletonList(task.getAssigneeId()), -1);
+    }
+
+    private void notifyResult(FlowEvent event) {
+        FlwInstance instance = instanceOf(event.getInstanceId());
+        if (instance == null) {
+            return;
+        }
+        Object result = event.getData() == null ? null : event.getData().get("result");
+        String outcome;
+        String bizTitle = safe(instance.getBizTitle());
+        switch (event.getType()) {
+            case COMPLETED:
+                outcome = "已通过审批";
+                break;
+            case REJECTED:
+                outcome = "审批被拒绝";
+                break;
+            default:
+                outcome = "已撤回";
+                break;
+        }
+        StringBuilder content = new StringBuilder("您提交的「" + bizTitle + "」" + outcome);
+        if (result != null) {
+            content.append("（结果：").append(result).append("）");
+        }
+        Object opinion = event.getData() == null ? null : event.getData().get("opinion");
+        if (opinion != null && !String.valueOf(opinion).isEmpty()) {
+            content.append("，意见：").append(opinion);
+        }
+        userMsgClient.sendUserMsg(instance.getSchId().intValue(),
+                Collections.singletonList(instance.getSubmitterId()), 1,
+                "flow.result", String.valueOf(instance.getId()),
+                "办件状态更新：" + bizTitle, content.toString(),
+                "/instance/" + instance.getId(),
+                "result:" + instance.getId() + ":" + instance.getVersion(), 30);
+    }
+
+    private void notifyUrge(FlowEvent event) {
+        FlwTask task = taskRepository.findById(event.getTaskId()).orElse(null);
+        FlwInstance instance = instanceOf(event.getInstanceId());
+        if (task == null || instance == null) {
+            return;
+        }
+        int count = task.getUrgeCount() == null ? 1 : task.getUrgeCount();
+        String content = "「" + safe(instance.getBizTitle()) + "」任务（"
+                + (task.getNodeName() == null ? task.getNodeId() : task.getNodeName())
+                + "）被催办（第 " + count + " 次），请尽快办理";
+        userMsgClient.sendUserMsg(instance.getSchId().intValue(),
+                Collections.singletonList(task.getAssigneeId()), 1,
+                "flow.urge", String.valueOf(instance.getId()),
+                "催办提醒：" + safe(instance.getBizTitle()), content,
+                "/task/" + task.getId(), "urge:" + task.getId() + ":" + count, 7);
+    }
+
+    private FlwInstance instanceOf(Long instanceId) {
+        return instanceId == null ? null : instanceRepository.findById(instanceId).orElse(null);
+    }
+
+    private static String safe(String s) {
+        return s == null ? "" : s;
+    }
+}

src/main/java/com/yunhai/flowcenter/repository/FlwAssigneeMapRepository.java

@@ -0,0 +1,22 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwAssigneeMap;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+
+public interface FlwAssigneeMapRepository extends JpaRepository<FlwAssigneeMap, Long> {
+
+    /** DEPT_KEY 解析：启用映射的办理人列表（概览 §六） */
+    @Query("select m from FlwAssigneeMap m where m.schId = :schId and m.deptKey = :deptKey and m.status = 0")
+    List<FlwAssigneeMap> findEnabled(@Param("schId") Long schId, @Param("deptKey") String deptKey);
+
+    /** 发布校验用：本校全部启用映射 */
+    List<FlwAssigneeMap> findEnabledBySchId(Long schId);
+
+    List<FlwAssigneeMap> findBySchIdAndDeptKeyOrderByUserIdAsc(Long schId, String deptKey);
+
+    FlwAssigneeMap findBySchIdAndDeptKeyAndUserId(Long schId, String deptKey, Integer userId);
+}

src/main/java/com/yunhai/flowcenter/repository/FlwAttachmentRepository.java

@@ -0,0 +1,11 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwAttachment;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+
+public interface FlwAttachmentRepository extends JpaRepository<FlwAttachment, Long> {
+
+    List<FlwAttachment> findByInstanceIdOrderByIdAsc(Long instanceId);
+}

src/main/java/com/yunhai/flowcenter/repository/FlwBranchRepository.java

@@ -0,0 +1,27 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwBranch;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+import java.util.Optional;
+
+public interface FlwBranchRepository extends JpaRepository<FlwBranch, Long> {
+
+    List<FlwBranch> findByInstanceId(Long instanceId);
+
+    Optional<FlwBranch> findByInstanceIdAndBranchKey(Long instanceId, String branchKey);
+
+    long countByInstanceIdAndStatus(Long instanceId, Integer status);
+
+    @Modifying
+    @Query("update FlwBranch b set b.status = 2 where b.instanceId = :instanceId and b.status = 0")
+    int invalidateRunningByInstance(@Param("instanceId") Long instanceId);
+
+    @Modifying
+    @Query("delete from FlwBranch b where b.instanceId = :instanceId")
+    int deleteByInstance(@Param("instanceId") Long instanceId);
+}

src/main/java/com/yunhai/flowcenter/repository/FlwCallbackLogRepository.java

@@ -0,0 +1,38 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwCallbackLog;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.time.LocalDateTime;
+import java.util.Collection;
+import java.util.List;
+
+public interface FlwCallbackLogRepository extends JpaRepository<FlwCallbackLog, Long> {
+
+    /** 重推扫描主路径：待推/重试中且到点 */
+    List<FlwCallbackLog> findTop50ByStatusAndNextRetryTimeLessThanEqualOrderByNextRetryTimeAsc(
+            Integer status, LocalDateTime now);
+
+    /** 管理端推送日志分页（状态/事件/办件可空） */
+    @Query("select l from FlwCallbackLog l where l.schId = :schId "
+            + "and (:status is null or l.status = :status) "
+            + "and (:event is null or l.event = :event) "
+            + "and (:instanceId is null or l.instanceId = :instanceId) order by l.id desc")
+    Page<FlwCallbackLog> pageLogs(@Param("schId") Long schId, @Param("status") Integer status,
+                                  @Param("event") String event, @Param("instanceId") Long instanceId,
+                                  Pageable pageable);
+
+    /** 死信列表 */
+    Page<FlwCallbackLog> findBySchIdAndStatusOrderByIdDesc(Long schId, Integer status, Pageable pageable);
+
+    /** 挂起列表（管理端）：待推且重试次数已达挂起阈值（持续重试中疑似消费方停机） */
+    @Query("select l from FlwCallbackLog l where l.schId = :schId and l.status = 0 "
+            + "and l.retryCount >= :minRetry order by l.id desc")
+    Page<FlwCallbackLog> pageHung(@Param("schId") Long schId, @Param("minRetry") int minRetry, Pageable pageable);
+
+    List<FlwCallbackLog> findByIdInAndSchId(Collection<Long> ids, Long schId);
+}

src/main/java/com/yunhai/flowcenter/repository/FlwCallbackRegRepository.java

@@ -0,0 +1,17 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwCallbackReg;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+import java.util.Optional;
+
+public interface FlwCallbackRegRepository extends JpaRepository<FlwCallbackReg, Long> {
+
+    Optional<FlwCallbackReg> findBySchIdAndAppKeyAndFlowGuid(Long schId, String appKey, String flowGuid);
+
+    /** CallbackDispatcher 匹配：该流程下所有启用注册（event 订阅在内存过滤，量小） */
+    List<FlwCallbackReg> findBySchIdAndFlowGuidAndStatus(Long schId, String flowGuid, Integer status);
+
+    List<FlwCallbackReg> findBySchIdOrderByUpdateTimeDesc(Long schId);
+}

src/main/java/com/yunhai/flowcenter/repository/FlwDefRepository.java

@@ -0,0 +1,43 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwDef;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+import java.util.Optional;
+
+public interface FlwDefRepository extends JpaRepository<FlwDef, Long> {
+
+    Optional<FlwDef> findBySchIdAndFlowGuidAndStatusAndVersionOrderByIdDesc(Long schId, String flowGuid, Integer status, Integer version);
+
+    /** flow_guid 解析规则：该 (sch_id, flow_guid) 下已发布中 version 最大者（概览 §4.1） */
+    Optional<FlwDef> findFirstBySchIdAndFlowGuidAndStatusOrderByVersionDesc(Long schId, String flowGuid, Integer status);
+
+    /** 任意状态（回调注册只要求流程线存在） */
+    Optional<FlwDef> findFirstBySchIdAndFlowGuidOrderByVersionDesc(Long schId, String flowGuid);
+
+    /** 同名草稿（保存新建时复用，避免 uk 冲突） */
+    Optional<FlwDef> findFirstBySchIdAndCodeAndStatus(Long schId, String code, Integer status);
+
+    @Query("select coalesce(max(d.version), 0) from FlwDef d where d.schId = :schId and d.code = :code")
+    int maxVersionByCode(@Param("schId") Long schId, @Param("code") String code);
+
+    @Query("select coalesce(max(d.version), 0) from FlwDef d where d.schId = :schId and d.flowGuid = :flowGuid")
+    int maxVersionByGuid(@Param("schId") Long schId, @Param("flowGuid") String flowGuid);
+
+    Optional<FlwDef> findFirstBySchIdAndCodeOrderByVersionDesc(Long schId, String code);
+
+    List<FlwDef> findBySchIdAndFlowGuidOrderByVersionDesc(Long schId, String flowGuid);
+
+    List<FlwDef> findBySchIdAndStatusOrderByUpdateTimeDesc(Long schId, Integer status);
+
+    List<FlwDef> findBySchIdOrderByUpdateTimeDesc(Long schId);
+
+    /** 已发布流程列表（oapi list 数据源）：每条流程线取最高已发布版本 */
+    @Query("select d from FlwDef d where d.schId = :schId and d.status = 1 "
+            + "and d.version = (select max(d2.version) from FlwDef d2 where d2.schId = d.schId "
+            + "and d2.flowGuid = d.flowGuid and d2.status = 1) order by d.updateTime desc")
+    List<FlwDef> findPublishedLatestPerGuid(@Param("schId") Long schId);
+}

src/main/java/com/yunhai/flowcenter/repository/FlwInstanceRepository.java

@@ -0,0 +1,32 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwInstance;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.util.List;
+import java.util.Optional;
+
+public interface FlwInstanceRepository extends JpaRepository<FlwInstance, Long> {
+
+    /** biz uk 幂等主键 */
+    Optional<FlwInstance> findBySchIdAndBizTypeAndBizId(Long schId, String bizType, String bizId);
+
+    List<FlwInstance> findBySchIdAndSubmitterIdAndStatusOrderByIdDesc(Long schId, Integer submitterId, Integer status);
+
+    /** 我提交的办件（分页，状态可空） */
+    @Query("select i from FlwInstance i where i.schId = :schId and i.submitterId = :submitterId "
+            + "and (:status is null or i.status = :status) order by i.id desc")
+    Page<FlwInstance> pageMy(@Param("schId") Long schId, @Param("submitterId") Integer submitterId,
+                             @Param("status") Integer status, Pageable pageable);
+
+    /** 管理端办件分页（状态/关键字可空） */
+    @Query("select i from FlwInstance i where i.schId = :schId "
+            + "and (:status is null or i.status = :status) "
+            + "and (:keyword is null or i.bizTitle like concat('%', :keyword, '%')) order by i.id desc")
+    Page<FlwInstance> pageAdmin(@Param("schId") Long schId, @Param("status") Integer status,
+                                @Param("keyword") String keyword, Pageable pageable);
+}

src/main/java/com/yunhai/flowcenter/repository/FlwTaskRepository.java

@@ -0,0 +1,51 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwTask;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+public interface FlwTaskRepository extends JpaRepository<FlwTask, Long> {
+
+    List<FlwTask> findByInstanceIdOrderByIdAsc(Long instanceId);
+
+    List<FlwTask> findByInstanceIdAndStatus(Long instanceId, Integer status);
+
+    List<FlwTask> findByInstanceIdAndStatusIn(Long instanceId, List<Integer> statuses);
+
+    /** 任务办理抢占（概览 §5.4）：affected=1 才获得推进权，防双击/并发重复推进 */
+    @Modifying
+    @Query("update FlwTask t set t.status = :target, t.handleTime = :handleTime, t.opinion = :opinion "
+            + "where t.id = :id and t.status = 0")
+    int claimAndFinish(@Param("id") Long id, @Param("target") Integer target,
+                       @Param("handleTime") LocalDateTime handleTime, @Param("opinion") String opinion);
+
+    @Modifying
+    @Query("update FlwTask t set t.status = 3 where t.instanceId = :instanceId and t.status = 0")
+    int invalidatePendingByInstance(@Param("instanceId") Long instanceId);
+
+    @Modifying
+    @Query("update FlwTask t set t.status = 3 where t.instanceId = :instanceId and t.status = 0 and t.id <> :exceptTaskId")
+    int invalidatePendingExcept(@Param("instanceId") Long instanceId, @Param("exceptTaskId") Long exceptTaskId);
+
+    /** 我的待办（主路径，走 assignee 索引） */
+    @Query("select t from FlwTask t where t.schId = :schId and t.assigneeId = :assigneeId and t.status = 0 "
+            + "order by t.arriveTime asc, t.id asc")
+    Page<FlwTask> pageTodo(@Param("schId") Long schId, @Param("assigneeId") Integer assigneeId, Pageable pageable);
+
+    /** 我的已办（办理过的历史任务） */
+    @Query("select t from FlwTask t where t.schId = :schId and t.assigneeId = :assigneeId and t.status in (1, 2) "
+            + "order by t.handleTime desc, t.id desc")
+    Page<FlwTask> pageDone(@Param("schId") Long schId, @Param("assigneeId") Integer assigneeId, Pageable pageable);
+
+    /** 超期待催任务（定时扫描：待办+超期+未达催办上限） */
+    @Query("select t from FlwTask t where t.status = 0 and t.deadline is not null and t.deadline < :now "
+            + "and t.urgeCount < :maxTimes")
+    List<FlwTask> findOverdue(@Param("now") LocalDateTime now, @Param("maxTimes") int maxTimes);
+}

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

@@ -0,0 +1,68 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.repository.FlwTaskRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.platform.utils.model.BoaUser;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * 用户面访问守卫（概览 §十）：提交人只读写自己办件；办理人只读写分派给自己的任务；
+ * 管理员本校可查、不可代批。
+ * 管理员口径与 FlowAdminGuard / svc-hall ApplyViewGuard / Notice NoticeFlowGuard 对齐：
+ * type==1（超管）或 roleId∈{2,5,7}（校级管理员）——三者必须同口径，否则校级管理员
+ * 能列办件却在详情页 403（本类原先只认 type==1，2026-09-14 校正）。
+ */
+@Service
+@RequiredArgsConstructor
+public class FlowAccessGuard {
+
+    private static final int SUPER_ADMIN_TYPE = 1;
+    private static final List<Integer> ADMIN_ROLE_IDS = Arrays.asList(2, 5, 7);
+
+    private final FlwTaskRepository taskRepository;
+
+    /** 办件详情可见：提交人本人 / 该办件任务办理人 / 本校管理员（超管或校级管理员） */
+    public void requireInstanceVisible(FlwInstance instance, BoaUser user) {
+        if (user == null || user.getId() == null) {
+            throw new BizException(ErrorCode.FORBIDDEN, "未登录");
+        }
+        if (instance.getSubmitterId().equals(user.getId())) {
+            return;
+        }
+        if (!taskRepository.findByInstanceIdOrderByIdAsc(instance.getId()).stream()
+                .anyMatch(t -> user.getId().equals(t.getAssigneeId()))) {
+            if (!isAdminOf(instance, user)) {
+                throw new BizException(ErrorCode.FORBIDDEN, "仅提交人/办理人/本校管理员可查看该办件");
+            }
+        }
+    }
+
+    /**
+     * 本校管理员（可查不可代批；办理权在 FlowTaskService 里再按 assigneeId 校验）。
+     * 超管与校级管理员均限本校——跨校仍 403，不放大可见范围。
+     */
+    private boolean isAdminOf(FlwInstance instance, BoaUser user) {
+        Long current = currentSchId(user);
+        if (current == null || !current.equals(instance.getSchId())) {
+            return false;
+        }
+        if (user.getType() != null && user.getType() == SUPER_ADMIN_TYPE) {
+            return true;
+        }
+        return user.getRoleIds() != null
+                && user.getRoleIds().stream().anyMatch(r -> r != null && ADMIN_ROLE_IDS.contains(r));
+    }
+
+    private Long currentSchId(BoaUser user) {
+        if (user.getCurrentRole() == null || user.getCurrentRole().getSchId() == null) {
+            return null;
+        }
+        return Long.valueOf(user.getCurrentRole().getSchId());
+    }
+}

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

@@ -0,0 +1,54 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.platform.utils.model.BoaUser;
+import org.springframework.stereotype.Service;
+
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * 管理面权限守卫（概览 §十）：超管（type==1，平台约定）全平台可管；
+ * 校级管理员（roleId∈{2,5,7}，对齐 UserHome OtherUtil 先例）限本校。
+ */
+@Service
+public class FlowAdminGuard {
+
+    private static final int SUPER_ADMIN_TYPE = 1;
+    private static final List<Integer> ADMIN_ROLE_IDS = Arrays.asList(2, 5, 7);
+
+    /** 校验管理权并返回管辖学校 id（超管可用参数 schId 指定目标校，否则取当前身份学校） */
+    public Long requireAdmin(BoaUser user, Long targetSchId) {
+        if (user == null || user.getId() == null) {
+            throw new BizException(ErrorCode.FORBIDDEN, "未登录");
+        }
+        if (user.getType() != null && user.getType() == SUPER_ADMIN_TYPE) {
+            if (targetSchId != null) {
+                return targetSchId;
+            }
+            Long current = currentSchId(user);
+            if (current != null) {
+                return current;
+            }
+            throw new BizException(ErrorCode.PARAM_ERROR, "超管请显式指定 schId（当前身份无学校归属）");
+        }
+        boolean roleMatch = user.getRoleIds() != null
+                && user.getRoleIds().stream().anyMatch(ADMIN_ROLE_IDS::contains);
+        Long current = currentSchId(user);
+        if (!roleMatch || current == null) {
+            throw new BizException(ErrorCode.FORBIDDEN, "无流程管理权限");
+        }
+        if (targetSchId != null && !targetSchId.equals(current)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "仅可管理本校流程");
+        }
+        return current;
+    }
+
+    private Long currentSchId(BoaUser user) {
+        if (user.getCurrentRole() == null || user.getCurrentRole().getSchId() == null) {
+            return null;
+        }
+        return Long.valueOf(user.getCurrentRole().getSchId());
+    }
+}

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

@@ -0,0 +1,146 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.flowcenter.callback.CallbackProperties;
+import com.yunhai.flowcenter.callback.CallbackPushService;
+import com.yunhai.flowcenter.entity.FlwCallbackLog;
+import com.yunhai.flowcenter.entity.FlwCallbackReg;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.repository.FlwCallbackLogRepository;
+import com.yunhai.flowcenter.repository.FlwCallbackRegRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.platform.utils.model.BasePageResult;
+import lombok.RequiredArgsConstructor;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * 回调注册/推送日志/死信管理（概览 §9.2）：
+ * 启停、secret 重置（重置后旧签名立即失效）、推送日志查询、死信列表与手工重推。
+ */
+@Service
+@RequiredArgsConstructor
+public class FlowCallbackAdminService {
+
+    private final FlwCallbackRegRepository regRepository;
+    private final FlwCallbackLogRepository logRepository;
+    private final CallbackPushService pushService;
+    private final CallbackProperties callbackProperties;
+
+    public List<FlwCallbackReg> listRegs(Long schId) {
+        return regRepository.findBySchIdOrderByUpdateTimeDesc(schId);
+    }
+
+    /** 启用/停用注册（停用后该注册不再收到推送，日志保留） */
+    @Transactional
+    public void setRegStatus(Long schId, Long regId, boolean enabled) {
+        FlwCallbackReg reg = requireReg(schId, regId);
+        reg.setStatus(enabled ? 0 : 1);
+        regRepository.save(reg);
+    }
+
+    /** secret 重置：新 secret 下发（管理端展示一次，不回显存量） */
+    @Transactional
+    public String resetSecret(Long schId, Long regId) {
+        FlwCallbackReg reg = requireReg(schId, regId);
+        String secret = UUID.randomUUID().toString().replace("-", "").toLowerCase();
+        reg.setSecret(secret);
+        regRepository.save(reg);
+        return secret;
+    }
+
+    /** 推送日志分页（状态/事件/办件筛选） */
+    public BasePageResult<FlwCallbackLog> pageLogs(Long schId, Integer status, String event,
+                                                   Long instanceId, Integer page, Integer size) {
+        Page<FlwCallbackLog> p = logRepository.pageLogs(schId, status, event, instanceId,
+                PageRequest.of(page == null || page < 1 ? 0 : page - 1,
+                        size == null || size < 1 || size > 100 ? 10 : size));
+        return new BasePageResult<>(p.getContent(), (int) p.getTotalElements(),
+                page == null || page < 1 ? 1 : page,
+                size == null || size < 1 || size > 100 ? 10 : size,
+                p.getTotalPages(), p.hasNext());
+    }
+
+    /** 死信列表 */
+    public BasePageResult<FlwCallbackLog> pageDead(Long schId, Integer page, Integer size) {
+        Page<FlwCallbackLog> p = logRepository.findBySchIdAndStatusOrderByIdDesc(schId,
+                FlwEnums.CallbackLogStatus.DEAD.getCode(),
+                PageRequest.of(page == null || page < 1 ? 0 : page - 1,
+                        size == null || size < 1 || size > 100 ? 10 : size));
+        return new BasePageResult<>(p.getContent(), (int) p.getTotalElements(),
+                page == null || page < 1 ? 1 : page,
+                size == null || size < 1 || size > 100 ? 10 : size,
+                p.getTotalPages(), p.hasNext());
+    }
+
+    /** 挂起列表：待推且 retryCount≥挂起阈值（持续重试中疑似消费方停机的可视入口） */
+    public BasePageResult<FlwCallbackLog> pageHung(Long schId, Integer page, Integer size) {
+        Page<FlwCallbackLog> p = logRepository.pageHung(schId, callbackProperties.getHangAlertRetries(),
+                PageRequest.of(page == null || page < 1 ? 0 : page - 1,
+                        size == null || size < 1 || size > 100 ? 10 : size));
+        return new BasePageResult<>(p.getContent(), (int) p.getTotalElements(),
+                page == null || page < 1 ? 1 : page,
+                size == null || size < 1 || size > 100 ? 10 : size,
+                p.getTotalPages(), p.hasNext());
+    }
+
+    /**
+     * 管理端手工标记死信（持续重试语义下死信的唯一人工入口：人工判定事件无意义时止血）。
+     * 标记后可经既有 rePush 复活。
+     */
+    @Transactional
+    public void markDead(Long schId, Long logId) {
+        FlwCallbackLog callbackLog = logRepository.findById(logId)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "推送日志不存在：" + logId));
+        if (!schId.equals(callbackLog.getSchId())) {
+            throw new BizException(ErrorCode.FORBIDDEN, "推送日志不属于该学校");
+        }
+        if (callbackLog.getStatus() != null
+                && callbackLog.getStatus() == FlwEnums.CallbackLogStatus.SUCCESS.getCode()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "已成功日志无需标记死信");
+        }
+        pushService.markDead(callbackLog, "管理端手工标记死信");
+    }
+
+    /** 手工重推（死信/失败日志）：置回待推并立即触发一次推送 */
+    @Transactional
+    public void rePush(Long schId, List<Long> logIds) {
+        if (logIds == null || logIds.isEmpty()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "请选择要重推的日志");
+        }
+        List<FlwCallbackLog> logs = logRepository.findByIdInAndSchId(logIds, schId);
+        if (logs.size() != logIds.size()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "存在不属于该校或不存在 dead/pending 日志");
+        }
+        for (FlwCallbackLog callbackLog : logs) {
+            if (callbackLog.getStatus() == FlwEnums.CallbackLogStatus.SUCCESS.getCode()) {
+                continue;
+            }
+            callbackLog.setStatus(FlwEnums.CallbackLogStatus.PENDING.getCode());
+            callbackLog.setRetryCount(0);
+            callbackLog.setNextRetryTime(LocalDateTime.now());
+            logRepository.save(callbackLog);
+        }
+        logRepository.flush();
+        for (FlwCallbackLog callbackLog : logs) {
+            if (callbackLog.getStatus() != null) {
+                pushService.pushAsync(callbackLog.getId());
+            }
+        }
+    }
+
+    private FlwCallbackReg requireReg(Long schId, Long regId) {
+        FlwCallbackReg reg = regRepository.findById(regId)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "回调注册不存在：" + regId));
+        if (!reg.getSchId().equals(schId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "回调注册不属于该学校");
+        }
+        return reg;
+    }
+}

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

@@ -0,0 +1,161 @@
+package com.yunhai.flowcenter.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.flowcenter.engine.DefValidator;
+import com.yunhai.flowcenter.engine.FlowDefModel;
+import com.yunhai.flowcenter.engine.FlowEngine;
+import com.yunhai.flowcenter.entity.FlwAssigneeMap;
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.repository.FlwAssigneeMapRepository;
+import com.yunhai.flowcenter.repository.FlwDefRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+import java.util.stream.Collectors;
+
+/**
+ * 流程定义管理（M1：JSON 文本编辑模式，概览 §9.2）：
+ * 保存=草稿直改/已发布升版本（flowGuid 跨版本不变）；发布跑静态校验（把"任务无主"拦在发布期）。
+ */
+@Service
+@RequiredArgsConstructor
+public class FlowDefAdminService {
+
+    private final FlwDefRepository defRepository;
+    private final FlwAssigneeMapRepository mapRepository;
+    private final FlowEngine flowEngine;
+    private final ObjectMapper objectMapper;
+
+    /** 定义列表：status 空=全量（各流程线各版本都展示，管理端"版本历史"内聚在行操作里） */
+    public List<FlwDef> list(Long schId, Integer status) {
+        if (status != null) {
+            return defRepository.findBySchIdAndStatusOrderByUpdateTimeDesc(schId, status);
+        }
+        return defRepository.findBySchIdOrderByUpdateTimeDesc(schId);
+    }
+
+    /** 全量列表（管理端首页：各流程线最新版本+状态聚合展示简化为全量返回） */
+    public List<FlwDef> listAll(Long schId) {
+        return defRepository.findPublishedLatestPerGuid(schId);
+    }
+
+    public FlwDef get(Long schId, Long id) {
+        FlwDef def = requireDef(schId, id);
+        return def;
+    }
+
+    /**
+     * 保存（新建语义按 baseGuid/同名草稿分派，避免 uk(sch,code,version) 冲突）：
+     * - id 非空：草稿直改；已发布/停用=复制升版本（同 flowGuid，version=max+1）
+     * - id 空 + baseGuid 非空：在该流程线上开新版本草稿（version=max+1，flowGuid 不变）——前端"升版本"
+     * - id 空 + 同名草稿存在：复用该草稿直改
+     * - id 空 + 全新 code：新流程线（flowGuid 生成，version=1）
+     */
+    @Transactional
+    public FlwDef save(Long schId, Long id, String code, String name, String contentJson, String baseGuid) {
+        // JSON 先解析再落库（语法错误不进库）
+        FlowDefModel parsed = FlowDefModel.parse(objectMapper, contentJson);
+        if (code == null || code.trim().isEmpty() || name == null || name.trim().isEmpty()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "code/name 必填");
+        }
+        FlwDef def;
+        if (id == null && baseGuid != null && !baseGuid.trim().isEmpty()) {
+            // 在既有流程线上开新版本草稿
+            defRepository.findFirstBySchIdAndFlowGuidOrderByVersionDesc(schId, baseGuid.trim())
+                    .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "baseGuid 流程线不存在"));
+            def = new FlwDef();
+            def.setSchId(schId);
+            def.setFlowGuid(baseGuid.trim());
+            def.setCode(code.trim());
+            def.setVersion(defRepository.maxVersionByGuid(schId, baseGuid.trim()) + 1);
+            def.setStatus(FlwEnums.DefStatus.DRAFT.getCode());
+        } else if (id == null) {
+            FlwDef draft = defRepository.findFirstBySchIdAndCodeAndStatus(
+                    schId, code.trim(), FlwEnums.DefStatus.DRAFT.getCode()).orElse(null);
+            if (draft != null) {
+                // 同名草稿复用直改
+                def = draft;
+            } else {
+                def = new FlwDef();
+                def.setSchId(schId);
+                def.setFlowGuid(UUID.randomUUID().toString().replace("-", "").toLowerCase());
+                def.setCode(code.trim());
+                def.setVersion(defRepository.maxVersionByCode(schId, code.trim()) + 1);
+                def.setStatus(FlwEnums.DefStatus.DRAFT.getCode());
+            }
+        } else {
+            def = requireDef(schId, id);
+            if (!def.getCode().equals(code.trim())) {
+                throw new BizException(ErrorCode.PARAM_ERROR, "流程编码不可修改");
+            }
+            if (def.getStatus() != FlwEnums.DefStatus.DRAFT.getCode()) {
+                // 升版本：复制行，保持 flowGuid
+                FlwDef next = new FlwDef();
+                next.setSchId(schId);
+                next.setFlowGuid(def.getFlowGuid());
+                next.setCode(def.getCode());
+                next.setVersion(defRepository.maxVersionByGuid(schId, def.getFlowGuid()) + 1);
+                next.setStatus(FlwEnums.DefStatus.DRAFT.getCode());
+                def = next;
+            }
+        }
+        def.setCode(code.trim());
+        def.setName(name.trim());
+        def.setContentJson(contentJson);
+        // 定义 JSON 里的 code/name 与行字段一致性校验（给绑定回显用行字段，JSON 内为主）
+        if (parsed.code != null && !parsed.code.trim().isEmpty() && !parsed.code.trim().equals(def.getCode())) {
+            def.setCode(parsed.code.trim());
+        }
+        if (parsed.name != null && !parsed.name.trim().isEmpty()) {
+            def.setName(parsed.name.trim());
+        }
+        return defRepository.save(def);
+    }
+
+    /** 发布：静态校验（START/END 唯一、无孤儿无环、DEPT_KEY 有启用映射）后置为已发布 */
+    @Transactional
+    public FlwDef publish(Long schId, Long id) {
+        FlwDef def = requireDef(schId, id);
+        if (def.getStatus() == FlwEnums.DefStatus.PUBLISHED.getCode()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "已是发布状态");
+        }
+        FlowDefModel model = FlowDefModel.parse(objectMapper, def.getContentJson());
+        Set<String> enabledDeptKeys = mapRepository.findEnabledBySchId(schId).stream()
+                .map(FlwAssigneeMap::getDeptKey).collect(Collectors.toSet());
+        DefValidator.validate(model, enabledDeptKeys);
+        def.setStatus(FlwEnums.DefStatus.PUBLISHED.getCode());
+        def.setPublishTime(LocalDateTime.now());
+        return defRepository.save(def);
+    }
+
+    /** 停用：不可新发起，存量跑完 */
+    @Transactional
+    public void offline(Long schId, Long id) {
+        FlwDef def = requireDef(schId, id);
+        def.setStatus(FlwEnums.DefStatus.DISABLED.getCode());
+        defRepository.save(def);
+    }
+
+    /** 同一流程线全部版本（降序） */
+    public List<FlwDef> versions(Long schId, String flowGuid) {
+        return defRepository.findBySchIdAndFlowGuidOrderByVersionDesc(schId, flowGuid);
+    }
+
+    private FlwDef requireDef(Long schId, Long id) {
+        FlwDef def = defRepository.findById(id)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "流程定义不存在：" + id));
+        if (!def.getSchId().equals(schId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "流程定义不属于该学校");
+        }
+        return def;
+    }
+
+}

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

@@ -0,0 +1,242 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.flowcenter.engine.FlowDefModel;
+import com.yunhai.flowcenter.engine.FlowEngine;
+import com.yunhai.flowcenter.entity.FlwAssigneeMap;
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.model.FlowModels;
+import com.yunhai.flowcenter.repository.FlwAssigneeMapRepository;
+import com.yunhai.flowcenter.repository.FlwDefRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.openapi.client.OpenApiUserClient;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.platform.utils.model.BoaUser;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 流程示意图出图（方案 §3.2）：后端按视图解析好节点 label/subLabel，前端只画图不解析。
+ * 三分支定位：byGuid=最高已发布版（用户面）；byInstance=办件 def 快照（用户面，可见性守卫在控制器）；
+ * build(defId 任意版本直调)=管理面草稿预览。
+ * 视图口径：dept 视图不展示人员姓名（USERS 节点只显"指定办理人"且不调 UserBase，防科室视图泄名单）；
+ * user 视图 DEPT_KEY=映射成员名、USERS=UserBase 补全（失败降级 #id 不阻塞）；缺省 auto 按节点自适应
+ * （DEPT_KEY 走科室文案、USERS 走人员文案）。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FlowDiagramService {
+
+    public static final String MODE_DEPT = "dept";
+    public static final String MODE_USER = "user";
+    public static final String MODE_AUTO = "auto";
+
+    /** dept 视图 USERS 节点固定副标（不列姓名） */
+    private static final String USERS_HINT_DEPT_VIEW = "指定办理人";
+
+    private final FlwDefRepository defRepository;
+    private final FlwAssigneeMapRepository mapRepository;
+    private final FlowEngine flowEngine;
+    private final OpenApiUserClient userClient;
+
+    /** flowGuid 分支：最高已发布版（查询范式同 OapiFlowService.getFlow） */
+    public FlowModels.DiagramVo byGuid(Long schId, String flowGuid, String mode) {
+        FlwDef def = defRepository.findFirstBySchIdAndFlowGuidAndStatusOrderByVersionDesc(
+                        schId, flowGuid, FlwEnums.DefStatus.PUBLISHED.getCode())
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "流程不存在或未发布"));
+        // 二道防线：查询本就按 schId 收敛，此处再显式比对（防仓库方法误用导致跨校出图）
+        if (!schId.equals(def.getSchId())) {
+            throw new BizException(ErrorCode.FORBIDDEN, "跨校不可查看");
+        }
+        return build(def, null, mode);
+    }
+
+    /** instanceId 分支：按办件 def 快照出图（可见性守卫在控制器 requireInstanceVisible） */
+    public FlowModels.DiagramVo byInstance(FlwInstance instance, String mode) {
+        FlwDef def = defRepository.findById(instance.getDefId())
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR,
+                        "流程定义不存在：" + instance.getDefId()));
+        return build(def, instance.getId(), mode);
+    }
+
+    /** 出图主体（管理面 defId 分支按 defId 任意版本直调，草稿可预览） */
+    public FlowModels.DiagramVo build(FlwDef def, Long instanceId, String mode) {
+        String m = normalizeMode(mode);
+        FlowDefModel model = flowEngine.parseModel(def);
+        FlowModels.DiagramVo vo = new FlowModels.DiagramVo();
+        vo.setFlowGuid(def.getFlowGuid());
+        vo.setDefId(def.getId());
+        vo.setInstanceId(instanceId);
+        vo.setName(def.getName());
+        vo.setVersion(def.getVersion());
+        vo.setStatus(def.getStatus());
+        vo.setMode(m);
+        List<FlowModels.NodeVo> nodes = new ArrayList<>();
+        for (FlowDefModel.Node n : model.nodes) {
+            nodes.add(toNodeVo(def.getSchId(), n, m));
+        }
+        vo.setNodes(nodes);
+        List<FlowModels.EdgeVo> edges = new ArrayList<>();
+        for (FlowDefModel.Edge e : model.edges) {
+            FlowModels.EdgeVo ev = new FlowModels.EdgeVo();
+            ev.setFrom(e.from);
+            ev.setTo(e.to);
+            edges.add(ev);
+        }
+        vo.setEdges(edges);
+        return vo;
+    }
+
+    private FlowModels.NodeVo toNodeVo(Long schId, FlowDefModel.Node n, String mode) {
+        FlowModels.NodeVo vo = new FlowModels.NodeVo();
+        vo.setId(n.id);
+        vo.setType(n.type);
+        vo.setCountersign(n.countersign);
+        vo.setDeadlineHours(n.deadlineHours);
+        if (!FlowDefModel.TYPE_APPROVAL.equals(n.type)) {
+            vo.setLabel(fixedLabel(n.type));
+            return vo;
+        }
+        vo.setLabel(n.name);
+        FlowDefModel.Assignee a = n.assignee;
+        if (a == null) {
+            return vo;
+        }
+        vo.setAssigneeType(a.type);
+        vo.setDeptKey(a.deptKey);
+        if (FlowDefModel.ASSIGNEE_DEPT_KEY.equals(a.type)) {
+            List<FlwAssigneeMap> maps = mapRepository.findEnabled(schId, a.deptKey);
+            if (MODE_USER.equals(mode)) {
+                vo.setSubLabel(namesWithSuffix(memberNames(maps), suffixes(n)));
+            } else {
+                // dept 视图与 auto 的 DEPT_KEY 自适应同文案：科室名 + 启用映射人数
+                vo.setLabel(deptLabel(n, a, maps));
+                List<String> parts = new ArrayList<>();
+                parts.add("科室 · " + maps.size() + "人");
+                parts.addAll(suffixes(n));
+                vo.setSubLabel(String.join(" · ", parts));
+            }
+        } else if (FlowDefModel.ASSIGNEE_USERS.equals(a.type)) {
+            if (MODE_DEPT.equals(mode)) {
+                vo.setSubLabel(USERS_HINT_DEPT_VIEW);
+            } else {
+                vo.setSubLabel(namesWithSuffix(userNames(a.userIds), suffixes(n)));
+            }
+        }
+        return vo;
+    }
+
+    /** 科室视图 label 兜底链：有映射行取 deptName（全空→deptKey）；无映射行→节点名（再退 deptKey） */
+    private String deptLabel(FlowDefModel.Node n, FlowDefModel.Assignee a, List<FlwAssigneeMap> maps) {
+        if (maps.isEmpty()) {
+            return firstNonBlank(n.name, a.deptKey);
+        }
+        for (FlwAssigneeMap m : maps) {
+            if (m.getDeptName() != null && !m.getDeptName().trim().isEmpty()) {
+                return m.getDeptName();
+            }
+        }
+        return firstNonBlank(a.deptKey, n.name);
+    }
+
+    /** 人员名单（顿号连接）+ 会签/时限后缀（" · "分隔）；名单与后缀均空则返回 null */
+    private String namesWithSuffix(List<String> names, List<String> suffixes) {
+        List<String> nonBlank = new ArrayList<>();
+        if (names != null) {
+            for (String s : names) {
+                if (s != null && !s.isEmpty()) {
+                    nonBlank.add(s);
+                }
+            }
+        }
+        if (nonBlank.isEmpty() && suffixes.isEmpty()) {
+            return null;
+        }
+        StringBuilder sb = new StringBuilder(String.join("、", nonBlank));
+        for (String s : suffixes) {
+            if (sb.length() > 0) {
+                sb.append(" · ");
+            }
+            sb.append(s);
+        }
+        return sb.toString();
+    }
+
+    private List<String> suffixes(FlowDefModel.Node n) {
+        List<String> parts = new ArrayList<>();
+        if (FlowDefModel.COUNTERSIGN_ANY.equals(n.countersign)) {
+            parts.add("任一人通过");
+        }
+        if (n.deadlineHours != null) {
+            parts.add("时限" + n.deadlineHours + "h");
+        }
+        return parts;
+    }
+
+    private List<String> memberNames(List<FlwAssigneeMap> maps) {
+        List<String> names = new ArrayList<>();
+        for (FlwAssigneeMap m : maps) {
+            names.add(blankToId(m.getUserName(), m.getUserId()));
+        }
+        return names;
+    }
+
+    /** USERS 定义直配人名（复用 OpenApiUserClient.getUserById 通道，失败/空名降级 #id 不抛错） */
+    private List<String> userNames(List<Integer> userIds) {
+        List<String> names = new ArrayList<>();
+        if (userIds == null) {
+            return names;
+        }
+        for (Integer uid : userIds) {
+            String name = null;
+            try {
+                BoaUser u = userClient.getUserById(String.valueOf(uid));
+                name = u == null ? null : u.getName();
+            } catch (Exception e) {
+                log.warn("[flow-center] 示意图人名补全失败 userId={}：{}", uid, e.getMessage());
+            }
+            names.add(blankToId(name, uid));
+        }
+        return names;
+    }
+
+    private String blankToId(String name, Integer userId) {
+        return name == null || name.trim().isEmpty() ? "#" + userId : name;
+    }
+
+    private String fixedLabel(String type) {
+        switch (type == null ? "" : type) {
+            case FlowDefModel.TYPE_START:
+                return "开始";
+            case FlowDefModel.TYPE_END:
+                return "结束";
+            case FlowDefModel.TYPE_PARALLEL_SPLIT:
+                return "并行分发";
+            case FlowDefModel.TYPE_PARALLEL_JOIN:
+                return "汇聚等待";
+            default:
+                return type;
+        }
+    }
+
+    private String normalizeMode(String mode) {
+        if (mode == null || mode.trim().isEmpty()) {
+            return MODE_AUTO;
+        }
+        String m = mode.trim();
+        if (MODE_DEPT.equals(m) || MODE_USER.equals(m) || MODE_AUTO.equals(m)) {
+            return m;
+        }
+        throw new BizException(ErrorCode.PARAM_ERROR, "mode 仅支持 dept/user");
+    }
+
+    private String firstNonBlank(String a, String b) {
+        return a != null && !a.trim().isEmpty() ? a : b;
+    }
+}

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

@@ -0,0 +1,224 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.flowcenter.engine.FlowDefModel;
+import com.yunhai.flowcenter.engine.FlowEngine;
+import com.yunhai.flowcenter.engine.FlowEvent;
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.repository.FlwBranchRepository;
+import com.yunhai.flowcenter.repository.FlwDefRepository;
+import com.yunhai.flowcenter.repository.FlwInstanceRepository;
+import com.yunhai.flowcenter.repository.FlwTaskRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * 办件生命周期：代发起（幂等 + R4 重启重提）、撤回。
+ *
+ * <p><b>R4 驳回/撤回后重提语义（开工说明 §7#1，详设定稿）</b>：biz uk 命中已终态办件
+ * （30 已拒绝 / 40 已撤回）时复用同一办件行"重启推进"——不新建、不报错：定义刷新为当前
+ * 已发布版本、提交快照全量覆盖、旧分支行清空、残留待办失效、status 回 10、提交时间刷新、
+ * version 自增（镜像方按 instanceVersion 单调推进到 10）。任务历史保留（1/2/3 状态行不动），
+ * 轨迹跨轮连续。status=10/20（在途/已完成）命中则纯幂等返回原办件（duplicated=true）。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FlowInstanceService {
+
+    private final FlwInstanceRepository instanceRepository;
+    private final FlwDefRepository defRepository;
+    private final FlwTaskRepository taskRepository;
+    private final FlwBranchRepository branchRepository;
+    private final FlowEngine flowEngine;
+    private final ApplicationEventPublisher eventPublisher;
+
+    /** 代发起申请体（oapi apply 与未来原生发起共用字段） */
+    @RequiredArgsConstructor
+    public static class ApplyCommand {
+        public final Long schId;
+        public final FlwDef def;
+        public final String bizType;
+        public final String bizId;
+        public final String bizTitle;
+        public final String bizUrl;
+        public final String bizSnapshot;
+        public final Integer submitterId;
+        public final String submitterName;
+        public final String formDataJson;
+    }
+
+    /** 代发起结果：instanceId + duplicated（命中既有办件=true，含重启重提） */
+    @Transactional
+    public ApplyOutcome apply(ApplyCommand cmd) {
+        FlwInstance existing = instanceRepository
+                .findBySchIdAndBizTypeAndBizId(cmd.schId, cmd.bizType, cmd.bizId).orElse(null);
+        if (existing != null) {
+            int status = existing.getStatus();
+            if (status == FlwEnums.InstanceStatus.APPROVING.getCode()
+                    || status == FlwEnums.InstanceStatus.COMPLETED.getCode()) {
+                return new ApplyOutcome(existing.getId(), true);
+            }
+            // 30/40：R4 重启推进（复用办件行，定义/快照/时间刷新，重新走 START）
+            restart(existing, cmd);
+            return new ApplyOutcome(existing.getId(), true);
+        }
+        FlwInstance instance = new FlwInstance();
+        instance.setSchId(cmd.schId);
+        instance.setDefId(cmd.def.getId());
+        instance.setDefCode(cmd.def.getCode());
+        instance.setDefVersion(cmd.def.getVersion());
+        instance.setBizType(cmd.bizType);
+        instance.setBizId(cmd.bizId);
+        instance.setBizTitle(cmd.bizTitle);
+        instance.setBizUrl(cmd.bizUrl);
+        instance.setBizSnapshot(cmd.bizSnapshot);
+        instance.setFormDataJson(cmd.formDataJson);
+        instance.setSubmitterId(cmd.submitterId);
+        instance.setSubmitterName(cmd.submitterName);
+        instance.setStatus(FlwEnums.InstanceStatus.APPROVING.getCode());
+        instance.setSubmitTime(LocalDateTime.now());
+        instanceRepository.saveAndFlush(instance);
+        flowEngine.startAdvance(instance, cmd.def);
+        publishSubmitted(instance);
+        return new ApplyOutcome(instance.getId(), false);
+    }
+
+    private void restart(FlwInstance instance, ApplyCommand cmd) {
+        log.info("[flow-center] R4 重启推进：instance={} 原 status={} biz={}/{}",
+                instance.getId(), instance.getStatus(), cmd.bizType, cmd.bizId);
+        instance.setDefId(cmd.def.getId());
+        instance.setDefCode(cmd.def.getCode());
+        instance.setDefVersion(cmd.def.getVersion());
+        instance.setBizTitle(cmd.bizTitle);
+        instance.setBizUrl(cmd.bizUrl);
+        instance.setBizSnapshot(cmd.bizSnapshot);
+        instance.setFormDataJson(cmd.formDataJson);
+        instance.setSubmitterId(cmd.submitterId);
+        instance.setSubmitterName(cmd.submitterName);
+        instance.setStatus(FlwEnums.InstanceStatus.APPROVING.getCode());
+        instance.setSubmitTime(LocalDateTime.now());
+        instance.setFinishTime(null);
+        instanceRepository.saveAndFlush(instance);
+        taskRepository.invalidatePendingByInstance(instance.getId());
+        branchRepository.deleteByInstance(instance.getId());
+        flowEngine.startAdvance(instance, cmd.def);
+        publishSubmitted(instance);
+    }
+
+    /**
+     * 撤回（概览 §5.3）：仅当尚无任何任务被办理时允许；全部待办失效、分支失效、办件=40。
+     */
+    @Transactional
+    public void withdraw(Long schId, Long instanceId) {
+        FlwInstance instance = requireInstance(schId, instanceId);
+        if (instance.getStatus() != FlwEnums.InstanceStatus.APPROVING.getCode()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "仅审批中的办件可撤回");
+        }
+        if (!taskRepository.findByInstanceIdAndStatusIn(instanceId,
+                java.util.Arrays.asList(FlwEnums.TaskStatus.APPROVED.getCode(),
+                        FlwEnums.TaskStatus.REJECTED.getCode())).isEmpty()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "已有任务被办理，不能撤回");
+        }
+        instance.setStatus(FlwEnums.InstanceStatus.WITHDRAWN.getCode());
+        instance.setFinishTime(LocalDateTime.now());
+        instanceRepository.saveAndFlush(instance);
+        taskRepository.invalidatePendingByInstance(instanceId);
+        branchRepository.invalidateRunningByInstance(instanceId);
+        Map<String, Object> data = new HashMap<>();
+        data.put("result", "WITHDRAWN");
+        eventPublisher.publishEvent(FlowEvent.of(FlowEvent.Type.WITHDRAWN, instanceId, null, data));
+    }
+
+    public FlwInstance requireInstance(Long schId, Long instanceId) {
+        FlwInstance instance = instanceRepository.findById(instanceId)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "办件不存在：" + instanceId));
+        if (!instance.getSchId().equals(schId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "办件不属于该学校");
+        }
+        return instance;
+    }
+
+    public FlwDef requireDef(Long defId) {
+        return defRepository.findById(defId)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "流程定义不存在：" + defId));
+    }
+
+    /**
+     * 催办（概览 §5.3）：提交人/管理员对办件的全部待办任务各催一次（URGE 事件 → UserMsg 通道，
+     * msgNo=urge:{taskId}:{N} 幂等）；次数上限取定义 settings.urge.maxTimes（默认 3；
+     * enabled=false → 0 = 不限次）。非提交人调用须是本校管理员（控制器已按 BoaUser 判定放行）。
+     */
+    @Transactional
+    public void urgeInstance(Long schId, Long instanceId, Integer operatorId) {
+        FlwInstance instance = requireInstance(schId, instanceId);
+        FlowDefModel model = flowEngine.parseModel(requireDef(instance.getDefId()));
+        int maxTimes = urgeMaxTimes(model);
+        java.util.List<com.yunhai.flowcenter.entity.FlwTask> pendings =
+                taskRepository.findByInstanceIdAndStatus(instanceId,
+                        com.yunhai.flowcenter.enums.FlwEnums.TaskStatus.PENDING.getCode());
+        if (pendings.isEmpty()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "无待办任务可催办");
+        }
+        for (com.yunhai.flowcenter.entity.FlwTask task : pendings) {
+            if (maxTimes > 0 && task.getUrgeCount() >= maxTimes) {
+                continue;
+            }
+            task.setUrgeCount(task.getUrgeCount() + 1);
+            taskRepository.save(task);
+            Map<String, Object> data = new HashMap<>();
+            data.put("taskId", task.getId());
+            data.put("urgeCount", task.getUrgeCount());
+            eventPublisher.publishEvent(FlowEvent.of(FlowEvent.Type.URGE,
+                    instanceId, task.getId(), data));
+        }
+    }
+
+    private static int urgeMaxTimes(FlowDefModel model) {
+        if (model == null || model.settings == null || model.settings.urge == null) {
+            return 3;
+        }
+        FlowDefModel.Urge urge = model.settings.urge;
+        if (Boolean.FALSE.equals(urge.enabled)) {
+            return 0;
+        }
+        return urge.maxTimes == null || urge.maxTimes <= 0 ? 3 : urge.maxTimes;
+    }
+
+    private void publishSubmitted(FlwInstance instance) {
+        FlowDefModel model = flowEngine.parseModel(requireDef(instance.getDefId()));
+        Map<String, Object> data = new HashMap<>();
+        data.put("nodeSummary", FlowEngine.nodeSummary(model));
+        eventPublisher.publishEvent(FlowEvent.of(FlowEvent.Type.SUBMITTED, instance.getId(), null, data));
+    }
+
+    /** 代发起结果值对象 */
+    @SuppressWarnings("unused")
+    public static class ApplyOutcome {
+        private final Long instanceId;
+        private final boolean duplicated;
+
+        public ApplyOutcome(Long instanceId, boolean duplicated) {
+            this.instanceId = instanceId;
+            this.duplicated = duplicated;
+        }
+
+        public Long getInstanceId() {
+            return instanceId;
+        }
+
+        public boolean isDuplicated() {
+            return duplicated;
+        }
+    }
+}

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

@@ -0,0 +1,85 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.flowcenter.entity.FlwAssigneeMap;
+import com.yunhai.flowcenter.repository.FlwAssigneeMapRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.platform.openapi.client.OpenApiUserClient;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+/**
+ * 办理人映射管理（概览 §4.7/§六）：DEPT_KEY → 办理人显式映射，成员检索经
+ * UserBase /oapi/user/byId 补全姓名快照（检索按 id 精确查；按名检索二期接 UserBase 模糊端点）。
+ */
+@Service
+@RequiredArgsConstructor
+public class FlowMapAdminService {
+
+    private final FlwAssigneeMapRepository mapRepository;
+    private final OpenApiUserClient userClient;
+
+    public List<FlwAssigneeMap> listByDept(Long schId, String deptKey) {
+        if (deptKey == null || deptKey.trim().isEmpty()) {
+            return mapRepository.findEnabledBySchId(schId);
+        }
+        return mapRepository.findBySchIdAndDeptKeyOrderByUserIdAsc(schId, deptKey.trim());
+    }
+
+    /** 新增/启用映射（uk: sch+dept+user；已存在则刷新姓名/状态） */
+    @Transactional
+    public FlwAssigneeMap save(Long schId, String deptKey, String deptName,
+                               Integer userId, String userName) {
+        if (deptKey == null || deptKey.trim().isEmpty() || userId == null) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "deptKey/userId 必填");
+        }
+        if (userName == null || userName.trim().isEmpty()) {
+            userName = fetchName(userId);
+        }
+        FlwAssigneeMap map = mapRepository.findBySchIdAndDeptKeyAndUserId(schId, deptKey.trim(), userId);
+        if (map == null) {
+            map = new FlwAssigneeMap();
+            map.setSchId(schId);
+            map.setDeptKey(deptKey.trim());
+            map.setUserId(userId);
+        }
+        map.setDeptName(deptName);
+        map.setUserName(userName);
+        map.setStatus(0);
+        return mapRepository.save(map);
+    }
+
+    /** 停用映射（保留历史，DEPT_KEY 解析只取 status=0） */
+    @Transactional
+    public void disable(Long schId, Long id) {
+        FlwAssigneeMap map = mapRepository.findById(id)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "映射不存在：" + id));
+        if (!map.getSchId().equals(schId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "映射不属于该学校");
+        }
+        map.setStatus(1);
+        mapRepository.save(map);
+    }
+
+    /** 成员检索：按用户 id 从 UserBase 取姓名快照（管理端录入校验） */
+    public BoaUser lookupUser(Integer userId) {
+        try {
+            return userClient.getUserById(String.valueOf(userId));
+        } catch (Exception e) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "UserBase 用户检索失败（服务不可达）");
+        }
+    }
+
+    private String fetchName(Integer userId) {
+        try {
+            BoaUser user = userClient.getUserById(String.valueOf(userId));
+            return user == null ? "" : (user.getName() == null ? "" : user.getName());
+        } catch (Exception e) {
+            return "";
+        }
+    }
+}

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

@@ -0,0 +1,213 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.flowcenter.engine.FlowEngine;
+import com.yunhai.flowcenter.entity.FlwBranch;
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.entity.FlwTask;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.model.FlowModels;
+import com.yunhai.flowcenter.repository.FlwBranchRepository;
+import com.yunhai.flowcenter.repository.FlwDefRepository;
+import com.yunhai.flowcenter.repository.FlwInstanceRepository;
+import com.yunhai.flowcenter.repository.FlwTaskRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.platform.utils.model.BasePageResult;
+import lombok.RequiredArgsConstructor;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * 用户面查询（我的办件/待办/已办/办件详情）。
+ */
+@Service
+@RequiredArgsConstructor
+public class FlowQueryService {
+
+    private final FlwInstanceRepository instanceRepository;
+    private final FlwTaskRepository taskRepository;
+    private final FlwBranchRepository branchRepository;
+    private final FlwDefRepository defRepository;
+    private final FlowEngine flowEngine;
+
+    public BasePageResult<FlowModels.InstanceItem> pageMy(Long schId, Integer submitterId,
+                                                          Integer status, Integer page, Integer size) {
+        Page<FlwInstance> p = instanceRepository.pageMy(schId, submitterId, status,
+                PageRequest.of(normPage(page), normSize(size)));
+        return toResult(p.getTotalElements(), p.getContent().stream().map(this::toInstanceItem)
+                .collect(Collectors.toList()), page, size);
+    }
+
+    public BasePageResult<FlowModels.TaskItem> pageTodo(Long schId, Integer assigneeId,
+                                                        Integer page, Integer size) {
+        Page<FlwTask> p = taskRepository.pageTodo(schId, assigneeId,
+                PageRequest.of(normPage(page), normSize(size)));
+        List<FlowModels.TaskItem> items = p.getContent().stream()
+                .map(this::toTaskItem).collect(Collectors.toList());
+        fillInstanceInfo(items);
+        return toResult(p.getTotalElements(), items, page, size);
+    }
+
+    public BasePageResult<FlowModels.TaskItem> pageDone(Long schId, Integer assigneeId,
+                                                        Integer page, Integer size) {
+        Page<FlwTask> p = taskRepository.pageDone(schId, assigneeId,
+                PageRequest.of(normPage(page), normSize(size)));
+        List<FlowModels.TaskItem> items = p.getContent().stream()
+                .map(this::toTaskItem).collect(Collectors.toList());
+        fillInstanceInfo(items);
+        return toResult(p.getTotalElements(), items, page, size);
+    }
+
+    /**
+     * 办件详情：快照 + 任务轨迹 + 分支进度 + 本人待办标记（办理页/详情页共用数据源）。
+     * viewerId 必须由控制器从 BoaUser.getId() 传入（CAS 会话 LoginUser.userId 是登录名字符串，
+     * 不是数字主键，不能直接转 Integer——2026-09-12 全链测试修复）。
+     */
+    public FlowModels.InstanceDetail detail(Long schId, Long instanceId, Integer viewerId) {
+        FlwInstance instance = instanceRepository.findById(instanceId)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "办件不存在"));
+        if (!instance.getSchId().equals(schId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "办件不属于该学校");
+        }
+        FlowModels.InstanceDetail detail = new FlowModels.InstanceDetail();
+        detail.setInstanceId(instance.getId());
+        detail.setSchId(instance.getSchId());
+        detail.setDefCode(instance.getDefCode());
+        detail.setDefVersion(instance.getDefVersion());
+        detail.setBizType(instance.getBizType());
+        detail.setBizId(instance.getBizId());
+        detail.setBizTitle(instance.getBizTitle());
+        detail.setBizUrl(instance.getBizUrl());
+        detail.setBizSnapshot(instance.getBizSnapshot());
+        detail.setFormDataJson(instance.getFormDataJson());
+        detail.setStatus(instance.getStatus());
+        detail.setCurrentNodes(instance.getCurrentNodes());
+        detail.setSubmitterId(instance.getSubmitterId());
+        detail.setSubmitterName(instance.getSubmitterName());
+        detail.setSubmitTime(str(instance.getSubmitTime()));
+        detail.setFinishTime(str(instance.getFinishTime()));
+        detail.setVersion(instance.getVersion());
+        List<FlwTask> tasks = taskRepository.findByInstanceIdOrderByIdAsc(instanceId);
+        List<Map<String, Object>> trace = new ArrayList<>();
+        for (FlwTask t : tasks) {
+            Map<String, Object> row = new HashMap<>();
+            row.put("taskId", t.getId());
+            row.put("nodeId", t.getNodeId());
+            row.put("nodeName", t.getNodeName());
+            row.put("assigneeId", t.getAssigneeId());
+            row.put("assigneeName", t.getAssigneeName());
+            row.put("status", t.getStatus());
+            row.put("opinion", t.getOpinion());
+            row.put("arriveTime", str(t.getArriveTime()));
+            row.put("handleTime", str(t.getHandleTime()));
+            row.put("deadline", str(t.getDeadline()));
+            row.put("urgeCount", t.getUrgeCount());
+            trace.add(row);
+        }
+        detail.setTrace(trace);
+        List<Map<String, Object>> branches = new ArrayList<>();
+        for (FlwBranch b : branchRepository.findByInstanceId(instanceId)) {
+            Map<String, Object> row = new HashMap<>();
+            row.put("branchKey", b.getBranchKey());
+            row.put("status", b.getStatus());
+            branches.add(row);
+        }
+        detail.setBranches(branches);
+        List<Long> myPending = new ArrayList<>();
+        if (viewerId != null) {
+            for (FlwTask t : tasks) {
+                if (viewerId.equals(t.getAssigneeId())
+                        && t.getStatus() == FlwEnums.TaskStatus.PENDING.getCode()) {
+                    myPending.add(t.getId());
+                }
+            }
+            detail.setMyPendingTask(!myPending.isEmpty());
+            detail.setMyPendingTaskIds(myPending);
+        }
+        FlwDef def = defRepository.findById(instance.getDefId()).orElse(null);
+        detail.setNodeSummary(def == null ? "" : FlowEngine.nodeSummary(flowEngine.parseModel(def)));
+        return detail;
+    }
+
+    /** 任务定位办件详情（办理页 /task/{taskId} 数据源：UserMsg jumpPath 只带 taskId） */
+    public FlowModels.InstanceDetail taskDetail(Long schId, Long taskId, Integer viewerId) {
+        FlwTask task = taskRepository.findById(taskId)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "任务不存在：" + taskId));
+        if (!task.getSchId().equals(schId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "任务不属于该学校");
+        }
+        return detail(schId, task.getInstanceId(), viewerId);
+    }
+
+    private FlowModels.InstanceItem toInstanceItem(FlwInstance instance) {
+        FlowModels.InstanceItem item = new FlowModels.InstanceItem();
+        item.setInstanceId(instance.getId());
+        item.setBizType(instance.getBizType());
+        item.setBizId(instance.getBizId());
+        item.setBizTitle(instance.getBizTitle());
+        item.setStatus(instance.getStatus());
+        item.setCurrentNodes(instance.getCurrentNodes());
+        item.setSubmitterName(instance.getSubmitterName());
+        item.setSubmitTime(str(instance.getSubmitTime()));
+        item.setFinishTime(str(instance.getFinishTime()));
+        item.setDefVersion(instance.getDefVersion());
+        return item;
+    }
+
+    private FlowModels.TaskItem toTaskItem(FlwTask t) {
+        FlowModels.TaskItem item = new FlowModels.TaskItem();
+        item.setTaskId(t.getId());
+        item.setInstanceId(t.getInstanceId());
+        item.setNodeId(t.getNodeId());
+        item.setNodeName(t.getNodeName());
+        item.setAssigneeName(t.getAssigneeName());
+        item.setStatus(t.getStatus());
+        item.setOpinion(t.getOpinion());
+        item.setArriveTime(str(t.getArriveTime()));
+        item.setHandleTime(str(t.getHandleTime()));
+        item.setDeadline(str(t.getDeadline()));
+        item.setUrgeCount(t.getUrgeCount());
+        return item;
+    }
+
+    private void fillInstanceInfo(List<FlowModels.TaskItem> items) {
+        for (FlowModels.TaskItem item : items) {
+            FlwInstance instance = instanceRepository.findById(item.getInstanceId()).orElse(null);
+            if (instance != null) {
+                item.setBizTitle(instance.getBizTitle());
+                item.setBizType(instance.getBizType());
+                item.setBizId(instance.getBizId());
+                item.setInstanceStatus(instance.getStatus());
+            }
+        }
+    }
+
+    private static String str(LocalDateTime t) {
+        return t == null ? null : t.toString();
+    }
+
+    private static int normPage(Integer page) {
+        return page == null || page < 1 ? 0 : page - 1;
+    }
+
+    private static int normSize(Integer size) {
+        return size == null || size < 1 || size > 100 ? 10 : size;
+    }
+
+    private static <T> BasePageResult<T> toResult(long total, List<T> content, Integer page, Integer size) {
+        int pageIndex = page == null || page < 1 ? 1 : page;
+        int pageSize = size == null || size < 1 || size > 100 ? 10 : size;
+        int totalPages = (int) Math.ceil(total / (double) pageSize);
+        return new BasePageResult<>(content, (int) total, pageIndex, pageSize, totalPages,
+                pageIndex < totalPages);
+    }
+}

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

@@ -0,0 +1,145 @@
+package com.yunhai.flowcenter.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.flowcenter.engine.FlowDefModel;
+import com.yunhai.flowcenter.engine.FlowEvent;
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.entity.FlwTask;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.repository.FlwBranchRepository;
+import com.yunhai.flowcenter.repository.FlwInstanceRepository;
+import com.yunhai.flowcenter.repository.FlwTaskRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * 任务办理：抢占（UPDATE WHERE status=0 原子语义）→ 事件发布 → 事务提交。
+ * 拒绝终态清理在本事务内完成（END_REJECTED）；同意后的节点放行推进交给
+ * FlowNodeAdvanceListener 在 AFTER_COMMIT 新事务里做——会签并发办理时各方提交的
+ * 快照互相看不到对方未提交的办理行，事务内判断"节点是否全部办结"必假，
+ * 提交后重查才是唯一可靠时机（推进串行化由办件乐观锁兜底）。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FlowTaskService {
+
+    private final ObjectMapper objectMapper;
+    private final FlwTaskRepository taskRepository;
+    private final FlwInstanceRepository instanceRepository;
+    private final FlwBranchRepository branchRepository;
+    private final ApplicationEventPublisher eventPublisher;
+
+    /**
+     * 办理（同意/拒绝收敛点，概览 §8.5 不变式 2）。
+     *
+     * @return 办理后的任务（含最新状态）
+     */
+    @Transactional
+    public FlwTask handle(Long schId, Long taskId, boolean approved, String opinion, Integer operatorId) {
+        FlwTask task = taskRepository.findById(taskId)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "任务不存在：" + taskId));
+        if (!task.getSchId().equals(schId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "任务不属于该学校");
+        }
+        if (!task.getAssigneeId().equals(operatorId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "仅任务办理人本人可办理");
+        }
+        if (!approved && (opinion == null || opinion.trim().isEmpty())) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "拒绝必须填写意见");
+        }
+        // 原子抢占：affected=1 才获得办理权（防双击/并发重复推进）
+        int target = approved ? FlwEnums.TaskStatus.APPROVED.getCode() : FlwEnums.TaskStatus.REJECTED.getCode();
+        LocalDateTime now = LocalDateTime.now();
+        if (taskRepository.claimAndFinish(taskId, target, now, opinion) != 1) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "任务已被办理或已失效，请刷新");
+        }
+        FlwTask handled = taskRepository.findById(taskId).orElse(null);
+        FlwInstance instance = instanceRepository.findById(task.getInstanceId())
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "办件不存在"));
+        if (instance.getStatus() != FlwEnums.InstanceStatus.APPROVING.getCode()) {
+            // 极端并发：抢占成功但办件已被终态（如同时撤回）——本任务保持已办理态，但不做任何推进
+            log.warn("[flow-center] 办理时办件已终态：instance={} status={} taskId={}",
+                    instance.getId(), instance.getStatus(), taskId);
+            return handled;
+        }
+        Map<String, Object> data = new HashMap<>();
+        data.put("nodeId", task.getNodeId());
+        data.put("nodeName", task.getNodeName());
+        data.put("assigneeId", task.getAssigneeId());
+        data.put("assigneeName", task.getAssigneeName());
+        data.put("approved", approved);
+        if (opinion != null && !opinion.isEmpty()) {
+            data.put("opinion", opinion);
+        }
+        eventPublisher.publishEvent(FlowEvent.of(FlowEvent.Type.TASK_HANDLED,
+                instance.getId(), taskId, data));
+        if (!approved) {
+            rejectFlow(instance, task, opinion);
+        }
+        return handled;
+    }
+
+    /** END_REJECTED 拒绝终态（概览 §5.3）：同批待办失效→分支失效→办件=30→拒绝事件 */
+    private void rejectFlow(FlwInstance instance, FlwTask task, String opinion) {
+        instance.setStatus(FlwEnums.InstanceStatus.REJECTED.getCode());
+        instance.setFinishTime(LocalDateTime.now());
+        instanceRepository.saveAndFlush(instance);
+        taskRepository.invalidatePendingByInstance(instance.getId());
+        branchRepository.invalidateRunningByInstance(instance.getId());
+        Map<String, Object> data = new HashMap<>();
+        data.put("result", "REJECTED");
+        data.put("rejectNode", task.getNodeName() == null ? task.getNodeId() : task.getNodeName());
+        data.put("rejectTaskId", task.getId());
+        data.put("opinion", opinion);
+        eventPublisher.publishEvent(FlowEvent.of(FlowEvent.Type.REJECTED,
+                instance.getId(), task.getId(), data));
+    }
+
+    /** 手工催办（提交人/管理员）：urge_count+1 + URGE 事件（UserMsg 通道） */
+    @Transactional
+    public void urge(Long schId, Long taskId, int maxTimes) {
+        FlwTask task = taskRepository.findById(taskId)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "任务不存在：" + taskId));
+        if (!task.getSchId().equals(schId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "任务不属于该学校");
+        }
+        if (task.getStatus() != FlwEnums.TaskStatus.PENDING.getCode()) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "仅待办任务可催办");
+        }
+        if (maxTimes > 0 && task.getUrgeCount() >= maxTimes) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "已达催办次数上限（" + maxTimes + " 次）");
+        }
+        task.setUrgeCount(task.getUrgeCount() + 1);
+        taskRepository.save(task);
+        Map<String, Object> data = new HashMap<>();
+        data.put("taskId", taskId);
+        data.put("urgeCount", task.getUrgeCount());
+        eventPublisher.publishEvent(FlowEvent.of(FlowEvent.Type.URGE,
+                task.getInstanceId(), taskId, data));
+    }
+
+    public FlwTask requireTask(Long schId, Long taskId) {
+        FlwTask task = taskRepository.findById(taskId)
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "任务不存在：" + taskId));
+        if (!task.getSchId().equals(schId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "任务不属于该学校");
+        }
+        return task;
+    }
+
+    /** def JSON 解析（推进监听器/详情页共用） */
+    public FlowDefModel modelOf(FlwDef def) {
+        return FlowDefModel.parse(objectMapper, def.getContentJson());
+    }
+}

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

@@ -0,0 +1,288 @@
+package com.yunhai.flowcenter.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.flowcenter.entity.FlwCallbackReg;
+import com.yunhai.flowcenter.entity.FlwDef;
+import com.yunhai.flowcenter.entity.FlwInstance;
+import com.yunhai.flowcenter.engine.FlowEngine;
+import com.yunhai.flowcenter.enums.FlwEnums;
+import com.yunhai.flowcenter.model.OapiModels;
+import com.yunhai.flowcenter.repository.FlwCallbackRegRepository;
+import com.yunhai.flowcenter.repository.FlwDefRepository;
+import com.yunhai.flowcenter.repository.FlwInstanceRepository;
+import com.yunhai.flowcenter.repository.FlwTaskRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import com.yunhai.platform.utils.model.BoaUser;
+import com.yunhai.platform.openapi.client.OpenApiUserClient;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpMethod;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.client.RestTemplate;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * 托管接入件（/oapi/flow/**，V2.0 Part D #5 前置到 M1）：
+ * list/{flowGuid}/apply/instance/callback/reg——出入参与 svc-hall FlowCenterClient 逐字对齐。
+ * 鉴权靠 appKey 签名（RequireAppSignFilter 强制 401）；submitterId 按概览 §5.5 做本校校验
+ * （经 UserBase /oapi/user/byId，UserBase 不可达时 fail-closed 拒绝发起）。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class OapiFlowService {
+
+    /**
+     * 提交人本校校验开关（概览 §5.5 fail-closed 默认开）。本地开发无 UserBase 可达时置 false
+     * （application.yml flow-center.submitter-school-check.enabled），生产必须保持 true。
+     */
+    @Value("${flow-center.submitter-school-check.enabled:true}")
+    private boolean submitterCheckEnabled;
+
+    private final FlwDefRepository defRepository;
+    private final FlwInstanceRepository instanceRepository;
+    private final FlwTaskRepository taskRepository;
+    private final FlwCallbackRegRepository regRepository;
+    private final FlowInstanceService instanceService;
+    private final FlowEngine flowEngine;
+    private final ObjectMapper objectMapper;
+    private final OpenApiUserClient userClient;
+
+    /** 已发布流程列表（每条流程线取最高已发布版本） */
+    public List<OapiModels.FlowSummaryVo> listFlows(Long schId) {
+        List<OapiModels.FlowSummaryVo> out = new ArrayList<>();
+        for (FlwDef def : defRepository.findPublishedLatestPerGuid(schId)) {
+            out.add(toSummary(def));
+        }
+        return out;
+    }
+
+    /** 流程详情回显（未发布/不存在返回 null，消费方按"未绑定流程"降级） */
+    public OapiModels.FlowSummaryVo getFlow(Long schId, String flowGuid) {
+        return defRepository.findFirstBySchIdAndFlowGuidAndStatusOrderByVersionDesc(
+                        schId, flowGuid, FlwEnums.DefStatus.PUBLISHED.getCode())
+                .map(this::toSummary).orElse(null);
+    }
+
+    /** 代发起（biz uk 幂等 + R4 重启重提，见 FlowInstanceService） */
+    @Transactional
+    public OapiModels.ApplyResultVo apply(Long schId, OapiModels.ApplyBody body) {
+        if (schId == null || body.getFlowGuid() == null || body.getBizType() == null
+                || body.getBizId() == null || body.getSubmitterId() == null) {
+            throw new BizException(ErrorCode.PARAM_ERROR,
+                    "缺少必要参数：schId/flowGuid/bizType/bizId/submitterId");
+        }
+        requireSchoolMember(schId, body.getSubmitterId());
+        FlwDef def = defRepository.findFirstBySchIdAndFlowGuidAndStatusOrderByVersionDesc(
+                        schId, body.getFlowGuid(), FlwEnums.DefStatus.PUBLISHED.getCode())
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR,
+                        "流程不存在或未发布：" + body.getFlowGuid()));
+        FlowInstanceService.ApplyCommand cmd = new FlowInstanceService.ApplyCommand(
+                schId, def,
+                body.getBizType(), body.getBizId(), body.getBizTitle(),
+                body.getBizUrl(), asSnapshotString(body.getBizSnapshot()),
+                body.getSubmitterId(), body.getSubmitterName(),
+                asFormDataString(body.getFormData()));
+        FlowInstanceService.ApplyOutcome outcome = instanceService.apply(cmd);
+        OapiModels.ApplyResultVo vo = new OapiModels.ApplyResultVo();
+        vo.setInstanceId(outcome.getInstanceId());
+        vo.setDuplicated(outcome.isDuplicated());
+        return vo;
+    }
+
+    /** 按业务键查办件（对账兜底；不存在返回 null——对账方按"漂移待清理"处理） */
+    public OapiModels.InstanceVo instanceByBiz(Long schId, String bizType, String bizId) {
+        FlwInstance instance = instanceRepository.findBySchIdAndBizTypeAndBizId(schId, bizType, bizId)
+                .orElse(null);
+        return instance == null ? null : toInstanceVo(instance);
+    }
+
+    /** 回调注册（uk: sch+appKey+flowGuid；重复注册=更新配置并重置 secret；注册时探活） */
+    @Transactional
+    public OapiModels.CallbackRegResultVo registerCallback(Long schId, String appKey,
+                                                           OapiModels.CallbackRegBody body) {
+        if (schId == null || appKey == null || body.getFlowGuid() == null || body.getCallbackUrl() == null) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "缺少必要参数：schId/flowGuid/callbackUrl");
+        }
+        // 绑定的流程须存在（草稿也允许先注册，发布后事件即按订阅分发）
+        defRepository.findFirstBySchIdAndFlowGuidOrderByVersionDesc(schId, body.getFlowGuid())
+                .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR,
+                        "流程不存在：" + body.getFlowGuid()));
+        String secret = uuid32();
+        FlwCallbackReg reg = regRepository.findBySchIdAndAppKeyAndFlowGuid(schId, appKey, body.getFlowGuid())
+                .orElse(null);
+        if (reg == null) {
+            reg = new FlwCallbackReg();
+            reg.setSchId(schId);
+            reg.setAppKey(appKey);
+            reg.setFlowGuid(body.getFlowGuid());
+        }
+        reg.setCallbackUrl(body.getCallbackUrl());
+        reg.setEventTypes(body.getEventTypes());
+        reg.setSecret(secret);
+        reg.setStatus(0);
+        regRepository.saveAndFlush(reg);
+        probeReachable(body.getCallbackUrl(), body.getFlowGuid(), secret);
+        OapiModels.CallbackRegResultVo vo = new OapiModels.CallbackRegResultVo();
+        vo.setSecret(secret);
+        return vo;
+    }
+
+    /**
+     * 可达性探活（概览 §十：拦住配错域名的低级故障）。只做连接级判定：
+     * 连不上（未知主机/拒绝/超时）视为不可达并拒绝注册；任何 HTTP 状态码（含 401/404）
+     * 都算可达——接收方验签过滤器在拿到 secret 前必然拒绝 ping，鉴权语义不在此验证。
+     */
+    private void probeReachable(String callbackUrl, String flowGuid, String secret) {
+        try {
+            RestTemplate template = rawTemplate();
+            HttpHeaders headers = new HttpHeaders();
+            headers.setContentType(MediaType.APPLICATION_JSON);
+            headers.set("X-Flw-EventId", uuid32());
+            headers.set("X-Flw-Timestamp", String.valueOf(System.currentTimeMillis()));
+            headers.set("X-Flw-Nonce", uuid32().substring(0, 16));
+            headers.set("X-Flw-Signature", "ping");
+            Map<String, Object> ping = new HashMap<>();
+            ping.put("eventId", uuid32());
+            ping.put("event", "ping");
+            ping.put("flowGuid", flowGuid);
+            ping.put("occurredTime", System.currentTimeMillis());
+            template.exchange(callbackUrl, HttpMethod.POST, new HttpEntity<>(ping, headers), String.class);
+        } catch (Exception e) {
+            Throwable root = rootCause(e);
+            log.warn("[flow-center] 回调地址探活失败：url={} cause={}", callbackUrl, root.toString());
+            throw new BizException(ErrorCode.PARAM_ERROR, "回调地址不可达：" + root.getMessage());
+        }
+    }
+
+    private RestTemplate rawTemplate() {
+        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
+        factory.setConnectTimeout(3000);
+        factory.setReadTimeout(3000);
+        return new RestTemplate(factory);
+    }
+
+    private static Throwable rootCause(Throwable e) {
+        Throwable cur = e;
+        while (cur.getCause() != null && cur.getCause() != cur) {
+            cur = cur.getCause();
+        }
+        return cur;
+    }
+
+    /** submitterId 本校校验（防跨租户脏数据，概览 §5.5；UserBase 不可达 fail-closed） */
+    private void requireSchoolMember(Long schId, Integer submitterId) {
+        if (!submitterCheckEnabled) {
+            log.warn("[flow-center] 提交人本校校验已关闭（仅限本地开发）: schId={} submitterId={}", schId, submitterId);
+            return;
+        }
+        BoaUser user;
+        try {
+            user = userClient.getUserById(String.valueOf(submitterId));
+        } catch (Exception e) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "提交人身份核验失败（UserBase 不可达）");
+        }
+        if (user == null) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "提交人不存在：" + submitterId);
+        }
+        Long userSchId = user.getSchool() == null || user.getSchool().getId() == null
+                ? null : Long.valueOf(user.getSchool().getId());
+        if (!schId.equals(userSchId)) {
+            throw new BizException(ErrorCode.FORBIDDEN, "提交人不属于该学校（防跨租户脏数据）");
+        }
+    }
+
+    private OapiModels.FlowSummaryVo toSummary(FlwDef def) {
+        OapiModels.FlowSummaryVo vo = new OapiModels.FlowSummaryVo();
+        vo.setFlowGuid(def.getFlowGuid());
+        vo.setName(def.getName());
+        vo.setVersion(def.getVersion());
+        vo.setNodeSummary(FlowEngine.nodeSummary(flowEngine.parseModel(def)));
+        return vo;
+    }
+
+    /** 办件出参：轨迹（含 assigneeId，拍板项#3 办理人放行判定依赖） */
+    public OapiModels.InstanceVo toInstanceVo(FlwInstance instance) {
+        OapiModels.InstanceVo vo = new OapiModels.InstanceVo();
+        vo.setInstanceId(instance.getId());
+        vo.setStatus(instance.getStatus());
+        vo.setVersion(instance.getVersion());
+        vo.setBizTitle(instance.getBizTitle());
+        vo.setCurrentNodes(instance.getCurrentNodes());
+        vo.setSubmitterId(instance.getSubmitterId());
+        vo.setSubmitterName(instance.getSubmitterName());
+        vo.setSubmitTime(instance.getSubmitTime() == null ? null : instance.getSubmitTime().toString());
+        vo.setFinishTime(instance.getFinishTime() == null ? null : instance.getFinishTime().toString());
+        List<com.yunhai.flowcenter.entity.FlwTask> tasks =
+                taskRepository.findByInstanceIdOrderByIdAsc(instance.getId());
+        List<Map<String, Object>> trace = new ArrayList<>();
+        Set<Integer> assigneeIds = new LinkedHashSet<>();
+        for (com.yunhai.flowcenter.entity.FlwTask t : tasks) {
+            assigneeIds.add(t.getAssigneeId());
+            Map<String, Object> row = new HashMap<>();
+            row.put("taskId", t.getId());
+            row.put("nodeId", t.getNodeId());
+            row.put("nodeName", t.getNodeName());
+            row.put("assigneeId", t.getAssigneeId());
+            row.put("assigneeName", t.getAssigneeName());
+            row.put("status", t.getStatus());
+            row.put("opinion", t.getOpinion());
+            row.put("arriveTime", t.getArriveTime() == null ? null : t.getArriveTime().toString());
+            row.put("handleTime", t.getHandleTime() == null ? null : t.getHandleTime().toString());
+            trace.add(row);
+        }
+        try {
+            vo.setTraceJson(objectMapper.writeValueAsString(trace));
+        } catch (Exception e) {
+            vo.setTraceJson("[]");
+        }
+        vo.setAssigneeIds(new ArrayList<>(assigneeIds));
+        FlwDef def = defRepository.findById(instance.getDefId()).orElse(null);
+        vo.setNodeSummary(def == null ? "" : FlowEngine.nodeSummary(flowEngine.parseModel(def)));
+        return vo;
+    }
+
+    private String asSnapshotString(Object bizSnapshot) {
+        if (bizSnapshot == null) {
+            return null;
+        }
+        if (bizSnapshot instanceof String) {
+            return (String) bizSnapshot;
+        }
+        try {
+            return objectMapper.writeValueAsString(bizSnapshot);
+        } catch (Exception e) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "bizSnapshot 不是可序列化的摘要内容");
+        }
+    }
+
+    private String asFormDataString(Map<String, Object> formData) {
+        if (formData == null || formData.isEmpty()) {
+            return null;
+        }
+        try {
+            return objectMapper.writeValueAsString(formData);
+        } catch (Exception e) {
+            throw new BizException(ErrorCode.PARAM_ERROR, "formData 不是合法的 JSON 对象");
+        }
+    }
+
+    private static String uuid32() {
+        return UUID.randomUUID().toString().replace("-", "").toLowerCase();
+    }
+}