# 支付订单表设计说明

## 一、订单表设计原因

### 1.1 订单号设计（双重订单号）

**系统订单号 (`pay_order_id`)**
- **作用**：系统内部唯一标识，用于查询、对账、退款等操作
- **生成规则**：`P` + `YYYYMMDDHHmmss` + `6位随机数`（如：P20240101120000123456）
- **唯一性**：通过 `uk_pay_order_id` 唯一索引保证
- **优势**：
  - 全局唯一，不受商户影响
  - 便于系统内部查询和关联
  - 对账时作为主键

**商户订单号 (`mch_order_no`)**
- **作用**：商户传入的订单号，用于幂等性校验
- **唯一性**：通过 `uk_mch_order_no(merchant_id, mch_order_no)` 联合唯一索引保证
- **优势**：
  - 同一商户下订单号唯一，防止重复提交
  - 商户侧可以自定义订单号规则
  - 支持商户订单号查询订单

**为什么需要两个订单号？**
- 系统订单号：保证全局唯一，便于系统内部管理
- 商户订单号：保证商户侧唯一，防止重复支付（幂等性）

### 1.2 关联关系设计

**商户与应用关联 (`merchant_id` + `app_id`)**
- **作用**：标识订单所属商户和应用
- **用途**：
  - 权限控制（商户只能查询自己的订单）
  - 对账统计（按商户/应用维度）
  - 通知路由（根据应用配置的通知地址）

**支付通道关联 (`channel_id`)**
- **作用**：记录实际使用的支付通道
- **用途**：
  - 退款时找到对应的插件和配置
  - 对账时关联通道信息
  - 统计通道使用情况

**支付方式与产品 (`method_code` + `product_code`)**
- **method_code**：支付方式（alipay/wechat/unionpay）
  - 用于统计、筛选、报表
- **product_code**：支付产品（alipay_h5/alipay_life/wechat_jsapi等）
  - 由插件根据用户环境自动选择
  - 用于记录实际使用的支付产品

### 1.3 金额字段设计

**订单金额 (`amount`)**
- 商户实际收款金额（扣除手续费前）
- 用于退款金额校验、对账

**手续费 (`fee`)**
- 可选字段，记录通道手续费
- 用于对账、结算、利润统计
- 如果不需要详细记录手续费，可以留空或通过 `extra` 存储

**币种 (`currency`)**
- 默认 CNY，支持国际化扩展
- 预留字段，便于后续支持多币种

### 1.4 状态流转设计

```
PENDING（待支付）
  ├─> SUCCESS（支付成功）← 收到渠道回调并验签通过
  ├─> FAIL（支付失败）← 用户取消、超时、渠道返回失败
  └─> CLOSED（已关闭）← 全额退款后
```

**状态说明**：
- **PENDING**：订单创建后，等待用户支付
- **SUCCESS**：支付成功，已收到渠道回调并验签通过
- **FAIL**：支付失败（用户取消、订单超时、渠道返回失败等）
- **CLOSED**：已关闭（全额退款后）

### 1.5 渠道信息设计

**渠道订单号 (`channel_order_no`)**
- 渠道返回的订单号
- 用于查询订单状态、退款等操作

**渠道交易号 (`channel_trade_no`)**
- 部分渠道有交易号概念（如支付宝的 trade_no）
- 用于对账、查询等

### 1.6 通知机制设计

**通知状态 (`notify_status`)**
- 0：未通知
- 1：已通知成功

**通知次数 (`notify_count`)**
- 记录通知次数，用于重试控制
- 配合 `ma_notify_task` 表实现异步通知

### 1.7 扩展性设计

**扩展字段 (`extra`)**
- JSON 格式，存储：
  - 支付参数（`pay_params`）：前端支付所需的参数
  - 退款信息（`refund_info`）：退款结果
  - 自定义字段：业务扩展字段

**订单过期时间 (`expire_time`)**
- 用于自动关闭超时订单
- 默认 30 分钟，可配置

## 二、索引设计说明

### 2.1 唯一索引

- **`uk_pay_order_id`**：保证系统订单号唯一
- **`uk_mch_order_no(merchant_id, mch_order_no)`**：保证同一商户下商户订单号唯一（幂等性）

### 2.2 普通索引

