# PayPal订单生命周期和字段填充说明

## 订单状态流转

PayPal订单会经历以下状态：

1. **CREATED** - 订单已创建（初始状态）
2. **PAYER_ACTION_REQUIRED** - 需要付款人操作（跳转到PayPal登录页）
3. **APPROVED** - 订单已批准（用户在PayPal批准支付）
4. **COMPLETED** - 订单已完成（订单被捕获后）

## 字段填充时机

### 创建订单时（CREATED状态）

以下字段在创建订单时通常为 **null**，这是**正常现象**：

- `payer_email` - null（用户尚未登录PayPal）
- `payer_name` - null（用户尚未登录PayPal）
- `payer_id` - null（用户尚未登录PayPal）
- `payment_status` - null（尚未支付）
- `capture_id` - null（尚未捕获订单）

**原因**：创建订单时，用户还没有在PayPal登录和批准支付，所以PayPal不会返回这些信息。

### 用户批准订单后（APPROVED状态）

以下字段会被填充：

- `payer_email` - 用户PayPal邮箱
- `payer_name` - 用户PayPal姓名
- `payer_id` - 用户PayPal账户ID
- `payment_status` - 仍为null（尚未捕获）
- `capture_id` - 仍为null（尚未捕获）

**触发时机**：
- 用户点击"立即支付"后跳转到PayPal
- 用户在PayPal登录并批准支付
- 系统通过Webhook事件 `CHECKOUT.ORDER.APPROVED` 或查询订单详情获取

### 订单被捕获后（COMPLETED状态）

以下字段会被填充：

- `payment_status` - 支付状态（如：COMPLETED）
- `capture_id` - 支付捕获ID

**触发时机**：
- 调用 `/api/paypal/orders/{orderId}/capture` 接口捕获订单
- 系统通过Webhook事件 `PAYMENT.CAPTURE.COMPLETED` 获取

## 与沙箱测试的关系

**这些字段为null与沙箱测试环境无关**，这是PayPal订单的正常生命周期：

- 在**生产环境**中，如果订单状态为CREATED，这些字段同样为null
- 只有在用户完成PayPal登录、批准支付、订单被捕获后，这些字段才会被填充
- 沙箱环境和生产环境的行为是一致的

## 如何查看完整信息

1. **查看 `order_data` 字段**：该字段存储了PayPal返回的完整JSON响应，包含所有信息
2. **查询订单详情**：调用 `/api/paypal/orders/{orderId}` 接口，系统会自动更新订单信息
3. **等待Webhook事件**：PayPal会发送Webhook事件，系统会自动更新订单信息

## 代码更新逻辑

系统会在以下时机自动更新订单信息：

1. **创建订单时**：调用 `createPaymentOrder` 方法
2. **查询订单时**：调用 `getOrder` 接口，自动调用 `updateOrderFromPayPal` 方法
3. **捕获订单时**：调用 `captureOrder` 接口，自动调用 `updateOrderFromPayPal` 方法
4. **Webhook事件**：处理Webhook事件时，自动调用 `updateOrderFromPayPal` 方法

## 建议

如果需要在订单创建后立即获取payer信息，可以：

1. 在用户从PayPal返回后，调用 `getOrder` 接口查询订单详情
2. 配置Webhook监听 `CHECKOUT.ORDER.APPROVED` 事件
3. 在订单确认页面加载时，主动查询一次PayPal订单详情