@chongyan/autospec 1.0.1

package/knowledge/standards/data-consistency.md

@@ -0,0 +1,1085 @@
+# 跨域系统数据一致性保证方案
+
+> **文档版本**: v1.0
+> **最后更新**: 2026-03-26
+> **适用范围**: 所有涉及跨域协作的分布式系统
+> **核心目标**: 定义跨域系统数据一致性保证的标准方案和最佳实践
+
+---
+
+## 概述
+
+在分布式系统架构中，当一个业务流程涉及多个业务域时，如何保证跨域数据的一致性是关键挑战。本文档定义了**三种主流的一致性保证方案**，以及**接口幂等性设计**的最佳实践。
+
+### 核心原则
+
+1. **业务优先**：根据业务特性选择合适的一致性方案，不是所有场景都需要强一致性
+2. **性能平衡**：在一致性和性能之间找到平衡点
+3. **可监控**：所有一致性方案必须有完善的监控和告警
+4. **可补偿**：异常场景必须有明确的补偿或人工介入机制
+
+---
+
+## 一致性级别对比
+
+| 一致性级别 | 特点 | 适用场景 | 典型方案 |
+|-----------|------|---------|---------|
+| **强一致性** | 实时保证数据一致 | 核心交易、关键数据操作 | 分布式事务（2PC/SAGA） |
+| **最终一致性** | 允许短暂不一致，但最终会一致 | 订单状态同步、数据同步 | 中间态 + 重试、消息队列 |
+| **弱一致性** | 不保证一致性 | 日志记录、统计分析 | 异步写入 |
+
+**系统推荐**：
+- **核心交易**：强一致性（分布式事务）
+- **订单状态**：最终一致性（中间态 + 重试 或 消息队列）
+- **统计数据**：弱一致性（异步同步）
+
+---
+
+## 方案一：分布式事务（强一致性）
+
+### 适用场景
+
+- ✅ 涉及核心数据操作（扣款、退款、转账）
+- ✅ 核心业务数据修改
+- ✅ 不可分割的业务操作（要么全部成功，要么全部失败）
+- ✅ 业务要求实时一致性
+
+### 不适用场景
+
+- ❌ 高并发场景（性能瓶颈）
+- ❌ 可接受短暂不一致的场景
+- ❌ 涉及外部系统的操作（外部系统可能不支持分布式事务）
+
+---
+
+### 1.1 两阶段提交（2PC - Two-Phase Commit）
+
+#### 原理
+
+```mermaid
+sequenceDiagram
+    participant C as 协调者
+    participant A as 系统 A
+    participant B as 系统 B
+
+    Note over C,B: 阶段 1: 准备阶段
+    C->>A: prepare（预操作）
+    A-->>C: 准备成功
+    C->>B: prepare（预操作）
+    B-->>C: 准备成功
+
+    Note over C,B: 阶段 2: 提交阶段
+    C->>A: commit（提交操作）
+    A-->>C: 提交成功
+    C->>B: commit（提交操作）
+    B-->>C: 提交成功
+```
+
+#### 优点
+- ✅ 强一致性保证
+- ✅ 实现简单，逻辑清晰
+- ✅ 数据库天然支持
+
+#### 缺点
+- ❌ 性能差（阻塞等待）
+- ❌ 单点故障（协调者故障导致阻塞）
+- ❌ 不适合高并发场景
+
+#### 实现示例（伪代码）
+
+```java
+@Transactional
+public void executeWithTwoPhaseCommit(TransactionContext context) {
+    // 阶段 1: 准备阶段
+    boolean systemAPrepared = systemAService.prepare(context);
+    boolean systemBPrepared = systemBService.prepare(context);
+
+    if (systemAPrepared && systemBPrepared) {
+        // 阶段 2: 提交阶段
+        try {
+            systemAService.commit(context);
+            systemBService.commit(context);
+        } catch (Exception e) {
+            // 提交失败，回滚
+            systemAService.rollback(context);
+            systemBService.rollback(context);
+            throw e;
+        }
+    } else {
+        // 准备失败，回滚
+        if (systemAPrepared) systemAService.rollback(context);
+        if (systemBPrepared) systemBService.rollback(context);
+        throw new TransactionException("准备阶段失败");
+    }
+}
+```
+
+#### 使用建议
+
+**推荐场景**：
+```
+✅ 账户转账
+   - 系统 A：扣减余额
+   - 系统 B：增加余额
+   - 要求：实时一致，不允许出现扣减但未增加的情况
+```
+
+**监控指标**：
+- 准备阶段成功率
+- 提交阶段成功率
+- 平均执行时间
+- 阻塞等待时间
+
+---
+
+### 1.2 SAGA 模式（补偿型分布式事务）
+
+#### 原理
+
+```mermaid
+sequenceDiagram
+    participant T as 交易域
+    participant A as 账户域
+    participant B as 业务域
+
+    Note over T,B: 正向流程
+    T->>A: 1. 冻结余额
+    A-->>T: 冻结成功
+    T->>B: 2. 创建订单
+    B-->>T: 创建成功
+    T->>A: 3. 扣减余额
+    A-->>T: 扣减成功
+    T->>B: 4. 确认订单
+    B-->>T: 确认成功
+
+    Note over T,B: 补偿流程（步骤 3 失败）
+    T->>B: C2. 取消订单
+    B-->>T: 取消成功
+    T->>A: C1. 解冻余额
+    A-->>T: 解冻成功
+```
+
+#### 核心要素
+
+1. **正向操作（Ti）**：每个步骤的正常操作
+2. **补偿操作（Ci）**：每个步骤的回滚操作
+3. **补偿规则**：如果 Ti 失败，则执行 Ci、Ci-1、...、C1
+
+#### 优点
+- ✅ 性能好（异步执行，非阻塞）
+- ✅ 可用性高（无协调者单点故障）
+- ✅ 适合长事务
+
+#### 缺点
+- ❌ 最终一致性（非实时）
+- ❌ 补偿逻辑复杂
+- ❌ 需要业务支持补偿操作
+
+#### 实现示例（伪代码）
+
+```java
+public class SagaOrchestrator {
+
+    private List<SagaStep> steps = new ArrayList<>();
+
+    public void execute() {
+        List<SagaStep> executedSteps = new ArrayList<>();
+
+        try {
+            // 正向执行
+            for (SagaStep step : steps) {
+                step.forward();
+                executedSteps.add(step);
+            }
+        } catch (Exception e) {
+            // 补偿执行（逆序）
+            Collections.reverse(executedSteps);
+            for (SagaStep step : executedSteps) {
+                try {
+                    step.compensate();
+                } catch (Exception ce) {
+                    // 补偿失败，记录日志，告警
+                    log.error("补偿失败：{}", step, ce);
+                    alertService.send("SAGA 补偿失败", step);
+                }
+            }
+            throw e;
+        }
+    }
+}
+
+// SAGA 步骤定义示例
+public class ExampleSaga {
+
+    @SagaStep(order = 1)
+    public void freezeResource(TransactionContext ctx) {
+        // 正向：冻结资源
+        resourceService.freeze(ctx.getResourceId());
+    }
+
+    @Compensate(for = "freezeResource")
+    public void unfreezeResource(TransactionContext ctx) {
+        // 补偿：解冻资源
+        resourceService.unfreeze(ctx.getResourceId());
+    }
+
+    @SagaStep(order = 2)
+    public void createOrder(TransactionContext ctx) {
+        // 正向：创建订单
+        orderService.create(ctx.getOrder());
+    }
+
+    @Compensate(for = "createOrder")
+    public void cancelOrder(TransactionContext ctx) {
+        // 补偿：取消订单
+        orderService.cancel(ctx.getOrderId());
+    }
+
+    @SagaStep(order = 3)
+    public void deductResource(TransactionContext ctx) {
+        // 正向：扣减资源
+        resourceService.deduct(ctx.getResourceId());
+    }
+
+    @Compensate(for = "deductResource")
+    public void refundResource(TransactionContext ctx) {
+        // 补偿：退还资源
+        resourceService.refund(ctx.getResourceId());
+    }
+}
+```
+
+#### 补偿策略表
+
+| 步骤 | 正向操作 | 补偿操作 | 补偿条件 | 补偿幂等性 |
+|------|---------|---------|---------|-----------|
+| 1 | 冻结资源 | 解冻资源 | 后续步骤失败 | 根据冻结记录 ID 解冻 |
+| 2 | 创建订单 | 取消订单 | 扣减失败 | 根据订单 ID 取消，支持重复取消 |
+| 3 | 扣减资源 | 退还资源 | 确认失败 | 根据交易流水号退还，支持重复退还 |
+
+#### 使用建议
+
+**推荐场景**：
+```
+✅ 下单扣库存
+   - 系统 A：冻结库存 → 扣减库存
+   - 系统 B：创建订单 → 确认订单
+   - 特点：可接受短暂不一致，有明确的补偿流程
+```
+
+**监控指标**：
+- 正向流程成功率
+- 补偿流程触发次数
+- 补偿流程成功率
+- 平均执行时间
+- 一致性达成时间（从发起到最终一致的时间）
+
+---
+
+## 方案二：中间态 + 定时任务重试（最终一致性）
+
+### 适用场景
+
+- ✅ 订单状态同步
+- ✅ 数据同步任务
+- ✅ 可接受延迟的业务操作
+- ✅ 外部系统调用（外部系统可能不可靠）
+
+### 不适用场景
+
+- ❌ 实时性要求高的场景
+- ❌ 核心数据操作
+
+---
+
+### 2.1 设计原理
+
+#### 核心思想
+
+1. **引入中间状态**：在业务流程中引入中间状态（如 PENDING、PROCESSING）
+2. **定时任务重试**：定时扫描中间状态的记录，重试未完成的操作
+3. **状态流转**：成功后流转到最终状态（SUCCESS、FAILED）
+
+#### 状态机设计
+
+```mermaid
+stateDiagram-v2
+    [*] --> INIT: 创建记录
+    INIT --> PROCESSING: 开始处理
+    PROCESSING --> SUCCESS: 处理成功
+    PROCESSING --> RETRY: 处理失败
+    RETRY --> PROCESSING: 定时任务重试
+    RETRY --> FAILED: 超过最大重试次数
+    SUCCESS --> [*]
+    FAILED --> [*]
+```
+
+#### 数据模型设计
+
+```java
+@Table(name = "sync_task")
+public class SyncTask {
+
+    @Id
+    private Long id;
+
+    // 业务 ID
+    private String bizId;
+
+    // 状态：INIT, PROCESSING, RETRY, SUCCESS, FAILED
+    private String status;
+
+    // 重试次数
+    private Integer retryCount;
+
+    // 最大重试次数
+    private Integer maxRetryCount;
+
+    // 下次重试时间
+    private LocalDateTime nextRetryTime;
+
+    // 错误信息
+    private String errorMessage;
+
+    // 创建时间
+    private LocalDateTime createTime;
+
+    // 更新时间
+    private LocalDateTime updateTime;
+}
+```
+
+---
+
+### 2.2 实现示例
+
+#### 业务流程
+
+```java
+@Service
+public class SyncService {
+
+    /**
+     * 同步数据到下游系统
+     */
+    public void syncData(String bizId) {
+        // 1. 创建同步任务
+        SyncTask task = new SyncTask();
+        task.setBizId(bizId);
+        task.setStatus("INIT");
+        task.setRetryCount(0);
+        task.setMaxRetryCount(5);
+        task.setNextRetryTime(LocalDateTime.now());
+        taskRepository.save(task);
+
+        // 2. 异步执行同步
+        executeSyncAsync(task);
+    }
+
+    /**
+     * 异步执行同步
+     */
+    @Async
+    private void executeSyncAsync(SyncTask task) {
+        try {
+            // 更新状态为 PROCESSING
+            task.setStatus("PROCESSING");
+            taskRepository.save(task);
+
+            // 调用下游系统
+            downstreamService.sync(task.getBizId());
+
+            // 同步成功
+            task.setStatus("SUCCESS");
+            taskRepository.save(task);
+
+        } catch (Exception e) {
+            // 同步失败，更新为 RETRY 状态
+            task.setStatus("RETRY");
+            task.setRetryCount(task.getRetryCount() + 1);
+            task.setErrorMessage(e.getMessage());
+
+            // 计算下次重试时间（指数退避）
+            long delayMinutes = (long) Math.pow(2, task.getRetryCount());
+            task.setNextRetryTime(LocalDateTime.now().plusMinutes(delayMinutes));
+
+            taskRepository.save(task);
+        }
+    }
+}
+```
+
+#### 定时任务扫描
+
+```java
+@Component
+public class SyncRetryJob {
+
+    /**
+     * 每分钟扫描一次需要重试的任务
+     */
+    @Scheduled(cron = "0 * * * * ?")
+    public void retryPendingTasks() {
+        // 1. 查询需要重试的任务
+        List<SyncTask> tasks = taskRepository.findByStatusAndNextRetryTimeBefore(
+            "RETRY", LocalDateTime.now()
+        );
+
+        // 2. 逐个重试
+        for (SyncTask task : tasks) {
+            // 检查是否超过最大重试次数
+            if (task.getRetryCount() >= task.getMaxRetryCount()) {
+                task.setStatus("FAILED");
+                taskRepository.save(task);
+
+                // 发送告警
+                alertService.send(
+                    "同步失败",
+                    String.format("业务 %s 同步失败，已重试 %d 次",
+                        task.getBizId(), task.getRetryCount())
+                );
+                continue;
+            }
+
+            // 重试
+            executeSyncAsync(task);
+        }
+    }
+}
+```
+
+---
+
+### 2.3 重试策略
+
+#### 指数退避（Exponential Backoff）
+
+```
+重试次数    延迟时间
+1          2^1 = 2 分钟
+2          2^2 = 4 分钟
+3          2^3 = 8 分钟
+4          2^4 = 16 分钟
+5          2^5 = 32 分钟
+```
+
+#### 固定延迟
+
+```
+所有重试都间隔固定时间，如 5 分钟
+```
+
+#### 推荐策略
+
+| 场景 | 推荐策略 | 理由 |
+|------|---------|------|
+| 外部系统调用 | 指数退避 | 避免频繁重试加剧外部系统压力 |
+| 内部系统同步 | 固定延迟 | 内部系统恢复快，固定延迟即可 |
+| 高优先级任务 | 短延迟 + 更多重试次数 | 快速恢复 |
+
+---
+
+### 2.4 使用建议
+
+**推荐场景**：
+```
+✅ 订单状态同步到数据仓库
+   - 主流程：创建订单 → 记录同步任务
+   - 异步任务：定时同步到数仓
+   - 失败处理：重试 5 次，失败后告警
+
+✅ 向外部系统推送数据
+   - 主流程：完成业务操作
+   - 异步任务：推送到外部系统
+   - 失败处理：重试 + 人工介入
+```
+
+**监控指标**：
+- 待重试任务数量
+- 重试成功率
+- 平均重试次数
+- 最终失败数量
+- 一致性达成时间
+
+---
+
+## 方案三：消息队列（最终一致性）
+
+### 适用场景
+
+- ✅ 异步通知
+- ✅ 事件驱动架构
+- ✅ 解耦系统间依赖
+- ✅ 高吞吐场景
+
+### 不适用场景
+
+- ❌ 实时性要求极高的场景
+- ❌ 强依赖顺序的场景（除非使用顺序消息）
+
+---
+
+### 3.1 设计原理
+
+#### 核心思想
+
+1. **发布 - 订阅模式**：生产者发布消息，消费者订阅消息
+2. **最终一致性**：通过消息的可靠投递保证最终一致
+3. **异步解耦**：生产者和消费者解耦，提高系统可用性
+
+#### 架构图
+
+```mermaid
+graph LR
+    A[系统 A] -->|1. 完成操作 | A
+    A -->|2. 发送消息 | MQ[消息队列]
+    MQ -->|3. 消费消息 | B[系统 B]
+    MQ -->|3. 消费消息 | C[系统 C]
+    MQ -->|3. 消费消息 | D[系统 D]
+
+    B -->|4. 更新数据 | B
+    C -->|4. 更新数据 | C
+    D -->|4. 更新数据 | D
+```
+
+---
+
+### 3.2 实现方案
+
+#### 3.2.1 本地消息表 + 定时任务（推荐）
+
+**保证消息可靠发送**
+
+```java
+@Service
+public class BizService {
+
+    @Transactional
+    public void executeBiz(BizRequest request) {
+        // 1. 完成业务操作
+        bizRepository.save(request);
+
+        // 2. 在同一个事务中，写入本地消息表
+        LocalMessage message = new LocalMessage();
+        message.setTopic("BIZ_COMPLETED");
+        message.setContent(JSON.toJSONString(request));
+        message.setStatus("PENDING");  // 待发送
+        messageRepository.save(message);
+
+        // 3. 事务提交后，业务和消息都保存成功
+    }
+}
+
+@Component
+public class MessageSenderJob {
+
+    /**
+     * 定时扫描本地消息表，发送待发送的消息
+     */
+    @Scheduled(fixedDelay = 5000) // 每 5 秒执行一次
+    public void sendPendingMessages() {
+        List<LocalMessage> messages = messageRepository.findByStatus("PENDING");
+
+        for (LocalMessage message : messages) {
+            try {
+                // 发送消息到 MQ
+                mqProducer.send(message.getTopic(), message.getContent());
+
+                // 更新状态为已发送
+                message.setStatus("SENT");
+                messageRepository.save(message);
+
+            } catch (Exception e) {
+                // 发送失败，更新重试次数
+                message.setRetryCount(message.getRetryCount() + 1);
+
+                if (message.getRetryCount() >= 5) {
+                    message.setStatus("FAILED");
+                    // 发送告警
+                    alertService.send("消息发送失败", message);
+                }
+                messageRepository.save(message);
+            }
+        }
+    }
+}
+```
+
+**数据模型**
+
+```java
+@Table(name = "local_message")
+public class LocalMessage {
+    @Id
+    private Long id;
+
+    // 消息主题
+    private String topic;
+
+    // 消息内容（JSON）
+    private String content;
+
+    // 状态：PENDING, SENT, FAILED
+    private String status;
+
+    // 重试次数
+    private Integer retryCount;
+
+    // 创建时间
+    private LocalDateTime createTime;
+}
+```
+
+---
+
+#### 3.2.2 事务消息
+
+**事务消息机制**
+
+```java
+@Service
+public class BizService {
+
+    @Autowired
+    private TransactionMQProducer producer;
+
+    public void executeBiz(BizRequest request) {
+        // 1. 发送半消息（Half Message）
+        Message message = new Message("BIZ_COMPLETED", JSON.toJSONBytes(request));
+        producer.sendMessageInTransaction(message, request);
+    }
+
+    /**
+     * 执行本地事务
+     */
+    @Override
+    public LocalTransactionState executeLocalTransaction(Message msg, Object arg) {
+        BizRequest request = (BizRequest) arg;
+
+        try {
+            // 执行本地事务：完成业务操作
+            bizRepository.save(request);
+
+            // 本地事务成功，提交消息
+            return LocalTransactionState.COMMIT_MESSAGE;
+
+        } catch (Exception e) {
+            // 本地事务失败，回滚消息
+            return LocalTransactionState.ROLLBACK_MESSAGE;
+        }
+    }
+
+    /**
+     * 检查本地事务状态（MQ 回查）
+     */
+    @Override
+    public LocalTransactionState checkLocalTransaction(MessageExt msg) {
+        // 根据消息 ID 查询本地事务状态
+        String bizId = msg.getUserProperty("bizId");
+        BizRecord record = bizRepository.findById(bizId);
+
+        if (record != null) {
+            return LocalTransactionState.COMMIT_MESSAGE;
+        } else {
+            return LocalTransactionState.ROLLBACK_MESSAGE;
+        }
+    }
+}
+```
+
+---
+
+### 3.3 消费者幂等性设计
+
+**消息去重表**
+
+```java
+@Service
+public class BizEventConsumer {
+
+    /**
+     * 消费业务事件
+     */
+    @RocketMQMessageListener(topic = "BIZ_COMPLETED", consumerGroup = "biz-service")
+    public void onMessage(String messageBody) {
+        BizEvent event = JSON.parseObject(messageBody, BizEvent.class);
+        String messageId = event.getMessageId();
+
+        // 1. 检查消息是否已处理（幂等性检查）
+        if (messageDeduplicateRepository.exists(messageId)) {
+            log.info("消息已处理，跳过：{}", messageId);
+            return;
+        }
+
+        try {
+            // 2. 处理业务逻辑
+            bizService.process(event);
+
+            // 3. 记录消息已处理
+            MessageDeduplication dedup = new MessageDeduplication();
+            dedup.setMessageId(messageId);
+            dedup.setProcessTime(LocalDateTime.now());
+            messageDeduplicateRepository.save(dedup);
+
+        } catch (Exception e) {
+            // 处理失败，抛出异常，消息会重新投递
+            throw new RuntimeException("处理消息失败", e);
+        }
+    }
+}
+
+@Table(name = "message_deduplication")
+public class MessageDeduplication {
+    @Id
+    private String messageId;  // 消息唯一 ID
+    private LocalDateTime processTime;  // 处理时间
+}
+```
+
+---
+
+### 3.4 使用建议
+
+**推荐场景**：
+```
+✅ 订单创建后通知多个下游系统
+   - 系统 A：创建订单 → 发送消息
+   - 系统 B：消费消息 → 更新账户
+   - 系统 C：消费消息 → 更新库存
+   - 系统 D：消费消息 → 发送通知
+
+✅ 事件驱动架构
+   - 解耦系统间依赖
+   - 异步处理，提高性能
+```
+
+**监控指标**：
+- 消息发送成功率
+- 消息消费成功率
+- 消息堆积量
+- 消费延迟
+- 重复消费次数
+
+---
+
+## 接口幂等性设计（必须）
+
+> **核心原则**：无论调用多少次，结果都一样，不会产生副作用
+
+### 为什么需要幂等性？
+
+在分布式系统中，由于网络不可靠、重试机制、消息队列重复投递等原因，同一个请求可能会被执行多次。如果接口不支持幂等性，可能导致：
+
+- ❌ 重复扣款
+- ❌ 重复创建订单
+- ❌ 数据不一致
+
+### 幂等性实现方案
+
+---
+
+### 4.1 唯一索引（数据库层）
+
+**适用场景**：创建订单、创建记录等插入操作
+
+```java
+@Table(name = "orders")
+public class Order {
+    @Id
+    private Long id;
+
+    // 业务幂等键（唯一索引）
+    @Column(unique = true)
+    private String bizUniqueKey;  // 如：userId + bizType + requestId
+
+    private String userId;
+    private String bizType;
+    private BigDecimal amount;
+}
+
+@Service
+public class OrderService {
+
+    public Order createOrder(OrderRequest request) {
+        // 生成幂等键
+        String bizUniqueKey = generateBizUniqueKey(request);
+
+        try {
+            Order order = new Order();
+            order.setBizUniqueKey(bizUniqueKey);
+            order.setUserId(request.getUserId());
+            orderRepository.save(order);
+            return order;
+
+        } catch (DuplicateKeyException e) {
+            // 违反唯一索引，说明订单已存在（幂等返回）
+            return orderRepository.findByBizUniqueKey(bizUniqueKey);
+        }
+    }
+
+    private String generateBizUniqueKey(OrderRequest request) {
+        // userId + bizType + requestId
+        return request.getUserId() + "_" +
+               request.getBizType() + "_" +
+               request.getRequestId();
+    }
+}
+```
+
+---
+
+### 4.2 分布式锁（Redis）
+
+**适用场景**：防止并发重复操作
+
+```java
+@Service
+public class OrderService {
+
+    @Autowired
+    private RedisLockService lockService;
+
+    public Order createOrder(OrderRequest request) {
+        String lockKey = "order:create:" + request.getRequestId();
+
+        // 尝试获取分布式锁
+        if (!lockService.tryLock(lockKey, 30, TimeUnit.SECONDS)) {
+            throw new BizException("请勿重复提交");
+        }
+
+        try {
+            // 检查订单是否已存在
+            Order existingOrder = orderRepository.findByRequestId(request.getRequestId());
+            if (existingOrder != null) {
+                return existingOrder;  // 幂等返回
+            }
+
+            // 创建订单
+            Order order = new Order();
+            order.setRequestId(request.getRequestId());
+            orderRepository.save(order);
+            return order;
+
+        } finally {
+            lockService.unlock(lockKey);
+        }
+    }
+}
+```
+
+---
+
+### 4.3 Token 机制
+
+**适用场景**：前端提交表单，防止重复提交
+
+```java
+@RestController
+public class OrderController {
+
+    /**
+     * 获取提交 Token
+     */
+    @GetMapping("/order/token")
+    public String getSubmitToken() {
+        String token = UUID.randomUUID().toString();
+        // 存储到 Redis，有效期 5 分钟
+        redisTemplate.opsForValue().set("submit:token:" + token, "1", 5, TimeUnit.MINUTES);
+        return token;
+    }
+
+    /**
+     * 提交订单
+     */
+    @PostMapping("/order/create")
+    public Order createOrder(@RequestBody OrderRequest request,
+                            @RequestHeader("Submit-Token") String token) {
+        // 验证 Token
+        String redisKey = "submit:token:" + token;
+        if (!redisTemplate.delete(redisKey)) {
+            throw new BizException("Token 无效或已使用");
+        }
+
+        // 创建订单
+        return orderService.createOrder(request);
+    }
+}
+```
+
+---
+
+### 4.4 状态机（业务层）
+
+**适用场景**：状态流转操作
+
+```java
+@Service
+public class OrderService {
+
+    /**
+     * 支付订单（幂等）
+     */
+    public void payOrder(String orderId) {
+        Order order = orderRepository.findById(orderId);
+
+        // 状态机校验
+        if (order.getStatus().equals("PAID")) {
+            // 已支付，幂等返回
+            log.info("订单已支付，跳过：{}", orderId);
+            return;
+        }
+
+        if (!order.getStatus().equals("PENDING")) {
+            throw new BizException("订单状态不允许支付：" + order.getStatus());
+        }
+
+        // 执行支付
+        paymentService.pay(orderId);
+
+        // 更新状态
+        order.setStatus("PAID");
+        orderRepository.save(order);
+    }
+}
+```
+
+---
+
+### 4.5 幂等性方案对比
+
+| 方案 | 优点 | 缺点 | 适用场景 |
+|------|------|------|---------|
+| **唯一索引** | 简单、可靠、性能好 | 需要设计幂等键 | 创建订单、创建记录 |
+| **分布式锁** | 防止并发 | 依赖 Redis、性能略差 | 高并发防重 |
+| **Token 机制** | 防止前端重复提交 | 需要额外接口获取 Token | 表单提交 |
+| **状态机** | 业务语义清晰 | 需要设计状态流转 | 状态变更操作 |
+
+---
+
+## 方案选择决策树
+
+```mermaid
+graph TD
+    A[需要跨域数据一致性] --> B{是否涉及核心操作？}
+    B -->|是 | C[分布式事务<br/>2PC/SAGA]
+    B -->|否 | D{实时性要求？}
+    D -->|实时 | E[SAGA 模式]
+    D -->|可延迟 | F{是否需要解耦？}
+    F -->|是 | G[消息队列<br/>可靠事件驱动]
+    F -->|否 | H[中间态 + 重试<br/>定时任务]
+
+    C --> I[接口必须幂等]
+    E --> I
+    G --> I
+    H --> I
+
+    style C fill:#ffe1e1
+    style E fill:#fff4e1
+    style G fill:#e1f5ff
+    style H fill:#e1ffe8
+    style I fill:#ffe1f5
+```
+
+---
+
+## 最佳实践
+
+### 1. 接口设计规范
+
+所有跨域接口必须满足：
+
+```java
+/**
+ * 标准跨域接口签名
+ */
+public interface CrossDomainService {
+
+    /**
+     * @param requestId 幂等键（必须）
+     * @param bizContext 业务上下文
+     * @return 处理结果
+     */
+    Result execute(String requestId, BizContext bizContext);
+}
+```
+
+### 2. 监控告警
+
+| 监控项 | 告警阈值 | 处理措施 |
+|--------|---------|---------|
+| 重试次数超限 | 单个任务重试 > 5 次 | 人工介入 |
+| 一致性延迟 | 达成一致时间 > 5 分钟 | 告警通知 |
+| 补偿失败 | 补偿操作失败 | 紧急告警 |
+| 消息堆积 | 堆积量 > 10000 | 扩容消费者 |
+
+### 3. 降级方案
+
+```java
+@Service
+public class SyncService {
+
+    @HystrixCommand(fallbackMethod = "syncFallback")
+    public void sync(String bizId) {
+        // 正常同步逻辑
+        downstreamService.sync(bizId);
+    }
+
+    /**
+     * 降级方案：记录到本地表，稍后重试
+     */
+    public void syncFallback(String bizId) {
+        log.warn("同步失败，降级处理：{}", bizId);
+
+        // 记录到本地表
+        SyncTask task = new SyncTask();
+        task.setBizId(bizId);
+        task.setStatus("PENDING");
+        taskRepository.save(task);
+    }
+}
+```
+
+### 4. 数据核对
+
+**定时核对任务**
+
+```java
+@Component
+public class DataReconciliationJob {
+
+    /**
+     * 每天凌晨核对数据一致性
+     */
+    @Scheduled(cron = "0 0 2 * * ?")
+    public void reconcile() {
+        // 1. 查询系统 A 的记录
+        List<Record> recordsA = repositoryA.findByDate(LocalDate.now().minusDays(1));
+
+        // 2. 查询系统 B 的流水
+        List<Transaction> transactionsB = repositoryB.findByDate(...);
+
+        // 3. 核对数据
+        for (Record record : recordsA) {
+            Transaction transaction = findMatchingTransaction(record, transactionsB);
+            if (transaction == null) {
+                // 数据不一致，告警
+                alertService.send("数据不一致", record);
+            }
+        }
+    }
+}
+```
+
+---
+
+## 参考资料
+
+- [分布式事务：SAGA 模式](https://microservices.io/patterns/data/saga.html)
+- [事务消息](https://rocketmq.apache.org/docs/transactionExample/)
+- [幂等性设计模式](https://www.enterpriseintegrationpatterns.com/patterns/messaging/IdempotentReceiver.html)
+- [最终一致性理论](https://www.allthingsdistributed.com/2008/12/eventually_consistent.html)
+
+---
+
+**维护者**: AutoSpec 团队
+**关联文档**: `knowledge/standards/coding-style.md`, `knowledge/standards/code-review.md`