- **`idx_merchant_app(merchant_id, app_id)`**：商户/应用维度查询
- **`idx_channel_id`**：通道维度查询
- **`idx_method_code`**：支付方式维度统计
- **`idx_status`**：状态筛选
- **`idx_pay_time`**：按支付时间查询（对账、统计）
- **`idx_created_at`**：按创建时间查询（分页、统计）

## 三、可能遗漏的字段（后续扩展）

### 3.1 退款相关字段

如果后续需要支持**部分退款**或**多次退款**，可以考虑添加：

```sql
`refund_amount` decimal(10,2) NOT NULL DEFAULT 0.00 COMMENT '已退款金额（累计）',
`refund_status` varchar(20) NOT NULL DEFAULT '' COMMENT '退款状态：PENDING-退款中, SUCCESS-退款成功, FAIL-退款失败',
`refund_time` datetime DEFAULT NULL COMMENT '最后退款时间',
```

**当前设计**：
- 退款信息存储在 `extra['refund_info']` 中
- 全额退款后订单状态改为 `CLOSED`
- 如果只需要全额退款，当前设计已足够

### 3.2 结算相关字段

如果后续需要**分账/结算**功能，可以考虑添加：

```sql
`settlement_status` varchar(20) NOT NULL DEFAULT '' COMMENT '结算状态：PENDING-待结算, SUCCESS-已结算, FAIL-结算失败',
`settlement_time` datetime DEFAULT NULL COMMENT '结算时间',
`settlement_amount` decimal(10,2) NOT NULL DEFAULT 0.00 COMMENT '结算金额',
```

**当前设计**：
- 结算信息可以通过 `extra` 存储
- 如果不需要复杂的结算流程，当前设计已足够

### 3.3 风控相关字段

如果需要**风控功能**，可以考虑添加：

```sql
`risk_level` varchar(20) NOT NULL DEFAULT '' COMMENT '风险等级：LOW-低, MEDIUM-中, HIGH-高',
`risk_score` int(11) NOT NULL DEFAULT 0 COMMENT '风险评分',
`risk_reason` varchar(255) NOT NULL DEFAULT '' COMMENT '风险原因',
```

**当前设计**：
- 风控信息可以通过 `extra` 存储
- 如果不需要复杂的风控系统，当前设计已足够

### 3.4 其他扩展字段

- **`user_id`**：用户ID（如果需要关联用户）
- **`device_info`**：设备信息（用于风控）
- **`remark`**：备注（管理员备注）
- **`close_reason`**：关闭原因（用户取消/超时/管理员关闭等）

## 四、设计原则总结

1. **幂等性**：通过 `uk_mch_order_no` 保证同一商户下订单号唯一
2. **可追溯性**：记录完整的订单信息、渠道信息、时间信息
3. **可扩展性**：通过 `extra` JSON 字段存储扩展信息
4. **性能优化**：合理的索引设计，支持常见查询场景
5. **业务完整性**：覆盖订单全生命周期（创建→支付→退款→关闭）

## 五、与代码的对应关系

| SQL 字段 | 代码字段 | 说明 |
|---------|---------|------|
| `pay_order_id` | `pay_order_id` | 系统订单号 |
| `merchant_id` | `merchant_id` | 商户ID |
| `app_id` | `app_id` | 应用ID |
| `mch_order_no` | `mch_order_no` | 商户订单号 |
| `method_code` | `method_code` | 支付方式 |
| `product_code` | `product_code` | 支付产品 |
| `channel_id` | `channel_id` | 通道ID |
| `amount` | `amount` | 订单金额 |
| `currency` | `currency` | 币种 |
| `status` | `status` | 订单状态 |
| `channel_order_no` | `channel_order_no` | 渠道订单号 |
| `channel_trade_no` | `channel_trade_no` | 渠道交易号 |
| `extra` | `extra` | 扩展字段（JSON） |

## 六、注意事项

1. **字段命名统一**：SQL 和代码中的字段名必须一致
2. **索引维护**：定期检查索引使用情况，优化慢查询
3. **数据归档**：历史订单数据量大时，考虑归档策略
4. **JSON 字段**：`extra` 字段使用 JSON 类型，便于扩展但查询性能略低
5. **时间字段**：`pay_time`、`expire_time` 等时间字段使用 `datetime` 类型，便于查询和统计