problems = new ArrayList<>();
+ VariableContract.validateDefinition(model, false);
if (model.nodes == null || model.nodes.isEmpty()) {
throw new BizException(ErrorCode.PARAM_ERROR, "流程定义缺少节点");
@@ -248,7 +249,7 @@ public final class DefValidator {
* （命名/唯一/同分支上下文由度约束段复用 {@link #validateOutlets} 口径）。
*
* EXPRESSION 模式（2026-10-10 四议题）分层校验：语法错/出口缺条件 → 发布期硬拦
- * （表单变量是子应用运行时传的，发布期无从核对 schema，一律放行、缺失按 null 注入求值）。
+ * 新契约的变量引用/类型/值域由 VariableContract 统一检查；历史无声明版本保持兼容。
*/
private static void validateCondition(FlowDefModel model, FlowDefModel.Node n, Set enabledRouterKeys,
List problems) {
diff --git a/src/main/java/com/yunhai/flowcenter/engine/FlowAdvanceService.java b/src/main/java/com/yunhai/flowcenter/engine/FlowAdvanceService.java
index 08f14ca..ef0e950 100644
--- a/src/main/java/com/yunhai/flowcenter/engine/FlowAdvanceService.java
+++ b/src/main/java/com/yunhai/flowcenter/engine/FlowAdvanceService.java
@@ -1,81 +1,201 @@
package com.yunhai.flowcenter.engine;
-import com.yunhai.flowcenter.entity.FlwDef;
-import com.yunhai.flowcenter.entity.FlwInstance;
-import com.yunhai.flowcenter.entity.FlwTask;
+import com.yunhai.flowcenter.entity.*;
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 com.yunhai.flowcenter.repository.*;
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;
+import org.springframework.transaction.annotation.*;
-/**
- * 节点放行推进（AFTER_COMMIT 监听器经代理调用本 bean，REQUIRES_NEW 生效——
- * 事务已提交后的同步监听阶段没有活动事务，@Modifying 批量语句必须有新事务承载）：
- * 该节点待办清零且办件在途才推进；并发冲突由 flw_instance.version 乐观锁暴露，监听器层负责重试。
- */
-@Slf4j
+import javax.persistence.EntityManager;
+import javax.persistence.PersistenceContext;
+import java.time.LocalDateTime;
+import java.util.*;
+
+/** D09: durable activation membership, serialized last-handler payload, and revision-scoped settlement. */
@Service
@RequiredArgsConstructor
public class FlowAdvanceService {
-
private final FlwInstanceRepository instanceRepository;
private final FlwDefRepository defRepository;
private final FlwTaskRepository taskRepository;
private final FlowEngine flowEngine;
+ private final FlwAdvanceIntentRepository intentRepository;
+ @PersistenceContext private EntityManager entityManager;
+
+ /** The listener groups the existing totalTasks TASK_CREATED events within their creation transaction. */
+ @Transactional(propagation = Propagation.MANDATORY)
+ public Long registerTask(FlowEvent event, Long activationIntentId) {
+ String nodeId = (String) event.getData().get("nodeId");
+ FlwAdvanceIntent intent;
+ if (activationIntentId == null) {
+ FlwInstance instance = instanceRepository.findById(event.getInstanceId()).orElseThrow(IllegalStateException::new);
+ intent = new FlwAdvanceIntent();
+ intent.setInstanceId(instance.getId());intent.setNodeId(nodeId);
+ intent.setActivationTaskId(event.getTaskId());
+ intent.setActivationDefId(instance.getDefId());intent.setActivationDefVersion(instance.getDefVersion());
+ intent.setActivationApplyRound(instance.getApplyRound());
+ intent.setStatus(FlwAdvanceIntent.STATE_DONE); // Registration only; no advance work before handling.
+ intent.setNextRetryAt(LocalDateTime.now());
+ } else {
+ intent = intentRepository.findById(activationIntentId).orElseThrow(IllegalStateException::new);
+ if (!Objects.equals(intent.getInstanceId(), event.getInstanceId()) || !Objects.equals(intent.getNodeId(), nodeId)) {
+ throw new IllegalStateException("Activation registration identity mismatch");
+ }
+ }
+ intent.addTask(event.getTaskId());
+ return intentRepository.save(intent).getId();
+ }
+
+ /** TRANSFERRED lacks the parent task ID. Accept only a uniquely proven parent activation, never guess by max ID. */
+ @Transactional(propagation = Propagation.MANDATORY)
+ public void registerTransfer(FlowEvent event) {
+ String nodeId = (String) event.getData().get("fromNodeId");
+ List generations = intentRepository.findByInstanceIdAndNodeIdOrderByIdDesc(event.getInstanceId(), nodeId);
+ Set parents = new HashSet<>();
+ List candidates = taskRepository.findTransferParentCandidates(event.getTaskId(), event.getOperatorId());
+ for (Long taskId : candidates) {
+ FlwAdvanceIntent parent = memberOf(generations, taskId);
+ if (parent == null) throw new IllegalStateException("D09 transfer parent requires audited activation backfill");
+ parents.add(parent.getId());
+ }
+ if (parents.size() != 1) throw new IllegalStateException("D09 ambiguous transfer activation; parent identity is required");
+ FlwAdvanceIntent parent = lockIntent(parents.iterator().next());
+ parent.addTask(event.getTaskId());
+ intentRepository.save(parent);
+ }
+
+ /** Called synchronously in the task transaction, after claimAndFinish. The head lock orders commits, not clocks/IDs. */
+ @Transactional(propagation = Propagation.MANDATORY)
+ public void recordHandled(FlowEvent event) {
+ String nodeId = (String) event.getData().get("nodeId");
+ FlwAdvanceIntent candidate = memberOf(intentRepository.findByInstanceIdAndNodeIdOrderByIdDesc(event.getInstanceId(), nodeId), event.getTaskId());
+ if (candidate == null) throw new IllegalStateException("D09 task has no proven activation; audited backfill required");
+ FlwAdvanceIntent intent = lockIntent(candidate.getId());
+ if (intent.handledTask(event.getTaskId())) return; // Duplicate/late publication cannot rewind the last handler.
+ intent.addHandledTask(event.getTaskId());intent.setTriggerTaskId(event.getTaskId());
+ intent.setEdgeName((String) event.getData().get("edgeName"));
+ intent.setAssigneeId((Integer) event.getData().get("assigneeId"));
+ intent.setAssigneeName((String) event.getData().get("assigneeName"));
+ intent.setStatus(FlwAdvanceIntent.STATE_PENDING);intent.setAttempts(0);
+ intent.setNextRetryAt(LocalDateTime.now());intent.setLastError(null);
+ intentRepository.save(intent);
+ }
+
+ public static final class IntentRef {
+ public final Long id;
+ public final Long revision;
+ public IntentRef(Long id, Long revision) { this.id = id; this.revision = revision; }
+ }
+
+ @Transactional(propagation = Propagation.REQUIRES_NEW, readOnly = true)
+ public IntentRef pendingForTask(Long instanceId, String nodeId, Long taskId) {
+ FlwAdvanceIntent intent = memberOf(intentRepository.findByInstanceIdAndNodeIdOrderByIdDesc(instanceId, nodeId), taskId);
+ return intent == null || !FlwAdvanceIntent.STATE_PENDING.equals(intent.getStatus()) ? null
+ : new IntentRef(intent.getId(), intent.getRevision());
+ }
/**
- * @param nodeId 待放行节点
- * @param edgeName 多出口节点所选出口（办理事件携带）；可空——兜底从该节点
- * 最近一条已同意任务的 edge_name 列重放（推进在 AFTER_COMMIT 新事务重查，
- * 事件传参只是快路径，落库的值才是权威）
- * @param operator 本节点办理人（TASK_HANDLED 事件 data 穿透；推进产生的
- * TASK_CREATED/COMPLETED 操作人信封字段来源），可空
- * @return 是否实际推进了
+ * One transaction owns validation, engine effects and settlement. RC sees the last committed task status;
+ * the head lock serializes against last-handler refresh, and instance @Version fences reactivation writes.
*/
- @Transactional(propagation = Propagation.REQUIRES_NEW)
- public boolean tryAdvance(Long instanceId, String nodeId, String edgeName, FlowOperator operator) {
- FlwInstance instance = instanceRepository.findById(instanceId).orElse(null);
- if (instance == null
- || instance.getStatus() != FlwEnums.InstanceStatus.APPROVING.getCode()) {
+ @Transactional(propagation = Propagation.REQUIRES_NEW, isolation = Isolation.READ_COMMITTED)
+ public boolean tryAdvance(Long intentId, Long observedRevision) {
+ FlwAdvanceIntent intent = lockIntent(intentId);
+ if (!ownsRevision(intent, observedRevision)) return false;
+ FlwAdvanceIntent latest = intentRepository.findFirstByInstanceIdAndNodeIdAndActivationTaskIdIsNotNullOrderByIdDesc(
+ intent.getInstanceId(), intent.getNodeId()).orElse(null);
+ if (latest != null && !Objects.equals(latest.getId(), intent.getId())) {
+ done(intent, "D09_STALE_ACTIVATION: successor=" + latest.getId());
+ handoff(latest.getId());
return false;
}
- // 已推进过的节点不再放行（currentNodes 由引擎在放行时移除，乐观锁保证互斥）
- String current = instance.getCurrentNodes();
- boolean active = current != null && java.util.Arrays.stream(current.split(","))
- .anyMatch(nodeId::equals);
- if (!active) {
+ if (intent.getActivationTaskId() == null || !intent.containsTask(intent.getActivationTaskId())
+ || intent.getTriggerTaskId() == null || !intent.handledTask(intent.getTriggerTaskId())) {
+ hold(intent, "D09_UNANCHORED: audited cohort/last-handler backfill required; not executed");
return false;
}
- long pending = taskRepository.findByInstanceIdAndStatus(instanceId,
- FlwEnums.TaskStatus.PENDING.getCode()).stream()
- .filter(t -> nodeId.equals(t.getNodeId()))
- .count();
- if (pending > 0) {
- return false;
+ FlwInstance instance = instanceRepository.findById(intent.getInstanceId()).orElse(null);
+ if (instance == null || instance.getStatus() != FlwEnums.InstanceStatus.APPROVING.getCode()
+ || !active(instance, intent.getNodeId())) {
+ done(intent, null);return false;
}
- FlwDef def = defRepository.findById(instance.getDefId()).orElse(null);
- if (def == null) {
- log.error("[flow-center] 办件定义缺失，推进中止：instance={} defId={}",
- instanceId, instance.getDefId());
- return false;
+ if (!Objects.equals(instance.getDefId(), intent.getActivationDefId())
+ || !Objects.equals(instance.getDefVersion(), intent.getActivationDefVersion())
+ || !Objects.equals(instance.getApplyRound(), intent.getActivationApplyRound())) {
+ hold(intent, "D09_IDENTITY_MISMATCH: no proven successor; audited backfill required");return false;
}
- String chosen = edgeName;
- if (chosen == null) {
- chosen = taskRepository.findByInstanceIdAndStatus(instanceId,
- FlwEnums.TaskStatus.APPROVED.getCode()).stream()
- .filter(t -> nodeId.equals(t.getNodeId()) && t.getEdgeName() != null)
- .max(java.util.Comparator.comparing(
- FlwTask::getHandleTime, java.util.Comparator.nullsFirst(java.util.Comparator.naturalOrder())))
- .map(FlwTask::getEdgeName)
- .orElse(null);
+ boolean pending = taskRepository.findByInstanceIdAndStatus(instance.getId(), FlwEnums.TaskStatus.PENDING.getCode())
+ .stream().anyMatch(t -> intent.getNodeId().equals(t.getNodeId()));
+ if (pending) {
+ // A future handler holds/obtains this same head lock and must re-arm it in its task transaction.
+ done(intent, null);return false;
}
- flowEngine.continueAdvance(instance, def, nodeId, chosen, operator);
- instanceRepository.save(instance);
+ FlwTask trigger = taskRepository.findById(intent.getTriggerTaskId()).orElse(null);
+ if (trigger == null || !intent.containsTask(trigger.getId())
+ || !Objects.equals(trigger.getInstanceId(), instance.getId())
+ || !Objects.equals(trigger.getNodeId(), intent.getNodeId())
+ || !Integer.valueOf(FlwEnums.TaskStatus.APPROVED.getCode()).equals(trigger.getStatus())) {
+ hold(intent, "D09_INVALID_LAST_HANDLER: not executed");return false;
+ }
+ FlwDef def = defRepository.findById(instance.getDefId()).orElseThrow(() -> new IllegalStateException("Missing activation definition"));
+ flowEngine.continueAdvance(instance, def, intent.getNodeId(), trigger.getEdgeName(),
+ FlowOperator.of(trigger.getAssigneeId(), trigger.getAssigneeName()));
+ if (active(instance, intent.getNodeId())) throw new IllegalStateException("Activation did not advance; retaining recoverable intent");
+ instanceRepository.saveAndFlush(instance); // An optimistic conflict rolls back engine writes AND settlement.
+ done(intent, null);
return true;
}
+
+ /** Never merge a worker's detached row. A refreshed revision owns its own retry budget. */
+ @Transactional(propagation = Propagation.REQUIRES_NEW)
+ public void defer(Long intentId, Long observedRevision, String error) {
+ FlwAdvanceIntent intent = lockIntent(intentId);
+ if (!ownsRevision(intent, observedRevision)) return;
+ intent.setAttempts(intent.getAttempts() + 1);intent.setLastError(truncate(error));
+ if (intent.getAttempts() >= 6) intent.setStatus(FlwAdvanceIntent.STATE_EXHAUSTED);
+ else intent.setNextRetryAt(LocalDateTime.now().plusSeconds(Math.min(1800, 30L * (1L << (intent.getAttempts() - 1)))));
+ intentRepository.save(intent);
+ }
+
+ private FlwAdvanceIntent lockIntent(Long id) {
+ // Queries in a handling transaction may already have loaded a stale RR snapshot into the identity map.
+ // A lock upgrade on that managed row checks its obsolete @Version before refresh can run.
+ // Flush our own changes, detach ONLY this row, then load a new managed row with a locking current read.
+ entityManager.flush();
+ FlwAdvanceIntent cached = entityManager.find(FlwAdvanceIntent.class, id);
+ if (cached != null) entityManager.detach(cached);
+ return intentRepository.findByIdForUpdate(id).orElse(null);
+ }
+
+ private void handoff(Long successorId) {
+ FlwAdvanceIntent successor = lockIntent(successorId);
+ // A stale worker must not consume its successor. Re-arm a previously waiting head, retaining its own payload.
+ if (successor != null && successor.getTriggerTaskId() != null && FlwAdvanceIntent.STATE_DONE.equals(successor.getStatus())) {
+ successor.setStatus(FlwAdvanceIntent.STATE_PENDING);successor.setAttempts(0);
+ successor.setNextRetryAt(LocalDateTime.now());successor.setLastError(null);intentRepository.save(successor);
+ }
+ }
+
+ private static FlwAdvanceIntent memberOf(List intents, Long taskId) {
+ FlwAdvanceIntent found = null;
+ for (FlwAdvanceIntent intent : intents) if (intent.containsTask(taskId)) {
+ if (found != null && !Objects.equals(found.getId(), intent.getId())) throw new IllegalStateException("Task belongs to multiple activations");
+ found = intent;
+ }
+ return found;
+ }
+ private static boolean ownsRevision(FlwAdvanceIntent intent, Long revision) {
+ return intent != null && FlwAdvanceIntent.STATE_PENDING.equals(intent.getStatus()) && Objects.equals(intent.getRevision(), revision);
+ }
+ private static boolean active(FlwInstance instance, String nodeId) {
+ return instance.getCurrentNodes() != null && Arrays.asList(instance.getCurrentNodes().split(",")).contains(nodeId);
+ }
+ private void done(FlwAdvanceIntent intent, String reason) {
+ intent.setStatus(FlwAdvanceIntent.STATE_DONE);intent.setLastError(reason);intentRepository.save(intent);
+ }
+ private void hold(FlwAdvanceIntent intent, String reason) {
+ intent.setStatus(FlwAdvanceIntent.STATE_EXHAUSTED);intent.setLastError(reason);intentRepository.save(intent);
+ }
+ private static String truncate(String s) { return s == null || s.length() <= 255 ? s : s.substring(0,255); }
}
diff --git a/src/main/java/com/yunhai/flowcenter/engine/FlowDefModel.java b/src/main/java/com/yunhai/flowcenter/engine/FlowDefModel.java
index db0076c..64c2f67 100644
--- a/src/main/java/com/yunhai/flowcenter/engine/FlowDefModel.java
+++ b/src/main/java/com/yunhai/flowcenter/engine/FlowDefModel.java
@@ -56,6 +56,18 @@ public class FlowDefModel {
public List nodes;
public List edges;
public Settings settings;
+ /** null = 历史无契约版本；新发布必须显式声明（无业务变量时为 []）。 */
+ public List variables;
+
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static class Variable {
+ public String key;
+ /** string/number/boolean/date/datetime/money/stringArray/fileArray/userArray */
+ public String type;
+ public Boolean required;
+ @com.fasterxml.jackson.annotation.JsonProperty("enum")
+ public List enumValues;
+ }
/**
* 画布坐标（nodeId → 左上角），仅前端设计器/查看器复用；引擎不消费。
* 缺失时前端自行做自动布局，故可选、可空。
diff --git a/src/main/java/com/yunhai/flowcenter/engine/FlowEngine.java b/src/main/java/com/yunhai/flowcenter/engine/FlowEngine.java
index 6c9bb7f..d1b7543 100644
--- a/src/main/java/com/yunhai/flowcenter/engine/FlowEngine.java
+++ b/src/main/java/com/yunhai/flowcenter/engine/FlowEngine.java
@@ -45,6 +45,9 @@ public class FlowEngine {
/** 发起后首推：从 START 激活（instance 已建好、status=10）。operator=null：TASK_CREATED/COMPLETED 的操作人回退发起人 */
public void startAdvance(FlwInstance instance, FlwDef def) {
FlowDefModel model = parseModel(def);
+ // D11：整份定义的固定 USERS 先整体预检，非法人不得等到后续节点才暴露（会留下卡单）。
+ // 校验失败抛业务异常，由发起事务整体回滚（零实例零任务）。
+ assigneeResolver.requireEligibleFixedAssignees(instance.getSchId(), model);
setCurrentNodes(instance, null);
advance(instance, model, model.start, null, null);
}
diff --git a/src/main/java/com/yunhai/flowcenter/engine/FlowEvent.java b/src/main/java/com/yunhai/flowcenter/engine/FlowEvent.java
index 30eb842..84b7efc 100644
--- a/src/main/java/com/yunhai/flowcenter/engine/FlowEvent.java
+++ b/src/main/java/com/yunhai/flowcenter/engine/FlowEvent.java
@@ -71,6 +71,46 @@ public class FlowEvent {
private final Map data;
private Map roundIdentity;
+ // ===== T05 稳定事件身份（2026-10-25） =====
+ /** 事实行 event_id：发布线程同步监听器在状态事务内落事实行时一次性赋值，全订阅方/重试复用 */
+ private String stableEventId;
+ /** 事实行 event_seq（实例内单调序号） */
+ private Integer stableEventSeq;
+ /**
+ * R2（Codex D04）冻结信封：事实落库时一次性构建的完整投递载荷 JSON（含 eventId/eventSeq/
+ * flowGuid 等全部信封字段）。正常分发与崩溃恢复分发共用同一份冻结体——恢复消息体不再缺
+ * eventId/eventSeq，两条路径字节级同构。事实行缺席（存量路径）为 null，由分发器现场构建。
+ */
+ private String stablePayloadJson;
+
+ public void assignStableIdentity(String eventId, Integer eventSeq) {
+ if (this.stableEventId != null) {
+ return; // 只赋一次：幂等重入（同事件多监听器）不换身份
+ }
+ this.stableEventId = eventId;
+ this.stableEventSeq = eventSeq;
+ }
+
+ public String getStableEventId() {
+ return stableEventId;
+ }
+
+ public Integer getStableEventSeq() {
+ return stableEventSeq;
+ }
+
+ /** 随稳定身份一并冻结完整投递信封（只赋一次；身份与信封同源同事务） */
+ public void assignStablePayload(String payloadJson) {
+ if (this.stablePayloadJson != null) {
+ return;
+ }
+ this.stablePayloadJson = payloadJson;
+ }
+
+ public String getStablePayloadJson() {
+ return stablePayloadJson;
+ }
+
public void captureRoundIdentity(Integer round, String requestToken) {
if (roundIdentity != null) return;
Map identity = new HashMap<>();
diff --git a/src/main/java/com/yunhai/flowcenter/engine/FlowNodeAdvanceListener.java b/src/main/java/com/yunhai/flowcenter/engine/FlowNodeAdvanceListener.java
index 1ac00c3..d0e8a93 100644
--- a/src/main/java/com/yunhai/flowcenter/engine/FlowNodeAdvanceListener.java
+++ b/src/main/java/com/yunhai/flowcenter/engine/FlowNodeAdvanceListener.java
@@ -1,50 +1,102 @@
package com.yunhai.flowcenter.engine;
+import com.yunhai.flowcenter.entity.FlwAdvanceIntent;
+import com.yunhai.flowcenter.repository.FlwAdvanceIntentRepository;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
+import org.springframework.context.event.EventListener;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
import org.springframework.orm.ObjectOptimisticLockingFailureException;
+import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
import org.springframework.transaction.event.TransactionPhase;
import org.springframework.transaction.event.TransactionalEventListener;
+import org.springframework.transaction.support.TransactionSynchronization;
+import org.springframework.transaction.support.TransactionSynchronizationManager;
-/**
- * 节点放行推进监听器：TASK_HANDLED 事件 AFTER_COMMIT 后在新事务里重查——
- * 该节点待办是否清零、办件是否仍在途，全部成立才继续推进（下一节点/JOIN 合并/END）。
- * 会签并发办理时各方提交的快照互相看不到对方未提交的办理行，事务内判断
- * "节点是否全部办结"必假，提交后重查才是唯一可靠时机；推进串行化由办件乐观锁兜底
- * （重试循环在监听器侧，跨 bean 调用 {@link FlowAdvanceService#tryAdvance} 保证 REQUIRES_NEW 生效）。
- */
+import java.time.LocalDateTime;
+import java.util.HashMap;
+import java.util.Map;
+
+/** TASK_CREATED establishes membership; TASK_HANDLED refreshes that same activation in the handling transaction. */
@Slf4j
@Component
@RequiredArgsConstructor
public class FlowNodeAdvanceListener {
-
private final FlowAdvanceService advanceService;
+ private final FlwAdvanceIntentRepository intentRepository;
+
+ @EventListener
+ @Order(Ordered.HIGHEST_PRECEDENCE + 2)
+ public void persistIntent(FlowEvent event) {
+ if (event.getData() == null) return;
+ if (event.getType() == FlowEvent.Type.TASK_CREATED) {
+ ActivationBatch batch = batch();
+ if (!batch.tasks.add(event.getTaskId())) return;
+ String key = event.getInstanceId() + ":" + event.getData().get("nodeId");
+ int total = ((Number) event.getData().get("totalTasks")).intValue();
+ if (total <= 0) throw new IllegalStateException("Missing activation batch size");
+ Registration registration = batch.nodes.get(key);
+ if (registration == null) { registration = new Registration(total);batch.nodes.put(key, registration); }
+ if (registration.total != total) throw new IllegalStateException("Activation batch size changed");
+ registration.intentId = advanceService.registerTask(event, registration.intentId);
+ if (--registration.remaining == 0) batch.nodes.remove(key);
+ } else if (event.getType() == FlowEvent.Type.TRANSFERRED) {
+ advanceService.registerTransfer(event);
+ } else if (event.getType() == FlowEvent.Type.TASK_HANDLED && event.getData().get("nodeId") != null) {
+ advanceService.recordHandled(event);
+ }
+ }
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true)
public void onTaskHandled(FlowEvent event) {
- if (event.getType() != FlowEvent.Type.TASK_HANDLED || event.getData() == null) {
- return;
- }
+ if (event.getType() != FlowEvent.Type.TASK_HANDLED || event.getData() == null) return;
String nodeId = (String) event.getData().get("nodeId");
- if (nodeId == null) {
- return;
- }
- String edgeName = (String) event.getData().get("edgeName");
- // 办理人随事件 data 穿透进推进链：新 TASK_CREATED/COMPLETED 的操作人信封字段（2026-09-20）
- FlowOperator operator = FlowOperator.of(
- (Integer) event.getData().get("assigneeId"),
- (String) event.getData().get("assigneeName"));
+ if (nodeId == null) return;
+ FlowAdvanceService.IntentRef ref = advanceService.pendingForTask(event.getInstanceId(), nodeId, event.getTaskId());
+ if (ref == null) return;
for (int attempt = 1; attempt <= 3; attempt++) {
- try {
- advanceService.tryAdvance(event.getInstanceId(), nodeId, edgeName, operator);
- return;
- } catch (ObjectOptimisticLockingFailureException e) {
- log.warn("[flow-center] 推进冲突重试 {}/3：instance={} node={}",
- attempt, event.getInstanceId(), nodeId);
+ try { advanceService.tryAdvance(ref.id, ref.revision);return; }
+ catch (ObjectOptimisticLockingFailureException conflict) {
+ log.warn("[flow-center] D09 advance conflict {}/3: intent={} revision={}", attempt, ref.id, ref.revision);
+ } catch (Exception failure) {
+ advanceService.defer(ref.id, ref.revision, failure.toString());return;
}
}
- log.error("[flow-center] 推进重试耗尽（请人工检查）：instance={} node={}",
- event.getInstanceId(), nodeId);
+ advanceService.defer(ref.id, ref.revision, "AFTER_COMMIT retries exhausted; sweep will resume");
+ }
+
+ @Scheduled(fixedDelay = 30_000)
+ public void sweepIntents() {
+ for (FlwAdvanceIntent detached : intentRepository.findTop50ByStatusAndNextRetryAtLessThanEqualOrderByCreateTimeAsc(
+ FlwAdvanceIntent.STATE_PENDING, LocalDateTime.now())) {
+ Long id = detached.getId(), revision = detached.getRevision();
+ try { advanceService.tryAdvance(id, revision); }
+ catch (Exception failure) { advanceService.defer(id, revision, failure.toString()); }
+ }
+ }
+
+ /** Synchronizations are suspended with REQUIRES_NEW; an outer activation batch cannot leak into its child. */
+ private static ActivationBatch batch() {
+ if (!TransactionSynchronizationManager.isSynchronizationActive()) throw new IllegalStateException("Activation requires its creation transaction");
+ for (TransactionSynchronization sync : TransactionSynchronizationManager.getSynchronizations()) {
+ if (sync instanceof ActivationBatch) return (ActivationBatch) sync;
+ }
+ ActivationBatch created = new ActivationBatch();
+ TransactionSynchronizationManager.registerSynchronization(created);return created;
+ }
+ private static final class ActivationBatch implements TransactionSynchronization {
+ final Map nodes = new HashMap<>();
+ final java.util.Set tasks = new java.util.HashSet<>();
+ @Override public void beforeCommit(boolean readOnly) {
+ if (!nodes.isEmpty()) throw new IllegalStateException("Incomplete activation membership; creation transaction must roll back");
+ }
+ }
+ private static final class Registration {
+ final int total;
+ int remaining;
+ Long intentId;
+ Registration(int total) { this.total = total;this.remaining = total; }
}
}
diff --git a/src/main/java/com/yunhai/flowcenter/engine/VariableContract.java b/src/main/java/com/yunhai/flowcenter/engine/VariableContract.java
new file mode 100644
index 0000000..d12d817
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/engine/VariableContract.java
@@ -0,0 +1,209 @@
+package com.yunhai.flowcenter.engine;
+
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.OffsetDateTime;
+import java.util.*;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/** D10 定义与发起共用的纯校验器；不转换输入，不依赖 FC/数据库。 */
+public final class VariableContract {
+ private VariableContract() { }
+ private static final Set TYPES = new HashSet<>(Arrays.asList(
+ "string", "number", "boolean", "date", "datetime", "money", "stringArray", "fileArray", "userArray"));
+ private static final String TOKEN = "(?:'(?:[^'\\\\]|\\\\.)*'|\"(?:[^\"\\\\]|\\\\.)*\"|-?\\d+(?:\\.\\d+)?|[A-Za-z_][A-Za-z0-9_]*)";
+ // 先分词以跳过完整字符串；不把函数参数字符串中的 "amount > 3" 当成比较。
+ private static final Pattern TOKENS = Pattern.compile(TOKEN + "|==|!=|>=|<=|>|<|\\S");
+ private static final Set COMPARISONS = new HashSet<>(Arrays.asList("==", "!=", ">=", "<=", ">", "<"));
+
+ public static Set referencedKeys(FlowDefModel model) {
+ Set keys = new LinkedHashSet<>();
+ for (FlowDefModel.Node n : model.nodes) {
+ if (n == null || !n.expressionJudge()) continue;
+ for (FlowDefModel.Edge e : model.outEdges(n.id)) {
+ if (e.condition == null || e.condition.trim().isEmpty()) continue;
+ try {
+ for (String key : ExpressionEvaluator.variableNames(e.condition.trim())) {
+ if (!DefValidator.EXPRESSION_BUILTINS.contains(key)) keys.add(key);
+ }
+ } catch (RuntimeException ex) {
+ // 历史版本保持原有语法异常跳过口径；新契约必须 fail closed。
+ if (model.variables != null) fail("表达式不合法：" + ex.getMessage());
+ }
+ }
+ }
+ return keys;
+ }
+
+ public static void validateDefinition(FlowDefModel model, boolean publishing) {
+ if (model.variables == null) {
+ if (publishing) fail("新发布版本必须声明 variables（无变量请显式声明 []）");
+ return;
+ }
+ Map fields = new LinkedHashMap<>();
+ for (FlowDefModel.Variable v : model.variables) {
+ if (v == null || v.key == null || !v.key.matches("[A-Za-z0-9_]{1,64}")) fail("变量 key 不合法");
+ if (DefValidator.EXPRESSION_BUILTINS.contains(v.key)) fail("变量不能占用内置键：" + v.key);
+ if (fields.put(v.key, v) != null) fail("变量 key 重复：" + v.key);
+ if (!TYPES.contains(v.type)) fail("变量类型不支持：" + v.key + " / " + v.type);
+ if (v.enumValues != null) {
+ if (!"string".equals(v.type) && !"stringArray".equals(v.type)) fail("enum 仅适用于字符串及字符串数组：" + v.key);
+ if (v.enumValues.isEmpty() || v.enumValues.contains(null)
+ || new HashSet<>(v.enumValues).size() != v.enumValues.size()) fail("enum 值域为空或重复：" + v.key);
+ for (String option : v.enumValues) {
+ if (blank(option)) fail("enum 值域不能含空白：" + v.key);
+ validateValue(v, "stringArray".equals(v.type) ? Collections.singletonList(option) : option, true);
+ }
+ }
+ }
+ for (String key : referencedKeys(model)) {
+ if (!fields.containsKey(key)) fail("表达式变量 " + key + " 未声明（不在关联表单字段集内或 variables 中）");
+ }
+ for (FlowDefModel.Node n : model.nodes) {
+ if (n == null || !n.expressionJudge()) continue;
+ for (FlowDefModel.Edge e : model.outEdges(n.id)) {
+ if (e.condition == null) continue;
+ Matcher m = TOKENS.matcher(e.condition);
+ List tokens = new ArrayList<>();
+ while (m.find()) tokens.add(m.group());
+ for (int i = 1; i + 1 < tokens.size(); i++) {
+ if (!COMPARISONS.contains(tokens.get(i))) continue;
+ checkLiteral(fields.get(tokens.get(i-1)), tokens.get(i+1));
+ checkLiteral(fields.get(tokens.get(i+1)), tokens.get(i-1));
+ }
+ }
+ }
+ }
+
+ private static void checkLiteral(FlowDefModel.Variable field, String token) {
+ if (field == null || "null".equals(token)) return;
+ Object value;
+ if (token.startsWith("'") || token.startsWith("\"")) {
+ // Aviator 的转义交由编译器；带转义字面量不做正则域推断。
+ if (token.indexOf('\\') >= 0) return;
+ value = token.substring(1, token.length() - 1);
+ } else if ("true".equals(token) || "false".equals(token)) value = Boolean.valueOf(token);
+ else if (token.matches("-?\\d+(\\.\\d+)?")) value = new BigDecimal(token);
+ else return;
+ try { validateValue(field, value, true); }
+ catch (BizException invalid) { fail("类型桶查②/域查③：" + invalid.getMessage()); }
+ }
+
+ public static void validateInput(FlowDefModel model, Map submitted) {
+ Set refs = referencedKeys(model);
+ if (model.variables == null) {
+ for (String key : refs) {
+ if (!submitted.containsKey(key) || submitted.get(key) == null) fail("流程条件所需变量缺失或为空（key=" + key + "）");
+ }
+ return;
+ }
+ validateDefinition(model, false);
+ Set declared = new HashSet<>();
+ for (FlowDefModel.Variable v : model.variables) {
+ declared.add(v.key);
+ validateValue(v, submitted.get(v.key), Boolean.TRUE.equals(v.required) || refs.contains(v.key));
+ }
+ for (String key : submitted.keySet()) if (!declared.contains(key)) fail("未声明的变量：" + key);
+ }
+
+ /** 必填/表达式引用均需实值；可选 null 可省略，其他非 null 值始终按类型与值域检查。 */
+ private static void validateValue(FlowDefModel.Variable v, Object value, boolean required) {
+ if (value == null) {
+ if (required) fail("变量缺失或为空：" + v.key);
+ return;
+ }
+ if (required && ((value instanceof String && blank((String) value))
+ || (value instanceof Collection && ((Collection) value).isEmpty()))) fail("变量未填写：" + v.key);
+ // FC 文本/单选和日期控件的清空值为 ""；仅非必填且未被表达式引用时视作未填。
+ // 数值控件空值是 null，不能借空字符串绕过 number/money/boolean/数组的类型检查。
+ if (!required && "".equals(value) && Arrays.asList("string", "date", "datetime").contains(v.type)) return;
+ boolean valid = false;
+ switch (v.type) {
+ case "string": valid = value instanceof String; break;
+ case "number": case "money":
+ if (value instanceof Number) {
+ try { new BigDecimal(value.toString()); valid = true; } catch (NumberFormatException ignored) { }
+ }
+ break;
+ case "boolean": valid = value instanceof Boolean; break;
+ case "date":
+ if (value instanceof String && ((String)value).matches("\\d{4}-\\d{2}-\\d{2}")) {
+ try { LocalDate.parse((String)value); valid = true; } catch (RuntimeException ignored) { }
+ }
+ break;
+ case "datetime":
+ if (value instanceof String && ((String)value).matches("\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?(Z|[+-]\\d{2}:\\d{2})?")) {
+ try { LocalDateTime.parse((String)value); valid = true; }
+ catch (RuntimeException local) {
+ try { OffsetDateTime.parse((String)value); valid = true; } catch (RuntimeException ignored) { }
+ }
+ }
+ break;
+ case "stringArray": case "fileArray": case "userArray":
+ valid = value instanceof List;
+ if (valid) for (Object item : (List)value) {
+ if ("stringArray".equals(v.type)) {
+ if (!(item instanceof String) || (v.enumValues != null && !v.enumValues.contains(item))) valid = false;
+ } else if (!validRecord(item, "fileArray".equals(v.type))) valid = false;
+ }
+ break;
+ default: break;
+ }
+ if (!valid) fail("变量类型/格式不合法：" + v.key + "（应为 " + v.type + "）");
+ if (value instanceof String && v.enumValues != null && !v.enumValues.contains(value)) fail("变量 " + v.key + " 不在枚举值域 " + v.enumValues + "：" + value);
+ }
+
+ private static boolean validRecord(Object value, boolean file) {
+ if (!(value instanceof Map)) return false;
+ Map row = (Map)value;
+ Object id = row.get("id");
+ try {
+ if (!(id instanceof Number) || new BigDecimal(id.toString()).scale() > 0 || ((Number)id).longValue() <= 0) return false;
+ } catch (NumberFormatException invalid) { return false; }
+ return file ? nonblank(row.get("fileName")) && nonblank(row.get("key")) : nonblank(row.get("name"));
+ }
+ private static boolean nonblank(Object value) { return value instanceof String && !blank((String)value); }
+ private static boolean blank(String value) {
+ return value.codePoints().allMatch(c -> Character.isWhitespace(c) || Character.isSpaceChar(c));
+ }
+
+ /** FC 快照是唯一派生来源，保存时传入的 variables 不能覆盖绑定表单的契约。 */
+ public static List fromSnapshot(Map snapshot) {
+ Object fields = snapshot.get("fields");
+ if (!(fields instanceof List)) fail("formContract.fields 必须为数组");
+ List variables = new ArrayList<>();
+ for (Object item : (List)fields) {
+ if (!(item instanceof Map)) fail("formContract 字段不合法");
+ Map field = (Map)item;
+ FlowDefModel.Variable v = new FlowDefModel.Variable();
+ v.key = (String)field.get("key");
+ v.required = Boolean.TRUE.equals(field.get("required"));
+ String type = String.valueOf(field.get("type"));
+ switch (type) {
+ case "text": case "textarea": case "phone": case "select": case "radio": v.type = "string"; break;
+ case "number": case "date": v.type = type; break;
+ case "checkbox": case "multiselect": case "address": v.type = "stringArray"; break;
+ case "image": case "upload": v.type = "fileArray"; break;
+ case "user": case "users": v.type = "userArray"; break;
+ default: fail("FC 字段类型不支持：" + v.key + " / " + type);
+ }
+ if (Arrays.asList("select", "radio", "checkbox", "multiselect").contains(type)) {
+ Object enums = field.get("enum");
+ if (!(enums instanceof List) || ((List)enums).isEmpty()) fail("FC 枚举值域缺失：" + v.key);
+ v.enumValues = new ArrayList<>();
+ for (Object option : (List)enums) {
+ if (!(option instanceof String)) fail("FC 枚举必须为字符串：" + v.key);
+ v.enumValues.add((String)option);
+ }
+ }
+ variables.add(v);
+ }
+ return variables;
+ }
+ private static void fail(String message) { throw new BizException(ErrorCode.PARAM_ERROR, message); }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwAdvanceIntent.java b/src/main/java/com/yunhai/flowcenter/entity/FlwAdvanceIntent.java
new file mode 100644
index 0000000..11bd28d
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwAdvanceIntent.java
@@ -0,0 +1,107 @@
+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.Version;
+import javax.persistence.UniqueConstraint;
+
+import java.time.LocalDateTime;
+
+/**
+ * 待推进意图（2026-10-25 T05）：任务办理事务内持久化"这个节点该继续推进了"的事实，
+ * 事务外 worker 领取执行——办理事务提交成功 ⇔ 推进意图已持久化，进程崩溃/重启后
+ * 扫描续跑（旧链路 AFTER_COMMIT 三次内存重试，耗尽只 log.error，重启即丢）。
+ *
+ * D09：每个激活批次记录精确任务成员，未办理时以 DONE 等待；办理同事务串行刷新
+ * 本批次的末笔任务及 PENDING 工作。worker 按 id+revision 锁定当前读，推进与结算同事务；
+ * NULL 代次只允许明确接棒或留待有证据的人工回填，不作为本代放行。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_advance_intent",
+ uniqueConstraints = @UniqueConstraint(name = "uk_flw_advance_activation", columnNames = "activation_task_id"),
+ indexes = {
+ @Index(name = "idx_flw_advance_intent_due", columnList = "status, next_retry_at"),
+ @Index(name = "idx_flw_advance_intent_instance", columnList = "instance_id")})
+public class FlwAdvanceIntent extends BaseEntity {
+
+ public static final String STATE_PENDING = "PENDING";
+ public static final String STATE_DONE = "DONE";
+ public static final String STATE_EXHAUSTED = "EXHAUSTED";
+
+ @Column(name = "instance_id", nullable = false)
+ private Long instanceId;
+
+ /** 触发推进的节点（TASK_HANDLED 的 nodeId） */
+ @Column(name = "node_id", nullable = false, length = 64)
+ private String nodeId;
+
+ /** First task CREATED in this activation batch; never the last task to finish. NULL = unanchored legacy work. */
+ @Column(name = "activation_task_id")
+ private Long activationTaskId;
+
+ /** Exact membership, including transfers; comma-delimited positive task IDs, e.g. ,12,14,. */
+ @Column(name = "activation_task_ids", columnDefinition = "LONGTEXT")
+ private String activationTaskIds;
+
+ @Column(name = "handled_task_ids", columnDefinition = "LONGTEXT")
+ private String handledTaskIds;
+
+ @Column(name = "trigger_task_id")
+ private Long triggerTaskId;
+
+ @Column(name = "activation_def_id")
+ private Long activationDefId;
+
+ @Column(name = "activation_def_version")
+ private Integer activationDefVersion;
+
+ @Column(name = "activation_apply_round")
+ private Integer activationApplyRound;
+
+ /** A detached worker may act/defer only the revision it actually observed. */
+ @Version
+ @Column(name = "revision", nullable = false)
+ private Long revision = 0L;
+
+ public boolean containsTask(Long id) { return contains(activationTaskIds, id); }
+ public boolean handledTask(Long id) { return contains(handledTaskIds, id); }
+ public void addTask(Long id) { if (!containsTask(id)) activationTaskIds = append(activationTaskIds, id); }
+ public void addHandledTask(Long id) { if (!handledTask(id)) handledTaskIds = append(handledTaskIds, id); }
+ private static boolean contains(String ids, Long id) { return ids != null && id != null && ids.contains("," + id + ","); }
+ private static String append(String ids, Long id) {
+ if (id == null || id <= 0) throw new IllegalArgumentException("Missing activation task identity");
+ return (ids == null ? "," : ids) + id + ",";
+ }
+
+ /** 出边名（可空=引擎默认路由） */
+ @Column(name = "edge_name", length = 128)
+ private String edgeName;
+
+ /** 办理人随行（推进链操作人信封，可空） */
+ @Column(name = "assignee_id")
+ private Integer assigneeId;
+
+ @Column(name = "assignee_name", length = 64)
+ private String assigneeName;
+
+ /** PENDING=待执行；DONE=已执行（含推进判定为无需推进的幂等结论）；EXHAUSTED=重试耗尽留人工 */
+ @Column(name = "status", nullable = false, length = 16)
+ private String status = STATE_PENDING;
+
+ @Column(name = "attempts", nullable = false)
+ private Integer attempts = 0;
+
+ /** 退避到期时间（耗尽前按指数退避续扫） */
+ @Column(name = "next_retry_at")
+ private LocalDateTime nextRetryAt;
+
+ @Column(name = "last_error", length = 255)
+ private String lastError;
+}
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwApplyCommand.java b/src/main/java/com/yunhai/flowcenter/entity/FlwApplyCommand.java
new file mode 100644
index 0000000..124023f
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwApplyCommand.java
@@ -0,0 +1,24 @@
+package com.yunhai.flowcenter.entity;
+import lombok.Getter;
+import lombok.Setter;
+import javax.persistence.*;
+/** Immutable settled command fact: ACCEPTED or REJECTED. Never repurpose a request ID. */
+@Entity @Getter @Setter
+@Table(name="flw_apply_command", uniqueConstraints=@UniqueConstraint(name="uk_flw_command_request",columnNames={"sch_id","source_principal_id","request_id"}),indexes=@Index(name="idx_flw_command_instance",columnList="instance_id"))
+public class FlwApplyCommand extends BaseEntity {
+ @Column(name="sch_id",nullable=false) private Long schId;
+ @Column(name="source_principal_id",nullable=false,length=36) private String sourcePrincipalId;
+ @Column(name="request_id",nullable=false,length=64) private String requestId;
+ @Column(name="canonical_hash",nullable=false,length=64) private String canonicalHash;
+ @Column(name="canonical_version",nullable=false) private Integer canonicalVersion;
+ @Column(name="biz_type",nullable=false,length=32) private String bizType;
+ @Column(name="biz_id",nullable=false,length=64) private String bizId;
+ @Column(name="flow_guid",nullable=false,length=32) private String flowGuid;
+ @Column(name="state",nullable=false,length=16) private String state;
+ @Column(name="instance_id") private Long instanceId;
+ @Column(name="apply_round") private Integer round;
+ @Column(name="def_version") private Integer defVersion;
+ @Column(name="def_id") private Long defId;
+ @Column(name="reject_code",length=64) private String rejectCode;
+ @Column(name="reject_detail",length=500) private String rejectDetail;
+}
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwBizCoordinate.java b/src/main/java/com/yunhai/flowcenter/entity/FlwBizCoordinate.java
new file mode 100644
index 0000000..f1d8027
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwBizCoordinate.java
@@ -0,0 +1,15 @@
+package com.yunhai.flowcenter.entity;
+import lombok.Getter;
+import lombok.Setter;
+import javax.persistence.*;
+@Entity @Getter @Setter
+@Table(name="flw_biz_coordinate", uniqueConstraints=@UniqueConstraint(name="uk_flw_coord", columnNames={"sch_id","source_principal_id","biz_type","biz_id"}))
+public class FlwBizCoordinate extends BaseEntity {
+ @Column(name="sch_id",nullable=false) private Long schId;
+ @Column(name="source_principal_id",nullable=false,length=36) private String sourcePrincipalId;
+ @Column(name="biz_type",nullable=false,length=32) private String bizType;
+ @Column(name="biz_id",nullable=false,length=64) private String bizId;
+ @Column(name="last_round",nullable=false) private Integer lastRound = 0;
+ @Column(name="last_instance_id") private Long lastInstanceId;
+ @Column(name="active_instance_id") private Long activeInstanceId;
+}
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwCallbackLog.java b/src/main/java/com/yunhai/flowcenter/entity/FlwCallbackLog.java
index a2cf36c..85d38c0 100644
--- a/src/main/java/com/yunhai/flowcenter/entity/FlwCallbackLog.java
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwCallbackLog.java
@@ -12,14 +12,16 @@ import javax.persistence.UniqueConstraint;
import java.time.LocalDateTime;
/**
- * 回调推送日志 = 重试队列（概览 §4.9）：eventId 唯一（重试不变，业务方按它幂等去重）；
+ * 回调推送日志 = 重试队列（概览 §4.9；2026-10-25 R2 幂等键改复合）：eventId 全订阅方复用
+ * （重试不变，业务方按它幂等去重），(event_id, reg_id) 复合唯一——同一事件对同一订阅方只建
+ * 一行，多订阅方各一行；并发 exists→insert 竞态由复合 uk 兜底（DuplicateKeyException=已建行）。
* payload_json 完整快照可重放；索引 (status, next_retry_time) 是扫描主路径。
*/
@Getter
@Setter
@Entity
@Table(name = "flw_callback_log",
- uniqueConstraints = @UniqueConstraint(name = "uk_flw_log_event", columnNames = "event_id"),
+ uniqueConstraints = @UniqueConstraint(name = "uk_flw_log_event_reg", columnNames = {"event_id", "reg_id"}),
indexes = {
@Index(name = "idx_flw_log_scan", columnList = "status, next_retry_time"),
@Index(name = "idx_flw_log_inst", columnList = "instance_id")})
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwCallbackReg.java b/src/main/java/com/yunhai/flowcenter/entity/FlwCallbackReg.java
index 5e04140..7f83a56 100644
--- a/src/main/java/com/yunhai/flowcenter/entity/FlwCallbackReg.java
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwCallbackReg.java
@@ -21,6 +21,9 @@ import javax.persistence.UniqueConstraint;
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="source_principal_id",length=36)
+ private String sourcePrincipalId;
+
/** 租户键 */
@Column(name = "sch_id", nullable = false)
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwCommandSource.java b/src/main/java/com/yunhai/flowcenter/entity/FlwCommandSource.java
new file mode 100644
index 0000000..e0b8e35
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwCommandSource.java
@@ -0,0 +1,10 @@
+package com.yunhai.flowcenter.entity;
+import lombok.Getter;
+import lombok.Setter;
+import javax.persistence.*;
+/** Persistent admission mutex. Rows survive application deletion; never recycle. */
+@Entity @Table(name="flw_command_source") @Getter @Setter
+public class FlwCommandSource {
+ @Id @Column(length=36) private String id;
+ @Column(nullable=false) private Integer appId;
+}
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwDef.java b/src/main/java/com/yunhai/flowcenter/entity/FlwDef.java
index edc7724..9204b9a 100644
--- a/src/main/java/com/yunhai/flowcenter/entity/FlwDef.java
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwDef.java
@@ -74,6 +74,15 @@ public class FlwDef extends BaseEntity {
@Column(name = "form_version")
private Integer formVersion;
+ /**
+ * 线级停发标志（2026-10-25 T03）：1=该 flowGuid 整线停发——阻止新发起/预览，不影响在途实例
+ * （在途按实例固定 defId 原版推进）。与版本级 status(DISABLED) 正交：线级停发后 enable()
+ * 恢复的只是版本状态，线仍不可新发起；enableLine 才恢复线可用性，且不改写任何发布内容字节。
+ * 批量 UPDATE 全版本行同值，读任一行即读线状态。
+ */
+ @Column(name = "line_offline", nullable = false, columnDefinition = "INT NOT NULL DEFAULT 0")
+ private Integer lineOffline = 0;
+
/** §5.1 流程定义 JSON */
@Column(name = "content_json", nullable = false, columnDefinition = "LONGTEXT")
private String contentJson;
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwInstance.java b/src/main/java/com/yunhai/flowcenter/entity/FlwInstance.java
index 42be69b..b8e8143 100644
--- a/src/main/java/com/yunhai/flowcenter/entity/FlwInstance.java
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwInstance.java
@@ -14,8 +14,9 @@ import java.time.LocalDateTime;
/**
* 办件实例（概览 §4.3 + V2.0 Part D）：托管模式下业务对象留在业务方，本表只存
- * biz_title/biz_url/biz_snapshot 快照与关联键；uk(sch_id, biz_type, biz_id) 幂等——
- * 同一业务对象一条办件，重复代发起返回原办件；驳回/撤回后重提复用同一行（R4 重启语义）。
+ * biz_title/biz_url/biz_snapshot 快照与关联键。正式命令每轮独立实例，唯一域为
+ * (school, sourcePrincipalId, bizType, bizId, applyRound)，单在途由坐标表事务指针保护。
+ * sourcePrincipalId=NULL / legacySlot=1 仅保留迁移前旧入口的一业务一行语义；正式模式关闭旧写入口。
*
* version 是乐观锁（推进串行化）兼回调 payload 的 instanceVersion（业务方按它丢弃乱序旧事件），
* 由 JPA @Version 在 flush 时自增。
@@ -24,12 +25,19 @@ import java.time.LocalDateTime;
@Setter
@Entity
@Table(name = "flw_instance",
- uniqueConstraints = @UniqueConstraint(name = "uk_flw_instance_biz",
- columnNames = {"sch_id", "biz_type", "biz_id"}),
+ uniqueConstraints = {
+ @UniqueConstraint(name = "uk_flw_instance_legacy", columnNames = {"sch_id", "biz_type", "biz_id", "legacy_slot"}),
+ @UniqueConstraint(name = "uk_flw_instance_round", columnNames = {"sch_id", "source_principal_id", "biz_type", "biz_id", "apply_round"})},
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="source_principal_id",length=36,updatable=false)
+ private String sourcePrincipalId;
+ /** 1 for legacy writers, NULL for formal commands. Migration must drop the old three-column UK. */
+ @Column(name="legacy_slot")
+ private Integer legacySlot = 1;
+
/** 租户键 */
@Column(name = "sch_id", nullable = false)
@@ -141,7 +149,7 @@ public class FlwInstance extends BaseEntity {
private String applyRequestToken;
/**
- * 当前发起轮次（1 起；随新一轮请求标识进位）。
+ * 当前发起轮次（1 起）。正式命令由服务端坐标锁内分配，不接受客户端 attempt 分轮。
*
*
轮次守卫是单调的：请求带来的 attempt 低于行上的 applyRound 就是陈旧轮次的迟到重投，
* 只回读现状。两侧（消费方命令行 + 本行）都持久化，崩溃恢复后仍能判出"哪一轮才是当前轮"。
@@ -149,6 +157,22 @@ public class FlwInstance extends BaseEntity {
@Column(name = "apply_round")
private Integer applyRound;
+ /**
+ * 受理时规范载荷指纹（2026-10-25 T04，SHA-256 十六进制）：同 requestToken 必须同指纹——
+ * 同 ID 不同载荷是两份命令，撞在同一个 token 上按冲突拒绝，不伪装成幂等成功。
+ * 存量行（指纹列为 NULL）跳过该核对（守卫缺省是关，与 token/round 存量纪律一致）。
+ */
+ @Column(name = "apply_payload_hash", length = 64)
+ private String applyPayloadHash;
+
+ /**
+ * 事件序号计数器（2026-10-25 T05）：实例内事件事实 eventSeq 的发号器。发号时在事务内
+ * 悲观锁住本行（findByIdForUpdate 当前读）再 +1——REPEATABLE READ 下对聚合做快照读会
+ * 拿到陈旧 max（FlowEngineIT 会签并发实证），行上计数器+行锁才是串行安全的。
+ */
+ @Column(name = "event_seq_counter")
+ private Integer eventSeqCounter;
+
/**
* 台账展示位（F11-4）：该办件是否「路由挂起」（审批中且最新 attempt 的路由判断行无出口）。
* 非持久列——由管理端办件分页（FlowAdminController.instancePage）按页查询后填充，
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwStateEvent.java b/src/main/java/com/yunhai/flowcenter/entity/FlwStateEvent.java
new file mode 100644
index 0000000..c85c3cc
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwStateEvent.java
@@ -0,0 +1,77 @@
+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;
+
+/**
+ * 流程状态事件事实（2026-10-25 T05）：状态/审批动作与不可变事件事实同一数据库事务落库。
+ *
+ * 关闭审计 E24 的丢失窗口：旧链路 AFTER_COMMIT 才按订阅生成 eventId、另事务落回调行——
+ * 提交到分发之间进程被杀，事件永久丢失（订阅方靠对账兜底）。本事实行在发布线程的同一事务内
+ * 写入：状态提交成功 ⇔ 事件事实已持久化；回调分发只是它的消费，崩溃后由 sweep 扫描补分发。
+ *
+ * 身份：{@code eventId} 在事实创建时一次性生成，全部订阅方/全部投递重试复用同一 eventId
+ * （消费端 (event_id, consumer_app_key) 唯一键去重）；{@code eventSeq} 为实例内尽力单调序号
+ * （FOR UPDATE 发号器；REQUIRES_NEW 子事务推进拓扑下极端并发窗口可能同值——有序性以
+ * eventSeq+发生时间为准，同实例严格全序需专用发号器，列入后续；不承诺全局副作用严格有序）。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_state_event",
+ uniqueConstraints = @UniqueConstraint(name = "uk_flw_state_event_id", columnNames = {"event_id"}),
+ indexes = {
+ @Index(name = "idx_flw_state_event_instance", columnList = "instance_id"),
+ @Index(name = "idx_flw_state_event_dispatch", columnList = "dispatched, create_time"),
+ @Index(name = "idx_flw_state_event_seq", columnList = "instance_id, event_seq")})
+public class FlwStateEvent extends BaseEntity {
+
+ /** 稳定事件身份（32 位 uuid 去横线；投递与重试全链复用） */
+ @Column(name = "event_id", nullable = false, length = 32)
+ private String eventId;
+
+ /** 租户键 */
+ @Column(name = "sch_id", nullable = false)
+ private Long schId;
+
+ /** 实例身份 */
+ @Column(name = "instance_id", nullable = false)
+ private Long instanceId;
+
+ /** 发布时冻结的申报轮次（旧事件不得被 AFTER_COMMIT 重读贴上新轮标签） */
+ @Column(name = "apply_round")
+ private Integer applyRound;
+
+ /** 实例内单调序号（1 起；同实例状态行锁内取 max+1） */
+ @Column(name = "event_seq", nullable = false)
+ private Integer eventSeq;
+
+ /** 事件类型码（FlowEvent.Type#getCode，与回调订阅枚举同值域） */
+ @Column(name = "event_type", nullable = false, length = 32)
+ private String eventType;
+
+ /** 关联任务（办件级事件为 null） */
+ @Column(name = "task_id")
+ private Long taskId;
+
+ /** 操作人（可空） */
+ @Column(name = "operator_id")
+ private Integer operatorId;
+
+ /** 完整载荷快照（与回调信封同构 JSON；发生时状态，不随后续变化） */
+ @Column(name = "payload_json", nullable = false, columnDefinition = "LONGTEXT")
+ private String payloadJson;
+
+ /**
+ * 分发标记：0=待分发（含崩溃窗口恢复）；1=已按当前订阅生成了全部回调行（或无可订阅方）。
+ * 分发幂等：重扫前按 (eventId, regId) 查重，不重复建投递行。
+ */
+ @Column(name = "dispatched", nullable = false)
+ private Integer dispatched = 0;
+}
diff --git a/src/main/java/com/yunhai/flowcenter/entity/FlwUsageGrant.java b/src/main/java/com/yunhai/flowcenter/entity/FlwUsageGrant.java
new file mode 100644
index 0000000..d0a913c
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/entity/FlwUsageGrant.java
@@ -0,0 +1,63 @@
+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;
+
+/**
+ * 应用使用授权（2026-10-25 T01）：哪个稳定应用主体可以在哪所学校使用哪条流程线。
+ *
+ * 与 {@link FlwApp}（定义保存白名单）和流程定义管理权（FlowAdminGuard 管理角色）三权分立：
+ * 有 flw_app 行不等于能新发起；是应用管理员也不等于能编辑/发布学校流程定义。
+ * 许可键是三元 {@code (schId, flowGuid, appId)}——appId 是 UserBase application_info 主键
+ * （稳定主体，appKey 可重置/注销后不复用历史来源），appKey 快照仅供展示回溯。
+ *
+ * 撤权语义：{@code enabled=0} 只拦截新发起；已受理命令的回执恢复、在途实例推进
+ * 不回读本表（P0-3 收口顺序：认证 → 自有命令回执 → 未命中才查新发起资格）。
+ */
+@Getter
+@Setter
+@Entity
+@Table(name = "flw_usage_grant",
+ uniqueConstraints = @UniqueConstraint(name = "uk_flw_usage_grant",
+ columnNames = {"sch_id", "flow_guid", "app_id"}),
+ indexes = {@Index(name = "idx_flw_usage_grant_sch_flow", columnList = "sch_id, flow_guid"),
+ @Index(name = "idx_flw_usage_grant_app", columnList = "app_id")})
+public class FlwUsageGrant extends BaseEntity {
+ @Column(name="source_principal_id",length=36)
+ private String sourcePrincipalId;
+
+
+ /** 租户键 */
+ @Column(name = "sch_id", nullable = false)
+ private Long schId;
+
+ /** 流程线稳定身份（跨版本不变；版本归属由 flw_def 承载） */
+ @Column(name = "flow_guid", nullable = false, length = 64)
+ private String flowGuid;
+
+ /** 稳定应用主体主键（UserBase application_info.id；非 appKey 凭据索引） */
+ @Column(name = "app_id", nullable = false)
+ private Integer appId;
+
+ /** 授权时的 appKey 快照（展示/审计回溯用；判权不读它） */
+ @Column(name = "app_key_snapshot", length = 64)
+ private String appKeySnapshot;
+
+ /** 应用名快照（授权时 UserBase 返回值；同步不自动刷新） */
+ @Column(name = "app_name_snapshot", length = 128)
+ private String appNameSnapshot;
+
+ /** 1=许可生效；0=撤销（只拦新发起） */
+ @Column(name = "enabled", nullable = false)
+ private Integer enabled = 1;
+
+ /** 备注（谁/为何授予或撤销，人工审计线索） */
+ @Column(name = "remark", length = 255)
+ private String remark;
+}
diff --git a/src/main/java/com/yunhai/flowcenter/model/FlowApplyRetryModels.java b/src/main/java/com/yunhai/flowcenter/model/FlowApplyRetryModels.java
index c8252cd..d31fc8e 100644
--- a/src/main/java/com/yunhai/flowcenter/model/FlowApplyRetryModels.java
+++ b/src/main/java/com/yunhai/flowcenter/model/FlowApplyRetryModels.java
@@ -39,6 +39,11 @@ public final class FlowApplyRetryModels {
* 这样"网络重投"与"用户授权重提"在中心侧也是两个不同的事实。
*/
private Boolean retryOnly;
+ /**
+ * 期望的前一轮次（T04 服务端轮次，可选）：显式重提必须声明基于第 N 轮；
+ * 服务端在坐标锁内核对并只分配 N+1，不信客户端 attempt。null=既有语义。
+ */
+ private Integer expectedPrevRound;
}
/** v2 响应：在旧 {instanceId,duplicated} 之上把"中心判出来的是哪一种命中"说清楚 */
@@ -74,6 +79,11 @@ public final class FlowApplyRetryModels {
public static final String REPLAY_ONLY = "REPLAY_ONLY";
public static final String RESTARTED = "RESTARTED";
public static final String CONCURRENT_CREATED = "CONCURRENT_CREATED";
+ /**
+ * 冲突（2026-10-25 T04）：同 token 异载荷、或带 token 撞上他人/其他轮次的在途与通过件——
+ * 调用方（OapiFlowService）把该分支翻译成业务异常，不伪装幂等成功。
+ */
+ public static final String CONFLICT = "CONFLICT";
private Branch() {
}
diff --git a/src/main/java/com/yunhai/flowcenter/model/FormalApplyModels.java b/src/main/java/com/yunhai/flowcenter/model/FormalApplyModels.java
new file mode 100644
index 0000000..74f9a9a
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/model/FormalApplyModels.java
@@ -0,0 +1,34 @@
+package com.yunhai.flowcenter.model;
+
+import lombok.Getter;
+import lombok.Setter;
+
+/** Service-owned v3 contract. No shared SDK DTO changes. */
+public final class FormalApplyModels {
+ private FormalApplyModels() { }
+ @Getter @Setter
+ public static class Request extends OapiModels.ApplyBody {
+ private String requestId;
+ private Long expectedPreviousInstanceId;
+ private Integer expectedPreviousRound;
+ }
+ @Getter @Setter
+ public static class Receipt {
+ private String state;
+ private String requestId;
+ private Long schoolId;
+ private String sourcePrincipalId;
+ private String canonicalHash;
+ private Integer canonicalVersion = 1;
+ private String bizType;
+ private String bizId;
+ private String flowGuid;
+ private Long instanceId;
+ private Integer round;
+ private Integer defVersion;
+ private Integer status;
+ private Integer version;
+ private String rejectCode;
+ private String rejectDetail;
+ }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/model/OapiModels.java b/src/main/java/com/yunhai/flowcenter/model/OapiModels.java
index a48a4b9..611203f 100644
--- a/src/main/java/com/yunhai/flowcenter/model/OapiModels.java
+++ b/src/main/java/com/yunhai/flowcenter/model/OapiModels.java
@@ -109,6 +109,11 @@ public final class OapiModels {
private Long instanceId;
private Integer applyRound;
private String requestToken;
+ /**
+ * 来源应用快照（2026-10-25 T04）：UNKNOWN 恢复链按"稳定来源+requestToken"核验命令归属的
+ * 依据——查得实例但 applyAppKey 与本应用不符=他人办件，不得认领（P0-4 关闭点）。
+ */
+ private String applyAppKey;
private Integer status;
private Integer version;
private String nodeSummary;
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwAdvanceIntentRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwAdvanceIntentRepository.java
new file mode 100644
index 0000000..6065599
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwAdvanceIntentRepository.java
@@ -0,0 +1,35 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwAdvanceIntent;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+import org.springframework.data.jpa.repository.Lock;
+import javax.persistence.LockModeType;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Optional;
+
+public interface FlwAdvanceIntentRepository extends JpaRepository {
+
+ /** 到点待执行：PENDING 且（无退避或已到期） */
+ @Query(value="select * from flw_advance_intent where status=:status "
+ + "and (next_retry_at is null or next_retry_at<=:now) order by create_time,id limit 50", nativeQuery=true)
+ List findTop50ByStatusAndNextRetryAtLessThanEqualOrderByCreateTimeAsc(
+ @Param("status") String status, @Param("now") LocalDateTime now);
+
+ List findByInstanceIdAndNodeIdOrderByIdDesc(Long instanceId, String nodeId);
+
+ Optional findFirstByInstanceIdAndNodeIdAndActivationTaskIdIsNotNullOrderByIdDesc(
+ Long instanceId, String nodeId);
+
+ @Lock(LockModeType.PESSIMISTIC_WRITE)
+ @Query("select i from FlwAdvanceIntent i where i.id=:id")
+ Optional findByIdForUpdate(@Param("id") Long id);
+
+ /** 幂等记账：同实例同节点是否已有未完成意图（办理事务内去重，避免并发办理堆积重复行） */
+ @Query("select count(i) > 0 from FlwAdvanceIntent i where i.instanceId = :instanceId "
+ + "and i.nodeId = :nodeId and i.status = 'PENDING'")
+ boolean existsPending(@Param("instanceId") Long instanceId, @Param("nodeId") String nodeId);
+}
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwApplyCommandRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwApplyCommandRepository.java
new file mode 100644
index 0000000..0c4a46d
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwApplyCommandRepository.java
@@ -0,0 +1,8 @@
+package com.yunhai.flowcenter.repository;
+import com.yunhai.flowcenter.entity.FlwApplyCommand;
+import org.springframework.data.jpa.repository.JpaRepository;
+import java.util.Optional;
+public interface FlwApplyCommandRepository extends JpaRepository {
+ boolean existsBySchIdAndSourcePrincipalIdAndFlowGuidAndState(Long school, String source, String flow, String state);
+ Optional findBySchIdAndSourcePrincipalIdAndRequestId(Long schId,String sourcePrincipalId,String requestId);
+}
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwBizCoordinateRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwBizCoordinateRepository.java
new file mode 100644
index 0000000..c8feb9a
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwBizCoordinateRepository.java
@@ -0,0 +1,14 @@
+package com.yunhai.flowcenter.repository;
+import com.yunhai.flowcenter.entity.FlwBizCoordinate;
+import org.springframework.data.jpa.repository.*;
+import org.springframework.data.repository.query.Param;
+import javax.persistence.LockModeType;
+import java.util.Optional;
+public interface FlwBizCoordinateRepository extends JpaRepository {
+ @Lock(LockModeType.PESSIMISTIC_WRITE)
+ @Query("select c from FlwBizCoordinate c where c.schId=:sch and c.sourcePrincipalId=:source and c.bizType=:type and c.bizId=:biz")
+ Optional lock(@Param("sch") Long sch,@Param("source") String source,@Param("type") String type,@Param("biz") String biz);
+ @Modifying
+ @Query("update FlwBizCoordinate c set c.activeInstanceId=null where c.schId=:sch and c.sourcePrincipalId=:source and c.bizType=:type and c.bizId=:biz and c.activeInstanceId=:instance and c.lastRound=:round")
+ int release(@Param("sch") Long sch,@Param("source") String source,@Param("type") String type,@Param("biz") String biz,@Param("instance") Long instance,@Param("round") Integer round);
+}
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwCallbackLogRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwCallbackLogRepository.java
index 03839d6..ee0a176 100644
--- a/src/main/java/com/yunhai/flowcenter/repository/FlwCallbackLogRepository.java
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwCallbackLogRepository.java
@@ -13,6 +13,9 @@ import java.util.List;
public interface FlwCallbackLogRepository extends JpaRepository {
+ /** T05 投递幂等：同一事件事实对同一订阅方只建一行（补分发与正常分发竞争时去重） */
+ boolean existsByEventIdAndRegId(String eventId, Long regId);
+
/** 重推扫描主路径：待推/重试中且到点 */
List findTop50ByStatusAndNextRetryTimeLessThanEqualOrderByNextRetryTimeAsc(
Integer status, LocalDateTime now);
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwCcRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwCcRepository.java
index 72c2488..cf8552a 100644
--- a/src/main/java/com/yunhai/flowcenter/repository/FlwCcRepository.java
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwCcRepository.java
@@ -14,7 +14,7 @@ public interface FlwCcRepository extends JpaRepository {
/** 抄送我的（用户面页签，走 user+sent_time 索引；appKey 可空=不按应用过滤，口径=定义归属 flw_def.app_key） */
@Query("select c from FlwCc c join FlwInstance i on i.id = c.instanceId join FlwDef d on d.id = i.defId "
+ "where c.schId = :schId and c.userId = :userId "
- + "and (:appKey is null or d.appKey = :appKey) order by c.sentTime desc")
+ + "and (:appKey is null or i.sourcePrincipalId = :appKey or (i.sourcePrincipalId is null and i.applyAppKey = :appKey)) order by c.sentTime desc")
Page pageCc(@Param("schId") Long schId, @Param("userId") Integer userId,
@Param("appKey") String appKey, Pageable pageable);
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwCommandSourceRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwCommandSourceRepository.java
new file mode 100644
index 0000000..716f64b
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwCommandSourceRepository.java
@@ -0,0 +1,10 @@
+package com.yunhai.flowcenter.repository;
+import com.yunhai.flowcenter.entity.FlwCommandSource;
+import org.springframework.data.jpa.repository.*;
+import org.springframework.data.repository.query.Param;
+import javax.persistence.LockModeType;
+import java.util.Optional;
+public interface FlwCommandSourceRepository extends JpaRepository {
+ @Lock(LockModeType.PESSIMISTIC_WRITE) @Query("select s from FlwCommandSource s where s.id=:id")
+ Optional lock(@Param("id") String id);
+}
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwDefRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwDefRepository.java
index 83f11b7..c582182 100644
--- a/src/main/java/com/yunhai/flowcenter/repository/FlwDefRepository.java
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwDefRepository.java
@@ -32,12 +32,22 @@ public interface FlwDefRepository extends JpaRepository {
List findBySchIdOrderByUpdateTimeDesc(Long schId);
- /** 已发布流程列表（oapi list 数据源）：每条流程线取最高已发布版本 */
- @Query("select d from FlwDef d where d.schId = :schId and d.status = 1 "
+ /**
+ * 已发布流程列表（oapi list 数据源）：每条流程线取最高已发布版本。
+ * 2026-10-25 T03：外层追加 {@code lineOffline=0}——线级停发的整线不出现在新发起预览源，
+ * 且不存在"停发后回退旧版"的形态（内层仍是该线已发布最高版本，停发不改变版本事实）。
+ */
+ @Query("select d from FlwDef d where d.schId = :schId and d.status = 1 and d.lineOffline = 0 "
+ "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 findPublishedLatestPerGuid(@Param("schId") Long schId);
+ /** 线级停发/恢复（T03）：批量 UPDATE 全版本行同值；返回受影响行数 */
+ @org.springframework.data.jpa.repository.Modifying
+ @Query("update FlwDef d set d.lineOffline = :offline where d.schId = :schId and d.flowGuid = :flowGuid")
+ int updateLineOffline(@Param("schId") Long schId, @Param("flowGuid") String flowGuid,
+ @Param("offline") Integer offline);
+
/** 在途统计（议题二④）：一次取回多条流程线的全部版本行 */
List findBySchIdAndFlowGuidIn(Long schId, Collection flowGuids);
}
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwInstanceRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwInstanceRepository.java
index 1cc57d6..05e6cd0 100644
--- a/src/main/java/com/yunhai/flowcenter/repository/FlwInstanceRepository.java
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwInstanceRepository.java
@@ -12,8 +12,35 @@ import java.util.List;
import java.util.Optional;
public interface FlwInstanceRepository extends JpaRepository {
+ @org.springframework.data.jpa.repository.Lock(javax.persistence.LockModeType.PESSIMISTIC_WRITE)
+ @Query("select i from FlwInstance i where i.id=:id")
+ Optional findFormalPreviousForUpdate(@Param("id") Long id);
+
+
+ /**
+ * T05 事件序号发号（2026-10-25 FlowEngineIT 会签并发实证三轮修正，终形态）：
+ * ①FOR UPDATE 标量当前读发号（取行 X 锁，任何隔离级别都看到已提交最新值）→
+ * ②按读到的值回写计数器（值已在我锁内计算，无竞态）→③事实行按该值落库。
+ * 纯快照读 max+1 会撞 uk；实体 merge 会触发 @Version 冲突；自增 UPDATE 后普通 SELECT
+ * 的读回在并发窗口同样不可靠——FOR UPDATE 标量读是唯一两全形态。
+ */
+ @org.springframework.data.jpa.repository.Query(
+ value = "select coalesce(event_seq_counter, 0) + 1 from flw_instance where id = :id for update",
+ nativeQuery = true)
+ Integer nextEventSeqForUpdate(@Param("id") Long id);
+
+ @org.springframework.data.jpa.repository.Modifying
+ @org.springframework.data.jpa.repository.Query(
+ value = "update flw_instance set event_seq_counter = :v where id = :id", nativeQuery = true)
+ int setEventSeqCounter(@Param("id") Long id, @Param("v") Integer v);
+
+ Optional findFirstBySchIdAndSourcePrincipalIdAndBizTypeAndBizIdOrderByApplyRoundDesc(Long school, String source, String type, String biz);
+
+ @Query("select i from FlwInstance i where i.schId=:school and i.sourcePrincipalId=:source and (:bizType is null or i.bizType=:bizType) and (:status is null or i.status=:status) order by i.id desc")
+ Page pageSelf(@Param("school") Long school,@Param("source") String source,@Param("bizType") String bizType,@Param("status") Integer status, Pageable pageable);
/** biz uk 幂等主键 */
+ @Query("select i from FlwInstance i where i.schId=?1 and i.bizType=?2 and i.bizId=?3 and i.sourcePrincipalId is null")
Optional findBySchIdAndBizTypeAndBizId(Long schId, String bizType, String bizId);
List findBySchIdAndSubmitterIdAndStatusOrderByIdDesc(Long schId, Integer submitterId, Integer status);
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwStateEventRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwStateEventRepository.java
new file mode 100644
index 0000000..3a77769
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwStateEventRepository.java
@@ -0,0 +1,24 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwStateEvent;
+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.List;
+
+public interface FlwStateEventRepository extends JpaRepository {
+
+ /** 实例内单调序号取号：调用方持有该实例的状态行锁（同事务状态变更），max+1 串行安全 */
+ @Query("select coalesce(max(e.eventSeq), 0) from FlwStateEvent e where e.instanceId = :instanceId")
+ int maxSeqByInstance(@Param("instanceId") Long instanceId);
+
+ /** 崩溃窗口恢复扫描：未分发且已过缓冲期（给 AFTER_COMMIT 首分发留时间） */
+ List findTop50ByDispatchedAndCreateTimeLessThanEqualOrderByCreateTimeAsc(
+ Integer dispatched, LocalDateTime deadline);
+
+ java.util.Optional findByEventId(String eventId);
+
+ boolean existsByEventId(String eventId);
+}
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwTaskRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwTaskRepository.java
index dc21dfc..f196414 100644
--- a/src/main/java/com/yunhai/flowcenter/repository/FlwTaskRepository.java
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwTaskRepository.java
@@ -13,6 +13,12 @@ import java.util.List;
public interface FlwTaskRepository extends JpaRepository {
+ /** Additive D09 query: the real transfer parent is in this set. Ambiguous generations must be rejected. */
+ @Query(value="select t.id from flw_task t join flw_task n on n.id=:newTaskId "
+ + "where t.instance_id=n.instance_id and t.node_id=n.node_id and t.status=5 "
+ + "and t.assignee_id=:operatorId and t.handle_time=n.arrive_time", nativeQuery=true)
+ List findTransferParentCandidates(@Param("newTaskId") Long newTaskId, @Param("operatorId") Integer operatorId);
+
List findByInstanceIdOrderByIdAsc(Long instanceId);
List findByInstanceIdAndStatus(Long instanceId, Integer status);
@@ -52,10 +58,13 @@ public interface FlwTaskRepository extends JpaRepository {
@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);
+ @Query("select t from FlwTask t join FlwInstance i on i.id=t.instanceId where t.schId=:school and i.sourcePrincipalId=:source and t.assigneeId=:user and t.status=0 and (:type is null or i.bizType=:type) order by t.id asc")
+ Page pageSelfTodo(@Param("school") Long school,@Param("source") String source,@Param("user") Integer user,@Param("type") String type, Pageable pageable);
+
/** 我的待办（主路径，走 assignee 索引；appKey 可空=不按应用过滤，口径=办件定义归属应用 flw_def.app_key） */
@Query("select t from FlwTask t join FlwInstance i on i.id = t.instanceId join FlwDef d on d.id = i.defId "
+ "where t.schId = :schId and t.assigneeId = :assigneeId and t.status = 0 "
- + "and (:appKey is null or d.appKey = :appKey) "
+ + "and (:appKey is null or i.sourcePrincipalId = :appKey or (i.sourcePrincipalId is null and i.applyAppKey = :appKey)) "
+ "order by t.arriveTime asc, t.id asc")
Page pageTodo(@Param("schId") Long schId, @Param("assigneeId") Integer assigneeId,
@Param("appKey") String appKey, Pageable pageable);
@@ -84,7 +93,7 @@ public interface FlwTaskRepository extends JpaRepository {
@Query("select t from FlwTask t join FlwInstance i on i.id = t.instanceId join FlwDef d on d.id = i.defId "
+ "where t.schId = :schId and t.assigneeId = :assigneeId "
+ "and t.status in :statuses "
- + "and (:appKey is null or d.appKey = :appKey) "
+ + "and (:appKey is null or i.sourcePrincipalId = :appKey or (i.sourcePrincipalId is null and i.applyAppKey = :appKey)) "
+ "and t.id = (select max(t2.id) from FlwTask t2 where t2.instanceId = t.instanceId "
+ " and t2.assigneeId = :assigneeId and t2.status in :statuses) "
+ "order by t.handleTime desc, t.id desc")
diff --git a/src/main/java/com/yunhai/flowcenter/repository/FlwUsageGrantRepository.java b/src/main/java/com/yunhai/flowcenter/repository/FlwUsageGrantRepository.java
new file mode 100644
index 0000000..ee3cd37
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/repository/FlwUsageGrantRepository.java
@@ -0,0 +1,18 @@
+package com.yunhai.flowcenter.repository;
+
+import com.yunhai.flowcenter.entity.FlwUsageGrant;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+import java.util.Optional;
+
+public interface FlwUsageGrantRepository extends JpaRepository {
+ boolean existsBySchIdAndFlowGuidAndSourcePrincipalIdAndEnabled(Long school, String flow, String source, Integer enabled);
+
+
+ Optional findBySchIdAndFlowGuidAndAppId(Long schId, String flowGuid, Integer appId);
+
+ List findBySchIdAndFlowGuidOrderByUpdateTimeDescIdDesc(Long schId, String flowGuid);
+
+ List findBySchIdAndAppIdOrderByUpdateTimeDescIdDesc(Long schId, Integer appId);
+}
diff --git a/src/main/java/com/yunhai/flowcenter/service/ApplyVariableValidator.java b/src/main/java/com/yunhai/flowcenter/service/ApplyVariableValidator.java
new file mode 100644
index 0000000..68ac889
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/service/ApplyVariableValidator.java
@@ -0,0 +1,49 @@
+package com.yunhai.flowcenter.service;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.yunhai.flowcenter.engine.FlowDefModel;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+import java.util.Map;
+import java.util.Set;
+
+/** 发起前按冻结的定义契约校验；历史无声明版本保留原有的引用变量存在性规则。 */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class ApplyVariableValidator {
+
+ private final ObjectMapper objectMapper;
+
+ /** def 的全部 EXPRESSION 出边引用的业务变量键（去重保序） */
+ public Set referencedBusinessKeys(FlowDefModel model) {
+ return com.yunhai.flowcenter.engine.VariableContract.referencedKeys(model);
+ }
+
+ public void requireVariablesPresent(FlowDefModel model, String formDataJson) {
+ com.yunhai.flowcenter.engine.VariableContract.validateInput(model, parse(formDataJson, model.variables != null));
+ }
+
+ /** 与 ConditionRouteService.parseVariables 同源：formData 顶层即变量；非对象 JSON=空（后续逐键报缺失） */
+ private Map parse(String formDataJson, boolean strict) {
+ if (formDataJson == null || formDataJson.trim().isEmpty()) {
+ return new java.util.HashMap<>();
+ }
+ try {
+ Map values = objectMapper.readValue(formDataJson, new TypeReference>() { });
+ if (values == null) {
+ if (strict) throw new IllegalArgumentException("null object");
+ return new java.util.HashMap<>();
+ }
+ return values;
+ } catch (Exception e) {
+ if (strict) throw new BizException(ErrorCode.PARAM_ERROR, "formData 必须为 JSON 对象");
+ return new java.util.HashMap<>();
+ }
+ }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowActorContextGate.java b/src/main/java/com/yunhai/flowcenter/service/FlowActorContextGate.java
new file mode 100644
index 0000000..7903e32
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowActorContextGate.java
@@ -0,0 +1,36 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+/**
+ * SDK 快捷审批 ActorContext 门禁（2026-10-25 T07 建立；同日 R1 返修改为无条件 fail-closed）。
+ *
+ * oapi 通道的 approve/reject 只有自报 operatorId/operatorName——appKey 验签证明的是
+ * 应用，不是用户；"task.assigneeId == operatorId" 的本人比较 likewise 只能证明调用方知道
+ * 办理人 ID，不能证明实际办理的用户。在"可验证用户证明"（面向 FL 的用户会话票据/受限委托：
+ * 绑定用户、学校、调用应用、任务/动作范围、期限与防重放标识，见 Codex 终审 D03/C.2）落地前，
+ * 快捷审批一律不放行，不存在放行配置。
+ *
+ * R1 返修（Codex 终审第一轮）：原 {@code flow-center.sdk-approve.require-user-proof}
+ * 开关的 false=存量放行语义已废除——未配置与 false 均不得默认放行不可信审批，此前依赖该
+ * 通道的存量消费方（work-leave、svc-hall 应用内审批快捷动作等）须迁移到标准 FL iframe/CAS
+ * 人工办理（{@code FlowUserController} → {@code FlowTaskService.handle}，会话用户身份，
+ * 不经本门）。未来 ActorContext 证明落地后，在此校验证明（用户/校/应用/任务/期限/nonce）
+ * 并按证明放行；届时再恢复配置化灰度。
+ */
+@Slf4j
+@Component
+public class FlowActorContextGate {
+
+ /** oapi 审批动作前置门（approve/reject 共用）：无条件拒绝 */
+ public void requireActorProof(Long schId, Long taskId, Integer operatorId) {
+ log.warn("[actor-gate] SDK 快捷审批被拒（无可验证用户证明，fail-closed）：schId={} taskId={} operatorId={}",
+ schId, taskId, operatorId);
+ throw new BizException(ErrorCode.FORBIDDEN,
+ "SDK 快捷审批未放行：仅凭 appKey/operatorId 不构成用户授权。"
+ + "请通过流程中心人工办理页（CAS）办理");
+ }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowCallbackAdminService.java b/src/main/java/com/yunhai/flowcenter/service/FlowCallbackAdminService.java
index e8d717d..1725612 100644
--- a/src/main/java/com/yunhai/flowcenter/service/FlowCallbackAdminService.java
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowCallbackAdminService.java
@@ -33,6 +33,7 @@ public class FlowCallbackAdminService {
private final FlwCallbackLogRepository logRepository;
private final CallbackPushService pushService;
private final CallbackProperties callbackProperties;
+ private final com.yunhai.flowcenter.callback.CallbackLogStore logStore;
public List listRegs(Long schId) {
return regRepository.findBySchIdOrderByUpdateTimeDesc(schId);
@@ -104,7 +105,6 @@ public class FlowCallbackAdminService {
* 管理端手工标记死信（持续重试语义下死信的唯一人工入口：人工判定事件无意义时止血）。
* 标记后可经既有 rePush 复活。
*/
- @Transactional
public void markDead(Long schId, Long logId) {
FlwCallbackLog callbackLog = logRepository.findById(logId)
.orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "推送日志不存在：" + logId));
@@ -119,7 +119,6 @@ public class FlowCallbackAdminService {
}
/** 手工重推（死信/失败日志）：置回待推并立即触发一次推送 */
- @Transactional
public void rePush(Long schId, List logIds) {
if (logIds == null || logIds.isEmpty()) {
throw new BizException(ErrorCode.PARAM_ERROR, "请选择要重推的日志");
@@ -128,20 +127,9 @@ public class FlowCallbackAdminService {
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());
- }
+ // 短事务提交并释放会话锁后才执行 HTTP；不能把管理端旧实体全量回写覆盖刚成功的状态。
+ for (Long id : logStore.resetForReplay(schId, logIds)) {
+ pushService.pushAsync(id);
}
}
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowDefAdminService.java b/src/main/java/com/yunhai/flowcenter/service/FlowDefAdminService.java
index f5826d7..da109e3 100644
--- a/src/main/java/com/yunhai/flowcenter/service/FlowDefAdminService.java
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowDefAdminService.java
@@ -3,6 +3,7 @@ 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.VariableContract;
import com.yunhai.flowcenter.engine.FlowEngine;
import com.yunhai.flowcenter.entity.FlwAssigneeMap;
import com.yunhai.flowcenter.entity.FlwDef;
@@ -218,7 +219,7 @@ public class FlowDefAdminService {
* 2026-10-20 C1 第一刀：def 关联了表单（form_uuid 非空）时，发布期拉 form-center schema 快照
* 嵌入版本行 content_json.formContract（与 defId 快照纪律同构：在途办件按发起时快照校验），
* 并做表达式键查①红牌（变量 ⊆ 快照字段 ∪ 内置变量）。拉取失败=发布阻断（可重试）；
- * 运行期对 form-center 零依赖。form_uuid 为空（存量线/Mode C）行为逐字不变。 */
+ * 运行期对 form-center 零依赖；新发布的无绑定版本必须显式声明 variables。 */
@Transactional
public FlwDef publish(Long schId, Long id) {
FlwDef def = requireDef(schId, id);
@@ -229,79 +230,33 @@ public class FlowDefAdminService {
throw new BizException(ErrorCode.PARAM_ERROR, "停用版本请走启用；修改表单关联须保存为新版本草稿");
}
FlowDefModel model = FlowDefModel.parse(objectMapper, def.getContentJson());
- DefValidator.validate(model, enabledDeptKeys(schId), enabledRouterKeys());
if (def.getFormUuid() != null && !def.getFormUuid().trim().isEmpty()) {
Map snapshot = checkedSchema(schId, def.getFormUuid().trim(),
def.getFormVersion(), "发布");
- List problems = new ArrayList<>();
- validateExpressionKeysAgainstSnapshot(model, snapshot, problems);
- validateExpressionTypesAndDomains(model, snapshot, problems);
- if (!problems.isEmpty()) {
- throw new BizException(ErrorCode.PARAM_ERROR,
- "发布校验失败（表达式三查）：\n" + String.join("\n", problems));
- }
- def.setContentJson(embedFormContract(def.getContentJson(), snapshot));
+ model.variables = VariableContract.fromSnapshot(snapshot);
+ VariableContract.validateDefinition(model, true);
+ DefValidator.validate(model, enabledDeptKeys(schId), enabledRouterKeys());
+ def.setContentJson(embedFormContract(def.getContentJson(), snapshot, model.variables));
} else if (def.getFormVersion() != null) {
throw new BizException(FormBindingErrorCode.INVALID_COORDINATE, "关联表单版本必须同时绑定 formUuid");
}
+ if (def.getFormUuid() == null || def.getFormUuid().trim().isEmpty()) {
+ VariableContract.validateDefinition(model, true);
+ DefValidator.validate(model, enabledDeptKeys(schId), enabledRouterKeys());
+ }
def.setStatus(FlwEnums.DefStatus.PUBLISHED.getCode());
def.setPublishTime(LocalDateTime.now());
return defRepository.save(def);
}
- /**
- * 表达式键查①（C1 三查之一，红牌）：对每条 EXPRESSION 判断的出边表达式，
- * 变量集 ⊆ 快照字段 keys ∪ 内置变量（{@link DefValidator#EXPRESSION_BUILTINS}）。
- * 不执行表达式、不改沙箱（口径与 v2 方案 §4.7 一致）。
- */
- private void validateExpressionKeysAgainstSnapshot(FlowDefModel model, Map snapshot,
- List problems) {
- @SuppressWarnings("unchecked")
- List> fields = (List>) snapshot.get("fields");
- java.util.Set fieldKeys = new java.util.HashSet<>();
- if (fields != null) {
- for (Map f : fields) {
- Object k = f.get("key");
- if (k != null) {
- fieldKeys.add(String.valueOf(k));
- }
- }
- }
- if (fieldKeys.isEmpty()) {
- problems.add("关联表单快照无字段（formContract.fields 为空）：请检查表单是否已发布");
- return;
- }
- for (FlowDefModel.Node n : model.nodes) {
- if (n == null || !n.expressionJudge()) {
- continue;
- }
- for (FlowDefModel.Edge e : model.outEdges(n.id)) {
- if (e.condition == null || e.condition.trim().isEmpty()) {
- continue;
- }
- List vars;
- try {
- vars = com.yunhai.flowcenter.engine.ExpressionEvaluator.variableNames(e.condition.trim());
- } catch (Exception ex) {
- // 语法错已由 DefValidator 拦下，这里理论上到不了；防御口径跳过
- continue;
- }
- for (String v : vars) {
- if (!fieldKeys.contains(v) && !DefValidator.EXPRESSION_BUILTINS.contains(v)) {
- problems.add("节点「" + n.name + "」出口「" + e.name + "」表达式变量 " + v
- + " 不在关联表单字段集内（快照 " + fieldKeys.size() + " 个字段）");
- }
- }
- }
- }
- }
-
/** content_json 顶层嵌入 formContract 节（ObjectNode 保字段顺序；原值存在则整体替换=本版快照） */
- private String embedFormContract(String contentJson, Map snapshot) {
+ private String embedFormContract(String contentJson, Map snapshot,
+ List variables) {
try {
com.fasterxml.jackson.databind.node.ObjectNode root = (com.fasterxml.jackson.databind.node.ObjectNode)
objectMapper.readTree(contentJson);
root.set("formContract", objectMapper.valueToTree(snapshot));
+ root.set("variables", objectMapper.valueToTree(variables));
return objectMapper.writeValueAsString(root);
} catch (BizException e) {
throw e;
@@ -310,109 +265,46 @@ public class FlowDefAdminService {
}
}
- // ===================== 三查②③（2026-10-20 C1 第一刀余量项） =====================
-
- /** 数值桶：可与数值字面量比大小的快照字段类型 */
- private static final java.util.Set NUMERIC_TYPES =
- new java.util.HashSet<>(java.util.Arrays.asList("number"));
- /** 值域字面量型（enum 域查③适用）：options 收进快照 enum 的类型 */
- private static final java.util.Set ENUM_TYPES =
- new java.util.HashSet<>(java.util.Arrays.asList("select", "radio"));
-
- /** `字段 op '字面量'` / `字段 op 数值`（op 含两侧空格容忍） */
- private static final java.util.regex.Pattern FIELD_STR_EQ = java.util.regex.Pattern.compile(
- "([A-Za-z_][A-Za-z0-9_]*)\\s*(==|!=)\\s*'([^']*)'");
- private static final java.util.regex.Pattern FIELD_NUM_CMP = java.util.regex.Pattern.compile(
- "([A-Za-z_][A-Za-z0-9_]*)\\s*(>=|<=|>|<)\\s*(-?\\d+(\\.\\d+)?)");
- private static final java.util.regex.Pattern NUM_FIELD_CMP = java.util.regex.Pattern.compile(
- "(-?\\d+(\\.\\d+)?)\\s*(>=|<=|>|<)\\s*([A-Za-z_][A-Za-z0-9_]*)");
-
- /**
- * 类型桶查②红牌 + 域查③红牌（启发式实现：正则模式匹配字面量比较形态，非 AST——
- * v2 §4.7 保守边界：不执行表达式、不做隐式转换，只拦"数值比较 × 非数值字段"与
- * "枚举等值 × 字面量不在值域"两类高发错配；不命中的形态留给运行期既有挂起纪律）。
- */
- @SuppressWarnings("unchecked")
- private void validateExpressionTypesAndDomains(FlowDefModel model, Map snapshot,
- List problems) {
- List> fields = (List>) snapshot.get("fields");
- if (fields == null || fields.isEmpty()) {
- return;
- }
- Map> fieldByKey = new HashMap<>();
- for (Map f : fields) {
- Object k = f.get("key");
- if (k != null) {
- fieldByKey.put(String.valueOf(k), f);
- }
- }
- for (FlowDefModel.Node n : model.nodes) {
- if (n == null || !n.expressionJudge()) {
- continue;
- }
- for (FlowDefModel.Edge e : model.outEdges(n.id)) {
- if (e.condition == null || e.condition.trim().isEmpty()) {
- continue;
- }
- String where = "节点「" + n.name + "」出口「" + e.name + "」";
- String expr = e.condition.trim();
- // ② 类型桶查：数值比较算子作用于非数值字段 → 红牌
- java.util.regex.Matcher m = FIELD_NUM_CMP.matcher(expr);
- while (m.find()) {
- checkNumericBucket(where, m.group(1), m.group(2), fieldByKey, problems);
- }
- m = NUM_FIELD_CMP.matcher(expr);
- while (m.find()) {
- checkNumericBucket(where, m.group(4), m.group(3), fieldByKey, problems);
- }
- // ② 类型桶查（字符串侧）：文本字面量等值比较数值字段 → 红牌
- // ③ 域查：枚举字段等值比较的字面量 ∉ 快照 enum 值域 → 红牌
- m = FIELD_STR_EQ.matcher(expr);
- while (m.find()) {
- String key = m.group(1);
- String op = m.group(2);
- String literal = m.group(3);
- Map field = fieldByKey.get(key);
- if (field == null) {
- continue; // 内置变量或未知键：①已拦/不属本查
- }
- String type = field.get("type") == null ? null : String.valueOf(field.get("type"));
- if (NUMERIC_TYPES.contains(type)) {
- problems.add(where + "：字段 " + key + " 是 number 类型，不能与字符串字面量 '"
- + literal + "' 做 " + op + " 比较（类型桶查②）");
- } else if (ENUM_TYPES.contains(type) && "==".equals(op)) {
- List enums = (List) field.get("enum");
- if (enums != null && !enums.isEmpty() && !enums.contains(literal)) {
- problems.add(where + "：字段 " + key + " 的值域是 " + enums
- + "，字面量 '" + literal + "' 不在其中（域查③）");
- }
- }
- }
- }
- }
- }
-
- private void checkNumericBucket(String where, String key, String op,
- Map> fieldByKey, List problems) {
- Map field = fieldByKey.get(key);
- if (field == null) {
- return;
- }
- String type = field.get("type") == null ? null : String.valueOf(field.get("type"));
- if (type != null && !NUMERIC_TYPES.contains(type)) {
- problems.add(where + "：字段 " + key + " 是 " + type + " 类型，不能做数值比较 "
- + key + " " + op + " 数字（类型桶查②）");
- }
- }
-
/** 停用：不可新发起，存量跑完 */
@Transactional
public void offline(Long schId, Long id) {
FlwDef def = requireDef(schId, id);
+ if (def.getStatus() == FlwEnums.DefStatus.DRAFT.getCode()) {
+ throw new BizException(ErrorCode.PARAM_ERROR, "草稿不能停用后启用，请先通过发布校验");
+ }
def.setStatus(FlwEnums.DefStatus.DISABLED.getCode());
defRepository.save(def);
}
+ /**
+ * 线级停发（2026-10-25 T03）：整条 flowGuid 停止新发起/预览，在途实例按各自固定 defId 原版跑完。
+ * 与版本级 {@link #offline} 正交（可叠加）；批量 UPDATE 全版本行，读任一行即读线状态。
+ * 不改写任何发布内容字节，恢复走 {@link #enableLine}。
+ */
+ @Transactional
+ public int offlineLine(Long schId, String flowGuid) {
+ requireLine(schId, flowGuid);
+ return defRepository.updateLineOffline(schId, flowGuid.trim(), 1);
+ }
+
+ /**
+ * 线级恢复（T03）：只恢复线的可用性——line_offline 归零；各版本 status/发布内容/版本指针
+ * 一律不动（停发期间发布新版不受影响，恢复后新发起即用当时最高已发布版）。
+ */
+ @Transactional
+ public int enableLine(Long schId, String flowGuid) {
+ requireLine(schId, flowGuid);
+ return defRepository.updateLineOffline(schId, flowGuid.trim(), 0);
+ }
+
+ private void requireLine(Long schId, String flowGuid) {
+ if (flowGuid == null || flowGuid.trim().isEmpty()
+ || defRepository.findFirstBySchIdAndFlowGuidOrderByVersionDesc(schId, flowGuid.trim())
+ .isPresent()) {
+ throw new BizException(ErrorCode.PARAM_ERROR, "流程线不存在：" + flowGuid);
+ }
+ }
+
/**
* 启用（2026-09-18）：只对"停用"版恢复为已发布，与 offline 对称。
* 复用发布期的静态校验（把"任务无主"重新拦一次）——若建的时候某科室还有启用办理人、之后
@@ -520,7 +412,12 @@ public class FlowDefAdminService {
}
def.setName(cleanName);
def.setAppKey(cleanAppKey);
- def.setContentJson(syncTopLevelName(def.getContentJson(), cleanName));
+ // 发布封存（2026-10-25 T03）：非草稿版本的执行文档不可变——行 name 照改（目录元数据），
+ // content_json 顶层 name 保持发布时字节，消除"已发布文档被原地改写"的旁路
+ //（审计 E02：updateMeta 曾同步改已发布 contentJson 顶层 name）。
+ if (def.getStatus() != null && def.getStatus() == FlwEnums.DefStatus.DRAFT.getCode()) {
+ def.setContentJson(syncTopLevelName(def.getContentJson(), cleanName));
+ }
try {
return defRepository.save(def);
} catch (DataIntegrityViolationException e) {
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowInstanceService.java b/src/main/java/com/yunhai/flowcenter/service/FlowInstanceService.java
index 8f8cdcc..0f54436 100644
--- a/src/main/java/com/yunhai/flowcenter/service/FlowInstanceService.java
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowInstanceService.java
@@ -24,7 +24,8 @@ import java.util.HashMap;
import java.util.Map;
/**
- * 办件生命周期：代发起（幂等 + R4 重启重提）、撤回。
+ * 引擎实例生命周期与迁移前代发起。正式命令通过 create/startFormalInstance 建立独立轮次实例，
+ * 命令受理、坐标锁和轮次分配归 FormalApplyCommandService；下述 R4 复用仅描述旧入口。
*
* R4 驳回/撤回后重提语义（开工说明 §7#1，详设定稿）：biz uk 命中已终态办件
* （30 已拒绝 / 40 已撤回）时复用同一办件行"重启推进"——不新建、不报错：定义刷新为当前
@@ -63,6 +64,13 @@ public class FlowInstanceService {
public final String applyAppCode;
/** 发起时指派快照 JSON（oapi apply 校验后渲染；null=无指派） */
public final String assignJson;
+
+ /**
+ * 受理载荷指纹（2026-10-25 T04，SHA-256 hex；非构造参数——13 参构造被
+ * {@code FlowEngineIT} 逐位钉住，由 {@code OapiFlowService} 在构建后赋值；
+ * null=存量调用方，指纹核对缺省关）。
+ */
+ public String payloadHash;
}
/** 代发起结果：instanceId + duplicated（命中既有办件=true，含重启重提） */
@@ -138,6 +146,10 @@ public class FlowInstanceService {
if (round != null) {
instance.setApplyRound(round);
}
+ if (cmd.payloadHash != null) {
+ // 新一轮命令重新取指纹（新轮=新命令，指纹跟随最新受理载荷）
+ instance.setApplyPayloadHash(cmd.payloadHash);
+ }
instance.setStatus(FlwEnums.InstanceStatus.APPROVING.getCode());
instance.setSubmitTime(LocalDateTime.now());
instance.setFinishTime(null);
@@ -297,6 +309,16 @@ public class FlowInstanceService {
public final String requestToken;
public final Integer attempt;
public final boolean retryOnly;
+ /**
+ * 期望的前一轮次（2026-10-25 T04 服务端轮次收口，可选）：显式申报"我基于第 N 轮重提"。
+ * 非空时：行轮次 ≠ N ⇒ STALE_ROUND（不重启）；通过则服务端分配 round=N+1，
+ * 不信客户端 attempt。null=既有客户端 attempt 语义（存量兼容）。
+ */
+ public final Integer expectedPrevRound;
+
+ public ApplyRetryPolicy(String requestToken, Integer attempt, boolean retryOnly) {
+ this(requestToken, attempt, retryOnly, null);
+ }
}
/** 守卫化结果：除 instanceId/duplicated 外，把"命中的是哪一种情形"落成稳定分支码 */
@@ -345,6 +367,15 @@ public class FlowInstanceService {
// 新一轮授权重提（attempt≥2）才走得动 R4——存量行的守卫缺省是**关**而不是开。
int currentRound = existing.getApplyRound() == null ? 1 : existing.getApplyRound();
if (token != null && token.equals(existing.getApplyRequestToken())) {
+ // T04（2026-10-25）：同 token 必须同指纹——同 ID 不同载荷是两份命令撞同一 token，
+ // 按冲突拒绝，不伪装成幂等成功。存量行（指纹 NULL）或请求无指纹时跳过（守卫缺省关）。
+ if (existing.getApplyPayloadHash() != null && cmd.payloadHash != null
+ && !existing.getApplyPayloadHash().equals(cmd.payloadHash)) {
+ log.warn("[flow-center] 同请求标识但载荷指纹不一致（冲突拒绝）：instance={} biz={}/{}",
+ existing.getId(), cmd.bizType, cmd.bizId);
+ return new GuardedOutcome(existing.getId(), true,
+ FlowApplyRetryModels.Branch.CONFLICT, existing.getApplyRound());
+ }
log.info("[flow-center] 同请求标识重投命中，只回读现状不重启：instance={} biz={}/{} status={}",
existing.getId(), cmd.bizType, cmd.bizId, existing.getStatus());
return new GuardedOutcome(existing.getId(), true,
@@ -353,6 +384,15 @@ public class FlowInstanceService {
int status = existing.getStatus();
if (status == FlwEnums.InstanceStatus.APPROVING.getCode()
|| status == FlwEnums.InstanceStatus.COMPLETED.getCode()) {
+ // T04：带 token 的请求撞上在途/通过件且 token 不符=另一份命令（审计 P0-2：
+ // "10/20 即使异命令也回 IDEMPOTENT"是把他人命令的成功当自己的）。无 token 的
+ // 存量调用方保持 IDEMPOTENT（守卫缺省关）。
+ if (token != null) {
+ log.warn("[flow-center] 在途/通过件命中且请求 token 不符（冲突拒绝）：instance={} biz={}/{}",
+ existing.getId(), cmd.bizType, cmd.bizId);
+ return new GuardedOutcome(existing.getId(), true,
+ FlowApplyRetryModels.Branch.CONFLICT, existing.getApplyRound());
+ }
return new GuardedOutcome(existing.getId(), true,
FlowApplyRetryModels.Branch.IDEMPOTENT, existing.getApplyRound());
}
@@ -363,21 +403,52 @@ public class FlowInstanceService {
return new GuardedOutcome(existing.getId(), true,
FlowApplyRetryModels.Branch.REPLAY_ONLY, existing.getApplyRound());
}
- int incomingRound = policy == null || policy.attempt == null ? 1 : policy.attempt;
- if (incomingRound <= currentRound) {
- log.warn("[flow-center] 陈旧轮次重投（不重启）：instance={} 行轮次={} 请求轮次={}",
- existing.getId(), currentRound, incomingRound);
- return new GuardedOutcome(existing.getId(), true,
- FlowApplyRetryModels.Branch.STALE_ROUND, existing.getApplyRound());
+ // T04 服务端轮次：显式 expectedPrevRound 时——行轮次必须恰为 N（否则陈旧），服务端只分配 N+1；
+ // 未显式时保持客户端 attempt 语义（存量兼容）。
+ Integer expectedPrev = policy == null ? null : policy.expectedPrevRound;
+ int incomingRound;
+ if (expectedPrev != null) {
+ if (expectedPrev != currentRound) {
+ log.warn("[flow-center] 重提前置轮次不符（不重启）：instance={} 行轮次={} 期望前轮={}",
+ existing.getId(), currentRound, expectedPrev);
+ return new GuardedOutcome(existing.getId(), true,
+ FlowApplyRetryModels.Branch.STALE_ROUND, existing.getApplyRound());
+ }
+ incomingRound = currentRound + 1;
+ } else {
+ incomingRound = policy == null || policy.attempt == null ? 1 : policy.attempt;
+ if (incomingRound <= currentRound) {
+ log.warn("[flow-center] 陈旧轮次重投（不重启）：instance={} 行轮次={} 请求轮次={}",
+ existing.getId(), currentRound, incomingRound);
+ return new GuardedOutcome(existing.getId(), true,
+ FlowApplyRetryModels.Branch.STALE_ROUND, existing.getApplyRound());
+ }
}
restart(existing, cmd, token, incomingRound);
return new GuardedOutcome(existing.getId(), true,
FlowApplyRetryModels.Branch.RESTARTED, incomingRound);
}
- /** 新建实例（与旧 apply 同一段代码形状：不复制第二份推进逻辑） */
+ /** Formal command caller must hold the coordinate lock in the same transaction. */
+ @Transactional(propagation = org.springframework.transaction.annotation.Propagation.MANDATORY)
+ public FlwInstance createFormalInstance(ApplyCommand cmd, String token, Integer round, String source) {
+ return createInstance(cmd, token, round, source);
+ }
+
+ @Transactional(propagation = org.springframework.transaction.annotation.Propagation.MANDATORY)
+ public void startFormalInstance(FlwInstance instance, ApplyCommand cmd) {
+ flowEngine.startAdvance(instance, cmd.def);
+ publishSubmitted(instance);
+ }
+
private void createInstance(ApplyCommand cmd, String token, Integer round) {
+ createInstance(cmd, token, round, null);
+ }
+
+ private FlwInstance createInstance(ApplyCommand cmd, String token, Integer round, String source) {
FlwInstance instance = new FlwInstance();
+ instance.setSourcePrincipalId(source);
+ instance.setLegacySlot(source == null ? 1 : null);
instance.setSchId(cmd.schId);
instance.setDefId(cmd.def.getId());
instance.setDefCode(cmd.def.getCode());
@@ -393,6 +464,7 @@ public class FlowInstanceService {
instance.setApplyAppCode(cmd.applyAppCode);
instance.setApplyRequestToken(token);
instance.setApplyRound(round);
+ instance.setApplyPayloadHash(cmd.payloadHash);
instance.setSubmitterId(cmd.submitterId);
instance.setSubmitterName(cmd.submitterName);
instance.setStatus(FlwEnums.InstanceStatus.APPROVING.getCode());
@@ -400,8 +472,11 @@ public class FlowInstanceService {
instanceRepository.saveAndFlush(instance);
appendTraceEvent(instance, FlwEnums.TaskStatus.NODE_SUBMIT, "发起申请",
FlwEnums.TaskStatus.SUBMITTED, cmd.submitterId, cmd.submitterName);
- flowEngine.startAdvance(instance, cmd.def);
- publishSubmitted(instance);
+ if (source == null) {
+ flowEngine.startAdvance(instance, cmd.def);
+ publishSubmitted(instance);
+ }
+ return instance;
}
/**
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowOapiSourceScope.java b/src/main/java/com/yunhai/flowcenter/service/FlowOapiSourceScope.java
new file mode 100644
index 0000000..f70ed42
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowOapiSourceScope.java
@@ -0,0 +1,65 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.flowcenter.entity.FlwInstance;
+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 org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+import org.springframework.web.context.request.RequestContextHolder;
+import org.springframework.web.context.request.ServletRequestAttributes;
+import org.springframework.web.servlet.HandlerInterceptor;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+/** Authenticated request scope; no user-supplied source/header is trusted. */
+@Component @RequiredArgsConstructor
+public class FlowOapiSourceScope implements HandlerInterceptor {
+ private static final String ATTRIBUTE = FlowOapiSourceScope.class.getName();
+ private final FlowSourcePrincipalResolver resolver;
+ private final FlwInstanceRepository instances;
+ private final FlwTaskRepository tasks;
+ @Value("${flow-center.formal-command.enabled:false}") private boolean enabled;
+
+ @Override
+ public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
+ if (!enabled) return true;
+ String source = resolver.resolve((String) request.getAttribute("yh.app.auth")).id;
+ request.setAttribute(ATTRIBUTE, source);
+ String id = request.getParameter("instanceId");
+ java.util.regex.Matcher pathId = java.util.regex.Pattern.compile("/instance/(\\d+)(?:/|$)").matcher(request.getRequestURI());
+ if (id == null && pathId.find()) id = pathId.group(1);
+ String taskId = request.getParameter("taskId");
+ java.util.regex.Matcher taskPath = java.util.regex.Pattern.compile("/task/(\\d+)(?:/|$)").matcher(request.getRequestURI());
+ if (taskId == null && taskPath.find()) taskId = taskPath.group(1);
+ if (id != null) requireOwn(parse(id), source);
+ if (taskId != null) {
+ Long task = parse(taskId);
+ requireOwn(tasks.findById(task).orElseThrow(() -> denied()).getInstanceId(), source);
+ }
+ return true;
+ }
+
+ private void requireOwn(Long id, String source) {
+ FlwInstance instance = instances.findById(id).orElseThrow(() -> denied());
+ if (!source.equals(instance.getSourcePrincipalId())) throw denied();
+ }
+
+ public static String current() {
+ String source = currentOr(null);
+ if (source == null) throw denied();
+ return source;
+ }
+ public static String currentOr(String fallback) {
+ if (!(RequestContextHolder.getRequestAttributes() instanceof ServletRequestAttributes)) return fallback;
+ Object value = ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getRequest().getAttribute(ATTRIBUTE);
+ return value instanceof String ? (String) value : fallback;
+ }
+ private Long parse(String value) {
+ try { return Long.valueOf(value); } catch (NumberFormatException e) { throw denied(); }
+ }
+ private static BizException denied() { return new BizException(ErrorCode.FORBIDDEN, "仅允许访问本应用来源的流程事实"); }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowRouterAdminService.java b/src/main/java/com/yunhai/flowcenter/service/FlowRouterAdminService.java
index 91c6b07..63e90d6 100644
--- a/src/main/java/com/yunhai/flowcenter/service/FlowRouterAdminService.java
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowRouterAdminService.java
@@ -162,15 +162,18 @@ public class FlowRouterAdminService {
}
/**
- * 重跑路由（F5-4 僵尸逃生门）：useLatestDef=true 时 def 改取该 flowGuid 当前已发布最高版本，
- * 办件 defId/defCode/defVersion 快照同步刷新（与 R4 重启同语义，只刷定义三列，不动业务快照/
- * 状态/时间），trace 落一行留痕（保留节点 id=reroute-def，nodeName 载明 v旧→v新）。
- * 锚定 128/129 僵尸案例：办件挂在 v1 的 CONDITION 节点、修好的表达式已发布为 v2，按 def 快照
- * 重跑永远打转——此开关让管理员一键切到 v2 续走。在途 CONDITION 节点在新定义不存在时
- * 按人类可读业务错拒绝（不猜测节点映射）。useLatestDef=false 现行为逐字不变。
+ * 重跑路由（挂起恢复唯一入口，§4.4）。2026-10-25 T03 在途锁版收口：useLatestDef=true 的
+ * "切到最新发布版续走"旁路已按"在途实例固定原版本"原则停用——新发布版只影响新申报；
+ * 挂起件按原定义重跑（修复表达式后按原版本重新发布或由发起方重新申报）。
+ * 保留参数与显式拒绝（不静默忽略），旧调用方拿到人类可读业务错。
*/
@Transactional
public void reroute(Long schId, Long instanceId, boolean useLatestDef) {
+ if (useLatestDef) {
+ throw new BizException(ErrorCode.PARAM_ERROR,
+ "在途换版已停用（在途实例固定使用原版本，新版本只影响新申报）；"
+ + "请修复表达式后按原版本重新发布，或让发起方终态后重新申报");
+ }
FlwInstance instance = instanceRepository.findById(instanceId)
.orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "办件不存在：" + instanceId));
if (!instance.getSchId().equals(schId)) {
@@ -183,58 +186,15 @@ public class FlowRouterAdminService {
if (def == null) {
throw new BizException(ErrorCode.PARAM_ERROR, "办件定义缺失");
}
- if (useLatestDef) {
- def = refreshToLatestPublishedDef(instance, def);
- }
String conditionNode = findParkedCondition(instance, def);
if (conditionNode == null) {
- throw new BizException(ErrorCode.PARAM_ERROR, useLatestDef
- ? "在途条件节点在最新已发布定义中不存在（节点已被改版移除/改型），无法按新定义重跑"
- : "办件未挂在条件分支节点（无挂起的路由判断，无需重跑）");
+ throw new BizException(ErrorCode.PARAM_ERROR,
+ "办件未挂在条件分支节点（无挂起的路由判断，无需重跑）");
}
flowEngine.rerouteCondition(instance, def, conditionNode);
instanceRepository.save(instance);
}
- /** 取 flowGuid 当前已发布最高版本并刷新办件定义快照（仅三列；已是最新则原样返回不落留痕） */
- private FlwDef refreshToLatestPublishedDef(FlwInstance instance, FlwDef current) {
- FlwDef latest = defRepository.findFirstBySchIdAndFlowGuidAndStatusOrderByVersionDesc(
- instance.getSchId(), current.getFlowGuid(), FlwEnums.DefStatus.PUBLISHED.getCode())
- .orElse(null);
- if (latest == null) {
- throw new BizException(ErrorCode.PARAM_ERROR, "该流程当前无已发布版本，无法按最新定义重跑");
- }
- if (latest.getId().equals(instance.getDefId())) {
- return latest;
- }
- instance.setDefId(latest.getId());
- instance.setDefCode(latest.getCode());
- instance.setDefVersion(latest.getVersion());
- appendRerouteDefTrace(instance, current.getVersion(), latest.getVersion());
- return latest;
- }
-
- /**
- * 定义切换留痕行（同 FlowInstanceService.appendTraceEvent 形态；彼方法私有且该类冻结，不共用）：
- * status=6 + 保留节点 id，nodeName 载明版本迁移；不参与引擎任何判断（同 submit/withdraw 行）。
- */
- private void appendRerouteDefTrace(FlwInstance instance, Integer fromVersion, Integer toVersion) {
- java.time.LocalDateTime now = java.time.LocalDateTime.now();
- com.yunhai.flowcenter.entity.FlwTask row = new com.yunhai.flowcenter.entity.FlwTask();
- row.setInstanceId(instance.getId());
- row.setSchId(instance.getSchId());
- row.setNodeId(FlwEnums.TaskStatus.NODE_REROUTE_DEF);
- row.setNodeName("按新版定义重跑（v" + fromVersion + "→v" + toVersion + "）");
- // assignee=0：管理端动作无自然办理人，落 0 不产生待办（同发起行脏数据兜底口径）
- row.setAssigneeId(0);
- row.setAssigneeName("管理端");
- row.setStatus(FlwEnums.TaskStatus.SUBMITTED.getCode());
- row.setArriveTime(now);
- row.setHandleTime(now);
- row.setUrgeCount(0);
- taskRepository.save(row);
- }
-
/** 在途节点里找 CONDITION（多个时取第一个；正常挂起只会有一个） */
private String findParkedCondition(FlwInstance instance, FlwDef def) {
String cur = instance.getCurrentNodes();
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowSourcePrincipalResolver.java b/src/main/java/com/yunhai/flowcenter/service/FlowSourcePrincipalResolver.java
new file mode 100644
index 0000000..56da8dc
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowSourcePrincipalResolver.java
@@ -0,0 +1,42 @@
+package com.yunhai.flowcenter.service;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.openapi.base.OpenApiAppClient;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+import java.util.UUID;
+
+@Service
+@RequiredArgsConstructor
+public class FlowSourcePrincipalResolver {
+ private final OpenApiAppClient appClient;
+
+ public Principal resolve(String authenticatedAppKey) {
+ if (authenticatedAppKey == null || authenticatedAppKey.trim().isEmpty()) {
+ throw new BizException(ErrorCode.UNAUTHORIZED, "缺少已认证的调用应用");
+ }
+ JsonNode app = appClient.getAppByKey(authenticatedAppKey);
+ if (app == null || !app.path("id").isIntegralNumber()) {
+ throw new BizException(ErrorCode.UNAUTHORIZED, "调用应用主体不可解析");
+ }
+ String source = app.path("sourcePrincipalId").asText("");
+ try {
+ if (!UUID.fromString(source).toString().equals(source)) throw new IllegalArgumentException();
+ } catch (IllegalArgumentException e) {
+ throw new BizException(ErrorCode.UNAUTHORIZED, "UserBase 稳定来源尚未迁移，禁止回退到数字 ID/appKey");
+ }
+ return new Principal(source, app.path("id").intValue(), authenticatedAppKey,
+ app.path("appCode").isTextual() ? app.path("appCode").textValue() : null);
+ }
+
+ @lombok.RequiredArgsConstructor
+ public static class Principal {
+ public final String id;
+ public final Integer appId;
+ public final String appKey;
+ public final String appCode;
+ }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowTaskService.java b/src/main/java/com/yunhai/flowcenter/service/FlowTaskService.java
index e397b50..ad9e74e 100644
--- a/src/main/java/com/yunhai/flowcenter/service/FlowTaskService.java
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowTaskService.java
@@ -246,7 +246,7 @@ public class FlowTaskService {
/**
* 移交（B4）：办理权转给他人。当前任务置 TRANSFERRED 留痕，同节点新建一条待办给目标人
* （deadline 沿用原任务）；推进监听器因新待办 pending>0 自然不放行，无需改推进逻辑。
- * 目标人存在性由 AssigneeResolver 严格校验（查不到必须拒绝，否则产生僵尸待办）。
+ * 目标人资格由 AssigneeResolver 终审（存在/启用/本校，D11）——查不到必须拒绝，否则产生僵尸待办。
*/
@Transactional
public void transfer(Long schId, Long taskId, Integer toUserId, String reason, Integer operatorId) {
@@ -259,7 +259,9 @@ public class FlowTaskService {
}
FlwInstance instance = instanceRepository.findById(task.getInstanceId())
.orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "办件不存在"));
- String toUserName = assigneeResolver.requireUserName(toUserId);
+ // D11 移交终审：目标必须存在/启用/属于本校；全部校验在抢占原任务之前完成，
+ // 失败不会先替换人员或改写任务状态。
+ String toUserName = assigneeResolver.requireEligibleAssigneeName(task.getSchId(), toUserId);
LocalDateTime now = LocalDateTime.now();
String fromLabel = task.getNodeName() == null ? task.getNodeId() : task.getNodeName();
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowUsageGrantAdminService.java b/src/main/java/com/yunhai/flowcenter/service/FlowUsageGrantAdminService.java
new file mode 100644
index 0000000..3e0e9ea
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowUsageGrantAdminService.java
@@ -0,0 +1,133 @@
+package com.yunhai.flowcenter.service;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.yunhai.flowcenter.entity.FlwUsageGrant;
+import com.yunhai.flowcenter.repository.FlwUsageGrantRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.openapi.base.OpenApiAppClient;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+/**
+ * 应用使用授权管理面（2026-10-25 T01）：学校×流程线×稳定主体的授予/撤销/查询。
+ *
+ *
授予时把 appKey 解析成 UserBase 稳定主键 appId 落库（授权对象是主体不是凭据），
+ * 并按学校开通事实做发放闸（enforce 开启时未开通拒发）。撤销只置 {@code enabled=0}
+ * （不删行，审计与幂等判据保留）；撤权只拦新发起，不回写在途实例与已受理命令。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FlowUsageGrantAdminService {
+
+ private final FlwUsageGrantRepository grantRepository;
+ private final UserBaseActivationClient activationClient;
+
+ @Autowired(required = false)
+ private OpenApiAppClient appClient;
+
+ @org.springframework.beans.factory.annotation.Value("${flow-center.formal-command.enabled:false}")
+ private boolean formalEnabled;
+
+ public List listByFlow(Long schId, String flowGuid) {
+ return grantRepository.findBySchIdAndFlowGuidOrderByUpdateTimeDescIdDesc(schId, flowGuid);
+ }
+
+ public List listByApp(Long schId, Integer appId) {
+ return grantRepository.findBySchIdAndAppIdOrderByUpdateTimeDescIdDesc(schId, appId);
+ }
+
+ /**
+ * 授予/重申（三元键 upsert）。
+ *
+ * @throws BizException appKey 不可解析为稳定主体（fail-closed，管理面必须授到真实主体上）；
+ * enforce 开启且应用未在该校开通或核验不可用
+ */
+ @Transactional
+ public FlwUsageGrant grant(Long schId, String flowGuid, String appKey, String remark, String operator) {
+ if (schId == null || schId <= 0 || flowGuid == null || flowGuid.trim().isEmpty()
+ || appKey == null || appKey.trim().isEmpty()) {
+ throw new BizException(ErrorCode.PARAM_ERROR, "schId/flowGuid/appKey 必填");
+ }
+ String cleanKey = appKey.trim();
+ JsonNode registered = fetchRegistered(cleanKey);
+ Integer appId = registered == null ? null : readId(registered);
+ if (appId == null) {
+ throw new BizException(ErrorCode.PARAM_ERROR,
+ "appKey 未能在 UserBase 解析出稳定应用主体，拒绝授权：" + cleanKey);
+ }
+ if (activationClient.isEnforce()
+ && !activationClient.isAppActivatedAtSchool(appId, schId)) {
+ throw new BizException(ErrorCode.FORBIDDEN,
+ "该应用未在学校 " + schId + " 开通，不能授予流程使用许可");
+ }
+ FlwUsageGrant grant = grantRepository
+ .findBySchIdAndFlowGuidAndAppId(schId, flowGuid.trim(), appId)
+ .orElseGet(FlwUsageGrant::new);
+ boolean isNew = grant.getId() == null;
+ if (isNew) {
+ grant.setSchId(schId);
+ grant.setFlowGuid(flowGuid.trim());
+ grant.setAppId(appId);
+ }
+ if (formalEnabled) {
+ String source = registered.path("sourcePrincipalId").asText("");
+ try {
+ if (!java.util.UUID.fromString(source).toString().equals(source)) throw new IllegalArgumentException();
+ } catch (IllegalArgumentException invalid) {
+ throw new BizException(ErrorCode.FORBIDDEN, "UserBase 稳定来源未迁移，不能发放正式许可");
+ }
+ if (!activationClient.isAppActivatedStrict(appId, schId)) throw new BizException(ErrorCode.FORBIDDEN, "学校未开通");
+ grant.setSourcePrincipalId(source);
+ }
+ grant.setAppKeySnapshot(cleanKey);
+ grant.setAppNameSnapshot(registered.path("appName").asText(null));
+ grant.setEnabled(1);
+ grant.setRemark(remark);
+ FlwUsageGrant saved = grantRepository.save(grant);
+ log.info("[usage-grant] 授予 schId={} flowGuid={} appId={} appKey={} operator={} 新建={}",
+ schId, flowGuid, appId, cleanKey, operator, isNew);
+ return saved;
+ }
+
+ /** 撤销（enabled=0，行保留）；幂等：对已撤销行重复撤销不报错 */
+ @Transactional
+ public FlwUsageGrant revoke(Long schId, String flowGuid, Integer appId, String remark, String operator) {
+ FlwUsageGrant grant = grantRepository
+ .findBySchIdAndFlowGuidAndAppId(schId, flowGuid, appId)
+ .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR,
+ "使用许可不存在：school=" + schId + " flow=" + flowGuid + " app=" + appId));
+ grant.setEnabled(0);
+ if (remark != null && !remark.trim().isEmpty()) {
+ grant.setRemark(remark.trim());
+ }
+ FlwUsageGrant saved = grantRepository.save(grant);
+ log.info("[usage-grant] 撤销 schId={} flowGuid={} appId={} operator={}（只拦新发起，在途不受影响）",
+ schId, flowGuid, appId, operator);
+ return saved;
+ }
+
+ private JsonNode fetchRegistered(String appKey) {
+ if (appClient == null) {
+ throw new BizException(ErrorCode.UNAUTHORIZED, "UserBase 应用注册通道未装配，拒绝授权");
+ }
+ try {
+ JsonNode node = appClient.getAppByKey(appKey);
+ return node == null || node.isNull() ? null : node;
+ } catch (RuntimeException e) {
+ log.warn("[usage-grant] UserBase 注册解析失败 appKey={}：{}", appKey, e.toString());
+ throw new BizException(ErrorCode.UNAUTHORIZED, "UserBase 应用注册解析不可用，请稍后重试");
+ }
+ }
+
+ private Integer readId(JsonNode registered) {
+ JsonNode idNode = registered.path("id");
+ return idNode.isNumber() ? idNode.intValue() : null;
+ }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/service/FlowUsageGrantGuard.java b/src/main/java/com/yunhai/flowcenter/service/FlowUsageGrantGuard.java
new file mode 100644
index 0000000..f8c8512
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/service/FlowUsageGrantGuard.java
@@ -0,0 +1,96 @@
+package com.yunhai.flowcenter.service;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.yunhai.flowcenter.entity.FlwUsageGrant;
+import com.yunhai.flowcenter.repository.FlwUsageGrantRepository;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.openapi.base.OpenApiAppClient;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+
+/**
+ * 应用使用许可闸门（2026-10-25 T01）：新发起必须持有生效的 (school, flowGuid, appId) 许可。
+ *
+ * 三层独立事实，缺一不可（enforce 开启时）：
+ *
+ * - 稳定主体：appKey 验签凭据 → UserBase 注册行主键 appId（appKey 可重置/复用，
+ * 不是主体；主体解析不可达=fail-closed 拒绝）；
+ * - FL 本地使用许可：{@code flw_usage_grant} 生效行（独立于 flw_app 定义保存白名单
+ * 与流程定义管理权）；
+ * - UB 学校开通：该应用在该校的平台开通事实（第二重证明，不因本地 grant 而豁免）。
+ *
+ *
+ * 撤权边界（P0-3）：本闸只拦"新发起"；已受理命令的回执恢复与在途实例不回读本表——
+ * 恢复路径的"是否已受理"判定归命令协议（T04），调用方负责在恢复命中时跳过本闸。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class FlowUsageGrantGuard {
+
+ private final FlwUsageGrantRepository grantRepository;
+ private final UserBaseActivationClient activationClient;
+
+ @Autowired(required = false)
+ private OpenApiAppClient appClient;
+
+ /** enforce 关闭时直通（灰度开关，与 FC 同款迁移策略）；开启后任何一关不过即拒 */
+ public boolean isEnforce() {
+ return activationClient.isEnforce();
+ }
+
+ /**
+ * 新发起资格核验：返回稳定主体 appId（供命令快照/审计使用）。
+ *
+ * @throws BizException enforce 开启时：主体解析不可用、无生效许可、未在该校开通、
+ * UB 资格核验不可用——四类都拒绝，不猜不降级
+ */
+ public Integer requireNewApplyGrant(Long schId, String flowGuid, String appKey) {
+ if (!isEnforce()) {
+ return null;
+ }
+ if (schId == null || flowGuid == null || flowGuid.trim().isEmpty()
+ || appKey == null || appKey.trim().isEmpty()) {
+ throw new BizException(ErrorCode.FORBIDDEN, "缺少使用许可判定所需的学校/流程线/调用主体");
+ }
+ Integer appId = resolveAppId(appKey.trim());
+ if (appId == null) {
+ throw new BizException(ErrorCode.FORBIDDEN, "调用应用主体解析不可用，已按未授权拒绝");
+ }
+ FlwUsageGrant grant = grantRepository.findBySchIdAndFlowGuidAndAppId(schId, flowGuid.trim(), appId)
+ .orElse(null);
+ if (grant == null || !Integer.valueOf(1).equals(grant.getEnabled())) {
+ log.warn("[usage-grant] 拒绝新发起（无生效使用许可）：schId={} flowGuid={} appId={} appKey={}",
+ schId, flowGuid, appId, appKey);
+ throw new BizException(ErrorCode.FORBIDDEN,
+ "该应用未获此流程线的使用许可（school=" + schId + " flow=" + flowGuid + "）");
+ }
+ if (!activationClient.isAppActivatedAtSchool(appId, schId)) {
+ log.warn("[usage-grant] 拒绝新发起（应用未在该校开通）：schId={} appId={}", schId, appId);
+ throw new BizException(ErrorCode.FORBIDDEN,
+ "该应用未在学校 " + schId + " 开通，不能发起新申报");
+ }
+ return appId;
+ }
+
+ /** appKey → UserBase 稳定主体主键；注册表不可达/查无/缺 id 一律 null（调用方拒绝） */
+ private Integer resolveAppId(String appKey) {
+ if (appClient == null) {
+ return null;
+ }
+ try {
+ JsonNode registered = appClient.getAppByKey(appKey);
+ if (registered == null || registered.isNull()) {
+ return null;
+ }
+ JsonNode idNode = registered.path("id");
+ return idNode.isNumber() ? idNode.intValue() : null;
+ } catch (RuntimeException e) {
+ log.warn("[usage-grant] UserBase 主体解析不可用 appKey={}：{}", appKey, e.toString());
+ return null;
+ }
+ }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/service/FormalApplyCommandService.java b/src/main/java/com/yunhai/flowcenter/service/FormalApplyCommandService.java
new file mode 100644
index 0000000..edd91ea
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/service/FormalApplyCommandService.java
@@ -0,0 +1,175 @@
+package com.yunhai.flowcenter.service;
+
+import com.yunhai.flowcenter.entity.*;
+import com.yunhai.flowcenter.model.FormalApplyModels;
+import com.yunhai.flowcenter.repository.*;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.RequiredArgsConstructor;
+import org.springframework.beans.BeanUtils;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.dao.DataIntegrityViolationException;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.support.TransactionTemplate;
+
+import java.util.Objects;
+
+/** Authoritative settled command facts; each accepted round gets a distinct engine instance. */
+@Service
+@RequiredArgsConstructor
+public class FormalApplyCommandService {
+ private final FlowSourcePrincipalResolver principals;
+ private final FormalPayloadCanonicalizer canonicalizer;
+ private final FlwCommandSourceRepository sources;
+ private final FlwBizCoordinateRepository coordinates;
+ private final FlwApplyCommandRepository commands;
+ private final FlwInstanceRepository instances;
+ private final FlwUsageGrantRepository grants;
+ private final UserBaseActivationClient activation;
+ private final OapiFlowService validation;
+ private final FlowInstanceService lifecycle;
+ private final TransactionTemplate transactions;
+
+ @Value("${flow-center.formal-command.enabled:false}")
+ private boolean enabled;
+
+ public FormalApplyModels.Receipt submit(Long school, String appKey, FormalApplyModels.Request request) {
+ requireEnabled();
+ validateShape(school, request);
+ FlowSourcePrincipalResolver.Principal principal = principals.resolve(appKey);
+ String hash = canonicalizer.hash(request);
+ // A source mutex INSERT can race on the very first command. Retry only outside rollback.
+ for (int attempt = 0; ; attempt++) {
+ try {
+ return transactions.execute(tx -> accept(school, principal, request, hash));
+ } catch (org.springframework.dao.TransientDataAccessException | DataIntegrityViolationException conflict) {
+ if (attempt >= 2) throw conflict;
+ }
+ }
+ }
+
+ public FormalApplyModels.Receipt query(Long school, String appKey, String requestId, String expectedHash) {
+ requireEnabled();
+ if (school == null || school <= 0 || !key(requestId, 64)) {
+ throw new BizException(ErrorCode.PARAM_ERROR, "学校/requestId 非法");
+ }
+ FlowSourcePrincipalResolver.Principal principal = principals.resolve(appKey);
+ return transactions.execute(tx -> {
+ FlwApplyCommand command = commands.findBySchIdAndSourcePrincipalIdAndRequestId(school, principal.id, requestId)
+ .orElse(null);
+ if (command == null) {
+ FormalApplyModels.Receipt absent = new FormalApplyModels.Receipt();
+ absent.setState("NOT_FOUND"); absent.setSchoolId(school);
+ absent.setSourcePrincipalId(principal.id); absent.setRequestId(requestId);
+ return absent;
+ }
+ if (expectedHash != null && !expectedHash.equals(command.getCanonicalHash())) throw conflict();
+ return receipt(command);
+ });
+ }
+
+ private FormalApplyModels.Receipt accept(Long school, FlowSourcePrincipalResolver.Principal source,
+ FormalApplyModels.Request request, String hash) {
+ FlwCommandSource mutex = sources.lock(source.id).orElse(null);
+ if (mutex == null) {
+ mutex = new FlwCommandSource(); mutex.setId(source.id); mutex.setAppId(source.appId);
+ sources.saveAndFlush(mutex);
+ } else if (!source.appId.equals(mutex.getAppId())) {
+ throw new BizException(ErrorCode.FORBIDDEN, "来源 UUID 的 UserBase 主体绑定发生变化");
+ }
+ FlwApplyCommand existing = commands.findBySchIdAndSourcePrincipalIdAndRequestId(school, source.id, request.getRequestId())
+ .orElse(null);
+ if (existing != null) {
+ if (!hash.equals(existing.getCanonicalHash())) throw conflict();
+ return receipt(existing);
+ }
+ FlwApplyCommand command = new FlwApplyCommand();
+ command.setSchId(school); command.setSourcePrincipalId(source.id); command.setRequestId(request.getRequestId());
+ command.setCanonicalHash(hash); command.setCanonicalVersion(1); command.setBizType(request.getBizType());
+ command.setBizId(request.getBizId()); command.setFlowGuid(request.getFlowGuid());
+ FlwBizCoordinate coordinate = coordinates.lock(school, source.id, request.getBizType(), request.getBizId()).orElse(null);
+ if (coordinate == null) {
+ coordinate = new FlwBizCoordinate(); coordinate.setSchId(school); coordinate.setSourcePrincipalId(source.id);
+ coordinate.setBizType(request.getBizType()); coordinate.setBizId(request.getBizId());
+ coordinates.saveAndFlush(coordinate);
+ }
+ if (instances.findBySchIdAndBizTypeAndBizId(school, request.getBizType(), request.getBizId()).isPresent()) {
+ return reject(command, "LEGACY_COORDINATE_NOT_MIGRATED", "旧业务坐标尚未审核迁移");
+ }
+ if (coordinate.getActiveInstanceId() != null) return reject(command, "IN_FLIGHT", "同一业务坐标已有在途实例");
+ if (!Objects.equals(coordinate.getLastRound(), request.getExpectedPreviousRound())
+ || !Objects.equals(coordinate.getLastInstanceId(), request.getExpectedPreviousInstanceId())) {
+ return reject(command, "PRECONDITION_FAILED", "首次申报须前轮为 0；重报须匹配前实例及轮次");
+ }
+ if (coordinate.getLastInstanceId() != null) {
+ FlwInstance previous = instances.findFormalPreviousForUpdate(coordinate.getLastInstanceId()).orElseThrow(IllegalStateException::new);
+ if (!Integer.valueOf(30).equals(previous.getStatus()) && !Integer.valueOf(40).equals(previous.getStatus())) {
+ return reject(command, "RESUBMIT_NOT_ALLOWED", "仅符合既有业务资格的拒绝/撤回件可显式新申报");
+ }
+ }
+ FlwUsageGrant grant = grants.findBySchIdAndFlowGuidAndAppId(school, request.getFlowGuid(), source.appId).orElse(null);
+ if (grant == null || !Integer.valueOf(1).equals(grant.getEnabled()) || !source.id.equals(grant.getSourcePrincipalId())) {
+ return reject(command, "USAGE_DENIED", "缺少与稳定来源绑定的流程使用许可");
+ }
+ // Unavailability throws and rolls back. A definitive false is a settled rejection.
+ if (!activation.isAppActivatedStrict(source.appId, school)) return reject(command, "SCHOOL_NOT_ACTIVATED", "调用应用未在该校开通");
+ FlowInstanceService.ApplyCommand prepared;
+ try {
+ prepared = validation.prepareFormal(school, source, request);
+ } catch (BizException denied) {
+ if (denied.getErrorCode() != ErrorCode.PARAM_ERROR && denied.getErrorCode() != ErrorCode.FORBIDDEN) throw denied;
+ return reject(command, "VALIDATION_REJECTED", denied.getMessage());
+ }
+ // Never catch persistence/engine/event failures below: the entire admission must roll back.
+ prepared.payloadHash = hash;
+ int round = Math.addExact(coordinate.getLastRound(), 1);
+ FlwInstance instance = lifecycle.createFormalInstance(prepared, request.getRequestId(), round, source.id);
+ coordinate.setLastRound(round); coordinate.setLastInstanceId(instance.getId()); coordinate.setActiveInstanceId(instance.getId());
+ coordinates.saveAndFlush(coordinate);
+ command.setState("ACCEPTED"); command.setRound(round); command.setInstanceId(instance.getId());
+ command.setDefId(instance.getDefId()); command.setDefVersion(instance.getDefVersion()); commands.saveAndFlush(command);
+ lifecycle.startFormalInstance(instance, prepared);
+ return receipt(command);
+ }
+
+ private FormalApplyModels.Receipt reject(FlwApplyCommand command, String code, String detail) {
+ command.setState("REJECTED"); command.setRejectCode(code);
+ command.setRejectDetail(detail == null ? null : detail.substring(0, Math.min(detail.length(), 500)));
+ commands.saveAndFlush(command);
+ return receipt(command);
+ }
+
+ private FormalApplyModels.Receipt receipt(FlwApplyCommand command) {
+ FormalApplyModels.Receipt result = new FormalApplyModels.Receipt();
+ BeanUtils.copyProperties(command, result);
+ result.setSchoolId(command.getSchId());
+ if ("ACCEPTED".equals(command.getState())) {
+ FlwInstance instance = instances.findById(command.getInstanceId()).orElseThrow(IllegalStateException::new);
+ if (!command.getSchId().equals(instance.getSchId()) || !command.getSourcePrincipalId().equals(instance.getSourcePrincipalId())
+ || !command.getBizType().equals(instance.getBizType()) || !command.getBizId().equals(instance.getBizId())
+ || !command.getRequestId().equals(instance.getApplyRequestToken()) || !command.getRound().equals(instance.getApplyRound())
+ || !command.getCanonicalHash().equals(instance.getApplyPayloadHash()) || !command.getDefVersion().equals(instance.getDefVersion())
+ || !Objects.equals(command.getDefId(), instance.getDefId())) {
+ throw new IllegalStateException("命令与实例事实不一致，禁止返回成功回执");
+ }
+ result.setStatus(instance.getStatus()); result.setVersion(instance.getVersion());
+ }
+ return result;
+ }
+
+ private void validateShape(Long school, FormalApplyModels.Request request) {
+ if (school == null || school <= 0 || request == null || request.getSubmitterId() == null
+ || !key(request.getRequestId(), 64) || !key(request.getBizType(), 32)
+ || !key(request.getBizId(), 64) || !key(request.getFlowGuid(), 32)) {
+ throw new BizException(ErrorCode.PARAM_ERROR, "正式命令缺少有效学校、requestId、业务坐标、流程线或提交人");
+ }
+ }
+ // MySQL 5.6 VARCHAR collations ignore trailing spaces, even *_bin. Reject, never trim/alias raw keys.
+ private boolean key(String value, int length) {
+ return value != null && !value.isEmpty() && value.equals(value.trim()) && value.length() <= length;
+ }
+ private void requireEnabled() {
+ if (!enabled) throw new BizException(ErrorCode.FORBIDDEN, "正式命令模式尚未完成迁移启用");
+ }
+ private BizException conflict() { return new BizException(ErrorCode.PARAM_ERROR, "REQUEST_ID_PAYLOAD_CONFLICT：原命令保持不变"); }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/service/FormalPayloadCanonicalizer.java b/src/main/java/com/yunhai/flowcenter/service/FormalPayloadCanonicalizer.java
new file mode 100644
index 0000000..d3f57b3
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/service/FormalPayloadCanonicalizer.java
@@ -0,0 +1,101 @@
+package com.yunhai.flowcenter.service;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.*;
+import com.yunhai.flowcenter.model.FormalApplyModels;
+import com.yunhai.flowcenter.model.OapiModels;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.*;
+
+/** v1 structural canonicalization, before definition lookup or server-side name enrichment. */
+@Component
+@RequiredArgsConstructor
+public class FormalPayloadCanonicalizer {
+ private final ObjectMapper mapper;
+
+ public String hash(FormalApplyModels.Request request) {
+ try {
+ ObjectNode node = mapper.createObjectNode();
+ node.set("flowGuid", mapper.valueToTree(request.getFlowGuid()));
+ node.set("bizType", mapper.valueToTree(request.getBizType()));
+ node.set("bizId", mapper.valueToTree(request.getBizId()));
+ node.set("bizTitle", mapper.valueToTree(request.getBizTitle()));
+ node.set("bizUrl", mapper.valueToTree(request.getBizUrl()));
+ node.set("submitterId", mapper.valueToTree(request.getSubmitterId()));
+ node.set("submitterName", mapper.valueToTree(request.getSubmitterName()));
+ node.set("formData", mapper.valueToTree(request.getFormData()));
+ node.set("expectedDefVersion", mapper.valueToTree(request.getExpectedDefVersion()));
+ node.set("expectedPreviousInstanceId", mapper.valueToTree(request.getExpectedPreviousInstanceId()));
+ node.set("expectedPreviousRound", mapper.valueToTree(request.getExpectedPreviousRound()));
+ node.set("bizSnapshot", jsonValue(request.getBizSnapshot()));
+ ObjectNode assigns = mapper.createObjectNode();
+ if (request.getAssigns() != null) {
+ for (OapiModels.AssignItem item : request.getAssigns()) {
+ if (item == null || item.getNodeId() == null || assigns.has(item.getNodeId())
+ || item.getUserIds() == null) {
+ throw invalid("指派节点缺失、重复或缺少人员集合");
+ }
+ TreeSet users = new TreeSet<>();
+ for (Integer uid : item.getUserIds()) {
+ if (uid == null || !users.add(uid)) {
+ throw invalid("指派人员为空或重复");
+ }
+ }
+ assigns.set(item.getNodeId(), mapper.valueToTree(users));
+ }
+ }
+ node.set("assigns", request.getAssigns() == null ? NullNode.instance : assigns);
+ String normalized = canonical(node);
+ byte[] bytes = MessageDigest.getInstance("SHA-256").digest(normalized.getBytes(StandardCharsets.UTF_8));
+ StringBuilder hex = new StringBuilder(64);
+ for (byte value : bytes) {
+ hex.append(Character.forDigit((value >>> 4) & 15, 16));
+ hex.append(Character.forDigit(value & 15, 16));
+ }
+ return hex.toString();
+ } catch (BizException e) {
+ throw e;
+ } catch (Exception e) {
+ throw invalid("无法规范化命令载荷");
+ }
+ }
+
+ private JsonNode jsonValue(Object value) throws Exception {
+ if (value == null) return NullNode.instance;
+ if (value instanceof String) {
+ JsonNode decoded = mapper.reader().with(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_TRAILING_TOKENS)
+ .readTree((String) value);
+ if (decoded == null) throw invalid("摘要 JSON 为空");
+ return decoded;
+ }
+ return mapper.valueToTree(value);
+ }
+
+ private String canonical(JsonNode node) throws Exception {
+ if (node.isObject()) {
+ SortedMap sorted = new TreeMap<>();
+ node.fields().forEachRemaining(e -> sorted.put(e.getKey(), e.getValue()));
+ StringJoiner out = new StringJoiner(",", "{", "}");
+ for (Map.Entry field : sorted.entrySet()) {
+ out.add(mapper.writeValueAsString(field.getKey()) + ":" + canonical(field.getValue()));
+ }
+ return out.toString();
+ }
+ if (node.isArray()) {
+ StringJoiner out = new StringJoiner(",", "[", "]");
+ for (JsonNode value : node) out.add(canonical(value));
+ return out.toString();
+ }
+ if (node.isNumber()) return node.decimalValue().stripTrailingZeros().toPlainString();
+ return mapper.writeValueAsString(node);
+ }
+
+ private BizException invalid(String message) { return new BizException(ErrorCode.PARAM_ERROR, message); }
+}
diff --git a/src/main/java/com/yunhai/flowcenter/service/OapiFlowService.java b/src/main/java/com/yunhai/flowcenter/service/OapiFlowService.java
index 0a6769b..2f1d870 100644
--- a/src/main/java/com/yunhai/flowcenter/service/OapiFlowService.java
+++ b/src/main/java/com/yunhai/flowcenter/service/OapiFlowService.java
@@ -106,15 +106,114 @@ public class OapiFlowService {
this.transactionTemplate = template;
}
+ /**
+ * T01 应用使用许可闸（2026-10-25）：新发起必须持有 (school, flowGuid, appId) 生效许可。
+ * setter 注入（构造被单测逐位钉住，同 transactionTemplate 先例）；未装配（老单测直接 new）
+ * 视为关闭，生产装配后由 {@code yh.flow.school-activation-enforce} 控制生效。
+ * enforce 开启时 UserBase 不可达 fail-closed（见 {@link FlowUsageGrantGuard}）。
+ */
+ private FlowUsageGrantGuard usageGrantGuard;
+
+ @org.springframework.beans.factory.annotation.Autowired(required = false)
+ public void setUsageGrantGuard(FlowUsageGrantGuard guard) {
+ this.usageGrantGuard = guard;
+ }
+
+ /**
+ * 发起期变量终审（字段注入：保持既有构造签名）。手工构造服务时也使用同一校验器，
+ * 所有拒绝均发生在实例创建之前。
+ */
+ private ApplyVariableValidator applyVariableValidator;
+
+ @org.springframework.beans.factory.annotation.Autowired(required = false)
+ public void setApplyVariableValidator(ApplyVariableValidator validator) {
+ this.applyVariableValidator = validator;
+ }
+
+ /** R1 SDK 快捷审批门禁（字段注入同上）：门禁无条件 fail-closed，装配与否均不放行 */
+ private FlowActorContextGate actorContextGate;
+
+ @org.springframework.beans.factory.annotation.Autowired(required = false)
+ public void setActorContextGate(FlowActorContextGate gate) {
+ this.actorContextGate = gate;
+ }
+
+ private void requireExpressionVariablesPresent(FlwDef def, String formDataJson) {
+ ApplyVariableValidator validator = applyVariableValidator == null
+ ? new ApplyVariableValidator(objectMapper) : applyVariableValidator;
+ validator.requireVariablesPresent(
+ FlowDefModel.parse(objectMapper, def.getContentJson()), formDataJson);
+ }
+
private FlowInstanceService.GuardedOutcome inTransaction(
org.springframework.transaction.support.TransactionCallback action) {
return transactionTemplate == null ? action.doInTransaction(null) : transactionTemplate.execute(action);
}
+ @Value("${flow-center.formal-command.enabled:false}")
+ private boolean formalCommandEnabled;
+
+ @org.springframework.beans.factory.annotation.Autowired
+ private FlowSourcePrincipalResolver sourcePrincipalResolver;
+ @org.springframework.beans.factory.annotation.Autowired private com.yunhai.flowcenter.repository.FlwApplyCommandRepository formalCommands;
+ @org.springframework.beans.factory.annotation.Autowired private com.yunhai.flowcenter.repository.FlwUsageGrantRepository formalGrants;
+
+ private void requireLegacyWriter() {
+ if (formalCommandEnabled) throw new BizException(ErrorCode.FORBIDDEN,
+ "正式命令模式已启用，请迁移到 /oapi/flow/commands；旧发起接口已关闭");
+ }
+
+ /** New-command validation only. Never call this while recovering a settled receipt. */
+ FlowInstanceService.ApplyCommand prepareFormal(Long schId, FlowSourcePrincipalResolver.Principal source,
+ com.yunhai.flowcenter.model.FormalApplyModels.Request body) {
+ BoaUser user;
+ try { user = userClient.getUserById(String.valueOf(body.getSubmitterId())); }
+ catch (RuntimeException unavailable) { throw new IllegalStateException("提交人权威查询不可用", unavailable); }
+ if (user == null || !Integer.valueOf(1).equals(user.getStatus()) || user.getSchool() == null || user.getSchool().getId() == null
+ || !schId.equals(Long.valueOf(user.getSchool().getId()))) {
+ throw new BizException(ErrorCode.FORBIDDEN, "提交人不存在或不属于该学校");
+ }
+ if (body.getAssigns() != null && !body.getAssigns().isEmpty() && body.getExpectedDefVersion() == null) {
+ throw new BizException(ErrorCode.PARAM_ERROR, "正式指派须携带预览定义版本锚");
+ }
+ FlwDef def = requirePublishedDefForApply(schId, body.getFlowGuid());
+ if (body.getExpectedDefVersion() != null && !body.getExpectedDefVersion().equals(def.getVersion())) {
+ throw new BizException(ErrorCode.PARAM_ERROR, "流程版本已改变，请刷新后使用新的请求 ID");
+ }
+ requireExpressionVariablesPresent(def, asFormDataString(body.getFormData()));
+ // D11：固定 USERS 属审批责任人，正式命令在受理阶段整体终审——任一非法即 VALIDATION_REJECTED，
+ // 不落实例、不做“过滤后继续”。运行期建任务仍由 FlowEngine/AssigneeResolver 再兜底。
+ assigneeResolver.requireEligibleFixedAssignees(schId, FlowDefModel.parse(objectMapper, def.getContentJson()));
+ String assigns = renderAssignJson(schId, def, body.getAssigns(), body.getSubmitterId());
+ return new FlowInstanceService.ApplyCommand(schId, def, body.getBizType(), body.getBizId(),
+ body.getBizTitle(), body.getBizUrl(), asSnapshotString(body.getBizSnapshot()),
+ body.getSubmitterId(), body.getSubmitterName(), asFormDataString(body.getFormData()),
+ source.appKey, source.appCode, assigns);
+ }
+
+ private boolean canReadFormalDefinition(Long school, String flow) {
+ String source = FlowOapiSourceScope.current();
+ return formalGrants.existsBySchIdAndFlowGuidAndSourcePrincipalIdAndEnabled(school, flow, source, 1)
+ || formalCommands.existsBySchIdAndSourcePrincipalIdAndFlowGuidAndState(school, source, flow, "ACCEPTED");
+ }
+
+ private void requireFormalPreviewGrant(Long school, String flow) {
+ if (!formalCommandEnabled) return;
+ FlowSourcePrincipalResolver.Principal principal = sourcePrincipalResolver.resolve(
+ (String)((org.springframework.web.context.request.ServletRequestAttributes)org.springframework.web.context.request.RequestContextHolder.currentRequestAttributes()).getRequest().getAttribute("yh.app.auth"));
+ if (!formalGrants.existsBySchIdAndFlowGuidAndSourcePrincipalIdAndEnabled(school, flow, principal.id, 1)
+ || !formalActivation.isAppActivatedStrict(principal.appId, school)) {
+ throw new BizException(ErrorCode.FORBIDDEN, "没有此流程线的发起预览权限");
+ }
+ }
+
+ @org.springframework.beans.factory.annotation.Autowired private UserBaseActivationClient formalActivation;
+
/** 已发布流程列表（每条流程线取最高已发布版本） */
public List listFlows(Long schId) {
List out = new ArrayList<>();
for (FlwDef def : defRepository.findPublishedLatestPerGuid(schId)) {
+ if (formalCommandEnabled && !canReadFormalDefinition(schId, def.getFlowGuid())) continue;
out.add(toSummary(def));
}
return out;
@@ -122,6 +221,7 @@ public class OapiFlowService {
/** 流程详情回显（未发布/不存在返回 null，消费方按"未绑定流程"降级） */
public OapiModels.FlowSummaryVo getFlow(Long schId, String flowGuid) {
+ if (formalCommandEnabled && !canReadFormalDefinition(schId, flowGuid)) return null;
return defRepository.findFirstBySchIdAndFlowGuidAndStatusOrderByVersionDesc(
schId, flowGuid, FlwEnums.DefStatus.PUBLISHED.getCode())
.map(this::toSummary).orElse(null);
@@ -131,16 +231,20 @@ public class OapiFlowService {
* 与 app_code 一起快照进办件（消息 jump_app 的权威来源，2026-10-12 起替代 bizType 冒充） */
@Transactional
public OapiModels.ApplyResultVo apply(Long schId, String appKey, OapiModels.ApplyBody body) {
+ requireLegacyWriter();
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()));
+ String cleanAppKey = appKey == null || appKey.trim().isEmpty() ? null : appKey.trim();
+ // T01 使用许可（v1 路径）：回执幂等（既有在途/通过件）不拦；无实例或终态件 R4 重启=新申报，
+ // 必须持有效使用许可。恢复感知的分支判定与 FlowInstanceService.apply 保持同键同序。
+ requireUsageGrantLegacyApply(schId, body.getFlowGuid(), cleanAppKey, body.getBizType(), body.getBizId());
+ FlwDef def = requirePublishedDefForApply(schId, body.getFlowGuid());
+ // T06 变量终审：EXPRESSION 引用的业务变量缺失/空=null 即拒（零实例），不等运行期 nil 放行
+ requireExpressionVariablesPresent(def, asFormDataString(body.getFormData()));
// S2.7 版本竞态（可选、opt-in）：调用方回带预览时的定义版本，改版即人类可读拒绝，
// 免得选好的 nodeId/候选人在新版本里对不上而报「指派节点不存在」。不传=现状逐字不变。
if (body.getExpectedDefVersion() != null
@@ -150,7 +254,6 @@ public class OapiFlowService {
+ "，当前已发布版本 " + def.getVersion() + "）");
}
String assignJson = renderAssignJson(schId, def, body.getAssigns(), body.getSubmitterId());
- String cleanAppKey = appKey == null || appKey.trim().isEmpty() ? null : appKey.trim();
FlowInstanceService.ApplyCommand cmd = new FlowInstanceService.ApplyCommand(
schId, def,
body.getBizType(), body.getBizId(), body.getBizTitle(),
@@ -184,23 +287,40 @@ public class OapiFlowService {
*/
public FlowApplyRetryModels.ApplyResultV2 applyV2(Long schId, String appKey,
FlowApplyRetryModels.ApplyRequestV2 body) {
+ requireLegacyWriter();
if (schId == null || body == 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()));
- if (body.getExpectedDefVersion() != null && !body.getExpectedDefVersion().equals(def.getVersion())) {
+ String cleanAppKey = appKey == null || appKey.trim().isEmpty() ? null : appKey.trim();
+ // T01 使用许可（v2 路径）：恢复感知——SAME_REQUEST/REPLAY_ONLY/IDEMPOTENT/STALE_ROUND
+ // 四类回执分支不拦（已受理命令的回执不因许可撤销丢失）；CREATED/RESTARTED（新申报/新轮）
+ // 必须持有效使用许可。分支判定与 FlowInstanceService.applyGuarded 同键同序；
+ // 完整命令协议（requestId/指纹/服务端轮次）统一归 T04 重排，此处不重构。
+ requireUsageGrantGuardedApply(schId, body.getFlowGuid(), cleanAppKey, body.getBizType(),
+ body.getBizId(), body.getRequestToken(), body.getAttempt(),
+ Boolean.TRUE.equals(body.getRetryOnly()));
+ FlwInstance existing = instanceRepository.findBySchIdAndBizTypeAndBizId(
+ schId, body.getBizType(), body.getBizId()).orElse(null);
+ boolean replay = existing != null && body.getRequestToken() != null
+ && !body.getRequestToken().trim().isEmpty()
+ && body.getRequestToken().trim().equals(existing.getApplyRequestToken());
+ // 同 token 用已受理版本构造原指纹；归属和异载荷冲突仍由 applyGuarded 原守卫裁决。
+ FlwDef def = replay ? defRepository.findById(existing.getDefId())
+ .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "原请求的定义版本不存在"))
+ : requirePublishedDefForApply(schId, body.getFlowGuid());
+ if (replay && !body.getFlowGuid().equals(def.getFlowGuid())) {
+ throw new BizException(ErrorCode.FORBIDDEN, "该业务键的办件绑定的流程线不同");
+ }
+ if (!replay) requireExpressionVariablesPresent(def, asFormDataString(body.getFormData()));
+ if (!replay && body.getExpectedDefVersion() != null && !body.getExpectedDefVersion().equals(def.getVersion())) {
throw new BizException(ErrorCode.PARAM_ERROR,
"流程已更新，请刷新后重新选择审批人（期望定义版本 " + body.getExpectedDefVersion()
+ "，当前已发布版本 " + def.getVersion() + "）");
}
String assignJson = renderAssignJson(schId, def, body.getAssigns(), body.getSubmitterId());
- String cleanAppKey = appKey == null || appKey.trim().isEmpty() ? null : appKey.trim();
FlowInstanceService.ApplyCommand cmd = new FlowInstanceService.ApplyCommand(
schId, def,
body.getBizType(), body.getBizId(), body.getBizTitle(),
@@ -208,8 +328,11 @@ public class OapiFlowService {
body.getSubmitterId(), body.getSubmitterName(),
asFormDataString(body.getFormData()),
cleanAppKey, resolveApplyAppCode(cleanAppKey), assignJson);
+ // T04：受理载荷指纹（服务端计算，不信任客户端自报）——同 token 异载荷按冲突拒绝
+ cmd.payloadHash = payloadHash(cmd);
FlowInstanceService.ApplyRetryPolicy policy = new FlowInstanceService.ApplyRetryPolicy(
- body.getRequestToken(), body.getAttempt(), Boolean.TRUE.equals(body.getRetryOnly()));
+ body.getRequestToken(), body.getAttempt(), Boolean.TRUE.equals(body.getRetryOnly()),
+ body.getExpectedPrevRound());
FlowInstanceService.GuardedOutcome outcome;
try {
@@ -218,6 +341,7 @@ public class OapiFlowService {
// 事务边界外重读：另一个并发请求已用同一业务键建好办件
return fromConcurrent(schId, cmd, policy);
}
+ requireNotConflict(outcome);
FlowApplyRetryModels.ApplyResultV2 vo = new FlowApplyRetryModels.ApplyResultV2();
vo.setInstanceId(outcome.instanceId);
vo.setDuplicated(outcome.duplicated);
@@ -235,6 +359,137 @@ public class OapiFlowService {
return vo;
}
+ /**
+ * 新发起的当前有效发布版解析（2026-10-25 T03 收口）：最高已发布版 + 线级停发守卫——
+ * 整线停发（line_offline=1）即拒绝新发起，且不回退到更旧的已发布版本（停发不是降级）。
+ * 在途实例不受影响（推进按实例固定 defId，不经本方法）。
+ */
+ private FlwDef requirePublishedDefForApply(Long schId, String flowGuid) {
+ FlwDef def = defRepository.findFirstBySchIdAndFlowGuidAndStatusOrderByVersionDesc(
+ schId, flowGuid, FlwEnums.DefStatus.PUBLISHED.getCode())
+ .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR,
+ "流程不存在或未发布：" + flowGuid));
+ if (def.getLineOffline() != null && def.getLineOffline() == 1) {
+ throw new BizException(ErrorCode.PARAM_ERROR,
+ "流程线已停发，暂停新发起（在途办件不受影响）：" + flowGuid);
+ }
+ return def;
+ }
+
+ /**
+ * T01 使用许可闸·v1 路径（恢复感知最小形态）：v1 无 token/轮次，回执与新申报的区分只能靠
+ * 既有实例状态——在途（10）/通过（20）命中=幂等回读放行；无实例=CREATED；终态（30/40）=R4
+ * 重启即新一轮申报。guard 未装配或未 enforce 时零行为（灰度开关，见 {@link FlowUsageGrantGuard}）。
+ */
+ private void requireUsageGrantLegacyApply(Long schId, String flowGuid, String appKey,
+ String bizType, String bizId) {
+ if (usageGrantGuard == null || !usageGrantGuard.isEnforce() || appKey == null) {
+ return;
+ }
+ FlwInstance existing = instanceRepository
+ .findBySchIdAndBizTypeAndBizId(schId, bizType, bizId).orElse(null);
+ if (!legacyApplyIsReceiptOnly(existing)) {
+ usageGrantGuard.requireNewApplyGrant(schId, flowGuid, appKey);
+ }
+ }
+
+ /**
+ * T01 使用许可闸·v2 路径：与 {@code FlowInstanceService.applyGuarded/settleExisting}
+ * 同键同序的分支预判（判定逻辑见 {@link #guardedApplyIsReceiptOnly}）；
+ * 新申报（CREATED/RESTARTED）必须过 {@link FlowUsageGrantGuard#requireNewApplyGrant}。
+ * 完整命令协议统一归 T04。
+ */
+ private void requireUsageGrantGuardedApply(Long schId, String flowGuid, String appKey,
+ String bizType, String bizId,
+ String requestToken, Integer attempt, boolean retryOnly) {
+ if (usageGrantGuard == null || !usageGrantGuard.isEnforce() || appKey == null) {
+ return;
+ }
+ FlwInstance existing = instanceRepository
+ .findBySchIdAndBizTypeAndBizId(schId, bizType, bizId).orElse(null);
+ if (!guardedApplyIsReceiptOnly(existing, requestToken, attempt, retryOnly)) {
+ usageGrantGuard.requireNewApplyGrant(schId, flowGuid, appKey);
+ }
+ }
+
+ /**
+ * v1 回执判定：true=该请求只会命中幂等回读（不建件不重启），false=会触发新申报或 R4 重启。
+ * 与 {@code FlowInstanceService.apply(ApplyCommand)} 的分支一一对应（包私有便于规则单测钉住）。
+ */
+ static boolean legacyApplyIsReceiptOnly(FlwInstance existing) {
+ return existing != null
+ && (existing.getStatus() == FlwEnums.InstanceStatus.APPROVING.getCode()
+ || existing.getStatus() == FlwEnums.InstanceStatus.COMPLETED.getCode());
+ }
+
+ /**
+ * v2 回执判定：与 {@code applyGuarded/settleExisting} 同键同序——
+ * SAME_REQUEST（同 token）→ REPLAY_ONLY（retryOnly）→ IDEMPOTENT（在途/通过）→
+ * STALE_ROUND（请求轮次≤行轮次，缺省按 1）四类回执返回 true；CREATED/RESTARTED 返回 false。
+ */
+ static boolean guardedApplyIsReceiptOnly(FlwInstance existing, String requestToken,
+ Integer attempt, boolean retryOnly) {
+ if (existing == null) {
+ return false;
+ }
+ String token = requestToken == null ? null : requestToken.trim();
+ if (token != null && !token.isEmpty() && token.equals(existing.getApplyRequestToken())) {
+ return true;
+ }
+ if (retryOnly) {
+ return true;
+ }
+ if (existing.getStatus() == FlwEnums.InstanceStatus.APPROVING.getCode()
+ || existing.getStatus() == FlwEnums.InstanceStatus.COMPLETED.getCode()) {
+ return true;
+ }
+ int currentRound = existing.getApplyRound() == null ? 1 : existing.getApplyRound();
+ int incomingRound = attempt == null ? 1 : attempt;
+ return incomingRound <= currentRound;
+ }
+
+ /**
+ * T04：CONFLICT 分支统一翻译成业务异常——冲突不是成功，调用方（SH 恢复链）收到 4xx
+ * 走 UNKNOWN → 按来源+token 复核，不得把他人/其他轮次的在途件当自己的受理结果。
+ */
+ private static void requireNotConflict(FlowInstanceService.GuardedOutcome outcome) {
+ if (outcome != null && FlowApplyRetryModels.Branch.CONFLICT.equals(outcome.branch)) {
+ throw new BizException(ErrorCode.CUSTOM,
+ "该业务键已有在途/终态申报且请求标识不符（另一命令或另一轮次），"
+ + "请按实例查询恢复，禁止跨命令认领；终态后重新申报请走显式重提");
+ }
+ }
+
+ /**
+ * 受理载荷指纹（T04）：SHA-256(流序规范化) over flowGuid|bizType|bizId|submitterId|bizTitle|
+ * bizUrl|bizSnapshot|formData|assignJson。重发链载荷逐字节同源 → 同指纹；
+ * 任何业务字段改动 → 不同指纹 → 冲突。expectedDefVersion 刻意不参与（重试期间发布新版本
+ * 不应把同一次命令误判成两份）。
+ */
+ private String payloadHash(FlowInstanceService.ApplyCommand cmd) {
+ String canon = String.join("|",
+ nullSafe(cmd.def == null ? null : cmd.def.getFlowGuid()),
+ nullSafe(cmd.bizType), nullSafe(cmd.bizId),
+ cmd.submitterId == null ? "" : String.valueOf(cmd.submitterId),
+ nullSafe(cmd.bizTitle), nullSafe(cmd.bizUrl),
+ nullSafe(cmd.bizSnapshot), nullSafe(cmd.formDataJson), nullSafe(cmd.assignJson));
+ try {
+ byte[] digest = java.security.MessageDigest.getInstance("SHA-256")
+ .digest(canon.getBytes(java.nio.charset.StandardCharsets.UTF_8));
+ StringBuilder sb = new StringBuilder(64);
+ for (byte b : digest) {
+ sb.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16));
+ }
+ return sb.toString();
+ } catch (java.security.NoSuchAlgorithmException e) {
+ throw new IllegalStateException("SHA-256 unavailable", e);
+ }
+ }
+
+ private static String nullSafe(String v) {
+ return v == null ? "" : v;
+ }
+
/**
* 并发撞键后的收口：重读既有实例 → 先核归属 → 同 token 记 {@code SAME_REQUEST}，
* 否则按幂等命中回读。归属不符就拒绝，绝不返回别人的办件 id。
@@ -263,8 +518,16 @@ public class OapiFlowService {
vo.setApplyRound(existing.getApplyRound());
vo.setStatus(existing.getStatus());
vo.setVersion(existing.getVersion());
- vo.setBranch(token != null && token.equals(existing.getApplyRequestToken())
- ? FlowApplyRetryModels.Branch.SAME_REQUEST : FlowApplyRetryModels.Branch.CONCURRENT_CREATED);
+ if (token != null && !token.equals(existing.getApplyRequestToken())) {
+ // T04：并发撞键且 token 不符=两份不同命令抢同一业务键——后到者冲突，不伪装幂等成功
+ //（旧 CONCURRENT_CREATED 分支只保留给无 token 的存量调用方）。
+ log.warn("[flow-center] 并发建件 token 不符（冲突拒绝）：instance={} biz={}/{}",
+ existing.getId(), cmd.bizType, cmd.bizId);
+ throw new BizException(ErrorCode.CUSTOM,
+ "该业务键已被另一并发命令创建（请求标识不符），请按实例查询恢复，不要换 ID 重发");
+ }
+ vo.setBranch(token != null ? FlowApplyRetryModels.Branch.SAME_REQUEST
+ : FlowApplyRetryModels.Branch.CONCURRENT_CREATED);
log.warn("[flow-center] 并发建件命中既有实例：instance={} biz={}/{} branch={}",
existing.getId(), cmd.bizType, cmd.bizId, vo.getBranch());
return vo;
@@ -298,12 +561,45 @@ public class OapiFlowService {
* apply 时指派严格校验（方案 §5.2 五条，不变量 I7）+ 快照渲染。
* assigns 空 → null（宽松回退 D3）。任何不过 → BizException(PARAM_ERROR) 拒绝发起。
*/
+ /**
+ * T06 required 覆盖判定（包私有纯函数，规则单测钉住）：定义里全部开启且必选的指派节点中，
+ * 提交项未覆盖的 nodeId 列表。空 assigns + 存在必选节点 ⇒ 全部缺失（空 assigns 不绕过）。
+ */
+ static List missingRequiredAssignNodes(FlowDefModel model, List assigns) {
+ java.util.Set submitted = new java.util.HashSet<>();
+ if (assigns != null) {
+ for (OapiModels.AssignItem item : assigns) {
+ if (item.getNodeId() != null) {
+ submitted.add(item.getNodeId());
+ }
+ }
+ }
+ List missing = new ArrayList<>();
+ for (FlowDefModel.Node n : model.nodes) {
+ if (n == null || !FlowDefModel.TYPE_APPROVAL.equals(n.type) || n.assignPolicy == null
+ || !Boolean.TRUE.equals(n.assignPolicy.required)) {
+ continue;
+ }
+ if (!submitted.contains(n.id)) {
+ missing.add(n.id);
+ }
+ }
+ return missing;
+ }
+
private String renderAssignJson(Long schId, FlwDef def, List assigns,
Integer submitterId) {
+ FlowDefModel model = FlowDefModel.parse(objectMapper, def.getContentJson());
+ // T06（2026-10-25）required 覆盖终审：遍历定义里全部开启且必选的指派节点——
+ // 不能只遍历请求里出现的项，更不能让空 assigns 绕过 required 检查（审计 §7.4 点名）。
+ List missing = missingRequiredAssignNodes(model, assigns);
+ if (!missing.isEmpty()) {
+ throw new BizException(ErrorCode.PARAM_ERROR,
+ "必选指派节点未提交人选（node=" + String.join(", ", missing) + "），请重新选择后提交");
+ }
if (assigns == null || assigns.isEmpty()) {
return null;
}
- FlowDefModel model = FlowDefModel.parse(objectMapper, def.getContentJson());
Map>> snapshot = new java.util.LinkedHashMap<>();
Set seenNodeIds = new LinkedHashSet<>();
for (OapiModels.AssignItem item : assigns) {
@@ -329,6 +625,16 @@ public class OapiFlowService {
throw new BizException(ErrorCode.PARAM_ERROR,
"不允许指派发起人本人：" + item.getNodeId());
}
+ // D11：手选人先逐人资格终审（存在/启用/校域），再核候选集——任一人不合格整体拒绝，
+ // 快照与实例均不落；不能只信前端候选列表，也不能以“在候选 ID 中”替代资格。
+ List> rows = new ArrayList<>();
+ for (Integer uid : uids) {
+ String userName = assigneeResolver.requireEligibleAssigneeName(schId, uid);
+ Map row = new HashMap<>();
+ row.put("userId", uid);
+ row.put("userName", userName);
+ rows.add(row);
+ }
// 候选集取 apply 时点全量（不剔除发起人，存量口径）；越集=契约破坏，拒绝
List candidates = assigneeResolver.resolve(schId, node);
Set candidateIds = new LinkedHashSet<>();
@@ -355,14 +661,6 @@ public class OapiFlowService {
"指派人数越界[" + min + "~" + max + "]：" + item.getNodeId());
}
}
- List> rows = new ArrayList<>();
- for (Integer uid : uids) {
- String userName = assigneeResolver.requireUserName(uid);
- Map row = new HashMap<>();
- row.put("userId", uid);
- row.put("userName", userName);
- rows.add(row);
- }
snapshot.put(item.getNodeId(), rows);
}
try {
@@ -377,13 +675,11 @@ public class OapiFlowService {
* 节点级解析异常降级空列表（I6）。
*/
public OapiModels.ApplyPreviewVo applyPreview(Long schId, String flowGuid, Integer submitterId) {
+ requireFormalPreviewGrant(schId, flowGuid);
if (schId == null || flowGuid == null || submitterId == null) {
throw new BizException(ErrorCode.PARAM_ERROR, "缺少必要参数：schId/flowGuid/submitterId");
}
- FlwDef def = defRepository.findFirstBySchIdAndFlowGuidAndStatusOrderByVersionDesc(
- schId, flowGuid, FlwEnums.DefStatus.PUBLISHED.getCode())
- .orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR,
- "流程不存在或未发布：" + flowGuid));
+ FlwDef def = requirePublishedDefForApply(schId, flowGuid);
FlowDefModel model = FlowDefModel.parse(objectMapper, def.getContentJson());
OapiModels.ApplyPreviewVo vo = new OapiModels.ApplyPreviewVo();
vo.setFlowGuid(def.getFlowGuid());
@@ -432,7 +728,7 @@ public class OapiFlowService {
/** 按业务键查办件（对账兜底；不存在返回 null——对账方按"漂移待清理"处理） */
public OapiModels.InstanceVo instanceByBiz(Long schId, String bizType, String bizId) {
- FlwInstance instance = instanceRepository.findBySchIdAndBizTypeAndBizId(schId, bizType, bizId)
+ FlwInstance instance = findByBizForOapi(schId, bizType, bizId)
.orElse(null);
return instance == null ? null : toInstanceVo(instance);
}
@@ -448,8 +744,9 @@ public class OapiFlowService {
if (schId == null || assigneeId == null) {
throw new BizException(ErrorCode.PARAM_ERROR, "缺少必要参数：schId/assigneeId");
}
- Page p = taskRepository.pageTodoBiz(schId, assigneeId, emptyToNull(bizType),
- PageRequest.of(normPage(page), normSize(size)));
+ Page p = formalCommandEnabled
+ ? taskRepository.pageSelfTodo(schId, FlowOapiSourceScope.current(), assigneeId, emptyToNull(bizType), PageRequest.of(normPage(page), normSize(size)))
+ : taskRepository.pageTodoBiz(schId, assigneeId, emptyToNull(bizType), PageRequest.of(normPage(page), normSize(size)));
List instanceIds = p.getContent().stream()
.map(FlwTask::getInstanceId).distinct().collect(java.util.stream.Collectors.toList());
Map instances = instanceIds.isEmpty()
@@ -468,8 +765,9 @@ public class OapiFlowService {
if (schId == null) {
throw new BizException(ErrorCode.PARAM_ERROR, "缺少必要参数：schId");
}
- Page p = instanceRepository.pageByBiz(schId, emptyToNull(bizType), status,
- PageRequest.of(normPage(page), normSize(size)));
+ Page p = formalCommandEnabled
+ ? instanceRepository.pageSelf(schId, FlowOapiSourceScope.current(), emptyToNull(bizType), status, PageRequest.of(normPage(page), normSize(size)))
+ : instanceRepository.pageByBiz(schId, emptyToNull(bizType), status, PageRequest.of(normPage(page), normSize(size)));
List items = p.getContent().stream()
.map(this::toInstanceItemVo).collect(java.util.stream.Collectors.toList());
return toPageResult(p.getTotalElements(), items, page, size);
@@ -501,8 +799,7 @@ public class OapiFlowService {
OapiModels.ByBizTasksVo vo = new OapiModels.ByBizTasksVo();
vo.setBizType(cleanBizType);
vo.setBizId(cleanBizId);
- FlwInstance instance = instanceRepository
- .findBySchIdAndBizTypeAndBizId(schId, cleanBizType, cleanBizId).orElse(null);
+ FlwInstance instance = findByBizForOapi(schId, cleanBizType, cleanBizId).orElse(null);
if (instance == null) {
return vo;
}
@@ -557,6 +854,7 @@ public class OapiFlowService {
@Transactional
public FlwTask approveTask(Long schId, Long taskId, Integer operatorId, String operatorName,
String opinion, String edgeName) {
+ requireActorProof(schId, taskId, operatorId);
requireOperator(schId, taskId, operatorId, operatorName);
return taskService.handle(schId, taskId, true, opinion, operatorId, edgeName);
}
@@ -565,10 +863,27 @@ public class OapiFlowService {
@Transactional
public FlwTask rejectTask(Long schId, Long taskId, Integer operatorId, String operatorName,
String opinion) {
+ requireActorProof(schId, taskId, operatorId);
requireOperator(schId, taskId, operatorId, operatorName);
return taskService.handle(schId, taskId, false, opinion, operatorId);
}
+ /**
+ * R1（Codex D03）：oapi 审批统一过 ActorContext 门——门禁本身无条件 fail-closed；
+ * 未装配（手工构造的老单测）时同样拒绝，不存在"未装配=直通"豁免。
+ */
+ private void requireActorProof(Long schId, Long taskId, Integer operatorId) {
+ if (actorContextGate != null) {
+ actorContextGate.requireActorProof(schId, taskId, operatorId);
+ return;
+ }
+ log.warn("[actor-gate] oapi 快捷审批被拒（门禁未装配，fail-closed）：schId={} taskId={} operatorId={}",
+ schId, taskId, operatorId);
+ throw new BizException(ErrorCode.FORBIDDEN,
+ "SDK 快捷审批未放行：仅凭 appKey/operatorId 不构成用户授权。"
+ + "请通过流程中心人工办理页（CAS）办理");
+ }
+
private void requireOperator(Long schId, Long taskId, Integer operatorId, String operatorName) {
if (schId == null || taskId == null || operatorId == null) {
throw new BizException(ErrorCode.PARAM_ERROR, "缺少必要参数：schId/taskId/operatorId");
@@ -673,7 +988,7 @@ public class OapiFlowService {
if (bizType == null || bizId == null) {
throw new BizException(ErrorCode.PARAM_ERROR, "缺少必要参数：instanceId 或 bizType/bizId");
}
- instance = instanceRepository.findBySchIdAndBizTypeAndBizId(schId, bizType, bizId)
+ instance = findByBizForOapi(schId, bizType, bizId)
.orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "办件不存在或不可见"));
}
return toProgressVo(instance);
@@ -686,6 +1001,10 @@ public class OapiFlowService {
* 业务边界保证），浏览器侧只认 token。
*/
public OapiModels.DiagramUrlVo diagramUrl(Long schId, Long instanceId, String flowGuid, String mode) {
+ if (formalCommandEnabled && instanceId == null && !canReadFormalDefinition(schId, flowGuid)) {
+ throw new BizException(ErrorCode.FORBIDDEN, "没有此流程定义的读取权限");
+ }
+
if (flowGuid != null && !flowGuid.trim().isEmpty()) {
FlwDef def = defRepository.findFirstBySchIdAndFlowGuidAndStatusOrderByVersionDesc(
schId, flowGuid.trim(), FlwEnums.DefStatus.PUBLISHED.getCode())
@@ -767,6 +1086,12 @@ public class OapiFlowService {
}
/** 进度/换图共用的办件定位（schId 收敛在次） */
+ private java.util.Optional findByBizForOapi(Long school, String type, String biz) {
+ return formalCommandEnabled
+ ? instanceRepository.findFirstBySchIdAndSourcePrincipalIdAndBizTypeAndBizIdOrderByApplyRoundDesc(school, FlowOapiSourceScope.current(), type, biz)
+ : instanceRepository.findBySchIdAndBizTypeAndBizId(school, type, biz);
+ }
+
private FlwInstance requireInstance(Long schId, Long instanceId) {
FlwInstance instance = instanceRepository.findById(instanceId)
.orElseThrow(() -> new BizException(ErrorCode.PARAM_ERROR, "办件不存在：" + instanceId));
@@ -1031,6 +1356,15 @@ public class OapiFlowService {
reg.setAppKey(appKey);
reg.setFlowGuid(body.getFlowGuid());
}
+ if (formalCommandEnabled) {
+ FlowSourcePrincipalResolver.Principal source = sourcePrincipalResolver.resolve(appKey);
+ com.yunhai.flowcenter.entity.FlwUsageGrant grant = formalGrants.findBySchIdAndFlowGuidAndAppId(schId, body.getFlowGuid(), source.appId).orElse(null);
+ boolean permitted = grant != null && Integer.valueOf(1).equals(grant.getEnabled()) && source.id.equals(grant.getSourcePrincipalId());
+ if (!permitted && !formalCommands.existsBySchIdAndSourcePrincipalIdAndFlowGuidAndState(schId, source.id, body.getFlowGuid(), "ACCEPTED")) {
+ throw new BizException(ErrorCode.FORBIDDEN, "没有 SELF 订阅权限");
+ }
+ reg.setSourcePrincipalId(source.id);
+ }
reg.setCallbackUrl(body.getCallbackUrl());
reg.setEventTypes(body.getEventTypes());
reg.setBasePath(body.getBasePath());
@@ -1125,6 +1459,7 @@ public class OapiFlowService {
vo.setInstanceId(instance.getId());
vo.setApplyRound(instance.getApplyRound());
vo.setRequestToken(instance.getApplyRequestToken());
+ vo.setApplyAppKey(instance.getApplyAppKey());
vo.setStatus(instance.getStatus());
vo.setVersion(instance.getVersion());
vo.setBizTitle(instance.getBizTitle());
diff --git a/src/main/java/com/yunhai/flowcenter/service/UserBaseActivationClient.java b/src/main/java/com/yunhai/flowcenter/service/UserBaseActivationClient.java
new file mode 100644
index 0000000..a958b08
--- /dev/null
+++ b/src/main/java/com/yunhai/flowcenter/service/UserBaseActivationClient.java
@@ -0,0 +1,81 @@
+package com.yunhai.flowcenter.service;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.yunhai.platform.apistd.BizException;
+import com.yunhai.platform.openapi.core.PlatformService;
+import com.yunhai.platform.openapi.core.YschOpenCall;
+import com.yunhai.platform.utils.exception.ErrorCode;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * UserBase「应用×学校开通」事实核验客户端（2026-10-25 T01，flow-center 侧）。
+ *
+ * 事实源=UserBase {@code sys_group_app_rel}（学校组单点开通，不沿祖先），
+ * 开放端点 {@code GET /oapi/app/activated?appId=&schoolId=}。enforce 开启时
+ * 不可达/异常一律抛错（fail-closed）——"UserBase 不可达"不得降级为"仅本地 grant 存在即放行"。
+ */
+@Slf4j
+@Component
+public class UserBaseActivationClient {
+
+ private static final String ACTIVATED_PATH = "/oapi/app/activated";
+
+ private final YschOpenCall openCall;
+
+ /**
+ * 资格核验总开关（T01 灰度）：false=不核（存量环境兼容）；true=强制核验。
+ * 生产开启前须确认 UserBase 已部署 {@code /oapi/app/activated} 且开通数据齐备。
+ */
+ @Value("${yh.flow.school-activation-enforce:false}")
+ private boolean enforce;
+
+ public UserBaseActivationClient(@Autowired(required = false) YschOpenCall openCall) {
+ this.openCall = openCall;
+ }
+
+ public boolean isEnforce() {
+ return enforce;
+ }
+
+ /**
+ * @return true=已开通；false=明确未开通（调用方按"未获使用资格"拒绝）
+ * @throws BizException enforce 开启且 UserBase 不可达/返回异常——fail-closed
+ */
+ public boolean isAppActivatedAtSchool(Integer appId, Long schoolId) {
+ if (!enforce) {
+ return true;
+ }
+ return isAppActivatedStrict(appId, schoolId);
+ }
+
+ /** Formal commands never inherit the legacy bypass switch. */
+ public boolean isAppActivatedStrict(Integer appId, Long schoolId) {
+ if (appId == null || schoolId == null || schoolId <= 0) {
+ throw new BizException(ErrorCode.UNAUTHORIZED, "应用学校开通资格核验缺少主体或校域");
+ }
+ if (openCall == null) {
+ throw new BizException(ErrorCode.UNAUTHORIZED, "应用学校开通资格核验不可用（未配置出站通道）");
+ }
+ Map query = new HashMap<>();
+ query.put("appId", String.valueOf(appId));
+ query.put("schoolId", String.valueOf(schoolId));
+ JsonNode data;
+ try {
+ data = openCall.get(PlatformService.USERBASE.key(), ACTIVATED_PATH, query, JsonNode.class);
+ } catch (RuntimeException e) {
+ log.warn("[usage-grant] UserBase 开通资格核验失败 appId={} schoolId={}：{}", appId, schoolId, e.toString());
+ throw new BizException(ErrorCode.UNAUTHORIZED, "应用学校开通资格核验不可用，请稍后重试");
+ }
+ if (data == null || data.isNull() || !data.hasNonNull("activated")) {
+ log.warn("[usage-grant] UserBase 开通资格核验返回异常 appId={} schoolId={}", appId, schoolId);
+ throw new BizException(ErrorCode.UNAUTHORIZED, "应用学校开通资格核验不可用，请稍后重试");
+ }
+ return data.path("activated").asBoolean(false);
+ }
+}
diff --git a/src/main/resources/sql/20261025_add_flw_def_line_offline.sql b/src/main/resources/sql/20261025_add_flw_def_line_offline.sql
new file mode 100644
index 0000000..3c36ef7
--- /dev/null
+++ b/src/main/resources/sql/20261025_add_flw_def_line_offline.sql
@@ -0,0 +1,6 @@
+-- 2026-10-25 T03：流程线级停发标志（整线停新发起，不影响在途；与版本级 status 正交）
+-- ddl-auto=update 会自动加列（NOT NULL DEFAULT 0）；本脚本为生产备案
+ALTER TABLE `flw_def`
+ ADD COLUMN `line_offline` INT NOT NULL DEFAULT 0 COMMENT '线级停发：1=整线停新发起/预览（在途不受影响）' AFTER `version`;
+
+-- 已有生产索引不含 line_offline；新发起解析走 (sch_id, flow_guid, status, version) 既有索引后过滤，暂不加列索引
diff --git a/src/main/resources/sql/20261025_add_flw_instance_payload_hash.sql b/src/main/resources/sql/20261025_add_flw_instance_payload_hash.sql
new file mode 100644
index 0000000..c09bd8c
--- /dev/null
+++ b/src/main/resources/sql/20261025_add_flw_instance_payload_hash.sql
@@ -0,0 +1,4 @@
+-- 2026-10-25 T04：受理载荷指纹（同 requestToken 不同载荷=冲突，不伪装幂等）
+-- ddl-auto=update 会自动加列；本脚本为生产备案。存量行保持 NULL=指纹核对缺省关。
+ALTER TABLE `flw_instance`
+ ADD COLUMN `apply_payload_hash` VARCHAR(64) NULL COMMENT '受理时规范载荷指纹 SHA-256（T04 同ID同指纹幂等/异载荷冲突）' AFTER `apply_round`;
diff --git a/src/main/resources/sql/20261025_create_flw_state_event_and_intent.sql b/src/main/resources/sql/20261025_create_flw_state_event_and_intent.sql
new file mode 100644
index 0000000..310bb24
--- /dev/null
+++ b/src/main/resources/sql/20261025_create_flw_state_event_and_intent.sql
@@ -0,0 +1,46 @@
+-- 2026-10-25 T05：状态事件事实（同事务落库）+ 待推进意图（办理事务内持久化）
+-- 注：event_seq 为尽力单调（REQUIRES_NEW 推进拓扑下极端并发可能同值），非唯一键；严格全序待专用发号器
+-- ddl-auto=update 会自动建表；本脚本为生产备案
+CREATE TABLE IF NOT EXISTS `flw_state_event` (
+ `id` BIGINT NOT NULL AUTO_INCREMENT,
+ `event_id` VARCHAR(32) NOT NULL COMMENT '稳定事件身份（全订阅方/重试复用）',
+ `sch_id` BIGINT NOT NULL,
+ `instance_id` BIGINT NOT NULL,
+ `apply_round` INT NULL COMMENT '发布时冻结的申报轮次',
+ `event_seq` INT NOT NULL COMMENT '实例内单调序号',
+ `event_type` VARCHAR(32) NOT NULL,
+ `task_id` BIGINT NULL,
+ `operator_id` INT NULL,
+ `payload_json` LONGTEXT NOT NULL COMMENT '发生时载荷快照',
+ `dispatched` INT NOT NULL DEFAULT 0 COMMENT '0=待分发（崩溃窗口恢复扫描）；1=已分发',
+ `create_by` VARCHAR(64) NULL, `create_time` DATETIME(6) NULL,
+ `update_by` VARCHAR(64) NULL, `update_time` DATETIME(6) NULL,
+ PRIMARY KEY (`id`),
+ UNIQUE KEY `uk_flw_state_event_id` (`event_id`),
+ KEY `idx_flw_state_event_instance` (`instance_id`),
+ KEY `idx_flw_state_event_dispatch` (`dispatched`, `create_time`),
+ KEY `idx_flw_state_event_seq` (`instance_id`, `event_seq`)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '流程状态事件事实（T05 同事务 outbox）';
+
+CREATE TABLE IF NOT EXISTS `flw_advance_intent` (
+ `id` BIGINT NOT NULL AUTO_INCREMENT,
+ `instance_id` BIGINT NOT NULL,
+ `node_id` VARCHAR(64) NOT NULL,
+ `edge_name` VARCHAR(128) NULL,
+ `assignee_id` INT NULL,
+ `assignee_name` VARCHAR(64) NULL,
+ `status` VARCHAR(16) NOT NULL DEFAULT 'PENDING' COMMENT 'PENDING/DONE/EXHAUSTED',
+ `attempts` INT NOT NULL DEFAULT 0,
+ `next_retry_at` DATETIME(6) NULL,
+ `last_error` VARCHAR(255) NULL,
+ `create_by` VARCHAR(64) NULL, `create_time` DATETIME(6) NULL,
+ `update_by` VARCHAR(64) NULL, `update_time` DATETIME(6) NULL,
+ PRIMARY KEY (`id`),
+ KEY `idx_flw_advance_intent_due` (`status`, `next_retry_at`),
+ KEY `idx_flw_advance_intent_instance` (`instance_id`)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '待推进意图（T05 办理事务内持久化+事务外 worker）';
+
+-- T05 修正（2026-10-25 FlowEngineIT 会签并发实证）：REPEATABLE READ 快照读 max+1 会撞 uk，
+-- 事件序号改为实例行上计数器（行锁内 +1）
+ALTER TABLE `flw_instance`
+ ADD COLUMN `event_seq_counter` INT NULL COMMENT '事件事实 eventSeq 发号器（T05 行锁内 +1）' AFTER `apply_payload_hash`;
diff --git a/src/main/resources/sql/20261025_create_flw_usage_grant.sql b/src/main/resources/sql/20261025_create_flw_usage_grant.sql
new file mode 100644
index 0000000..498928b
--- /dev/null
+++ b/src/main/resources/sql/20261025_create_flw_usage_grant.sql
@@ -0,0 +1,21 @@
+-- 2026-10-25 T01：应用使用授权（学校×流程线×稳定应用主体）
+-- ddl-auto=update 会自动建表；本脚本为生产备案（生产建议停自动 DDL 后手工执行）
+-- 撤权语义：enabled=0 只拦新发起；已受理命令回执恢复与在途实例不回读本表。
+CREATE TABLE IF NOT EXISTS `flw_usage_grant` (
+ `id` BIGINT NOT NULL AUTO_INCREMENT,
+ `sch_id` BIGINT NOT NULL COMMENT '租户键',
+ `flow_guid` VARCHAR(64) NOT NULL COMMENT '流程线稳定身份（跨版本不变）',
+ `app_id` INT NOT NULL COMMENT '稳定应用主体主键（UserBase application_info.id）',
+ `app_key_snapshot` VARCHAR(64) NULL COMMENT '授权时 appKey 快照（审计回溯；判权不读）',
+ `app_name_snapshot` VARCHAR(128) NULL COMMENT '授权时应用名快照',
+ `enabled` INT NOT NULL DEFAULT 1 COMMENT '1=许可生效；0=撤销（只拦新发起）',
+ `remark` VARCHAR(255) NULL COMMENT '备注（人工审计线索）',
+ `create_by` VARCHAR(64) NULL,
+ `create_time` DATETIME(6) NULL,
+ `update_by` VARCHAR(64) NULL,
+ `update_time` DATETIME(6) NULL,
+ PRIMARY KEY (`id`),
+ UNIQUE KEY `uk_flw_usage_grant` (`sch_id`, `flow_guid`, `app_id`),
+ KEY `idx_flw_usage_grant_sch_flow` (`sch_id`, `flow_guid`),
+ KEY `idx_flw_usage_grant_app` (`app_id`)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COMMENT = '应用使用授权（T01 三权分立：使用许可≠定义管理权≠flw_app 白名单）';
diff --git a/src/main/resources/sql/20261025_drop_event_seq_uk.sql b/src/main/resources/sql/20261025_drop_event_seq_uk.sql
new file mode 100644
index 0000000..ecb3094
--- /dev/null
+++ b/src/main/resources/sql/20261025_drop_event_seq_uk.sql
@@ -0,0 +1,3 @@
+-- 已在开发库按旧形态建过表的场合执行一次；新库直接用主脚本（无 uk）
+ALTER TABLE `flw_state_event` DROP INDEX `uk_flw_state_event_seq`;
+ALTER TABLE `flw_state_event` ADD INDEX `idx_flw_state_event_seq` (`instance_id`, `event_seq`);
diff --git a/src/main/resources/sql/20261025_fix_flw_callback_log_uk.sql b/src/main/resources/sql/20261025_fix_flw_callback_log_uk.sql
new file mode 100644
index 0000000..896e962
--- /dev/null
+++ b/src/main/resources/sql/20261025_fix_flw_callback_log_uk.sql
@@ -0,0 +1,12 @@
+-- 2026-10-25 R2（Codex 终审 D04）：flw_callback_log 投递幂等键从 event_id 单列改为 (event_id, reg_id) 复合。
+--
+-- 背景：T05 起投递行 eventId 复用事实行稳定身份——同一事件对全部匹配订阅方各建一行（每 reg 一行），
+-- 旧的单列 uk_flw_log_event(event_id) 会误拒第二订阅方的合法投递行（第二行插入即撞唯一键）；
+-- 同时并发"exists→insert"竞态不是幂等证明，改由复合 uk 兜底（DuplicateKeyException=另一路径已建行，
+-- 调用方按幂等成功处理）。
+--
+-- 执行说明：仅在已按旧形态建过 uk 的库执行一次；新库由 ddl-auto=update / 建表脚本直接生成复合键。
+-- 本脚本不具幂等性（DROP INDEX 重复执行报 1091）——按 Codex D15 口径纳入发布前置检查清单，
+-- 先 SHOW INDEX FROM flw_callback RESULTS 确认现存索引名再执行对应分支。
+ALTER TABLE `flw_callback_log` DROP INDEX `uk_flw_log_event`;
+ALTER TABLE `flw_callback_log` ADD UNIQUE KEY `uk_flw_log_event_reg` (`event_id`, `reg_id`);
diff --git a/src/main/resources/sql/20261026_d09_activation_intent_draft.sql b/src/main/resources/sql/20261026_d09_activation_intent_draft.sql
new file mode 100644
index 0000000..ab0e7e3
--- /dev/null
+++ b/src/main/resources/sql/20261026_d09_activation_intent_draft.sql
@@ -0,0 +1,102 @@
+-- D09 DRAFT ONLY. Never run this file against production as part of application startup.
+-- Quiesce handling, transfer, return, restart and advance workers before an audited legacy backfill.
+-- Apply additive columns first, then deploy ALL D09 writers together; mixed old/new writers are unsafe.
+-- The root task is an identity, not a completion-order comparison. Never backfill MAX(task_id).
+ALTER TABLE flw_advance_intent
+ ADD COLUMN activation_task_id BIGINT NULL,
+ ADD COLUMN activation_task_ids LONGTEXT NULL,
+ ADD COLUMN handled_task_ids LONGTEXT NULL,
+ ADD COLUMN trigger_task_id BIGINT NULL,
+ ADD COLUMN activation_def_id BIGINT NULL,
+ ADD COLUMN activation_def_version INT NULL,
+ ADD COLUMN activation_apply_round INT NULL,
+ ADD COLUMN revision BIGINT NOT NULL DEFAULT 0,
+ ADD UNIQUE KEY uk_flw_advance_activation (activation_task_id);
+
+-- Inventory is a rollout gate, not an automatic guess of the historical cohort/last handler:
+-- SELECT instance_id,node_id,id,status FROM flw_advance_intent WHERE activation_task_id IS NULL AND status IN ('PENDING','EXHAUSTED');
+-- NULL work without a registered successor is held EXHAUSTED, never executed or silently marked DONE.
+-- For a still-active legacy node, an operator supplies the EXACT audited current task cohort.
+-- If pending tasks remain, p_trigger must be NULL: their future real handling re-arms the new head.
+-- If all tasks are already handled, p_trigger requires independent evidence of the LAST handler;
+-- equal handle_time/ID order is NOT evidence. Ambiguous history stays held for an explicit audited resolution.
+-- p_audit_ref identifies that evidence. A successor is inserted BEFORE NULL work is retired, atomically.
+-- Test harness extracts the procedure below as ONE JDBC statement; mysql clients need DELIMITER $$ ... $$.
+DELIMITER $$
+-- D09_BACKFILL_BEGIN
+CREATE PROCEDURE d09_backfill_activation(IN p_instance BIGINT, IN p_node VARCHAR(64), IN p_tasks JSON,
+ IN p_trigger BIGINT, IN p_audit_ref VARCHAR(128))
+BEGIN
+ DECLARE v_root BIGINT;
+ DECLARE v_def BIGINT;
+ DECLARE v_version INT;
+ DECLARE v_round INT;
+ DECLARE v_status INT;
+ DECLARE v_nodes TEXT;
+ DECLARE v_pending INT;
+ DECLARE v_count INT;
+ DECLARE v_head BIGINT;
+ DECLARE v_members LONGTEXT;
+ DECLARE v_handled JSON;
+ DECLARE v_edge VARCHAR(128);
+ DECLARE v_user INT;
+ DECLARE v_name VARCHAR(64);
+ DECLARE EXIT HANDLER FOR SQLEXCEPTION BEGIN ROLLBACK; RESIGNAL; END;
+ IF p_audit_ref IS NULL OR LENGTH(TRIM(p_audit_ref))=0 OR p_tasks IS NULL
+ OR JSON_TYPE(p_tasks)<>'ARRAY' OR JSON_LENGTH(p_tasks)=0 THEN
+ SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='D09 audited cohort input is required';
+ END IF;
+ IF EXISTS (SELECT 1 FROM JSON_TABLE(p_tasks,'$[*]' COLUMNS(ord FOR ORDINALITY,task_id BIGINT PATH '$')) j
+ WHERE JSON_TYPE(JSON_EXTRACT(p_tasks,CONCAT('$[',j.ord-1,']')))<>'INTEGER' OR j.task_id<=0) THEN
+ SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='D09 task identities must be positive integers';
+ END IF;
+ START TRANSACTION;
+ SELECT def_id,def_version,apply_round,status,current_nodes INTO v_def,v_version,v_round,v_status,v_nodes
+ FROM flw_instance WHERE id=p_instance FOR UPDATE;
+ IF v_status IS NULL OR v_status<>10 OR FIND_IN_SET(p_node,COALESCE(v_nodes,''))=0 THEN
+ SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='D09 legacy node is not currently active';
+ END IF;
+ IF EXISTS (SELECT 1 FROM flw_advance_intent WHERE instance_id=p_instance AND node_id=p_node AND activation_task_id IS NOT NULL) THEN
+ SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='D09 registered successor exists; do not overwrite it';
+ END IF;
+ SELECT COUNT(DISTINCT t.id),MIN(t.id) INTO v_count,v_root
+ FROM flw_task t JOIN JSON_TABLE(p_tasks,'$[*]' COLUMNS(task_id BIGINT PATH '$')) j ON j.task_id=t.id
+ WHERE t.instance_id=p_instance AND t.node_id=p_node AND t.status IN (0,1,3,5);
+ IF v_count<>JSON_LENGTH(p_tasks) THEN
+ SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='D09 cohort has duplicates, foreign or invalid tasks';
+ END IF;
+ SET v_members=CONCAT(',',REPLACE(REPLACE(REPLACE(CAST(p_tasks AS CHAR),'[',''),']',''),' ',''),',');
+ IF EXISTS (SELECT 1 FROM flw_task WHERE instance_id=p_instance AND node_id=p_node AND status=0
+ AND LOCATE(CONCAT(',',id,','),v_members)=0) THEN
+ SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='D09 cohort omits current pending tasks';
+ END IF;
+ SELECT COUNT(*) INTO v_pending FROM flw_task WHERE instance_id=p_instance AND node_id=p_node AND status=0;
+ IF (v_pending=0 AND p_trigger IS NULL) OR (v_pending>0 AND p_trigger IS NOT NULL) THEN
+ SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='D09 pending cohort waits; completed cohort needs proven last handler';
+ END IF;
+ IF p_trigger IS NOT NULL THEN
+ IF LOCATE(CONCAT(',',p_trigger,','),v_members)=0
+ OR NOT EXISTS (SELECT 1 FROM flw_task WHERE id=p_trigger AND status=1) THEN
+ SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='D09 last handler is not an approved cohort member';
+ END IF;
+ SELECT edge_name,assignee_id,assignee_name INTO v_edge,v_user,v_name FROM flw_task WHERE id=p_trigger;
+ END IF;
+ SELECT JSON_ARRAYAGG(id) INTO v_handled FROM flw_task
+ WHERE instance_id=p_instance AND node_id=p_node AND status<>0 AND LOCATE(CONCAT(',',id,','),v_members)>0;
+ INSERT INTO flw_advance_intent(instance_id,node_id,activation_task_id,activation_task_ids,handled_task_ids,
+ trigger_task_id,activation_def_id,activation_def_version,activation_apply_round,revision,
+ edge_name,assignee_id,assignee_name,status,attempts,next_retry_at,last_error,create_time,update_time,create_by)
+ VALUES(p_instance,p_node,v_root,v_members,
+ IF(v_handled IS NULL,NULL,CONCAT(',',REPLACE(REPLACE(REPLACE(CAST(v_handled AS CHAR),'[',''),']',''),' ',''),',')),
+ p_trigger,v_def,v_version,v_round,0,v_edge,v_user,v_name,IF(p_trigger IS NULL,'DONE','PENDING'),0,NOW(),
+ LEFT(CONCAT('D09_AUDITED_BACKFILL: ',p_audit_ref),255),NOW(),NOW(),LEFT(p_audit_ref,64));
+ SET v_head=LAST_INSERT_ID();
+ UPDATE flw_advance_intent SET status='DONE',revision=revision+1,update_time=NOW(),
+ last_error=LEFT(CONCAT('D09_HANDOFF: successor=',v_head,' audit=',p_audit_ref),255)
+ WHERE instance_id=p_instance AND node_id=p_node AND activation_task_id IS NULL AND status IN ('PENDING','EXHAUSTED');
+ COMMIT;
+END
+-- D09_BACKFILL_END
+$$
+DELIMITER ;
+-- No CALL is executed by this draft. Audit the cohort before an explicitly approved maintenance invocation.
diff --git a/src/main/resources/sql/20261026_formal_commands_draft.sql b/src/main/resources/sql/20261026_formal_commands_draft.sql
new file mode 100644
index 0000000..b8276cb
--- /dev/null
+++ b/src/main/resources/sql/20261026_formal_commands_draft.sql
@@ -0,0 +1,45 @@
+-- REVIEW DRAFT. No production execution is authorized.
+-- Stop ALL legacy writers and take a verified backup before the transactional model cutover.
+-- MySQL 5.6: DDL auto-commits. Apply in a maintenance window, then validate indexes before enabling.
+ALTER TABLE flw_instance ADD COLUMN source_principal_id varchar(36) CHARACTER SET ascii COLLATE ascii_bin NULL,
+ ADD COLUMN legacy_slot int NULL DEFAULT 1;
+-- Keep every legacy row in slot 1. Do NOT infer its source UUID or fabricate command history.
+UPDATE flw_instance SET legacy_slot=1 WHERE source_principal_id IS NULL;
+ALTER TABLE flw_instance DROP INDEX uk_flw_instance_biz,
+ ADD UNIQUE KEY uk_flw_instance_legacy(sch_id,biz_type,biz_id,legacy_slot),
+ ADD UNIQUE KEY uk_flw_instance_round(sch_id,source_principal_id,biz_type,biz_id,apply_round);
+ALTER TABLE flw_usage_grant ADD COLUMN source_principal_id varchar(36) CHARACTER SET ascii COLLATE ascii_bin NULL;
+ALTER TABLE flw_callback_reg ADD COLUMN source_principal_id varchar(36) CHARACTER SET ascii COLLATE ascii_bin NULL;
+-- UUID grants require explicit audited re-grant; subscriptions require authenticated re-registration.
+CREATE TABLE flw_command_source (
+ id varchar(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL PRIMARY KEY, app_id int NOT NULL
+) ENGINE=InnoDB;
+CREATE TABLE flw_biz_coordinate (
+ id bigint NOT NULL AUTO_INCREMENT PRIMARY KEY, sch_id bigint NOT NULL,
+ source_principal_id varchar(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+ biz_type varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+ biz_id varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+ last_round int NOT NULL DEFAULT 0, last_instance_id bigint NULL, active_instance_id bigint NULL,
+create_by varchar(255) NULL, create_time datetime NULL, update_by varchar(255) NULL, update_time datetime NULL,
+ UNIQUE KEY uk_flw_coord(sch_id,source_principal_id,biz_type,biz_id)
+) ENGINE=InnoDB;
+CREATE TABLE flw_apply_command (
+ id bigint NOT NULL AUTO_INCREMENT PRIMARY KEY, sch_id bigint NOT NULL,
+ source_principal_id varchar(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+ request_id varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+ canonical_hash varchar(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
+ canonical_version int NOT NULL,
+ biz_type varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+ biz_id varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL,
+ flow_guid varchar(32) NOT NULL, state varchar(16) NOT NULL, instance_id bigint NULL,
+ apply_round int NULL, def_id bigint NULL, def_version int NULL, reject_code varchar(64) NULL, reject_detail varchar(500) NULL,
+create_by varchar(255) NULL, create_time datetime NULL, update_by varchar(255) NULL, update_time datetime NULL,
+ UNIQUE KEY uk_flw_command_request(sch_id,source_principal_id,request_id),
+ KEY idx_flw_command_instance(instance_id)
+) ENGINE=InnoDB;
+-- New formal comparisons require exact string identity. Review collation/index byte limits first.
+-- On pre-existing case-insensitive columns, use the following explicit conversion (not an implicit code assumption):
+ALTER TABLE flw_instance MODIFY biz_type varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NULL,
+ MODIFY biz_id varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NULL;
+-- Do not enable formal-command.enabled until legacy coordinate migration policy is applied.
+-- A clean/new coordinate is supported now; an overlapping legacy coordinate returns LEGACY_COORDINATE_NOT_MIGRATED.
diff --git a/src/test/java/com/yunhai/flowcenter/callback/CallbackConcurrentPushIT.java b/src/test/java/com/yunhai/flowcenter/callback/CallbackConcurrentPushIT.java
new file mode 100644
index 0000000..ffa3e1d
--- /dev/null
+++ b/src/test/java/com/yunhai/flowcenter/callback/CallbackConcurrentPushIT.java
@@ -0,0 +1,265 @@
+package com.yunhai.flowcenter.callback;
+
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpServer;
+import com.yunhai.flowcenter.entity.FlwCallbackLog;
+import com.yunhai.flowcenter.entity.FlwCallbackReg;
+import com.yunhai.flowcenter.notify.UserMsgClient;
+import com.yunhai.flowcenter.repository.FlwCallbackLogRepository;
+import com.yunhai.flowcenter.repository.FlwCallbackRegRepository;
+import com.yunhai.flowcenter.service.FlowCallbackAdminService;
+import com.yunhai.platform.apistd.BizException;
+import org.junit.jupiter.api.*;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import javax.sql.DataSource;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.sql.Connection;
+import java.time.LocalDateTime;
+import java.util.*;
+import java.util.concurrent.*;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.mock;
+
+/** 两个独立本地集合、独立数据库会话，共用真 MySQL 8 和受屏障控制的真 HTTP 接收端。 */
+@SpringBootTest(webEnvironment=SpringBootTest.WebEnvironment.RANDOM_PORT)
+@ActiveProfiles("test")
+class CallbackConcurrentPushIT {
+ @Autowired FlwCallbackLogRepository logs;
+ @Autowired FlwCallbackRegRepository regs;
+ @Autowired CallbackLogStore store;
+ @Autowired DataSource dataSource;
+ @Autowired JdbcTemplate jdbc;
+ // 仅关闭与本类无关的扫描；竞争由测试屏障精确触发，不让调度器成为第三个执行者。
+ @MockBean CallbackDispatcher dispatcher;
+
+ HttpServer server;
+ ExecutorService serverThreads;
+ ExecutorService workers;
+ final List logIds=new ArrayList<>(), regIds=new ArrayList<>();
+ final AtomicReference receiver=new AtomicReference<>();
+ final AtomicInteger hits=new AtomicInteger(), active=new AtomicInteger(), maxActive=new AtomicInteger();
+ final List eventIds=new CopyOnWriteArrayList<>(), bodies=new CopyOnWriteArrayList<>();
+ CountingMessages messages;
+ CallbackProperties properties;
+
+ interface Receiver { int respond(int sequence) throws Exception; }
+
+ @BeforeEach void setup() throws Exception {
+ assertEquals(13429,jdbc.queryForObject("SELECT @@port",Integer.class));
+ assertTrue(jdbc.queryForObject("SELECT @@version",String.class).startsWith("8."));
+ assertEquals("c:/users/chenx/.zcode/tmp/fl-d09-zcode-mysql8/",
+ jdbc.queryForObject("SELECT @@datadir",String.class).replace('\\','/').toLowerCase());
+ assertEquals("fl_d09_20261026",jdbc.queryForObject("SELECT DATABASE()",String.class));
+ messages=new CountingMessages();properties=new CallbackProperties();properties.setAlertUserIds("999");
+ workers=Executors.newFixedThreadPool(4);serverThreads=Executors.newCachedThreadPool();
+ server=HttpServer.create(new InetSocketAddress("127.0.0.1",0),0);server.setExecutor(serverThreads);
+ receiver.set(n -> 200);
+ server.createContext("/callback",this::receive);server.start();
+ }
+
+ @AfterEach void cleanup() throws Exception {
+ if (workers!=null) {workers.shutdownNow();assertTrue(workers.awaitTermination(12,TimeUnit.SECONDS));}
+ if (server!=null) server.stop(0);
+ if (serverThreads!=null) serverThreads.shutdownNow();
+ for (Long id:logIds) logs.deleteById(id);
+ for (Long id:regIds) regs.deleteById(id);
+ }
+
+ void receive(HttpExchange exchange) {
+ int now=active.incrementAndGet();maxActive.accumulateAndGet(now,Math::max);
+ try {
+ int sequence=hits.incrementAndGet();
+ eventIds.add(exchange.getRequestHeaders().getFirst("X-Flw-EventId"));
+ bodies.add(new String(org.springframework.util.StreamUtils.copyToByteArray(exchange.getRequestBody()),StandardCharsets.UTF_8));
+ int status=receiver.get().respond(sequence);
+ byte[] body="{\"ok\":true}".getBytes(StandardCharsets.UTF_8);
+ exchange.sendResponseHeaders(status,body.length);exchange.getResponseBody().write(body);
+ } catch (Exception failure) {
+ throw new IllegalStateException(failure);
+ } finally {active.decrementAndGet();exchange.close();}
+ }
+
+ CallbackPushService executor(CallbackLogStore claimStore) {
+ return new CallbackPushService(logs,regs,properties,claimStore,messages,mock(ObjectProvider.class));
+ }
+
+ FlwCallbackLog row(String eventId) {
+ FlwCallbackReg reg=new FlwCallbackReg();reg.setSchId(1L);reg.setFlowGuid(UUID.randomUUID().toString().replace("-",""));
+ reg.setAppKey("100018");reg.setStatus(0);reg.setSecret("p22-secret");
+ reg.setCallbackUrl("http://127.0.0.1:"+server.getAddress().getPort()+"/callback");reg=regs.saveAndFlush(reg);regIds.add(reg.getId());
+ FlwCallbackLog row=new FlwCallbackLog();row.setSchId(1L);row.setRegId(reg.getId());row.setEventId(eventId);
+ row.setEvent("flow.submitted");row.setInstanceId(0L);row.setBizType("p22");row.setBizId(eventId);
+ row.setPayloadJson("{\"eventId\":\""+eventId+"\",\"event\":\"flow.submitted\"}");
+ row.setNextRetryTime(LocalDateTime.now());row=logs.saveAndFlush(row);logIds.add(row.getId());return row;
+ }
+ FlwCallbackLog row() {return row(UUID.randomUUID().toString().replace("-",""));}
+ FlwCallbackLog current(Long id) {return logs.findById(id).orElseThrow(AssertionError::new);}
+ void gate(CountDownLatch latch) throws InterruptedException {assertTrue(latch.await(8,TimeUnit.SECONDS),"barrier timed out");}
+
+ /** 每一轮真正同时争抢；胜者 HTTP 阻塞到落败执行者已返回，排除“恰巧串行”的假证明。 */
+ void contest(FlwCallbackLog row, int result) throws Exception {
+ CallbackPushService a=executor(store),b=executor(store);
+ assertNotSame(ReflectionTestUtils.getField(a,"IN_FLIGHT"),ReflectionTestUtils.getField(b,"IN_FLIGHT"));
+ CountDownLatch entered=new CountDownLatch(1),release=new CountDownLatch(1),returned=new CountDownLatch(1);
+ receiver.set(n -> {entered.countDown();gate(release);return result;});
+ CyclicBarrier start=new CyclicBarrier(2);
+ Future x=workers.submit(()->{start.await(5,TimeUnit.SECONDS);try {a.pushAsync(row.getId());} finally {returned.countDown();}return null;});
+ Future y=workers.submit(()->{start.await(5,TimeUnit.SECONDS);try {b.pushAsync(row.getId());} finally {returned.countDown();}return null;});
+ try {
+ gate(entered);gate(returned);
+ assertEquals(1,active.get());assertTrue(a.inFlight(row.getId()) ^ b.inFlight(row.getId()));
+ assertEquals(0,jdbc.queryForObject("SELECT count(*) FROM information_schema.innodb_trx WHERE trx_mysql_thread_id="
+ + "IS_USED_LOCK(SHA2(CONCAT(LOWER(DATABASE()), ':flw_callback:', ?, ':', ?),256))",Integer.class,row.getEventId(),row.getRegId()),
+ "HTTP 期间不得持有数据库事务");
+ } finally {release.countDown();}
+ x.get(12,TimeUnit.SECONDS);y.get(12,TimeUnit.SECONDS);
+ }
+
+ @Test void independentExecutorsHaveExactlyOneEffectiveDispatcher() throws Exception {
+ FlwCallbackLog row=row();contest(row,200);
+ assertEquals(1,hits.get());assertEquals(1,maxActive.get());assertEquals(1,current(row.getId()).getStatus());
+ assertEquals(0,current(row.getId()).getRetryCount());
+ executor(store).pushAsync(row.getId());assertEquals(1,hits.get(),"重复认领成功行不应再发 HTTP");
+ assertThat(eventIds).containsExactly(row.getEventId());assertThat(bodies).containsExactly(row.getPayloadJson());
+ }
+
+ @Test void competingFailuresIncrementOncePerValidAttemptAndAlertOnlyOnCommittedThreshold() throws Exception {
+ FlwCallbackLog row=row();
+ List backoff=properties.getRetryBackoffMinutes();
+ for (int attempt=1;attempt<=7;attempt++) {
+ LocalDateTime before=LocalDateTime.now();contest(row,503);
+ FlwCallbackLog saved=current(row.getId());long minutes=attempt<=backoff.size()?backoff.get(attempt-1):60;
+ assertEquals(attempt,saved.getRetryCount());assertEquals(attempt,hits.get());assertEquals(0,saved.getStatus());
+ assertNotNull(saved.getLastError());assertThat(saved.getNextRetryTime())
+ .isAfterOrEqualTo(before.plusMinutes(minutes)).isBeforeOrEqualTo(LocalDateTime.now().plusMinutes(minutes));
+ assertEquals(attempt>=6?1:0,messages.hung.get());
+ }
+ assertEquals(1,maxActive.get());assertThat(eventIds).allMatch(row.getEventId()::equals);
+ }
+
+ void awaitExpired(FlwCallbackLog row) throws Exception {
+ // 直接等待数据库释放旧会话锁，不用 sleep，也不触碰旧连接以免续租。
+ try (Connection connection=dataSource.getConnection();java.sql.PreparedStatement acquire=connection.prepareStatement(
+ "SELECT GET_LOCK(SHA2(CONCAT(LOWER(DATABASE()), ':flw_callback:', ?, ':', ?),256),6)")) {
+ acquire.setString(1,row.getEventId());acquire.setLong(2,row.getRegId());
+ try(java.sql.ResultSet rs=acquire.executeQuery()){rs.next();assertEquals(1,rs.getInt(1),"expired owner must release its claim");}
+ try(java.sql.PreparedStatement release=connection.prepareStatement(
+ "SELECT RELEASE_LOCK(SHA2(CONCAT(LOWER(DATABASE()), ':flw_callback:', ?, ':', ?),256))")) {
+ release.setString(1,row.getEventId());release.setLong(2,row.getRegId());release.execute();
+ }
+ }
+ }
+
+ @ParameterizedTest @CsvSource({"503,200,true", "200,503,false", "503,502,false"})
+ void lateOldResultCannotOverwriteNewSuccessOrNewFailure(int oldStatus, int newStatus, boolean sameExecutor) throws Exception {
+ FlwCallbackLog row=row();CallbackPushService old=executor(new CallbackLogStore(logs,dataSource,1));
+ CountDownLatch entered=new CountDownLatch(1),releaseOld=new CountDownLatch(1);
+ receiver.set(n -> {if(n==1){entered.countDown();gate(releaseOld);return oldStatus;}return newStatus;});
+ Future first=workers.submit(()->old.pushAsync(row.getId()));
+ try {
+ gate(entered);awaitExpired(row);
+ // 同一服务实例也须能在本地旧线程未退出时恢复；另一路验证独立执行者。
+ (sameExecutor ? old : executor(store)).pushAsync(row.getId());
+ FlwCallbackLog newer=current(row.getId());
+ assertEquals(newStatus==200?1:0,newer.getStatus());assertEquals(newStatus==200?0:1,newer.getRetryCount());
+ releaseOld.countDown();first.get(12,TimeUnit.SECONDS);
+ FlwCallbackLog after=current(row.getId());
+ assertEquals(newer.getStatus(),after.getStatus());assertEquals(newer.getRetryCount(),after.getRetryCount());
+ assertEquals(newer.getLastError(),after.getLastError());assertEquals(newer.getNextRetryTime(),after.getNextRetryTime());
+ assertEquals(newer.getLastHttpStatus(),after.getLastHttpStatus());assertEquals(newer.getPushTime(),after.getPushTime());
+ assertEquals(newer.getUpdateTime(),after.getUpdateTime());assertEquals(2,hits.get());
+ assertThat(eventIds).containsExactly(row.getEventId(),row.getEventId());
+ } finally {releaseOld.countDown();}
+ }
+
+ @Test void abandonedAndAbortedClaimBothRecoverWithoutARecordMigration() throws Exception {
+ for (boolean abort:Arrays.asList(false,true)) {
+ FlwCallbackLog row=row();
+ try (CallbackLogStore.Claim orphan=new CallbackLogStore(logs,dataSource,1).tryClaim(row.getId())) {
+ assertNotNull(orphan);assertTrue(orphan.active());
+ assertNull(store.tryClaim(row.getId()));
+ if(abort)((Connection)ReflectionTestUtils.getField(orphan,"connection")).abort(Runnable::run);
+ awaitExpired(row);executor(store).pushAsync(row.getId());
+ assertEquals(1,current(row.getId()).getStatus());assertFalse(orphan.failure("late failure",null,1));
+ assertFalse(orphan.success(200));assertEquals(0,current(row.getId()).getRetryCount());
+ }
+ }
+ assertEquals(2,hits.get());
+ }
+
+ @Test void aClaimCanSettleOnlyOnceAndReleasedSessionRestoresItsTimeout() throws Exception {
+ FlwCallbackLog row=row();
+ try (CallbackLogStore.Claim claim=store.tryClaim(row.getId())) {
+ assertNotNull(claim);assertTrue(((Connection)ReflectionTestUtils.getField(claim,"connection")).getAutoCommit());
+ assertTrue(claim.failure("first", "503",1));assertFalse(claim.failure("duplicate",null,5));assertFalse(claim.success(200));
+ }
+ assertEquals(1,current(row.getId()).getRetryCount());assertEquals("first",current(row.getId()).getLastError());
+ try (Connection connection=dataSource.getConnection();java.sql.Statement st=connection.createStatement();
+ java.sql.ResultSet rs=st.executeQuery("SELECT @@session.wait_timeout")) {
+ rs.next();assertEquals(jdbc.queryForObject("SELECT @@global.wait_timeout",Long.class),Long.valueOf(rs.getLong(1)));
+ }
+ }
+
+ @Test void differentSubscriptionsShareEventIdentityButHaveIndependentDispatchRights() throws Exception {
+ FlwCallbackLog a=row(),b=row(a.getEventId());
+ CountDownLatch entered=new CountDownLatch(2),release=new CountDownLatch(1);
+ receiver.set(n -> {entered.countDown();gate(release);return 200;});
+ Future first=workers.submit(()->executor(store).pushAsync(a.getId()));
+ Future second=workers.submit(()->executor(store).pushAsync(b.getId()));
+ try {gate(entered);assertEquals(2,active.get());}finally {release.countDown();}
+ first.get(12,TimeUnit.SECONDS);second.get(12,TimeUnit.SECONDS);
+ assertEquals(1,current(a.getId()).getStatus());assertEquals(1,current(b.getId()).getStatus());
+ assertThat(eventIds).containsExactlyInAnyOrder(a.getEventId(),a.getEventId());
+ FlwCallbackLog duplicate=new FlwCallbackLog();org.springframework.beans.BeanUtils.copyProperties(a,duplicate,"id");
+ assertThrows(org.springframework.dao.DataIntegrityViolationException.class,()->logs.saveAndFlush(duplicate));
+ }
+
+ @Test void manualActionsCannotResetOrOverwriteAnActiveOrSuccessfulAttempt() throws Exception {
+ FlwCallbackLog row=row();CallbackPushService worker=executor(store);
+ FlowCallbackAdminService admin=new FlowCallbackAdminService(regs,logs,worker,properties,store);
+ CountDownLatch entered=new CountDownLatch(1),release=new CountDownLatch(1);
+ receiver.set(n -> {entered.countDown();gate(release);return 200;});
+ Future sending=workers.submit(()->worker.pushAsync(row.getId()));
+ try {
+ gate(entered);
+ assertThrows(BizException.class,()->admin.rePush(1L,Collections.singletonList(row.getId())));
+ assertThrows(BizException.class,()->admin.markDead(1L,row.getId()));
+ assertEquals(0,current(row.getId()).getRetryCount());
+ } finally {release.countDown();}
+ sending.get(12,TimeUnit.SECONDS);assertEquals(1,current(row.getId()).getStatus());
+ assertThrows(BizException.class,()->worker.markDead(row,"stale admin snapshot"));
+ admin.rePush(1L,Collections.singletonList(row.getId()));assertEquals(1,hits.get());
+ }
+
+ @Test void batchManualReplayCommitsBeforeHttpAndKeepsSuccessfulRowsUntouched() {
+ FlwCallbackLog a=row(),b=row();CallbackPushService worker=executor(store);
+ worker.markDead(a,"manual");worker.pushAsync(b.getId());
+ FlowCallbackAdminService admin=new FlowCallbackAdminService(regs,logs,worker,properties,store);
+ receiver.set(n -> {assertEquals(0,current(a.getId()).getStatus());assertEquals(0,current(a.getId()).getRetryCount());return 200;});
+ admin.rePush(1L,Arrays.asList(a.getId(),b.getId()));
+ assertEquals(2,hits.get());assertEquals(1,current(a.getId()).getStatus());assertEquals(1,current(b.getId()).getStatus());
+ }
+
+ static class CountingMessages extends UserMsgClient {
+ final AtomicInteger hung=new AtomicInteger();
+ CountingMessages(){super(null,null,false,"");}
+ @Override public void sendUserMsg(Integer sch,List users,Integer type,String bizType,String bizId,
+ String title,String content,String path,String app,String number,Integer expiry) {
+ if(number!=null&&number.startsWith("hang:"))hung.incrementAndGet();
+ }
+ }
+}
diff --git a/src/test/java/com/yunhai/flowcenter/callback/CallbackDispatchIT.java b/src/test/java/com/yunhai/flowcenter/callback/CallbackDispatchIT.java
index 5728e74..d29c65b 100644
--- a/src/test/java/com/yunhai/flowcenter/callback/CallbackDispatchIT.java
+++ b/src/test/java/com/yunhai/flowcenter/callback/CallbackDispatchIT.java
@@ -171,9 +171,10 @@ class CallbackDispatchIT extends FlowTestSupport {
+ "\"submitterId\":201,\"submitterName\":\"张三\"}";
org.springframework.http.ResponseEntity applyResp =
client.post("/oapi/flow/apply?schId=1", body, JsonNode.class);
- // 3. 轮询 stub：submitted + task.created 两事件都到齐（探活 ping 不计）
+ // 3. 轮询 stub：submitted + task.created 两事件都到齐（探活 ping 不计；异步首推
+ // 可能被启动扫描的遗留行恢复推送短暂占池，等待上限放宽——P1-1）
waitUntil(() -> received.stream().anyMatch(r -> r.body.contains("flow.submitted"))
- && received.stream().anyMatch(r -> r.body.contains("flow.task.created")), 10_000);
+ && received.stream().anyMatch(r -> r.body.contains("flow.task.created")), 60_000);
boolean hasSubmitted = false;
boolean hasTaskCreated = false;
for (Received r : received) {
@@ -221,10 +222,13 @@ class CallbackDispatchIT extends FlowTestSupport {
.filter(r -> r.body != null && r.body.contains("\"ping\"")).findFirst().orElse(null);
assertNotNull(ping, "注册探活应命中 stub");
assertAppSignature("/callback/flow", ping);
- // 4. 日志表成功态（异步推送落定，轮询等待）
- assertTrue(logRepository.findAll().size() >= 2);
+ // 4. 日志表成功态（异步推送落定，轮询等待——只认本用例两行，残留行不计）
waitUntil(() -> logRepository.findAll().stream()
- .allMatch(l -> l.getStatus() == FlwEnums.CallbackLogStatus.SUCCESS.getCode()), 10_000);
+ .filter(l -> "cb-1".equals(l.getBizId())).count() >= 2, 60_000);
+ waitUntil(() -> logRepository.findAll().stream()
+ .filter(l -> "cb-1".equals(l.getBizId()))
+ .allMatch(l -> l.getStatus() == FlwEnums.CallbackLogStatus.SUCCESS.getCode()),
+ 60_000);
}
/**
@@ -261,7 +265,7 @@ class CallbackDispatchIT extends FlowTestSupport {
+ "\"submitterId\":201,\"submitterName\":\"张三\"}";
client.post("/oapi/flow/apply?schId=1", body, JsonNode.class);
- waitUntil(() -> hits.stream().anyMatch(r -> r.body != null && r.body.contains("flow.submitted")), 10_000);
+ waitUntil(() -> hits.stream().anyMatch(r -> r.body != null && r.body.contains("flow.submitted")), 60_000);
Received push = hits.stream()
.filter(r -> r.body != null && r.body.contains("flow.submitted"))
.findFirst().orElseThrow(IllegalStateException::new);
@@ -288,16 +292,14 @@ class CallbackDispatchIT extends FlowTestSupport {
+ "\"submitterId\":201,\"submitterName\":\"张三\"}";
client.post("/oapi/flow/apply?schId=1", body, JsonNode.class);
- // 首推失败：retryCount=1（异步首推，轮询等待）
- waitUntil(() -> logRepository.findAll().stream()
- .anyMatch(l -> l.getRetryCount() != null && l.getRetryCount() >= 1), 10_000);
+ // 首推失败：retryCount=1（异步首推，轮询等待——只认本用例行）
+ waitFirstFailureLanded("cb-2");
// 手工逐次触发扫描语义再失败 5 轮（共 6 次，越过退避表 5 项）
+ FlwCallbackLog hung = soleRow("cb-2");
for (int round = 0; round < 5; round++) {
- for (FlwCallbackLog row : logRepository.findAll()) {
- pushService.pushAsync(row.getId());
- }
+ pushService.pushAsync(hung.getId());
+ hung = logRepository.findById(hung.getId()).orElseThrow(IllegalStateException::new);
}
- FlwCallbackLog hung = logRepository.findAll().get(0);
// T1.1 核心语义：持续重试不自动死信——status 仍=0、retryCount=6、nextRetry≈now+60min（封顶）
assertEquals(FlwEnums.CallbackLogStatus.PENDING.getCode(), hung.getStatus(),
"越过退避表后必须保持待推持续重试，不得自动死信");
@@ -308,8 +310,9 @@ class CallbackDispatchIT extends FlowTestSupport {
&& hung.getNextRetryTime().isBefore(expectedNext.plusMinutes(5)),
"越过退避表后 nextRetryTime 应封顶 +60 分钟: " + hung.getNextRetryTime());
assertTrue(logRepository.findAll().stream()
- .allMatch(l -> l.getStatus() == FlwEnums.CallbackLogStatus.PENDING.getCode()),
- "任何行都不应出现死信（status=2）");
+ .filter(l -> "cb-2".equals(l.getBizId()))
+ .allMatch(l -> l.getStatus() == FlwEnums.CallbackLogStatus.PENDING.getCode()),
+ "本用例行不应出现死信（status=2）");
assertNotNull(hung.getLastError());
}
@@ -330,23 +333,21 @@ class CallbackDispatchIT extends FlowTestSupport {
+ "\"bizType\":\"svc_item\",\"bizId\":\"cb-4\",\"bizTitle\":\"张三的告警件\","
+ "\"submitterId\":201,\"submitterName\":\"张三\"}";
client.post("/oapi/flow/apply?schId=1", body, JsonNode.class);
- waitUntil(() -> logRepository.findAll().stream()
- .anyMatch(l -> l.getRetryCount() != null && l.getRetryCount() >= 1), 10_000);
+ waitFirstFailureLanded("cb-4");
// 失败到第 6 次（=挂起阈值）：告警恰一次
+ FlwCallbackLog row = soleRow("cb-4");
for (int round = 0; round < 5; round++) {
- for (FlwCallbackLog row : logRepository.findAll()) {
- pushService.pushAsync(row.getId());
- }
+ pushService.pushAsync(row.getId());
+ row = logRepository.findById(row.getId()).orElseThrow(IllegalStateException::new);
}
assertEquals(1, STUB_USER_MSG.hangAlerts.get(), "第 6 次失败后挂起告警应恰发送一次");
// 第 7 次失败：仍是 1（恰一次）
- for (FlwCallbackLog row : logRepository.findAll()) {
- pushService.pushAsync(row.getId());
- }
+ pushService.pushAsync(row.getId());
+ row = logRepository.findById(row.getId()).orElseThrow(IllegalStateException::new);
assertEquals(1, STUB_USER_MSG.hangAlerts.get(), "第 7 次失败后告警计数仍应为 1");
- assertEquals(7, logRepository.findAll().get(0).getRetryCount());
+ assertEquals(7, row.getRetryCount());
}
@Test
@@ -373,13 +374,12 @@ class CallbackDispatchIT extends FlowTestSupport {
client.post("/oapi/flow/apply?schId=1", body, JsonNode.class);
// 首推 500 → 进入重试（status=0, retryCount=1）
- waitUntil(() -> logRepository.findAll().stream()
- .anyMatch(l -> l.getRetryCount() != null && l.getRetryCount() >= 1), 10_000);
+ waitFirstFailureLanded("cb-5");
// 消费方恢复后（扫描/重推触发）→ 200 → status=1 + pushTime 落定
- for (FlwCallbackLog row : logRepository.findAll()) {
- pushService.pushAsync(row.getId());
- }
- FlwCallbackLog recovered = logRepository.findAll().get(0);
+ FlwCallbackLog failed = soleRow("cb-5");
+ pushService.pushAsync(failed.getId());
+ FlwCallbackLog recovered = logRepository.findById(failed.getId())
+ .orElseThrow(IllegalStateException::new);
assertEquals(FlwEnums.CallbackLogStatus.SUCCESS.getCode(), recovered.getStatus(),
"瞬时失败恢复后应自动治愈为成功");
assertNotNull(recovered.getPushTime());
@@ -402,37 +402,39 @@ class CallbackDispatchIT extends FlowTestSupport {
+ "\"bizType\":\"svc_item\",\"bizId\":\"cb-6\",\"bizTitle\":\"张三的管理件\","
+ "\"submitterId\":201,\"submitterName\":\"张三\"}";
client.post("/oapi/flow/apply?schId=1", body, JsonNode.class);
- waitUntil(() -> logRepository.findAll().stream()
- .anyMatch(l -> l.getRetryCount() != null && l.getRetryCount() >= 1), 10_000);
+ waitFirstFailureLanded("cb-6");
+ FlwCallbackLog hung = soleRow("cb-6");
for (int round = 0; round < 5; round++) {
- for (FlwCallbackLog row : logRepository.findAll()) {
- pushService.pushAsync(row.getId());
- }
+ pushService.pushAsync(hung.getId());
+ hung = logRepository.findById(hung.getId()).orElseThrow(IllegalStateException::new);
}
- FlwCallbackLog hung = logRepository.findAll().get(0);
assertEquals(6, hung.getRetryCount());
+ final FlwCallbackLog hungRow = hung;
- // 挂起列表：status=0 且 retryCount≥阈值的分页行，不含正常行
+ // 挂起列表：包含本用例挂起行，且该行合法（status=0、retryCount≥阈值）
com.yunhai.platform.utils.model.BasePageResult hungPage =
callbackAdminService.pageHung(SCH, 1, 10);
- assertTrue(hungPage.getContent().stream().anyMatch(l -> l.getId().equals(hung.getId())));
- assertTrue(hungPage.getContent().stream()
- .allMatch(l -> l.getStatus() == FlwEnums.CallbackLogStatus.PENDING.getCode()
- && l.getRetryCount() >= 6));
+ assertTrue(hungPage.getContent().stream().anyMatch(l -> l.getId().equals(hungRow.getId())));
+ FlwCallbackLog listed = hungPage.getContent().stream()
+ .filter(l -> l.getId().equals(hungRow.getId())).findFirst()
+ .orElseThrow(IllegalStateException::new);
+ assertTrue(listed.getStatus() == FlwEnums.CallbackLogStatus.PENDING.getCode()
+ && listed.getRetryCount() >= 6,
+ "挂起列表中的本用例行必须待推且达阈值");
// 管理端手工标记死信（唯一死信入口）
- callbackAdminService.markDead(SCH, hung.getId());
- FlwCallbackLog dead = logRepository.findById(hung.getId()).orElseThrow(IllegalStateException::new);
+ callbackAdminService.markDead(SCH, hungRow.getId());
+ FlwCallbackLog dead = logRepository.findById(hungRow.getId()).orElseThrow(IllegalStateException::new);
assertEquals(FlwEnums.CallbackLogStatus.DEAD.getCode(), dead.getStatus());
// 恢复消费方地址后既有 rePush 复活：置回待推立即推送 → 成功
regRow.setCallbackUrl("http://localhost:" + stubPort + "/callback/flow");
regRepository.save(regRow);
- callbackAdminService.rePush(SCH, java.util.Collections.singletonList(hung.getId()));
+ callbackAdminService.rePush(SCH, java.util.Collections.singletonList(hungRow.getId()));
waitUntil(() -> {
- FlwCallbackLog row = logRepository.findById(hung.getId()).orElse(null);
+ FlwCallbackLog row = logRepository.findById(hungRow.getId()).orElse(null);
return row != null && row.getStatus() == FlwEnums.CallbackLogStatus.SUCCESS.getCode();
- }, 10_000);
+ }, 60_000);
}
@Test
@@ -465,6 +467,29 @@ class CallbackDispatchIT extends FlowTestSupport {
return body;
}
+ /**
+ * 本用例自建投递行（bizId 每用例唯一）。P1-1 教训：库中会残留上一轮运行未推完的
+ * PENDING 行（崩溃/中断运行遗产），启动扫描会立即恢复推送它们——等待谓词与行定位
+ * 一律以本用例 bizId 过滤，不与残留行混淆。
+ */
+ private FlwCallbackLog soleRow(String bizId) {
+ java.util.List rows = logRepository.findAll().stream()
+ .filter(l -> bizId.equals(l.getBizId()))
+ .collect(java.util.stream.Collectors.toList());
+ assertEquals(1, rows.size(), "本用例应恰有一条投递行：bizId=" + bizId);
+ return rows.get(0);
+ }
+
+ /** 等待本用例行首推失败落定（retryCount≥1）且首推线程已完全退出 IN_FLIGHT——
+ * 否则紧随的手动重推首轮会被在途跳过静默吞计（P1-1 实测根因）。 */
+ private void waitFirstFailureLanded(String bizId) {
+ waitUntil(() -> logRepository.findAll().stream().anyMatch(l ->
+ bizId.equals(l.getBizId()) && l.getRetryCount() != null && l.getRetryCount() >= 1),
+ 60_000);
+ FlwCallbackLog row = soleRow(bizId);
+ waitUntil(() -> !pushService.inFlight(row.getId()), 10_000);
+ }
+
/** 应用签名断言：canonical = METHOD + "\n" + 剥离 base-path 后的 path(+排序 query) + "\n" + ts */
private void assertAppSignature(String expectedTarget, Received r) {
assertNotNull(r.appKey, "推送必须带 X-App-Key");
diff --git a/src/test/java/com/yunhai/flowcenter/callback/CallbackFactDispatchIT.java b/src/test/java/com/yunhai/flowcenter/callback/CallbackFactDispatchIT.java
new file mode 100644
index 0000000..12b5683
--- /dev/null
+++ b/src/test/java/com/yunhai/flowcenter/callback/CallbackFactDispatchIT.java
@@ -0,0 +1,382 @@
+package com.yunhai.flowcenter.callback;
+
+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.support.FlowTestSupport;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.aop.support.AopUtils;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.boot.test.mock.mockito.SpyBean;
+import org.springframework.context.ApplicationEventPublisher;
+import org.springframework.dao.DataAccessResourceFailureException;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.scheduling.TaskScheduler;
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.util.AopTestUtils;
+import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.transaction.PlatformTransactionManager;
+import org.springframework.transaction.support.TransactionSynchronizationManager;
+import org.springframework.transaction.support.TransactionTemplate;
+
+import javax.persistence.EntityManager;
+import javax.persistence.PersistenceContext;
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mockingDetails;
+
+/**
+ * C01: real business commit -> real AFTER_COMMIT -> independent fact commit, plus the real sweep entry.
+ * Run alone on the existing P2-2 MySQL 8 fixture (13429/fl_d09_20261026), with ddl-auto=validate.
+ * No test-managed transaction. Only HTTP transport is mocked: all facts/deliveries use real repositories.
+ */
+@SpringBootTest(properties = "spring.jpa.hibernate.ddl-auto=validate")
+@ActiveProfiles("test")
+@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)
+class CallbackFactDispatchIT extends FlowTestSupport {
+
+ @Autowired private DataSource dataSource;
+ @Autowired private JdbcTemplate jdbc;
+ @Autowired private PlatformTransactionManager transactionManager;
+ @Autowired private ApplicationEventPublisher publisher;
+ @PersistenceContext private EntityManager entityManager;
+ @SpyBean private CallbackDispatcher dispatcher;
+ @SpyBean private CallbackFactStore factStore;
+ @SpyBean private CallbackLogStore logStore;
+ @MockBean private CallbackPushService pushService;
+ @MockBean private TaskScheduler scheduler;
+
+ private ExecutorService worker;
+ private final AtomicBoolean skipNormalDispatch = new AtomicBoolean();
+ private final AtomicBoolean failFactCommit = new AtomicBoolean();
+ private final AtomicBoolean failSecondDelivery = new AtomicBoolean();
+ private final AtomicInteger deliveryAttempts = new AtomicInteger();
+ private final AtomicInteger flushedButRolledBack = new AtomicInteger();
+ private final AtomicInteger factTransactions = new AtomicInteger();
+ private final AtomicReference