monisuo/DATABASE_SCHEMA.md

# 数据库表结构说明

## 📊 表关系图

```
sys_user (用户表)
    │
    ├─── account_fund (资金账户表) - 1:1
    │       │
    │       └─── account_flow (资金流水表) - 1:N
    │
    └─── account_trade (交易账户表) - 1:N
            │
            └─── order_trade (交易订单表) - 1:N

order_fund (充提订单表)
    │
    └─── account_flow (资金流水表)
```

---

## 1. 用户表 (sys_user)

**用途**: 存储用户基本信息

| 字段名 | 类型 | 说明 | 备注 |
|--------|------|------|------|
| id | bigint(20) | 主键ID | 自增 |
| username | varchar(50) | 账号 | 唯一 |
| password | varchar(100) | 密码 | BCrypt加密 |
| nickname | varchar(50) | 昵称 | |
| avatar | varchar(255) | 头像URL | |
| phone | varchar(20) | 手机号 | |
| email | varchar(100) | 邮箱 | |
| kyc_status | tinyint(1) | KYC状态 | 0-未激活, 1-已激活 |
| id_card_front | varchar(255) | 身份证正面照URL | |
| id_card_back | varchar(255) | 身份证反面照URL | |
| status | tinyint(1) | 状态 | 0-禁用, 1-正常 |
| last_login_time | datetime | 最后登录时间 | |
| last_login_ip | varchar(50) | 最后登录IP | |
| token | varchar(500) | 当前Token | |
| create_time | datetime | 创建时间 | |
| update_time | datetime | 更新时间 | |

**索引**:
- PRIMARY KEY (id)
- UNIQUE KEY uk_username (username)

---

## 2. 资金账户表 (account_fund) ⭐ 充值目标

**用途**: 存储用户资金账户信息（USDT）

| 字段名 | 类型 | 说明 | 备注 |
|--------|------|------|------|
| id | bigint(20) | 主键ID | 自增 |
| user_id | bigint(20) | 用户ID | 唯一，关联sys_user.id |
| **balance** | decimal(20,8) | **USDT余额** | **⭐ 充值审批通过后增加** |
| frozen | decimal(20,8) | 冻结金额 | 提现申请时冻结 |
| **total_deposit** | decimal(20,8) | **累计充值** | **⭐ 充值审批通过后增加** |
| total_withdraw | decimal(20,8) | 累计提现 | 提现成功后增加 |
| create_time | datetime | 创建时间 | |
| update_time | datetime | 更新时间 | |

**索引**:
- PRIMARY KEY (id)
- UNIQUE KEY uk_user_id (user_id)

**关系**: 
- 每个用户有且仅有一个资金账户
- 1:1 关系（通过 user_id 唯一索引保证）

**充值审批逻辑**:
```java
// 充值审批通过时
balance = balance + 充值金额
total_deposit = total_deposit + 充值金额
update_time = NOW()
```

---

## 3. 交易账户表 (account_trade)

**用途**: 存储用户各币种持仓信息

| 字段名 | 类型 | 说明 | 备注 |
|--------|------|------|------|
| id | bigint(20) | 主键ID | 自增 |
| user_id | bigint(20) | 用户ID | 关联sys_user.id |
| coin_code | varchar(20) | 币种代码 | 如 BTC, ETH, USDT |
| quantity | decimal(20,8) | 持仓数量 | |
| frozen | decimal(20,8) | 冻结数量 | |
| avg_price | decimal(20,8) | 平均成本价 | |
| total_buy | decimal(20,8) | 累计买入数量 | |
| total_sell | decimal(20,8) | 累计卖出数量 | |
| create_time | datetime | 创建时间 | |
| update_time | datetime | 更新时间 | |

**索引**:
- PRIMARY KEY (id)
- UNIQUE KEY uk_user_coin (user_id, coin_code)

**关系**:
- 每个用户可以有多个交易账户（每个币种一个）
- 1:N 关系

---

