# 云印签支付流程完整性检查

## 一、支付创建流程

### 1. 前端流程 ✅
- **位置**: `jnc-webview/src/components/Payment.vue`
- **步骤**:
  1. 用户选择 `yunyinSignPay_wechat` 或 `yunyinSignPay_alipay`
  2. 调用 `/pay/payment` 接口
  3. 获取 `prepay_id` 或 `prepay_data`（支付链接）
  4. 直接跳转到支付链接：`window.location.href = prepayUrl`

### 2. 后端流程 ✅
- **位置**: `jnc-server/app/main/api/internal/logic/pay/paymentlogic.go`
- **步骤**:
  1. 接收支付请求
  2. 从查询缓存获取用户姓名和手机号
  3. **查询是否有未完成的签署**（复用逻辑）
  4. 如果有未完成签署：
     - 复用 `task_id` 和 `participant_id`
     - 获取新的支付链接
  5. 如果没有未完成签署：
     - 获取 token 和操作ID（带缓存）
     - 发起签署流程
     - 获取支付链接
  6. 创建订单记录（`order` 表）
  7. 创建云印签订单记录（`yunyin_sign_pay_order` 表）
  8. 返回支付链接（字符串类型，使用 `PrepayId` 字段）

### 3. 数据存储 ✅
- **订单表** (`order`):
  - `order_no`: 订单号
  - `payment_platform`: `yunyinSignPay_wechat` 或 `yunyinSignPay_alipay`
  - `status`: `pending`
  - **注意**: 不再在 `remark` 中存储云印签信息

- **云印签订单表** (`yunyin_sign_pay_order`):
  - `order_id`: 关联订单ID
  - `user_id`: 用户ID（用于查询未完成签署）
  - `task_id`: 任务ID/流程ID（唯一索引）
  - `participant_id`: 参与者ID
  - `source_order_code`: 源订单号（用于查询支付状态）
  - `amount`: 支付金额
  - `pay_type`: 支付类型（0=微信，1=支付宝）
  - `sign_status`: 签署状态（0=待签署）
  - `pay_status`: 支付状态（0=待支付）
  - `user_mobile`: 用户手机号（冗余字段）
  - `user_name`: 用户姓名（冗余字段）

## 二、支付状态查询流程

### 1. 前端轮询 ✅
- **位置**: `jnc-webview/src/views/PaymentResult.vue`
- **步骤**:
  1. 用户从支付页面返回后，进入支付结果页面
  2. 从 URL 参数获取 `order_no` 或 `out_trade_no`
  3. 首次调用 `/pay/check` 接口
  4. 如果状态是 `pending`，开始轮询（每3秒一次，最多30次）
  5. 如果状态变为 `paid` 或 `refunded`，停止轮询并跳转到结果页面

### 2. 后端主动查询 ✅
- **位置**: `jnc-server/app/main/api/internal/logic/pay/paymentchecklogic.go`
- **步骤**:
  1. 查询订单状态
  2. 如果订单状态是 `pending` 且支付平台是云印签：
     - 调用 `QueryPayeeBill` 查询云印签平台
     - 使用 `sourceOrderCode`（订单号）查询
  3. 根据云印签返回的 `payStatus` 更新订单状态：
     - `2` (支付成功) → `paid`
     - `3` (支付失败) → `failed`
     - `4` (已退款) → `refunded`
     - `0, 1` (订单生成/支付中) → 保持 `pending`
  4. 同步更新 `yunyin_sign_pay_order` 表的支付状态
  5. 如果支付成功，发送异步任务处理后续流程

### 3. 状态映射 ✅
- **云印签 payStatus**:
  - `0`: 订单生成
  - `1`: 支付中
  - `2`: 支付成功
  - `3`: 支付失败
  - `4`: 已退款

- **我们的订单状态**:
  - `pending`: 待支付
  - `paid`: 已支付
  - `failed`: 支付失败
  - `refunded`: 已退款

- **我们的支付状态** (`yunyin_sign_pay_order.pay_status`):
  - `0`: 待支付
  - `1`: 已支付
  - `2`: 已退款

## 三、前后端数据字段一致性 ✅

