@chongyan/autospec 1.0.2 → 1.0.4

package/knowledge/07-standards/02-data-consistency.md

@@ -1,1085 +0,0 @@
-# 跨域系统数据一致性保证方案
-
-> **文档版本**: 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/07-standards/00-coding-style.md`, `knowledge/07-standards/01-code-review.md`