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

## 📋 概述

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

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

## 🗄️ 数据库变更

### 1. 执行数据库优化脚本

```bash
# 执行数据库优化脚本
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. 验证数据库变更

```sql
-- 检查唯一索引
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` 中添加以下配置：

```yaml
# 游戏完成检测配置
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` 中增加以下日志配置：

```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. 验证冷却机制

```bash
# 测试冷却功能
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. 验证编号唯一性

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

### 3. 验证完成检测

监控日志中的以下关键信息：
- 登录缓冲期保护日志
- 完成检测置信度日志  
- 状态变更确认日志

## 📊 监控指标

### 1. 数据库监控

```sql
-- 监控冷却记录数量
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. 验证缓存和数据库同步

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

### 问题2：误判完成状态

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

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

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

### 问题3：编号仍然重复

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

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

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

## 🔄 回滚方案

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

### 1. 代码回滚

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

# 重新部署
mvn clean package -DskipTests
```

### 2. 数据库回滚

```sql
-- 保留数据，只移除新表
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. 数据库优化

```sql
-- 定期清理过期数据
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. 说明当前系统状态

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