### 1. 支付创建接口 (`/pay/payment`)
- **请求字段**: `pay_method` (支持 `yunyinSignPay_wechat`, `yunyinSignPay_alipay`)
- **响应字段**:
  - `prepay_id`: 支付链接（字符串类型）
  - `prepay_data`: 备用字段（对象类型）
  - `order_no`: 订单号

- **前端读取**: `data.value.data.prepay_id || data.value.data.prepay_data` ✅

### 2. 支付状态查询接口 (`/pay/check`)
- **请求字段**: `order_no`
- **响应字段**:
  - `type`: `"query"`
  - `status`: `"pending"` | `"paid"` | `"failed"` | `"refunded"`

- **前端处理**: 根据 `status` 判断是否继续轮询 ✅

## 四、潜在问题和改进建议

### ⚠️ 问题1: 支付完成后用户可能不会自动跳转
**现状**: 云印签支付完成后，用户可能不会自动跳转回我们的页面
**解决方案**: 
- ✅ 已实现：前端通过轮询主动查询支付状态
- ✅ 已实现：用户手动返回后，支付结果页面会自动轮询

### ⚠️ 问题2: 订单状态更新需要检查并发
**现状**: 使用乐观锁更新订单状态，但需要确保不会重复更新
**检查**: ✅ 已实现：使用 `UpdateWithVersion` 和检查 `order.Status == "pending"`

### ⚠️ 问题3: 查询失败时的处理
**现状**: 如果查询云印签平台失败，会记录错误但继续返回当前状态
**检查**: ✅ 已实现：错误处理完善，不影响正常流程

### ⚠️ 问题4: 未找到收款单记录的处理
**现状**: 如果订单刚创建，云印签平台可能还没有记录
**检查**: ✅ 已实现：返回错误但不影响，继续返回 `pending` 状态，前端会继续轮询

## 五、完整流程验证

### 场景1: 首次支付（创建新签署流程）✅
1. 用户选择云印签支付
2. 后端查询无未完成签署
3. 创建新签署流程
4. 创建订单和云印签订单记录
5. 返回支付链接
6. 前端跳转到支付页面
7. 用户完成支付
8. 前端轮询查询状态
9. 后端主动查询云印签平台
10. 更新订单状态为 `paid`
11. 发送异步任务处理后续流程
12. 前端跳转到结果页面

### 场景2: 复用未完成签署 ✅
1. 用户之前创建了签署但未支付
2. 用户再次选择云印签支付
3. 后端查询到未完成签署
4. 复用 `task_id` 和 `participant_id`
5. 获取新的支付链接
6. 创建新订单和云印签订单记录（关联新的订单）
7. 返回支付链接
8. 后续流程同场景1

### 场景3: 支付失败 ✅
1. 用户支付失败
2. 前端轮询查询状态
3. 后端查询到 `payStatus = 3`
4. 更新订单状态为 `failed`
5. 前端显示支付失败提示

### 场景4: 退款 ✅
1. 订单已支付
2. 发生退款
3. 前端轮询查询状态
4. 后端查询到 `payStatus = 4`
5. 更新订单状态为 `refunded`
6. 更新退款时间
7. 前端显示退款状态

## 六、总结

### ✅ 已完成的流程
1. 支付创建流程（包括复用逻辑）
2. 支付状态主动查询
3. 订单状态自动更新
4. 云印签订单表数据同步
5. 前后端数据字段一致性
6. 错误处理和边界情况

### ✅ 代码质量
- 使用了事务保证数据一致性
- 使用了乐观锁避免并发问题
- 错误处理完善
- 日志记录详细

### ✅ 前后端联调
- API 接口定义清晰
- 数据字段命名一致
- 状态映射正确
- 轮询机制完善

## 七、建议测试点

1. **首次支付流程**: 验证创建新签署流程是否正常
2. **复用签署流程**: 验证复用逻辑是否正常工作
3. **支付成功**: 验证状态更新和后续流程是否正常
4. **支付失败**: 验证失败状态是否正确处理
5. **退款**: 验证退款状态是否正确处理
6. **网络异常**: 验证查询失败时的容错处理
7. **并发支付**: 验证同一用户多次支付的场景
8. **订单状态一致性**: 验证订单表和云印签订单表的状态是否同步