## 4. 充提订单表 (order_fund)

**用途**: 存储充值和提现订单

| 字段名 | 类型 | 说明 | 备注 |
|--------|------|------|------|
| id | bigint(20) | 主键ID | 自增 |
| order_no | varchar(32) | 订单号 | 唯一，F+时间戳 |
| user_id | bigint(20) | 用户ID | 关联sys_user.id |
| username | varchar(50) | 用户账号 | 冗余字段 |
| type | tinyint(1) | 类型 | 1-充值, 2-提现 |
| amount | decimal(20,8) | 金额(USDT) | |
| wallet_id | bigint(20) | 钱包ID | 充值订单使用 |
| wallet_address | varchar(255) | 钱包地址 | 充值/提现地址 |
| withdraw_contact | varchar(100) | 提现联系方式 | |
| **status** | tinyint(1) | **状态** | **见状态说明** |
| pay_time | datetime | 用户打款时间 | |
| confirm_time | datetime | 确认/审批时间 | |
| approve_admin_id | bigint(20) | 审批管理员ID | |
| approve_admin_name | varchar(50) | 审批管理员名称 | |
| approve_time | datetime | 审批时间 | |
| reject_reason | varchar(255) | 驳回原因 | |
| remark | varchar(255) | 用户备注 | |
| admin_remark | varchar(255) | 管理员备注 | |
| create_time | datetime | 创建时间 | |
| update_time | datetime | 更新时间 | |

**订单状态说明**:

**充值订单**:
- 1 = 待付款（用户刚申请充值）
- 2 = 待确认（用户已确认打款，等待管理员审批）⭐ 可审批
- 3 = 已完成（管理员审批通过，余额已到账）
- 4 = 已驳回（管理员审批驳回）
- 5 = 已取消

**提现订单**:
- 1 = 待审批（用户申请提现，等待管理员审批）⭐ 可审批
- 2 = 已完成（管理员审批通过，已打款）
- 3 = 已驳回（管理员审批驳回，余额已退还）
- 4 = 已取消

**索引**:
- PRIMARY KEY (id)
- UNIQUE KEY uk_order_no (order_no)
- KEY idx_user_id (user_id)
- KEY idx_status (status)
- KEY idx_type (type)

---

## 5. 资金流水表 (account_flow)

**用途**: 记录资金账户的所有变动

| 字段名 | 类型 | 说明 | 备注 |
|--------|------|------|------|
| id | bigint(20) | 主键ID | 自增 |
| user_id | bigint(20) | 用户ID | |
| flow_no | varchar(32) | 流水号 | |
| flow_type | tinyint(1) | 流水类型 | 见类型说明 |
| amount | decimal(20,8) | 变动金额 | 正数=收入，负数=支出 |
| balance_before | decimal(20,8) | 变动前余额 | |
| balance_after | decimal(20,8) | 变动后余额 | |
| coin_code | varchar(20) | 相关币种 | 默认USDT |
| related_order_no | varchar(32) | 关联订单号 | |
| remark | varchar(255) | 备注 | |
| create_time | datetime | 创建时间 | |

**流水类型**:
- 1 = 充值
- 2 = 提现
- 3 = 划转转入（资金账户 -> 交易账户）
- 4 = 划转转出（交易账户 -> 资金账户）
- 5 = 买入
- 6 = 卖出

**充值审批流水记录**:
```java
flow_type = 1 (充值)
amount = +100.00 (正数)
balance_before = 0.00 (审批前余额)
balance_after = 100.00 (审批后余额)
coin_code = USDT
related_order_no = F20260324001 (充值订单号)
remark = "充值"
```

---

## 📋 充值完整流程示例

### 示例数据

**用户**: user1 (ID=1)

#### 1. 初始状态

**sys_user**:
```
id=1, username=user1, status=1
```

**account_fund** (资金账户):
```
id=1, user_id=1, balance=0.00, frozen=0.00, 
total_deposit=0.00, total_withdraw=0.00
```

