monisuo/check_cold_wallet.md

# 充值功能检查报告

## 🔍 问题诊断

### ❌ 核心问题：缺少 `cold_wallet` 表

**数据库初始化脚本 `sql/init.sql` 中没有创建 `cold_wallet` 表**

#### 影响：
1. **后端报错**: `ColdWalletService.getDefaultWallet()` 返回 `null`
2. **接口失败**: 充值接口返回 "系统暂未配置充值地址"
3. **前端异常**: 用户无法看到充值钱包地址

---

## ✅ 已修复内容

### 1. 更新数据库初始化脚本

**文件**: `sql/init.sql`

**新增内容**:
```sql
-- 11. 冷钱包地址表
CREATE TABLE `cold_wallet` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `name` varchar(50) NOT NULL COMMENT '钱包名称',
  `address` varchar(255) NOT NULL COMMENT '钱包地址',
  `network` varchar(20) NOT NULL DEFAULT 'TRC20' COMMENT '网络类型',
  `is_default` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否默认',
  `status` tinyint(1) NOT NULL DEFAULT '1' COMMENT '状态',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 插入默认测试钱包
INSERT INTO `cold_wallet` VALUES
('USDT-TRC20 主钱包', 'TRX1234567890abcdefghijklmnopqrstuvwxyz1234', 'TRC20', 1, 1);
```

### 2. 创建补丁脚本

**文件**: `sql/patch_cold_wallet.sql`

用于已有数据库的增量更新。

### 3. 补充 order_fund 表字段

**新增字段**:
- `wallet_id` - 关联冷钱包ID
- `wallet_address` - 钱包地址（冗余）
- `withdraw_contact` - 提现联系方式
- `pay_time` - 用户打款时间
- `confirm_time` - 确认/审批时间

---

## 📋 执行步骤

### 方式一：全新安装

```bash
# 1. 创建数据库
mysql -u root -p -e "CREATE DATABASE monisuo DEFAULT CHARSET utf8mb4;"

# 2. 执行初始化脚本（已包含 cold_wallet 表）
mysql -u root -p monisuo < sql/init.sql
```

### 方式二：已有数据库（推荐）

```bash
# 执行补丁脚本
mysql -u monisuo -p monisuo < sql/patch_cold_wallet.sql
```

### 方式三：手动执行 SQL

```sql
-- 连接数据库
mysql -u monisuo -p monisuo

-- 执行以下 SQL（从 sql/patch_cold_wallet.sql 复制）
CREATE TABLE `cold_wallet` (...);
INSERT INTO `cold_wallet` VALUES (...);
ALTER TABLE `order_fund` ADD COLUMN ...;
```

---

## 🧪 测试验证

### 1. 数据库验证

```sql
-- 检查表是否创建成功
SHOW TABLES LIKE 'cold_wallet';

-- 检查默认钱包数据
SELECT * FROM cold_wallet WHERE is_default = 1;

-- 检查 order_fund 表结构
DESC order_fund;
```

### 2. 接口测试

```bash
# 运行测试脚本
./test_deposit_api.sh
```

### 3. 前端测试

1. 启动后端服务
2. 登录前端应用
3. 进入"资产"页面
4. 点击"充值"按钮
5. 输入充值金额
6. 检查是否显示钱包地址

---

## 🎯 充值流程说明

### 用户端流程

```
1. 用户申请充值
   POST /api/fund/deposit
   参数: { amount: "100", remark: "充值" }
   
2. 系统返回充值信息
   返回: {
     orderNo: "FD20260323...",
     walletAddress: "TRX123...",
     walletNetwork: "TRC20",
     amount: "100"
   }
   
3. 用户线下打款到指定地址

4. 用户确认已打款
   POST /api/fund/confirmPay
   参数: { orderNo: "FD20260323..." }
   
5. 等待管理员审批
   订单状态: 待确认 (status=2)
```

### 管理员审批流程

```
1. 查看待审批订单
   GET /admin/fund/orders?status=2

2. 审批通过/驳回
   POST /admin/fund/approve
   参数: {
     orderNo: "FD20260323...",
     status: 2,  // 2=通过, 3=驳回
     rejectReason: "驳回原因",
     adminRemark: "管理员备注"
   }
   
3. 审批通过后自动入账
   - 用户余额增加
   - 记录资金流水
```

---

## 📊 订单状态流转

### 充值订单

```
申请充值 → 待付款(1) → 用户确认打款 → 待确认(2) → 管理员审批
                                                    ↓
                                            已完成(3) / 已驳回(4)
                                                    
用户可随时取消 → 已取消(5)
```

### 提现订单

```
申请提现 → 待审批(1) → 管理员审批 → 已完成(2) / 已驳回(3)
                              ↓
                      驳回后自动解冻余额
                      
用户可随时取消 → 已取消(4)
```

---

## ⚠️ 注意事项

1. **冷钱包必须配置**: 至少要有一个 `is_default=1, status=1` 的钱包地址
2. **权限验证**: 所有充值接口需要用户登录（Token 验证）
3. **金额验证**: 充值金额必须大于 0
4. **事务安全**: 所有资金操作使用事务（@Transactional）
5. **数据冗余**: order_fund 表中冗余了 wallet_address，避免关联查询

---

## 🚀 下一步建议

1. ✅ **立即执行**: 运行 `sql/patch_cold_wallet.sql` 补丁
2. ✅ **重启后端**: 确保新表结构生效
3. ✅ **运行测试**: 执行 `./test_deposit_api.sh` 验证
4. ✅ **前端测试**: 在资产页面测试充值功能

---

**生成时间**: 2026-03-23 18:10
**修复状态**: ✅ 代码已修复，等待数据库补丁执行