# Transfer 模块数据库设计文档

> 更新时间: 2025-06-19 03:43
> 模块: Transfer
> 表前缀: kku_transfer_
> 维护状态: 🔄 持续维护中

## 数据库概述

Transfer 模块使用2个主要数据表：
- `kku_transfer_apps`: 划转应用配置表
- `kku_transfer_orders`: 划转订单表

## 表结构设计

### 1. kku_transfer_apps - 划转应用配置表

存储外部应用的划转配置信息，包括API地址、汇率设置、账户映射等。

```sql
CREATE TABLE `kku_transfer_apps` (
  `id` int unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `keyname` varchar(50) NOT NULL COMMENT '应用标识符',
  `title` varchar(100) NOT NULL COMMENT '应用显示名称',
  `description` text COMMENT '应用描述信息',
  `out_id2` int DEFAULT NULL COMMENT '开放接口ID',
  `out_id3` int DEFAULT NULL COMMENT '三方平台ID',
  `currency_id` int NOT NULL COMMENT '货币类型ID',
  `fund_id` int NOT NULL COMMENT '资金账户类型ID',
  `fund_to_uid` int DEFAULT NULL COMMENT '转入目标账户UID',
  `fund_in_uid` int DEFAULT NULL COMMENT '转入来源账户UID',
  `exchange_rate` decimal(10,4) NOT NULL DEFAULT '1.0000' COMMENT '汇率(1个外部币能兑换多少内部币)',
  `order_callback_url` varchar(255) DEFAULT NULL COMMENT '结果通知API地址(为空则不通知)',
  `order_in_info_url` varchar(255) DEFAULT NULL COMMENT '转入查询API地址(为空则不查询)',
  `order_out_create_url` varchar(255) DEFAULT NULL COMMENT '转出创建API地址(为空则不创建)',
  `order_out_info_url` varchar(255) DEFAULT NULL COMMENT '转出查询API地址(为空则不查询)',
  `is_enabled` tinyint(1) NOT NULL DEFAULT '1' COMMENT '是否启用(1=启用,0=禁用)',
  `created_at` timestamp NULL DEFAULT NULL COMMENT '创建时间',
  `updated_at` timestamp NULL DEFAULT NULL COMMENT '更新时间',
  `deleted_at` timestamp NULL DEFAULT NULL COMMENT '删除时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_keyname` (`keyname`),
  KEY `idx_out_id` (`out_id`),
  KEY `idx_currency_id` (`currency_id`),
  KEY `idx_enabled` (`is_enabled`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='划转应用配置表';
```

#### 字段说明

| 字段名 | 类型 | 说明 | 示例值 |
|--------|------|------|--------|
| id | int unsigned | 主键ID | 1 |
| keyname | varchar(50) | 应用唯一标识符 | game_app_a |
| title | varchar(100) | 应用显示名称 | 游戏应用A |
| description | text | 应用描述信息 | 热门游戏应用 |
| out_id2 | int | 开放接口ID | 2001 |
| out_id3 | int | 三方平台ID | 3001 |
| currency_id | int | 货币类型(1=金币,2=钻石,3=人民币,4=美元) | 2 |
| fund_id | int | 资金账户类型ID | 2 |
| fund_to_uid | int | 转入目标账户UID | 15 |
| fund_in_uid | int | 转入来源账户UID | 16 |
| exchange_rate | decimal(10,4) | 汇率比例(1外部币=N内部币) | 1.0450 |
| fee_in_rate | decimal(5,4) | 转入手续费率 | 0.0050 |
| fee_out_rate | decimal(5,4) | 转出手续费率 | 0.0100 |
| fee_in_min | decimal(15,4) | 转入最低手续费 | 0.1000 |
| fee_in_max | decimal(15,4) | 转入最高手续费 | 10.0000 |
| fee_out_min | decimal(15,4) | 转出最低手续费 | 0.2000 |
| fee_out_max | decimal(15,4) | 转出最高手续费 | 20.0000 |
| fee_account_uid | int | 手续费收取账户UID | 1 |
| transfer_in_enabled | tinyint(1) | 是否允许转入 | 1 |
| transfer_out_enabled | tinyint(1) | 是否允许转出 | 1 |
| order_callback_url | varchar(255) | 结果通知API地址(为空则不通知) | https://api.game.com/callback |
| order_in_info_url | varchar(255) | 转入查询API地址(为空则不查询) | https://api.game.com/order/info |
| order_out_create_url | varchar(255) | 转出创建API地址(为空则不创建) | https://api.game.com/order/create |
| order_out_info_url | varchar(255) | 转出查询API地址(为空则不查询) | https://api.game.com/order/status |
| is_enabled | tinyint(1) | 是否启用 | 1 |

#### 索引说明
- `PRIMARY`: 主键索引
- `uk_keyname`: 应用标识符唯一索引
- `idx_out_id2`: 开放接口ID索引
- `idx_currency_id`: 货币类型索引
- `idx_enabled`: 启用状态索引

#### 业务逻辑说明
**外部API地址配置规则:**
- 当外部API地址字段为空(NULL)时，系统将只在农场内部运转逻辑，不进行外部通信
- `order_callback_url` 为空：不发送结果通知，订单完成后仅更新内部状态
- `order_in_info_url` 为空：不查询外部转入状态，仅依赖内部逻辑判断
- `order_out_create_url` 为空：不调用外部创建接口，仅进行内部资金操作
- `order_out_info_url` 为空：不查询外部转出状态，仅依赖内部逻辑判断

**应用ID字段说明:**
- `out_id2`: 开放接口ID，用于开放API对接
- `out_id3`: 三方平台ID，用于第三方平台集成

### 2. kku_transfer_orders - 划转订单表

存储具体的划转订单信息，包括订单状态、金额、处理时间等。

```sql
CREATE TABLE `kku_transfer_orders` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `transfer_app_id` int unsigned NOT NULL COMMENT '划转应用ID',
  `out_id` int NOT NULL COMMENT '外部应用ID',
  `out_order_id` varchar(100) NOT NULL COMMENT '外部订单ID',
  `out_user_id` varchar(50) DEFAULT NULL COMMENT '外部用户ID',
  `user_id` int unsigned NOT NULL COMMENT '内部用户ID',
  `currency_id` int NOT NULL COMMENT '货币类型ID',
  `fund_id` int NOT NULL COMMENT '资金账户类型ID',
  `type` tinyint NOT NULL COMMENT '订单类型(1=转入,2=转出)',
  `status` tinyint NOT NULL DEFAULT '1' COMMENT '订单状态',
  `out_amount` decimal(30,10) NOT NULL COMMENT '外部金额',
  `amount` decimal(30,10) NOT NULL COMMENT '内部金额',
  `exchange_rate` decimal(10,4) NOT NULL COMMENT '使用汇率(1外部币=N内部币)',
  `callback_data` json DEFAULT NULL COMMENT '回调数据',
  `error_message` text COMMENT '错误信息',
  `remark` varchar(255) DEFAULT NULL COMMENT '备注信息',
  `processed_at` timestamp NULL DEFAULT NULL COMMENT '处理时间',
  `callback_at` timestamp NULL DEFAULT NULL COMMENT '回调时间',
  `completed_at` timestamp NULL DEFAULT NULL COMMENT '完成时间',
  `created_at` timestamp NULL DEFAULT NULL COMMENT '创建时间',
  `updated_at` timestamp NULL DEFAULT NULL COMMENT '更新时间',
  `deleted_at` timestamp NULL DEFAULT NULL COMMENT '删除时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_out_order` (`out_id`, `out_order_id`),
  KEY `idx_transfer_app_id` (`transfer_app_id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_status` (`status`),
  KEY `idx_type` (`type`),
  KEY `idx_created_at` (`created_at`),
  KEY `idx_processed_at` (`processed_at`),
  CONSTRAINT `fk_transfer_orders_app` FOREIGN KEY (`transfer_app_id`) REFERENCES `kku_transfer_apps` (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='划转订单表';
```

#### 字段说明

| 字段名 | 类型 | 说明 | 示例值 |
|--------|------|------|--------|
| id | bigint unsigned | 主键ID | 12345 |
| transfer_app_id | int unsigned | 划转应用ID | 1 |
| out_id | int | 外部应用ID | 1001 |
| out_order_id | varchar(100) | 外部订单ID | EXT_ORDER_123456 |
| out_user_id | varchar(50) | 外部用户ID | EXT_USER_789 |
| user_id | int unsigned | 内部用户ID | 456 |
| currency_id | int | 货币类型ID | 2 |
| fund_id | int | 资金账户类型ID | 2 |
| type | tinyint | 订单类型 | 1 |
| status | tinyint | 订单状态 | 100 |
| out_amount | decimal(30,10) | 外部金额 | 100.5000000000 |
| amount | decimal(30,10) | 内部金额 | 96.1538461538 |
| exchange_rate | decimal(10,4) | 使用汇率(1外部币=N内部币) | 0.9568 |
| fee_rate | decimal(5,4) | 手续费率 | 0.0100 |
| fee_amount | decimal(15,4) | 手续费金额 | 1.0000 |
| actual_amount | decimal(15,4) | 实际到账金额 | 99.0000 |
| callback_data | json | 回调数据 | {"game_id": 123} |
| error_message | text | 错误信息 | 外部API调用失败 |
| remark | varchar(255) | 备注信息 | 游戏充值 |
| processed_at | timestamp | 处理时间 | 2025-06-15 14:54:00 |
| callback_at | timestamp | 回调时间 | 2025-06-15 14:55:00 |
| completed_at | timestamp | 完成时间 | 2025-06-15 14:56:00 |

#### 索引说明
- `PRIMARY`: 主键索引
- `uk_out_order`: 外部订单唯一索引(防重复)
- `idx_transfer_app_id`: 划转应用ID索引
- `idx_user_id`: 用户ID索引
- `idx_status`: 订单状态索引
- `idx_type`: 订单类型索引
- `idx_created_at`: 创建时间索引
- `idx_processed_at`: 处理时间索引

#### 外键约束
- `fk_transfer_orders_app`: 关联划转应用表

## 枚举值定义

### 订单类型 (type)
- `1`: 转入 (IN) - 从外部应用向用户转入
- `2`: 转出 (OUT) - 从用户向外部应用转出

### 订单状态 (status)
- `1`: 已创建 (CREATED) - 订单已创建，等待处理
- `20`: 处理中 (PROCESSING) - 正在处理中，等待回调
- `30`: 已回调 (CALLBACK) - 回调成功，等待最终确认
- `100`: 已完成 (COMPLETED) - 订单处理完成
- `-1`: 失败 (FAILED) - 订单处理失败

### 货币类型 (currency_id)
- `1`: 金币
- `2`: 钻石  
- `3`: 人民币
- `4`: 美元

## 数据初始化

### 示例应用配置
```sql
INSERT INTO `kku_transfer_apps` (
    `keyname`, `title`, `description`, `out_id`, `out_id2`, `out_id3`, `currency_id`, `fund_id`,
    `exchange_rate`, `order_callback_url`, `order_out_create_url`, `is_enabled`, `created_at`, `updated_at`
) VALUES
('game_app_demo', '演示游戏应用', '用于测试的演示应用', 1001, 2001, 3001, 2, 2, 1.0000, 'https://demo.game.com/callback', 'https://demo.game.com/order/create', 1, NOW(), NOW()),
('game_app_a', '游戏应用A', '热门游戏应用A', 1002, 2002, NULL, 2, 2, 1.0450, 'https://api.game-a.com/callback', 'https://api.game-a.com/order/create', 1, NOW(), NOW()),
('farm_internal', '农场内部应用', '仅在农场内部运转，不调用外部API', 1003, NULL, NULL, 1, 1, 1.0000, NULL, NULL, 1, NOW(), NOW());
```

## 数据维护

### 清理过期数据
建议定期清理超过6个月的已完成订单数据：

```sql
-- 清理6个月前的已完成订单
DELETE FROM `kku_transfer_orders` 
WHERE `status` = 100 
  AND `completed_at` < DATE_SUB(NOW(), INTERVAL 6 MONTH);
```

### 数据统计查询
```sql
-- 按应用统计订单数量
SELECT 
    ta.title AS app_name,
    COUNT(*) AS total_orders,
    SUM(CASE WHEN to.type = 1 THEN 1 ELSE 0 END) AS in_orders,
    SUM(CASE WHEN to.type = 2 THEN 1 ELSE 0 END) AS out_orders,
    SUM(to.amount) AS total_amount
FROM kku_transfer_orders to
LEFT JOIN kku_transfer_apps ta ON to.transfer_app_id = ta.id
WHERE to.created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY)
GROUP BY ta.id, ta.title
ORDER BY total_amount DESC;
```

### 性能优化建议

1. **分区表**: 对于大量历史数据，可考虑按月分区
2. **索引优化**: 根据查询模式添加复合索引
3. **数据归档**: 定期归档历史数据到备份表
4. **读写分离**: 查询操作使用只读副本

## 备份策略

1. **全量备份**: 每日凌晨进行全量备份
2. **增量备份**: 每小时进行增量备份
3. **实时同步**: 关键数据实时同步到备份库
4. **数据校验**: 定期校验数据完整性

## 相关文档

- [手续费使用指南](FEE_USAGE.md) - 手续费功能的详细说明
- [汇率概念说明](EXCHANGE_RATE_CONCEPT.md) - 汇率计算和转换规则
- [模块设计文档](README.md) - 完整的模块设计说明

---

> 文档创建时间: 2025-06-15 14:53
> 最后更新时间: 2025-06-19 03:43
> 数据库版本: MySQL 8.0+
> 字符集: utf8mb4_unicode_ci