# Transfer模块部署文档

## 部署概述

Transfer模块是一个完整的资金划转解决方案，支持农场内部模式和外部API模式。本文档详细说明了模块的部署、配置和维护流程。

## 系统要求

### 基础环境
- PHP >= 8.1
- Laravel >= 9.0
- MySQL >= 8.0
- Redis >= 6.0（用于队列和缓存）

### 扩展要求
- BCMath扩展（高精度数学计算）
- cURL扩展（外部API调用）
- JSON扩展（数据序列化）

### 依赖模块
- Fund模块（资金管理）
- OpenAPI模块（对外接口，可选）

## 部署步骤

### 1. 数据库部署

#### 1.1 执行建表SQL
```bash
# 连接到MySQL数据库
mysql -u username -p database_name

# 执行建表SQL
source app/Module/Transfer/Database/transfer_tables.sql
```

#### 1.2 执行初始化数据
```bash
# 执行初始化数据SQL
source app/Module/Transfer/Database/transfer_init_data.sql
```

#### 1.3 创建性能索引
```bash
# 执行性能优化SQL
source app/Module/Transfer/Database/optimization.sql
```

### 2. 配置文件部署

#### 2.1 发布配置文件
```bash
# 发布Transfer配置文件
php artisan vendor:publish --tag=transfer-config
```

#### 2.2 配置环境变量
在 `.env` 文件中添加：
```env
# Transfer模块配置
TRANSFER_DEBUG=false
TRANSFER_API_TIMEOUT=30
TRANSFER_QUEUE_CONNECTION=redis
TRANSFER_CACHE_DRIVER=redis
```

#### 2.3 修改配置文件
编辑 `config/transfer.php`：
```php
// 根据生产环境需求调整配置
'api' => [
    'timeout' => env('TRANSFER_API_TIMEOUT', 30),
    'retry_times' => 3,
],

'queue' => [
    'default' => env('TRANSFER_QUEUE_CONNECTION', 'redis'),
],
```

### 3. 队列配置

#### 3.1 配置队列驱动
在 `config/queue.php` 中确保Redis配置正确：
```php
'connections' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'default',
        'queue' => env('REDIS_QUEUE', 'default'),
        'retry_after' => 90,
        'block_for' => null,
    ],
],
```

#### 3.2 启动队列工作进程
```bash
# 启动Transfer队列工作进程
php artisan queue:work redis --queue=transfer,transfer_callback --sleep=3 --tries=3 --max-time=3600

# 使用Supervisor管理队列进程（推荐）
# 创建 /etc/supervisor/conf.d/transfer-worker.conf
```

Supervisor配置示例：
```ini
[program:transfer-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/artisan queue:work redis --queue=transfer,transfer_callback --sleep=3 --tries=3 --max-time=3600
directory=/path/to/project
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/transfer-worker.log
stopwaitsecs=3600
```

### 4. 定时任务配置

#### 4.1 添加Cron任务
```bash
# 编辑crontab
crontab -e

# 添加以下任务
# Transfer订单处理（每5分钟）
*/5 * * * * cd /path/to/project && php artisan transfer:process --type=orders --limit=100 >> /dev/null 2>&1

# Transfer回调处理（每2分钟）
*/2 * * * * cd /path/to/project && php artisan transfer:process --type=callbacks --limit=50 >> /dev/null 2>&1

# 每日统计报告（每天凌晨1点）
0 1 * * * cd /path/to/project && php artisan transfer:stats --period=yesterday --export=/var/log/transfer-daily-stats.csv >> /dev/null 2>&1
```

### 5. 权限配置

#### 5.1 文件权限
```bash
# 设置正确的文件权限
chown -R www-data:www-data /path/to/project/storage
chown -R www-data:www-data /path/to/project/bootstrap/cache
chmod -R 755 /path/to/project/storage
chmod -R 755 /path/to/project/bootstrap/cache
```

#### 5.2 日志目录权限
```bash
# 创建Transfer日志目录
mkdir -p /var/log/transfer
chown www-data:www-data /var/log/transfer
chmod 755 /var/log/transfer
```

## 配置说明

### 1. 应用配置

#### 1.1 农场内部模式
适用于纯内部资金流转，无需外部API：
```php
// 所有API URL留空即为农场内部模式
'order_callback_url' => null,
'order_in_info_url' => null,
'order_out_create_url' => null,
'order_out_info_url' => null,
```

#### 1.2 外部API模式
适用于与外部系统对接：
```php
// 配置相应的API端点
'order_callback_url' => 'https://external-api.com/callback',
'order_out_create_url' => 'https://external-api.com/transfer/create',
'order_out_info_url' => 'https://external-api.com/transfer/info',
```

