领域实体与事件溯源 (Domain Entity and Event Sourcing)

import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonProperty;

public class OrderDomainEntity extends DomainEntity {

    @JsonProperty("card_last_four")
    private String cardLastFour;

    // 内存中的临时 CVV：绝不序列化或持久化到事件存储库
    @JsonIgnore
    private String cvv;

    // ...
}

import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonProperty;
import org.stacksaga.annotation.SagaDomainEntity;
import org.stacksaga.annotation.SagaDomainEntityVersion;
import org.stacksaga.api.DomainEntity;

@SagaDomainEntity(
        version = @SagaDomainEntityVersion(major = 1, minor = 0, patch = 0),
        name = "OrderDomainEntity"
)
public class OrderDomainEntity extends DomainEntity {

    // 序列化并存储在事件存储库中（对于 Trace-Window 仪表盘安全脱敏）
    @JsonProperty("token")
    private String encodedToken;

    public OrderDomainEntity() {
        super(OrderDomainEntity.class);
    }

    /**
     * 业务方法 / 执行器调用此方法获取真实解密数据。
     * 标注 @JsonIgnore 以免 Jackson 将其序列化到事件存储库或 Trace-Window 中。
     */
    @JsonIgnore
    public String getTokenAsString() {
        return decodeOrDecrypt(this.encodedToken);
    }

    public String getEncodedToken() {
        return this.encodedToken;
    }

    public void setEncodedToken(String encodedToken) {
        this.encodedToken = encodedToken;
    }
}

@Component
public class OrderDomainEntityKeyGenerator extends AbstractDomainEntityKeyGenerator {

    @Override
    public String generateIdempotencyKey(
            SafeIdempotentInput safeIdempotentInput,
            UnSafeIdempotentInput unSafeIdempotentInput
    ) {
        DomainEntity domainEntity = unSafeIdempotentInput.domainEntity();

        // 检查事务是否起源于 1.1.0 之前（覆盖 1.0.0、1.0.1、1.0.2 等）
        if (domainEntity != null && domainEntity.compare("1.1.0") < 0) {
            return generateLegacyIdempotencyKey(safeIdempotentInput);
        }

        // 1.1.0 及以上版本的标准键生成逻辑
        return generateModernIdempotencyKey(safeIdempotentInput);
    }

    private String generateLegacyIdempotencyKey(SafeIdempotentInput safeInput) {
        // 1.1.0 之前版本中使用的旧版键生成公式
        final String rawKey = safeInput.transactionId().toString() + ":" + safeInput.currentExecutionName();
        return this.hashGenerator().generateHash(rawKey, HashGenerator.ALGType.MD5);
    }

    private String generateModernIdempotencyKey(SafeInput safeInput) {
        // 1.1.0+ 的更新版键生成公式
        final String rawKey = new StringJoiner(":")
                .add(safeInput.transactionId().toString())
                .add(safeInput.currentExecutionName())
                .add(safeInput.executionMode().name().toLowerCase())
                .toString();
        return this.hashGenerator().generateHash(rawKey, HashGenerator.ALGType.MD5);
    }
}

@SagaDomainEntity(
        version = @SagaDomainEntityVersion(major = 1, minor = 0, patch = 0),
        name = "OrderDomainEntity"
)
@Getter
@Setter
public class OrderDomainEntity extends DomainEntity {

    public OrderDomainEntity() {
        super(OrderDomainEntity.class);
    }

    @JsonProperty("order_id")
    private String orderId;

    @JsonProperty("username")
    private String username;

    @JsonProperty("total")
    private Double total;

    @JsonProperty("is_active")
    private Integer isActive;

    @JsonProperty("comment")
    private String comment; (1)

    @JsonProperty("item_details")
    private List<ItemDetail> itemDetails = new ArrayList<>();

    @Getter
    @Setter
    @AllArgsConstructor
    @NoArgsConstructor
    public static class ItemDetail implements Serializable { (2)

        @JsonProperty("item_name")
        private String itemName;

        @JsonProperty("qty")
        private int qty;

        @JsonProperty("price")
        private double price;

        @JsonProperty("note")
        private String note; (3)
    }
}

@SagaDomainEntity(
        version = @SagaDomainEntityVersion(major = 1, minor = 1, patch = 0),
        name = "OrderDomainEntity"
)
@Getter
@Setter
public class OrderDomainEntity extends DomainEntity {

    public OrderDomainEntity() {
        super(OrderDomainEntity.class);
    }

    @JsonProperty("order_id")
    private String orderId;

    @JsonProperty("username")
    private String username;

    @JsonProperty("total")
    private Double total;

    @JsonProperty("is_active")
    private Integer isActive;

    // 从根类中移除了字段 'comment' (1)

    @JsonProperty("item_details")
    private List<ItemDetail> itemDetails = new ArrayList<>();

    @Getter
    @Setter
    @AllArgsConstructor
    @NoArgsConstructor
    public static class ItemDetail extends UnknownPropertyArchive { (2)

        @JsonProperty("item_name")
        private String itemName;

        @JsonProperty("qty")
        private int qty;

        @JsonProperty("price")
        private double price;

        // 从 ItemDetail 中移除了字段 'note' (3)
    }
}

@SagaExecutor(executeFor = "order-service", value = "OrderSaveExecutor")
@AllArgsConstructor
public class OrderSaveExecutor implements CommandExecutor<OrderDomainEntity> {

    @Override
    public ProcessStepManager<OrderDomainEntity> doProcess(
            OrderDomainEntity currentDomainEntity,
            ProcessStepManagerUtil<OrderDomainEntity> stepManager,
            String idempotencyKey
    ) throws RetryableExecutorException, NonRetryableExecutorException {

        // 检查事务是否起源于 1.1.0 之前（覆盖 1.0.0、1.0.1 等）
        if (currentDomainEntity.compare("1.1.0") < 0) { (1)
            // 检索根级缺失属性
            Object comment = currentDomainEntity.getMissingProperties().get("comment"); (2)
            if (comment != null) {
                log.info("Processing legacy transaction with comment: {}", comment);
            }

            // 从内部行项中检索嵌套缺失属性
            for (OrderDomainEntity.ItemDetail itemDetail : currentDomainEntity.getItemDetails()) { (3)
                Object note = itemDetail.getMissingProperties().get("note");
                if (note != null) {
                    log.info("Legacy item note: {}", note);
                }
            }
        } else {
            // 1.1.0+ 的标准执行路径
            log.info("Processing standard order: {}", currentDomainEntity.getOrderId());
        }

        return stepManager.next(UpdateStockExecutor.class, "SAVED_ORDER");
    }

    @Override
    public SagaExecutionEventName doRevert(
            NonRetryableExecutorException primaryExecutionException,
            OrderDomainEntity finalDomainEntityState,
            RevertHintStore revertHintStore,
            String idempotencyKey
    ) throws RetryableExecutorException {
        // 回滚逻辑同样可以按需检查 finalDomainEntityState.compare(...) 或 getMissingProperties()
        return SagaExecutionEventName.of("REVERTED_ORDER_SAVE");
    }
}