kknongchang_2506/app/Module/Transfer/Docs/DATABASE.md

Transfer 模块数据库设计文档

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

数据库概述

Transfer 模块使用2个主要数据表：

• kku_transfer_apps: 划转应用配置表
• kku_transfer_orders: 划转订单表

表结构设计

1. kku_transfer_apps - 划转应用配置表

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

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 - 划转订单表

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

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: 美元

数据初始化

示例应用配置

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个月的已完成订单数据：

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

数据统计查询

-- 按应用统计订单数量
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. 数据校验: 定期校验数据完整性

相关文档

• 手续费使用指南 - 手续费功能的详细说明
• 汇率概念说明 - 汇率计算和转换规则
• 模块设计文档 - 完整的模块设计说明

---

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