**account_trade** (交易账户 - USDT):
```
id=1, user_id=1, coin_code=USDT, quantity=0.00
```

---

#### 2. 申请充值（100 USDT）

**order_fund** (新建订单):
```
id=1, order_no=F20260324001, user_id=1, type=1, 
amount=100.00, status=1 (待付款)
```

**account_fund**: 无变化

---

#### 3. 确认打款

**order_fund**:
```
status=2 (待确认), pay_time=2026-03-24 10:30:00
```

**account_fund**: 无变化

---

#### 4. 管理员审批通过 ⭐ 关键步骤

**order_fund**:
```
status=3 (已完成), 
approve_admin_id=1, 
approve_admin_name='管理员',
approve_time=2026-03-24 11:00:00,
confirm_time=2026-03-24 11:00:00
```

**account_fund** (更新):
```sql
UPDATE account_fund 
SET balance = 0.00 + 100.00 = 100.00,      -- ⭐ 余额增加
    total_deposit = 0.00 + 100.00 = 100.00, -- ⭐ 累计充值增加
    update_time = '2026-03-24 11:00:00'
WHERE user_id = 1;
```

**account_flow** (新建流水):
```
id=1, user_id=1, flow_no=FL20260324001,
flow_type=1 (充值),
amount=100.00 (正数),
balance_before=0.00,
balance_after=100.00,
coin_code=USDT,
related_order_no=F20260324001,
remark='充值',
create_time=2026-03-24 11:00:00
```

---

#### 5. 最终状态

**account_fund**:
```
id=1, user_id=1, 
balance=100.00,           -- ⭐ 已增加
frozen=0.00,
total_deposit=100.00,     -- ⭐ 已增加
total_withdraw=0.00
```

---

## 🔍 关键SQL查询

### 查询用户资金账户
```sql
SELECT 
    u.id as user_id,
    u.username,
    af.balance,
    af.frozen,
    af.total_deposit,
    af.total_withdraw
FROM sys_user u
LEFT JOIN account_fund af ON u.id = af.user_id
WHERE u.id = [用户ID];
```

### 查询用户交易账户
```sql
SELECT 
    at.id,
    at.user_id,
    at.coin_code,
    at.quantity,
    at.frozen,
    at.avg_price,
    c.price as current_price,
    (at.quantity * c.price) as value_usdt
FROM account_trade at
LEFT JOIN coin c ON at.coin_code = c.code
WHERE at.user_id = [用户ID] AND at.quantity > 0;
```

### 查询充值订单及账户余额
```sql
SELECT 
    of.order_no,
    of.user_id,
    of.amount as order_amount,
    of.status as order_status,
    of.approve_time,
    af.balance as current_balance,
    af.total_deposit
FROM order_fund of
LEFT JOIN account_fund af ON of.user_id = af.user_id
WHERE of.order_no = '[订单号]';
```

---

## ⚠️ 重要说明

### 资金账户 vs 交易账户

1. **资金账户 (account_fund)**:
   - 每个用户只有1个
   - 存储USDT余额
   - 充值/提现操作
   - 划转操作的来源/目标

2. **交易账户 (account_trade)**:
   - 每个用户可以有多个（每个币种一个）
   - 存储各币种持仓
   - 买入/卖出操作
   - 划转操作的目标/来源

### 充值资金流向

```
充值审批通过
    ↓
资金账户.balance += 充值金额        (⭐ 必须更新)
资金账户.total_deposit += 充值金额  (⭐ 必须更新)
    ↓
创建资金流水记录
    ↓
用户可以:
1. 提现（从资金账户扣除）
2. 划转到交易账户（资金账户 -> 交易账户USDT）
3. 用USDT买入其他币种（交易账户USDT -> 交易账户BTC/ETH等）
```

---

**最后更新**: 2026-03-24 13:45
**数据库版本**: V1.0
**字符集**: utf8mb4
**引擎**: InnoDB