payment-kit 1.20.5 → 1.20.7

package/doc/vendor_fulfillment_system.md

@@ -0,0 +1,929 @@
+# 多供应商发货系统完整实现方案
+
+## 📋 项目概述
+
+本文档总结了 Payment Kit 中多供应商发货系统的完整实现，包括架构设计、流程逻辑、技术实现和问题解决方案。
+
+## 🎯 系统目标
+
+### 核心需求
+
+1. **多供应商支持**: 一个订单可以包含多个供应商的商品
+2. **异步发货**: 不同供应商可以独立、并行发货
+3. **状态协调**: 统一管理所有供应商的发货状态
+4. **容错机制**: 处理发货失败、重试、超时等异常情况
+5. **分成处理**: 所有供应商发货完成后，自动进行佣金分成
+6. **退款保障**: 任何供应商失败即全额退款，确保用户权益
+
+### 业务规则
+
+- **全部成功**: 所有供应商发货成功 → 进行佣金分成
+- **任何失败**: 有任何供应商失败、超时或超过重试次数 → **对已成功的供应商发起退货请求** → 全额退款给用户
+- **超时时间**: 5分钟无响应视为超时
+- **重试次数**: 最多3次重试
+- **退货机制**: 对已完成发货的供应商发起退货请求
+
+## 🏗️ 系统架构
+
+### 架构模式: 协调器模式 (Coordinator Pattern)
+
+#### 🔄 **核心流程 (文字版)**
+
+```
+1. Payment Success
+   ↓
+2. vendor-commission.ts
+   ├─ 检查供应商配置
+   ├─ 无供应商 → 直接冷钱包转账 ✅
+   └─ 有供应商 → 调用协调器
+
+3. vendor-fulfillment-coordinator.ts
+   ├─ 启动发货流程
+   ├─ 初始化 vendor_info 状态
+   ├─ 为每个供应商创建发货任务
+   └─ 被动等待通知
+
+4. vendor-fulfillment.ts (并行执行)
+   ├─ 供应商A发货 → 通知协调器 ✅
+   ├─ 供应商B发货 → 通知协调器 ✅
+   ├─ 供应商C发货 → 通知协调器 ❌
+   └─ 重试机制 (最多3次)
+
+5. vendor-fulfillment-coordinator.ts
+   ├─ 接收所有通知
+   ├─ 更新 vendor_info 状态 (事务+锁)
+   ├─ 检查整体状态
+   ├─ 全部成功 → 分成 + 冷钱包 ✅
+   └─ 任何失败 → 🔄 对已成功供应商发起退货请求 → 全额退款 ❌
+```
+
+#### 📊 **详细架构图**
+
+```mermaid
+graph TD
+    A[Payment Success] --> B[Vendor Commission Queue]
+    B --> C{Has Vendor Config?}
+    C -->|No| D[Direct Deposit to Cold Wallet]
+    C -->|Yes| E[Start Multi-Vendor Fulfillment]
+    
+    E --> F[Initialize vendor_info]
+    F --> G[Emit vendor.fulfillment.queued Events]
+    
+    G --> H1[Vendor Fulfillment Queue - Launcher]
+    G --> H2[Vendor Fulfillment Queue - DID Names]
+    G --> H3[Vendor Fulfillment Queue - Vendor N]
+    
+    H1 --> I1[LauncherAdapter.fulfillOrder]
+    H2 --> I2[DIDNamesAdapter.fulfillOrder]
+    H3 --> I3[VendorAdapter.fulfillOrder]
+    
+    I1 --> J1{Success?}
+    I2 --> J2{Success?}
+    I3 --> J3{Success?}
+    
+    J1 -->|Yes| K1[Update vendor_info: completed]
+    J1 -->|No| L1[Update vendor_info: failed + Retry]
+    J2 -->|Yes| K2[Update vendor_info: completed]
+    J2 -->|No| L2[Update vendor_info: failed + Retry]
+    J3 -->|Yes| K3[Update vendor_info: completed]
+    J3 -->|No| L3[Update vendor_info: failed + Retry]
+    
+    K1 --> M[Trigger Coordinator]
+    K2 --> M
+    K3 --> M
+    L1 --> N{Max Retries?}
+    L2 --> N
+    L3 --> N
+    
+    N -->|No| H1
+    N -->|Yes| O[Update vendor_info: max_retries_exceeded]
+    O --> M
+    
+    M --> P[Fulfillment Coordinator]
+    P --> Q{All Completed?}
+    Q -->|Yes| R[Trigger Commission Process]
+    Q -->|No| S{Any Failed/Timeout?}
+    S -->|Yes| T[Handle Partial Failure]
+    S -->|No| U[Wait for More Completions]
+    
+    T --> V[Request Return from Completed Vendors]
+    V --> X[Full Refund]
+    
+    R --> Y[Commission & Payout Processing]
+    X --> Z[Refund Processing]
+```
+
+### 核心组件
+
+#### 1. **Vendor Commission Queue** (`vendor-commission.ts`)
+
+- **职责**: 决策流程入口，判断是否需要供应商发货
+- **输入**: PaymentIntent ID
+- **输出**: 直接转冷钱包 OR 启动多供应商发货流程
+
+#### 2. **Vendor Fulfillment Coordinator** (`vendor-fulfillment-coordinator.ts`)
+
+- **职责**: 协调多个供应商的发货状态，决策后续流程
+- **核心功能**:
+  - 初始化 `vendor_info` 状态
+  - 分发发货任务到各个供应商队列
+  - 收集和分析供应商状态
+  - 决策分成或退款
+
+#### 3. **Vendor Fulfillment Queue** (`vendor-fulfillment.ts`)
+
+- **职责**: 处理单个供应商的发货请求
+- **核心功能**:
+  - 调用供应商适配器 (Adapter)
+  - 处理发货重试
+  - 更新供应商状态
+  - 通知协调器
+
+#### 4. **Vendor Adapters** (`libs/adapters/`)
+
+- **职责**: 与具体供应商系统集成
+- **实现**: `LauncherAdapter`, `DIDNamesAdapter`
+- **接口统一**: `VendorAdapter` 接口
+
+## 📊 数据模型
+
+### CheckoutSession.vendor_info 结构
+
+```typescript
+interface VendorInfo {
+  vendor_id: string;           // 供应商ID
+  order_id: string;           // 供应商订单ID
+  status: 'pending' | 'completed' | 'failed' | 'max_retries_exceeded' | 'return_requested';
+  amount: string;             // 订单金额
+  attempts: number;           // 重试次数
+  lastAttemptAt: string;      // 最后尝试时间
+  error_message?: string;     // 错误信息
+  commissionAmount?: string;  // 佣金金额
+  service_url?: string;       // 服务访问URL
+  completedAt?: string;       // 完成时间
+  // 🆕 退货请求相关字段
+  returnRequest?: {
+    reason: string;                    // 退货原因
+    requestedAt: string;              // 请求时间
+    status: 'pending' | 'accepted' | 'rejected'; // 退货状态
+    returnDetails?: string;           // 退货详情
+  };
+}
+```
+
+### 状态流转
+
+```
+正常流程:
+pending → completed ✅
+
+重试流程:
+pending → failed → pending (retry) → completed ✅
+pending → failed → pending (retry) → failed → max_retries_exceeded ❌
+
+退货流程 (🆕):
+completed → return_requested (当其他供应商失败时)
+```
+
+## 🔄 核心流程
+
+### 📋 **流程概览**
+
+```
+📥 用户支付成功
+   ↓
+🔍 检查是否有供应商配置
+   ├─ 无供应商 → 💰 直接转冷钱包 (结束)
+   └─ 有供应商 → 🚀 启动多供应商发货流程
+       ↓
+📊 初始化供应商状态追踪
+   ↓
+🔀 并行发送发货任务给所有供应商
+   ├─ 📦 供应商A: Launcher 发货
+   ├─ 📦 供应商B: DID Names 发货  
+   └─ 📦 供应商C: 其他供应商发货
+       ↓ (各自独立处理)
+📝 每个供应商完成后更新状态
+   ↓
+🎯 协调器检查整体状态
+   ├─ ✅ 全部成功 → 💸 佣金分成
+   └─ ❌ 任何失败 → 🔄 对已成功供应商发起退货请求 → 全额退款
+```
+
+### 1. 支付成功触发
+
+```typescript
+// payment.ts
+async function updateCheckoutSessionOnPaymentSuccess() {
+  // ... 更新支付状态 ...
+  
+  // 触发供应商佣金处理
+  await vendorCommissionQueue.push({
+    paymentIntentId: paymentIntent.id,
+    retryOnError: true,
+  });
+}
+```
+
+### 2. 供应商佣金决策
+
+```typescript
+// vendor-commission.ts
+export const handleVendorCommission = async (job: VendorCommissionJob) => {
+  const hasVendorConfig = await checkIfPaymentIntentHasVendors(paymentIntentId);
+  
+  if (!hasVendorConfig) {
+    // 无供应商配置 → 直接转冷钱包
+    await executeDirectDepositVault(paymentIntent);
+    return;
+  }
+
+  // 有供应商配置 → 启动多供应商发货流程
+  await startVendorFulfillment(checkoutSessionId, paymentIntentId);
+};
+```
+
+### 3. 多供应商发货启动
+
+```typescript
+// vendor-fulfillment-coordinator.ts
+export async function startVendorFulfillment(
+  checkoutSessionId: string,
+  paymentIntentId: string
+) {
+  // 1. 初始化供应商信息
+  const vendorConfigs = await getVendorConfigurations(checkoutSessionId);
+  const vendorInfo: VendorInfo[] = vendorConfigs.map(config => ({
+    vendor_id: config.vendor_id,
+    order_id: '',
+    status: 'pending',
+    amount: '0',
+    attempts: 0,
+    lastAttemptAt: new Date().toISOString(),
+  }));
+  
+  await updateVendorInfo(checkoutSessionId, vendorInfo);
+
+  // 2. 为每个供应商分发发货任务
+  for (const config of vendorConfigs) {
+    const jobId = `vendor-fulfillment-${checkoutSessionId}-${config.vendor_id}`;
+    
+    events.emit('vendor.fulfillment.queued', jobId, {
+      checkoutSessionId,
+      paymentIntentId,
+      vendorId: config.vendor_id,
+      vendorConfig: config,
+      retryOnError: true,
+    });
+  }
+}
+```
+
+### 4. 单供应商发货处理
+
+```typescript
+// vendor-fulfillment.ts
+export const handleVendorFulfillment = async (job: VendorFulfillmentJob) => {
+  const { checkoutSessionId, paymentIntentId, vendorId, vendorConfig } = job;
+
+  try {
+    // 调用供应商发货服务
+    const fulfillmentResult = await VendorFulfillmentService.fulfillSingleVendorOrder(
+      checkoutSessionId,
+      paymentIntentId,
+      vendorConfig
+    );
+
+    // 发货成功 → 通知协调器
+    await notifyVendorFulfillmentComplete(checkoutSessionId, paymentIntentId, vendorId, 'completed', {
+      orderId: fulfillmentResult.orderId,
+      commissionAmount: fulfillmentResult.commissionAmount,
+      serviceUrl: fulfillmentResult.serviceUrl,
+    });
+  } catch (error) {
+    // 发货失败 → 通知协调器，让队列系统处理重试
+    await notifyVendorFulfillmentComplete(checkoutSessionId, paymentIntentId, vendorId, 'failed', {
+      lastError: error.message,
+    });
+    
+    throw error; // 重新抛出，触发队列重试
+  }
+};
+```
+
+### 5. 协调器状态管理
+
+```typescript
+// vendor-fulfillment-coordinator.ts
+async function handleFulfillmentCoordination(job: CoordinatorJob) {
+  const { checkoutSessionId, paymentIntentId } = job;
+
+  // 1. 获取所有供应商的当前状态
+  const vendorInfo = await getVendorInfo(checkoutSessionId);
+  const vendorConfigs = await getVendorConfigurations(checkoutSessionId);
+
+  // 2. 分析当前状态
+  const analysis = analyzeVendorStates(vendorInfo, vendorConfigs);
+
+  // 3. 根据分析结果决策
+  if (analysis.allCompleted) {
+    // 所有供应商发货成功 → 触发分成
+    await triggerCommissionProcess(checkoutSessionId, paymentIntentId);
+  } else if (analysis.anyMaxRetriesExceeded || analysis.shouldTimeout) {
+    // 有供应商超过重试次数或超时 → 决策是否部分退款
+    await handlePartialFailure(checkoutSessionId, paymentIntentId, vendorInfo, analysis);
+  } else {
+    // 还有供应商在处理中 → 等待下次发货完成通知
+    logger.info('Some vendors still in progress, waiting for completion');
+  }
+}
+
+function analyzeVendorStates(vendorInfo: VendorInfo[], vendorConfigs: any[]) {
+  const successfulVendors = vendorInfo.filter(vendor => vendor.status === 'completed');
+  const failedVendors = vendorInfo.filter(vendor => vendor.status === 'failed');
+  const maxRetriesExceededVendors = vendorInfo.filter(vendor => vendor.status === 'max_retries_exceeded');
+  const pendingVendors = vendorInfo.filter(vendor => vendor.status === 'pending');
+
+  const allCompleted = successfulVendors.length === vendorConfigs.length;
+  const anyMaxRetriesExceeded = maxRetriesExceededVendors.length > 0;
+  
+  // 检查超时（包括长时间pending状态）
+  const now = Date.now();
+  const shouldTimeout = vendorInfo.some(vendor => {
+    if (!vendor.lastAttemptAt) return false;
+    const timeSinceLastAttempt = now - new Date(vendor.lastAttemptAt).getTime();
+    
+    // 对于pending状态，如果超过超时时间，也认为是超时
+    if (vendor.status === 'pending' && timeSinceLastAttempt > MAX_FULFILLMENT_TIMEOUT) {
+      return true;
+    }
+    
+    return timeSinceLastAttempt > MAX_FULFILLMENT_TIMEOUT;
+  });
+
+  return {
+    allCompleted,
+    anyMaxRetriesExceeded,
+    shouldTimeout,
+    successfulVendors,
+    failedVendors,
+    maxRetriesExceededVendors,
+    pendingVendors,
+    totalVendors: vendorConfigs.length,
+  };
+}
+```
+
+### 6. 失败处理
+
+```typescript
+// 协调器决策逻辑
+if (analysis.allCompleted) {
+  // 所有供应商发货成功 → 触发分成
+  await triggerCommissionProcess(checkoutSessionId, paymentIntentId);
+} else if (analysis.anyMaxRetriesExceeded || analysis.shouldTimeout || analysis.failedVendors.length > 0) {
+  // 有任何供应商失败、超过重试次数或超时 → 对已成功的供应商发起退货请求，再退款
+  await initiateFullRefund(checkoutSessionId, paymentIntentId, 'vendor_failure_detected');
+} else {
+  // 还有供应商在处理中 → 等待下次发货完成通知
+  logger.info('Some vendors still in progress, waiting for completion');
+}
+```
+
+## 🔧 技术实现细节
+
+### 1. 竞态条件解决方案
+
+**问题**: 多个供应商同时更新 `vendor_info` 字段导致数据覆盖
+
+**解决方案**: 数据库事务 + 行锁
+
+```typescript
+async function updateSingleVendorInfo(
+  checkoutSessionId: string,
+  vendorId: string,
+  update: Partial<VendorInfo>
+): Promise<void> {
+  const lockKey = `vendor-info-${checkoutSessionId}`;
+  const lock = await getLock(lockKey); // 应用层锁
+
+  try {
+    // 使用数据库事务确保原子性操作
+    await sequelize.transaction(async (transaction: any) => {
+      // 在事务中读取最新数据，加行锁
+      const checkoutSession = await CheckoutSession.findByPk(checkoutSessionId, {
+        transaction,
+        lock: transaction.LOCK.UPDATE, // 数据库行锁
+      });
+
+      if (!checkoutSession) {
+        throw new Error(`CheckoutSession not found: ${checkoutSessionId}`);
+      }
+
+      const current = (checkoutSession.vendor_info as VendorInfo[]) || [];
+      const index = current.findIndex((vendor) => vendor.vendor_id === vendorId);
+
+      // 更新数据
+      if (index >= 0) {
+        current[index] = { ...current[index], ...update };
+      } else {
+        current.push({ vendor_id: vendorId, ...update });
+      }
+
+      // 在同一事务中更新
+      await CheckoutSession.update(
+        { vendor_info: current },
+        { where: { id: checkoutSessionId }, transaction }
+      );
+    });
+  } finally {
+    lock.release(); // 释放应用层锁
+  }
+}
+```
+
+### 2. 事件驱动架构
+
+**优势**:
+
+- **解耦**: 各组件独立，易于维护
+- **扩展性**: 容易添加新的供应商适配器
+- **可观测性**: 每个步骤都有明确的事件和日志
+
+**事件流**:
+
+```
+payment_intent.succeeded → vendor.commission.queued → vendor.fulfillment.queued → vendor.fulfillment.completed → fulfillment.coordination.triggered → commission.processing.started
+```
+
+### 3. 队列系统设计
+
+**特性**:
+
+- **持久化**: 作业存储在数据库中，重启不丢失
+- **重试机制**: 自动重试失败的作业，最多3次
+- **并发控制**: 多个供应商并行处理
+- **优雅降级**: 单个供应商失败不影响其他供应商
+
+**队列配置**:
+
+```typescript
+const vendorFulfillmentQueue = createQueue({
+  name: 'vendor-fulfillment',
+  onJob: handleVendorFulfillment,
+  maxRetries: 3,
+  retryDelay: 5000, // 5秒延迟重试
+});
+```
+
+### 4. 供应商适配器接口
+
+**统一接口设计**:
+
+```typescript
+interface VendorAdapter {
+  fulfillOrder(params: FulfillOrderParams): Promise<FulfillOrderResult>;
+  requestReturn(params: ReturnRequestParams): Promise<ReturnRequestResult>; // 🆕 退货请求接口
+}
+
+interface FulfillOrderParams {
+  productCode: string;
+  customerId: string;
+  amount: string;
+  currency: string;
+  metadata?: Record<string, any>;
+}
+
+interface FulfillOrderResult {
+  orderId: string;
+  status: 'completed' | 'pending' | 'failed';
+  serviceUrl?: string;
+  estimatedTime?: number;
+  message?: string;
+  progress?: number;
+  installationInfo?: InstallationInfo;
+}
+
+// 🆕 退货请求相关接口
+interface ReturnRequestParams {
+  orderId: string;              // 原订单ID
+  vendorOrderId?: string;       // 供应商内部订单ID
+  reason: string;               // 退货原因
+  paymentIntentId: string;      // 支付意图ID
+  customParams?: Record<string, any>; // 自定义参数
+}
+
+interface ReturnRequestResult {
+  orderId: string;
+  status: 'requested' | 'accepted' | 'rejected' | 'failed';
+  message: string;
+  expectedProcessingTime?: number;      // 预期处理时间(秒)
+  returnDetails?: {
+    instructions: string;       // 退货说明
+    contactInfo?: string;       // 联系方式
+    deadline?: string;          // 退货截止时间
+  };
+}
+```
+
+**具体实现示例**:
+
+```typescript
+// LauncherAdapter - 模拟应用部署
+export class LauncherAdapter implements VendorAdapter {
+  async fulfillOrder(params: FulfillOrderParams): Promise<FulfillOrderResult> {
+    const appId = generateAppId();
+    const serviceUrl = `https://${appId}.slp.abtnet.io/.well-known/service/admin/overview`;
+    
+    return {
+      orderId: `launcher_order_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+      status: 'completed', // 立即完成（测试模式）
+      serviceUrl,
+      estimatedTime: 0,
+      message: 'Launcher application installation completed successfully',
+      progress: 100,
+      installationInfo: {
+        appId,
+        appUrl: `https://${appId}.slp.abtnet.io`,
+        adminUrl: serviceUrl,
+        status: 'completed',
+        estimatedCompletionTime: new Date().toISOString(),
+      },
+    };
+  }
+}
+
+// DIDNamesAdapter - 模拟域名注册
+export class DIDNamesAdapter implements VendorAdapter {
+  async fulfillOrder(params: FulfillOrderParams): Promise<FulfillOrderResult> {
+    return {
+      orderId: `didnames_order_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+      status: 'completed',
+      serviceUrl: 'https://bbqaxpyvvmw7prkuecfwoavocixwuithkshfnjd4gai.did.abtnet.io',
+      estimatedTime: 0,
+      message: 'DID Names service activated successfully',
+      progress: 100,
+    };
+  }
+  
+  // 🆕 退货请求实现
+  async requestReturn(params: ReturnRequestParams): Promise<ReturnRequestResult> {
+    // 发起退货请求
+    return {
+      orderId: params.orderId,
+      status: 'requested',
+      message: 'Return request submitted for Launcher application',
+      expectedProcessingTime: 1800, // 30分钟处理时间
+      returnDetails: {
+        instructions: 'Application will be automatically destroyed within 30 minutes',
+        contactInfo: 'support@launcher.example.com',
+        deadline: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // 24小时
+      },
+    };
+  }
+}
+
+// DIDNamesAdapter - 模拟域名注册
+export class DIDNamesAdapter implements VendorAdapter {
+  async fulfillOrder(params: FulfillOrderParams): Promise<FulfillOrderResult> {
+    return {
+      orderId: `didnames_order_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+      status: 'completed',
+      serviceUrl: 'https://bbqaxpyvvmw7prkuecfwoavocixwuithkshfnjd4gai.did.abtnet.io',
+      estimatedTime: 0,
+      message: 'DID Names service activated successfully',
+      progress: 100,
+    };
+  }
+  
+  // 🆕 退货请求实现
+  async requestReturn(params: ReturnRequestParams): Promise<ReturnRequestResult> {
+    // 发起退货请求
+    return {
+      orderId: params.orderId,
+      status: 'requested',
+      message: 'Return request submitted for DID Names service',
+      expectedProcessingTime: 600, // 10分钟处理时间
+      returnDetails: {
+        instructions: 'Domain service will be deactivated and domain released to available pool',
+        contactInfo: 'support@didnames.example.com',
+        deadline: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(), // 7天
+      },
+    };
+  }
+}
+```
+
+## 🔍 监控和调试
+
+### 📊 **状态追踪流程**
+
+```
+🔍 日志追踪点:
+
+1️⃣ 发货启动
+   └─ 'Starting vendor fulfillment process' 
+   └─ { checkoutSessionId, vendorCount }
+
+2️⃣ 供应商状态更新 (关键！)
+   ├─ '🔧 updateSingleVendorInfo - Before update'
+   ├─ '🔧 updateSingleVendorInfo - Current vendor info (in transaction)'
+   ├─ '🔧 updateSingleVendorInfo - Database update completed'
+   └─ '🔧 updateSingleVendorInfo - Lock released'
+
+3️⃣ 协调器决策
+   ├─ 'Vendor fulfillment analysis' { analysis }
+   ├─ 'All vendors completed successfully' ✅
+   ├─ 'Some vendors failed, initiating full refund' ❌
+   └─ 'Some vendors still in progress' ⏳
+
+4️⃣ 错误处理
+   └─ 'Vendor fulfillment failed' { vendorId, error, attempts }
+
+5️⃣ 退货请求流程 (🆕)
+   ├─ '🔄 Starting return request process'
+   ├─ '📤 Requesting return for vendor' { vendorId, orderId }
+   ├─ '✅ Return request submitted successfully'
+   ├─ '❌ Return request failed'
+   └─ '🏁 Return request process completed'
+```
+
+### 日志策略
+
+**调试日志关键点**:
+
+```typescript
+// 1. 发货启动
+logger.info('Starting vendor fulfillment process', { checkoutSessionId, vendorCount });
+
+// 2. 供应商状态更新
+logger.info('🔧 updateSingleVendorInfo - Before update', { checkoutSessionId, vendorId, update });
+logger.info('🔧 updateSingleVendorInfo - Current vendor info (in transaction)', { vendorIndex, currentVendorStatus });
+logger.info('🔧 updateSingleVendorInfo - Database update completed (in transaction)', { updateStatus });
+
+// 3. 协调器决策
+logger.info('Vendor fulfillment analysis', { checkoutSessionId, analysis });
+logger.info('All vendors completed successfully, triggering commission', { successfulVendors });
+
+// 4. 错误处理
+logger.error('Vendor fulfillment failed', { vendorId, error: error.message, attempts });
+
+// 5. 退货请求流程 (🆕)
+logger.info('🔄 Starting return request process', { checkoutSessionId, paymentIntentId, reason });
+logger.info('📤 Requesting return for vendor', { vendorId, orderId, reason });
+logger.info('✅ Return request submitted successfully', { vendorId, returnStatus, expectedTime });
+logger.error('❌ Return request failed', { vendorId, orderId, error });
+logger.info('🏁 Return request process completed', { totalVendors, successful, failed });
+```
+
+**关键指标监控**:
+
+- 供应商发货成功率
+- 平均发货时间
+- 重试次数分布
+- 超时发生频率
+- 竞态条件检测
+- 🆕 **退货请求相关指标**:
+  - 退货请求触发频率
+  - 各供应商退货请求成功率
+  - 退货请求响应时间
+  - 退货请求失败原因分析
+
+## 🔄 **退货请求系统**
+
+### 🎯 **退货机制概述**
+
+当多供应商发货过程中出现失败时，系统需要对已经成功发货的供应商**发起退货请求**，通知供应商处理退货事宜，然后直接进行全额退款。
+
+#### **退货请求触发条件**
+
+- ✅ 任何供应商发货失败
+- ✅ 任何供应商发货超时 (5分钟)  
+- ✅ 任何供应商超过最大重试次数 (3次)
+
+#### **退货流程设计**
+
+```
+❌ 失败检测
+   ↓
+🔍 筛选已成功发货的供应商 (status: 'completed')
+   ↓
+📤 并行发送退货请求
+   ├─ 📦 Launcher: 通知退货，提供退货说明
+   ├─ 📦 DID Names: 通知退货，提供退货说明
+   └─ 📦 其他供应商: 发送退货请求
+       ↓
+📝 更新状态为 return_requested
+   ↓
+💰 立即执行全额退款给用户 (不等待供应商处理完成)
+```
+
+### 🏗️ **退货请求系统实现**
+
+#### **1. 退货请求协调器实现**
+
+```typescript
+// vendor-fulfillment-coordinator.ts
+async function initiateFullRefund(
+  checkoutSessionId: string, 
+  paymentIntentId: string, 
+  reason: string
+): Promise<void> {
+  logger.warn('Initiating full refund with return requests', {
+    checkoutSessionId, paymentIntentId, reason
+  });
+
+  try {
+    // 🔄 第一步：对已成功发货的供应商发起退货请求
+    await requestReturnsFromCompletedVendors(checkoutSessionId, paymentIntentId, reason);
+
+    // 💰 第二步：立即创建退款记录并执行退款（不等待退货处理完成）
+    const refund = await Refund.create({
+      type: 'refund',
+      amount: paymentIntent.amount,
+      description: `Full refund due to ${reason}`,
+      // ... 其他字段
+    });
+
+  } catch (error) {
+    logger.error('Failed to create full refund', { error: error.message });
+  }
+}
+
+async function requestReturnsFromCompletedVendors(
+  checkoutSessionId: string,
+  paymentIntentId: string,
+  reason: string
+): Promise<void> {
+  const checkoutSession = await CheckoutSession.findByPk(checkoutSessionId);
+  const vendorInfos = (checkoutSession.vendor_info as VendorInfo[]) || [];
+  
+  // 筛选已完成的供应商
+  const completedVendors = vendorInfos.filter(vendor => vendor.status === 'completed');
+
+  if (completedVendors.length === 0) {
+    logger.info('No completed vendors to request returns from', { checkoutSessionId });
+    return;
+  }
+
+  // 并行处理所有供应商的退货请求
+  const returnRequestPromises = completedVendors.map(vendor => 
+    requestReturnFromSingleVendor(checkoutSessionId, paymentIntentId, vendor, reason)
+  );
+
+  const returnResults = await Promise.allSettled(returnRequestPromises);
+  
+  // 记录退货请求结果
+  logger.info('🏁 Return request process completed', {
+    checkoutSessionId,
+    totalVendors: completedVendors.length,
+    successful: returnResults.filter(r => r.status === 'fulfilled').length,
+    failed: returnResults.filter(r => r.status === 'rejected').length,
+  });
+}
+
+async function requestReturnFromSingleVendor(
+  checkoutSessionId: string,
+  paymentIntentId: string,
+  vendor: VendorInfo,
+  reason: string
+): Promise<void> {
+  try {
+    // 1. 获取供应商适配器
+    const vendorAdapter = VendorFulfillmentService.getVendorAdapter(vendor.vendor_key);
+
+    // 2. 调用供应商的退货请求方法
+    const returnResult = await vendorAdapter.requestReturn({
+      orderId: vendor.order_id,
+      reason: `Return request due to: ${reason}`,
+      paymentIntentId,
+      customParams: {
+        returnType: 'order_failure',
+        originalAmount: vendor.amount,
+      },
+    });
+
+    // 3. 更新为退货请求状态
+    await updateSingleVendorInfo(checkoutSessionId, vendor.vendor_id, {
+      status: 'return_requested',
+      returnRequest: {
+        reason,
+        requestedAt: new Date().toISOString(),
+        status: returnResult.status === 'requested' ? 'pending' : returnResult.status,
+        returnDetails: returnResult.returnDetails?.instructions || returnResult.message,
+      },
+    });
+
+    logger.info('✅ Return request submitted successfully', {
+      vendorId: vendor.vendor_id,
+      returnStatus: returnResult.status,
+      expectedTime: returnResult.expectedProcessingTime,
+    });
+  } catch (error) {
+    logger.error('❌ Return request failed', {
+      vendorId: vendor.vendor_id,
+      error: error.message,
+    });
+
+    // 更新状态为退货请求失败，但继续退款流程
+    await updateSingleVendorInfo(checkoutSessionId, vendor.vendor_id, {
+      status: 'return_requested', // 标记为已请求退货（即使请求失败）
+      error_message: `Return request failed: ${error.message}`,
+    });
+
+    // 不重新抛出错误，退货请求失败不影响用户退款
+  }
+}
+```
+
+#### **2. 供应商适配器退货请求实现**
+
+```typescript
+// LauncherAdapter 退货请求实现
+export class LauncherAdapter implements VendorAdapter {
+  async requestReturn(params: ReturnRequestParams): Promise<ReturnRequestResult> {
+    logger.info('Requesting return for Launcher order', {
+      orderId: params.orderId,
+      reason: params.reason,
+    });
+
+    // 发起退货请求 - 这里只是通知，不立即执行销毁
+    return {
+      orderId: params.orderId,
+      status: 'requested',
+      message: 'Return request submitted for Launcher application',
+      expectedProcessingTime: 1800, // 30分钟处理时间
+      returnDetails: {
+        instructions: 'Application will be automatically destroyed within 30 minutes. You will receive confirmation email once completed.',
+        contactInfo: 'support@launcher.example.com',
+        deadline: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // 24小时内处理
+      },
+    };
+  }
+}
+
+// DIDNamesAdapter 退货请求实现
+export class DIDNamesAdapter implements VendorAdapter {
+  async requestReturn(params: ReturnRequestParams): Promise<ReturnRequestResult> {
+    logger.info('Requesting return for DID Names order', {
+      orderId: params.orderId,
+      reason: params.reason,
+    });
+
+    // 发起退货请求 - 通知供应商处理退货
+    return {
+      orderId: params.orderId,
+      status: 'requested',
+      message: 'Return request submitted for DID Names service',
+      expectedProcessingTime: 600, // 10分钟处理时间
+      returnDetails: {
+        instructions: 'Domain service will be deactivated and domain released to available pool within 10 minutes.',
+        contactInfo: 'support@didnames.example.com',
+        deadline: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(), // 7天内处理
+      },
+    };
+  }
+}
+```
+
+### 🔒 **退货请求系统特性**
+
+#### **简化设计**
+
+- **请求即忘**: 发起退货请求后立即进行用户退款，不等待供应商处理结果
+- **状态记录**: 在 `vendor_info` 中记录退货请求状态和详情
+- **容错优先**: 退货请求失败不影响用户退款流程
+
+#### **用户体验优先**
+
+- **快速退款**: 用户立即获得退款，无需等待供应商处理
+- **透明记录**: 系统记录所有退货请求的详细信息
+- **后台处理**: 供应商退货处理在后台异步进行
+
+#### **并发处理**
+
+- **并行请求**: 同时对多个供应商发起退货请求
+- **异步设计**: 退货请求不阻塞退款流程
+- **错误隔离**: 单个供应商退货请求失败不影响其他供应商
+
+### 📊 **退货请求监控指标**
+
+#### **关键指标**
+
+- **退货请求触发率**: `退货请求次数 / 总订单数`
+- **退货请求成功率**: `成功发起退货请求数 / 总退货请求数`
+- **平均请求响应时间**: 从触发到请求完成的时间
+- **供应商响应表现**: 各供应商的退货请求响应情况
+
+#### **告警策略**
+
+- 退货请求成功率低于 95% 时告警
+- 退货请求平均响应时间超过 10 秒时告警
+- 特定供应商退货请求连续失败 3 次时告警
+
+### 🎯 **业务价值**
+
+1. **用户体验优先**: 用户立即获得退款，无需等待供应商处理
+2. **简化流程**: 去除复杂的分布式事务逻辑，降低系统复杂度
+3. **风险隔离**: 供应商退货处理问题不影响用户权益
+4. **操作透明**: 完整记录退货请求过程，便于后续跟踪和审计