# 用户日志系统

> 用户日志表，用于给用户看的日志表，记录用户相关的信息

## 1. 系统概述

用户日志系统是一个专门为用户提供操作记录查看的功能模块，主要用于记录和展示用户在游戏中的各种操作和变更信息。

### 1.1 设计目标

- **用户友好**：为用户提供清晰易懂的操作记录
- **实时性**：及时记录用户的各种操作
- **可追溯**：用户可以查看历史操作记录
- **性能优化**：采用异步收集机制，不影响主业务流程

### 1.2 核心特点

- 采用文字描述而非结构化数据，便于用户理解
- 支持分页查询，提升查询性能
- 支持清空功能，用户可以清理历史记录
- 异步收集机制，定时批量处理

## 2. 核心逻辑

### 2.1 数据收集流程

1. **计划任务扫描**：每2秒执行计划任务，扫描各个原始日志表的新增记录
2. **数据转换**：将原始日志数据转换为用户友好的文字描述
3. **批量写入**：将转换后的日志批量写入用户日志表
4. **记录追踪**：记录已处理的最大ID，避免重复处理

### 2.2 数据存储策略

- **不记录结构化数据**：原始数据在各业务表中已存在
- **采用文字记录**：例如'打开礼包获得普通种子*100'，'除虫消耗除草剂*1'
- **记录关联信息**：存储相关表名和记录ID，便于问题排查

## 3. 数据库设计

### 3.1 用户日志表 (kku_user_logs)

```sql
CREATE TABLE `kku_user_logs` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `user_id` int NOT NULL COMMENT '用户ID',
  `message` text NOT NULL COMMENT '日志消息内容',
  `source_type` varchar(50) DEFAULT NULL COMMENT '来源类型（fund, item, farm等）',
  `source_id` int DEFAULT NULL COMMENT '来源记录ID',
  `source_table` varchar(100) DEFAULT NULL COMMENT '来源表名',
  `created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_created_at` (`created_at`),
  KEY `idx_source` (`source_type`, `source_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户日志表';
```

### 3.2 字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint unsigned | 主键ID，自增 |
| user_id | int | 用户ID，关联用户表 |
| message | text | 日志消息内容，用户友好的文字描述 |
| source_type | varchar(50) | 来源类型，如fund、item、farm等 |
| source_id | int | 来源记录ID，关联具体的业务记录 |
| source_table | varchar(100) | 来源表名，便于追溯原始数据 |
| created_at | timestamp | 创建时间 |

## 4. 接口设计

### 4.1 获取用户日志

**请求消息**：`RequestUserLogData`
- `page`：分页信息

**响应消息**：`ResponseUserLogdata`
- `page`：分页信息
- `logs`：日志列表，每个日志包含：
  - `msg`：日志消息
  - `time`：时间

### 4.2 清空用户日志

**请求消息**：`RequestUserClearLog`

**响应消息**：`ResponseUserClearLog`

## 5. 实现架构

### 5.1 模块结构

```
app/Module/Game/
├── Models/
│   └── UserLog.php                    # 用户日志模型
├── Services/
│   ├── UserLogService.php             # 用户日志服务
│   └── UserLogScheduleService.php     # 日志调度服务
├── Logics/
│   ├── UserLogLogic.php               # 用户日志逻辑
│   ├── UserLogCollectorManager.php    # 收集器管理器
│   └── UserLogCollectors/             # 日志收集器目录
│       ├── BaseLogCollector.php       # 收集器基类
│       ├── FundLogCollector.php       # 资金日志收集器
│       ├── ItemLogCollector.php       # 物品日志收集器
│       └── FarmLogCollector.php       # 农场日志收集器
├── Jobs/
│   └── CollectUserLogJob.php          # 日志收集任务
├── Commands/
│   ├── CollectUserLogsCommand.php     # 日志收集命令
│   └── CleanExpiredUserLogsCommand.php # 清理过期日志命令
└── AdminControllers/
    └── UserLogController.php          # 后台管理控制器

app/Module/AppGame/Handler/User/
├── LogDataHandler.php                 # 用户日志数据Handler
└── ClearLogHandler.php                # 清空日志Handler
```

### 5.2 计划任务架构

系统采用计划任务架构，通过定时扫描各模块的日志表来收集用户日志：

- **资金日志表**：扫描fund_logs表的新增记录
- **物品日志表**：扫描item_transaction_logs表的新增记录
- **农场日志表**：扫描farm_harvest_logs表的新增记录
- **宠物日志表**：扫描相关宠物操作记录表

## 6. 日志消息格式

### 6.1 资金相关

- 获得资金：`获得{资金名称} {数量}`
- 消耗资金：`消耗{资金名称} {数量}`
- 示例：`获得金币 1000`、`消耗钻石 50`

### 6.2 物品相关

- 获得物品：`获得{物品名称} {数量}`
- 消耗物品：`消耗{物品名称} {数量}`
- 示例：`获得普通种子 100`、`消耗除草剂 1`

### 6.3 农场相关

- 种植作物：`在{土地编号}种植{作物名称}`
- 收获作物：`收获{土地编号}的{作物名称}，获得{产出}`
- 房屋升级：`房屋升级到{等级}级`

### 6.4 宠物相关

- 获得宠物：`获得宠物{宠物名称}`
- 宠物升级：`宠物{宠物名称}升级到{等级}级`
- 技能使用：`宠物{宠物名称}使用技能{技能名称}`

## 7. 性能优化

### 7.1 异步收集

- 使用队列任务异步处理日志收集
- 避免在主业务流程中直接写入日志
- 批量处理，提升写入性能

### 7.2 数据清理

- 提供用户主动清空功能
- 定期清理过期日志（可配置保留天数）
- 分页查询，避免一次性加载大量数据

### 7.3 索引优化

- 用户ID索引：快速查询用户日志
- 时间索引：支持时间范围查询
- 来源索引：便于按来源类型查询

## 8. 使用示例

### 8.1 启动日志收集

```php
// 命令行方式
php artisan game:collect-user-logs