### 2. 安全配置

#### 2.1 API签名验证
```php
'security' => [
    'signature_verification' => true,
    'signature_method' => 'md5',
],
```

#### 2.2 IP白名单（可选）
```php
'security' => [
    'ip_whitelist_enabled' => true,
    'ip_whitelist' => [
        '192.168.1.100',
        '10.0.0.50',
    ],
],
```

### 3. 性能配置

#### 3.1 缓存配置
```php
'cache' => [
    'enabled' => true,
    'app_config_ttl' => 3600,
    'stats_ttl' => 300,
],
```

#### 3.2 队列配置
```php
'queue' => [
    'max_tries' => 3,
    'timeout' => 120,
    'failed_job_retention' => 86400,
],
```

## 监控和维护

### 1. 日志监控

#### 1.1 应用日志
```bash
# 查看Transfer模块日志
tail -f storage/logs/laravel.log | grep Transfer

# 查看队列日志
tail -f /var/log/transfer-worker.log
```

#### 1.2 数据库日志
```bash
# 查看慢查询日志
tail -f /var/log/mysql/slow.log | grep transfer
```

### 2. 性能监控

#### 2.1 队列监控
```bash
# 查看队列状态
php artisan queue:monitor redis:transfer,redis:transfer_callback

# 查看失败任务
php artisan queue:failed
```

#### 2.2 数据库监控
```sql
-- 查看表大小
SELECT 
    TABLE_NAME,
    ROUND(((DATA_LENGTH + INDEX_LENGTH) / 1024 / 1024), 2) AS 'Size (MB)',
    TABLE_ROWS
FROM information_schema.TABLES 
WHERE TABLE_NAME LIKE 'kku_transfer_%';

-- 查看索引使用情况
SHOW INDEX FROM kku_transfer_orders;
```

### 3. 健康检查

#### 3.1 创建健康检查脚本
```bash
#!/bin/bash
# transfer-health-check.sh

# 检查数据库连接
php artisan tinker --execute="DB::connection()->getPdo();"

# 检查队列工作进程
ps aux | grep "queue:work" | grep -v grep

# 检查Redis连接
redis-cli ping

# 检查最近的订单处理情况
php artisan transfer:stats --period=today
```

#### 3.2 设置监控告警
```bash
# 添加到crontab，每10分钟检查一次
*/10 * * * * /path/to/transfer-health-check.sh || echo "Transfer health check failed" | mail -s "Transfer Alert" admin@example.com
```

## 故障排除

### 1. 常见问题

#### 1.1 队列任务失败
```bash
# 查看失败任务详情
php artisan queue:failed

# 重试失败任务
php artisan queue:retry all

# 清除失败任务
php artisan queue:flush
```

#### 1.2 外部API调用失败
```bash
# 检查网络连接
curl -I https://external-api.com/health

# 查看API调用日志
grep "ExternalApiService" storage/logs/laravel.log
```

#### 1.3 数据库性能问题
```sql
-- 查看正在执行的查询
SHOW PROCESSLIST;

-- 查看锁等待情况
SELECT * FROM information_schema.INNODB_LOCKS;

-- 优化表
OPTIMIZE TABLE kku_transfer_orders;
```

### 2. 紧急恢复

#### 2.1 数据备份恢复
```bash
# 恢复数据库备份
mysql -u username -p database_name < transfer_backup.sql
```

#### 2.2 服务重启
```bash
# 重启队列工作进程
supervisorctl restart transfer-worker:*

# 重启Web服务
systemctl restart nginx
systemctl restart php8.1-fpm
```

## 升级指南

### 1. 版本升级步骤
1. 备份数据库和配置文件
2. 停止队列工作进程
3. 更新代码
4. 执行数据库迁移（如有）
5. 更新配置文件
6. 重启服务
7. 验证功能正常

### 2. 兼容性检查
- 检查PHP版本兼容性
- 检查依赖模块版本
- 验证API接口兼容性
- 测试核心功能

## 安全建议

1. **定期更新密钥**：定期更换API签名密钥
2. **访问控制**：限制后台管理访问IP
3. **数据加密**：敏感数据传输使用HTTPS
4. **审计日志**：保留详细的操作日志
5. **权限最小化**：数据库用户权限最小化

## 联系支持

如遇到部署问题，请联系技术支持团队，并提供：
- 错误日志
- 系统环境信息
- 配置文件内容
- 问题复现步骤