# order_db 注单库

## 数据库定位

order_db 保存下注订单、局号、状态机、回调状态和超时补偿记录。它是业务订单事实源，但不是资金事实源，资金事实以 wallet_ledger 为准。

## 核心表

### bet_orders 注单表

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| bet_order_id | varchar(128) | 注单号，唯一 |
| merchant_id | bigint | 商户 ID |
| player_id | bigint | 玩家 ID |
| game_code | varchar(64) | 游戏编码 |
| round_id | varchar(128) | 局号 |
| client_request_id | varchar(128) | 客户端请求号 |
| bet_amount | numeric(28, 8) | 下注金额 |
| win_amount | numeric(28, 8) | 派彩金额 |
| status | varchar(32) | 状态机状态 |
| display_status | varchar(32) | 前端展示状态 |
| config_version | varchar(64) | 游戏配置版本 |
| result_hash | varchar(128) | 结果哈希 |
| created_at | timestamptz | 创建时间 |
| updated_at | timestamptz | 更新时间 |

### order_timeout_tasks 超时任务表

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| task_id | bigint | 任务 ID |
| bet_order_id | varchar(128) | 注单号 |
| task_type | varchar(32) | DEBIT_TIMEOUT、SETTLE_TIMEOUT、CALLBACK_TIMEOUT |
| next_retry_at | timestamptz | 下次重试时间 |
| retry_count | int | 重试次数 |
| status | varchar(32) | PENDING、DONE、MANUAL |

## 超时原则

- 玩家超时但 Go 扣款成功时，订单进入 `DEBIT_SUCCESS` 或 `SETTLE_PENDING`，前端可显示处理中。
- 不允许因为客户端超时直接退款，必须由补偿任务根据账本和订单状态判断。
- 回调失败不影响资金事实，只影响商户通知状态。

## 示例 SQL

```sql
create unique index uk_bet_orders_id on bet_orders(bet_order_id);
create unique index uk_bet_orders_idem on bet_orders(merchant_id, client_request_id);
create index idx_timeout_tasks_next on order_timeout_tasks(status, next_retry_at);
```