game_server/OPTIMIZATION_IMPLEMENTATION_GUIDE.md

游戏平台系统优化实施指南

📋 概述

本指南详细说明了针对以下三个问题的系统优化方案：

1. 设备10分钟内重复调用问题
2. 用户刚扫码就显示已打完问题
3. 同一编号出现两条链接问题

🗄️ 数据库变更

1. 执行数据库优化脚本

# 执行数据库优化脚本
mysql -u your_username -p your_database < database_improvements.sql

关键变更：

• ✅ link_task 表已有 UNIQUE INDEX uk_code_no （解决问题3）
• ➕ 新增 machine_cooldown 表（解决问题1）
• ➕ 新增 game_completion_log 表（解决问题2）
• ➕ 新增相关索引优化

2. 验证数据库变更

-- 检查唯一索引
SHOW INDEX FROM link_task WHERE Key_name = 'uk_code_no';

-- 检查新表是否创建成功
SHOW TABLES LIKE '%cooldown%';
SHOW TABLES LIKE '%completion%';

-- 检查冷却表结构
DESC machine_cooldown;

🔧 代码部署

1. 新增文件列表

需要添加以下新文件到项目中：

src/main/java/com/gameplatform/server/model/entity/cooldown/
├── MachineCooldown.java

src/main/java/com/gameplatform/server/model/entity/detection/
├── GameCompletionLog.java

src/main/java/com/gameplatform/server/mapper/cooldown/
├── MachineCooldownMapper.java

src/main/java/com/gameplatform/server/service/detection/
├── GameCompletionDetectionService.java

src/main/resources/mapper/cooldown/
├── MachineCooldownMapper.xml

2. 修改现有文件

以下文件已被优化，需要更新：

• src/main/java/com/gameplatform/server/service/cooldown/MachineCooldownService.java
• src/main/java/com/gameplatform/server/service/link/LinkGenerationService.java
• src/main/java/com/gameplatform/server/service/link/DeviceTaskUpdateService.java
• src/main/java/com/gameplatform/server/service/link/LinkStatusService.java

⚙️ 配置调整

1. 应用配置

在 application.yml 中添加以下配置：

# 游戏完成检测配置
game:
  completion:
    detection:
      login-buffer-seconds: 30        # 登录后缓冲时间（秒）
      confirmation-interval: 10       # 完成确认间隔（秒）
      confidence-threshold: MEDIUM    # 置信度阈值

# 设备冷却配置  
machine:
  cooldown:
    duration-minutes: 10              # 冷却时间（分钟）
    cleanup-interval: 30              # 清理间隔（分钟）
    cache-enabled: true               # 启用内存缓存

# 编号生成配置
code:
  generation:
    max-retry-attempts: 5             # 最大重试次数
    use-timestamp-fallback: true      # 启用时间戳后备策略

2. 日志配置

在 logback-spring.xml 中增加以下日志配置：

<!-- 冷却服务日志 -->
<logger name="com.gameplatform.server.service.cooldown" level="INFO" />

<!-- 完成检测服务日志 -->
<logger name="com.gameplatform.server.service.detection" level="INFO" />

<!-- 编号生成日志 -->
<logger name="com.gameplatform.server.service.link.LinkGenerationService" level="DEBUG" />

🔍 功能验证

1. 验证冷却机制

# 测试冷却功能
curl -X POST "http://localhost:8080/api/test/cooldown" \
  -H "Content-Type: application/json" \
  -d '{"machineId": "test001", "reason": "测试冷却"}'

# 检查冷却状态
curl "http://localhost:8080/api/test/cooldown/test001"

2. 验证编号唯一性

-- 检查是否有重复编号
SELECT code_no, COUNT(*) as count 
FROM link_task 
GROUP BY code_no 
HAVING count > 1;

3. 验证完成检测

监控日志中的以下关键信息：