// 指定收集器
php artisan game:collect-user-logs --collector=fund

// 重置进度
php artisan game:collect-user-logs --reset

// 程序调用
UserLogScheduleService::collectNow(); // 同步执行
UserLogScheduleService::scheduleCollection(); // 异步执行
```

### 8.2 查询日志

```php
// 获取用户日志列表
$logs = UserLogService::getUserLogs($userId, $page, $pageSize);

// 清空用户日志
UserLogService::clearUserLogs($userId);

// 获取收集器状态
$status = UserLogScheduleService::checkCollectorsStatus();
```

## 9. 扩展性设计

### 9.1 消息模板

支持配置化的消息模板，便于国际化和个性化：

```php
$templates = [
    'fund.gain' => '获得{fund_name} {amount}',
    'fund.cost' => '消耗{fund_name} {amount}',
    'item.gain' => '获得{item_name} {quantity}',
    // ...
];
```

### 9.2 过滤规则

支持配置哪些事件需要记录日志，避免记录过多无用信息：

```php
$logRules = [
    'fund' => ['min_amount' => 100], // 只记录100以上的资金变更
    'item' => ['exclude_types' => ['temp']], // 排除临时物品
    // ...
];
```

## 10. 实现计划

### 10.1 第一阶段：基础功能

1. **创建数据库表**：创建用户日志表
2. **创建模型**：UserLog模型，包含基本的CRUD操作
3. **创建服务**：UserLogService，提供日志记录和查询功能
4. **创建Handler**：LogDataHandler，处理前端日志查询请求

### 10.2 第二阶段：事件集成

1. **创建监听器**：UserLogCollectorListener，监听各模块事件
2. **集成资金模块**：监听资金变更事件
3. **集成物品模块**：监听物品变更事件
4. **集成农场模块**：监听农场操作事件

### 10.3 第三阶段：优化完善

1. **异步处理**：创建队列任务，异步处理日志收集
2. **后台管理**：创建后台管理界面
3. **性能优化**：添加索引，优化查询性能
4. **数据清理**：实现定期清理功能

## 11. 技术要点

### 11.1 计划任务收集

使用计划任务定时扫描各模块的原始日志表：

```php
// 每2秒执行一次日志收集
* * * * * php artisan game:collect-user-logs

// 或者通过队列异步执行
CollectUserLogJob::dispatchCollection();
```

### 11.2 收集器架构

每个模块都有对应的日志收集器，继承自基类：

```php
class FundLogCollector extends BaseLogCollector
{
    protected string $sourceTable = 'fund_logs';
    protected string $sourceType = 'fund';

    protected function getNewRecords(int $lastProcessedId)
    {
        return FundLogModel::where('id', '>', $lastProcessedId)
            ->orderBy('id')
            ->limit($this->maxRecords)
            ->get();
    }

    protected function convertToUserLog($record): ?array
    {
        // 转换逻辑
    }
}
```

### 11.3 进度追踪

使用缓存记录每个收集器的处理进度：

```php
// 获取上次处理的最大ID
$lastProcessedId = Cache::get("user_log_collector:last_processed_id:{$sourceTable}", 0);

// 更新处理进度
Cache::put("user_log_collector:last_processed_id:{$sourceTable}", $newId, 86400);
```

## 12. 注意事项

### 12.1 性能考虑

- 避免在主业务流程中同步写入日志
- 使用异步队列处理日志收集
- 合理设置日志保留期限，定期清理过期数据

### 12.2 数据一致性

- 确保日志记录与业务操作的一致性
- 处理异常情况，避免日志丢失
- 提供手动补录机制

### 12.3 用户体验

- 提供清晰易懂的日志消息
- 支持分页查询，避免一次性加载过多数据
- 提供筛选和搜索功能

## 13. 测试策略

### 13.1 单元测试

- 测试日志记录功能
- 测试消息生成逻辑
- 测试查询和分页功能

### 13.2 集成测试

- 测试事件监听和日志收集
- 测试与各模块的集成
- 测试异步处理功能

### 13.3 性能测试

- 测试大量日志的查询性能
- 测试异步处理的性能
- 测试数据库索引效果

## 14. 维护和监控

### 14.1 日志监控

- 监控日志收集的成功率
- 监控队列任务的执行情况
- 监控数据库性能

### 14.2 数据维护

- 定期清理过期日志
- 监控数据库存储空间
- 备份重要日志数据

### 14.3 问题排查

- 提供日志查询工具
- 记录系统运行日志
- 建立问题处理流程

## 15. 总结

用户日志系统是游戏中重要的功能模块，通过合理的设计和实现，可以为用户提供良好的操作记录查看体验，同时为系统运维提供有价值的数据支持。

### 15.1 关键成功因素

- **性能优化**：异步处理，避免影响主业务
- **用户体验**：清晰的消息格式，便捷的查询功能
- **可维护性**：模块化设计，便于扩展和维护
- **数据安全**：合理的数据保留策略，避免数据泄露

### 15.2 后续优化方向

- **智能分析**：基于日志数据进行用户行为分析
- **个性化推荐**：根据用户操作习惯提供个性化建议
- **实时通知**：重要操作的实时通知功能
- **数据可视化**：提供图表展示用户操作趋势