• 登录缓冲期保护日志
• 完成检测置信度日志
• 状态变更确认日志

📊 监控指标

1. 数据库监控

-- 监控冷却记录数量
SELECT 
    status,
    COUNT(*) as count,
    MIN(cooldown_end_time) as earliest_end,
    MAX(cooldown_end_time) as latest_end
FROM machine_cooldown 
GROUP BY status;

-- 监控完成检测日志
SELECT 
    detection_source,
    completion_confidence,
    COUNT(*) as count,
    AVG(is_confirmed) as confirmation_rate
FROM game_completion_log 
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 1 DAY)
GROUP BY detection_source, completion_confidence;

2. 应用监控

关键指标：

• 冷却队列大小：machineCooldownService.getCooldownQueueSize()
• 待确认检测数量：completionDetectionService.getPendingCount()
• 编号生成重试率：监控日志中的重试次数

🚨 故障排除

问题1：冷却机制不生效

症状：设备仍在10分钟内重复调用

排查步骤：

1. 检查数据库连接和表结构
2. 查看冷却服务日志
3. 验证缓存和数据库同步

-- 检查冷却记录
SELECT * FROM machine_cooldown 
WHERE machine_id = '问题设备ID' 
ORDER BY created_at DESC LIMIT 5;

问题2：误判完成状态

症状：用户刚登录就被标记为完成

排查步骤：

1. 检查登录缓冲期配置
2. 查看完成检测日志
3. 验证置信度阈值设置

-- 检查完成检测日志
SELECT * FROM game_completion_log 
WHERE machine_id = '问题设备ID' 
ORDER BY created_at DESC LIMIT 10;

问题3：编号仍然重复

症状：数据库中出现重复编号

排查步骤：

1. 验证唯一索引是否生效
2. 检查编号生成日志
3. 确认重试机制工作正常

-- 强制检查唯一约束
ALTER TABLE link_task ADD CONSTRAINT uk_code_no_check UNIQUE (code_no);

🔄 回滚方案

如果新版本出现问题，可以按以下步骤回滚：

1. 代码回滚

# 恢复原版本代码
git checkout HEAD~1 -- src/main/java/com/gameplatform/server/service/

# 重新部署
mvn clean package -DskipTests

2. 数据库回滚

-- 保留数据，只移除新表
DROP TABLE IF EXISTS machine_cooldown;
DROP TABLE IF EXISTS game_completion_log;
DROP TABLE IF EXISTS code_sequence;
DROP TABLE IF EXISTS system_monitor;

-- 移除新增索引
ALTER TABLE link_task DROP INDEX idx_machine_status;
ALTER TABLE link_task DROP INDEX idx_status_updated;
ALTER TABLE link_task DROP INDEX idx_login_time;

注意：uk_code_no 唯一索引建议保留，因为它解决了编号重复问题。

📈 性能优化建议

1. 数据库优化

-- 定期清理过期数据
DELETE FROM machine_cooldown 
WHERE status = 'EXPIRED' 
AND updated_at < DATE_SUB(NOW(), INTERVAL 7 DAY);

DELETE FROM game_completion_log 
WHERE created_at < DATE_SUB(NOW(), INTERVAL 30 DAY);

2. 缓存优化

• 适当调整冷却缓存大小
• 定期清理过期缓存记录
• 监控缓存命中率

3. 并发优化

• 考虑使用分布式锁（Redis）
• 优化数据库连接池配置
• 调整事务隔离级别

📋 部署检查清单

• 数据库脚本执行完成
• 新文件添加到项目
• 现有文件更新完成
• 配置文件更新
• 日志配置调整
• 应用重启成功
• 功能验证通过
• 监控指标正常
• 回滚方案准备就绪

📞 技术支持

如在实施过程中遇到问题，请：

1. 收集相关日志文件
2. 记录具体错误信息
3. 提供复现步骤
4. 说明当前系统状态

这样可以更快速地定位和解决问题。