用户日志系统

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

1. 系统概述

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

1.1 设计目标

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

1.2 核心特点

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

2. 核心逻辑

2.1 数据收集流程

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

2.2 数据存储策略

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

3. 数据库设计

3.1 用户日志表 (kku_user_logs)

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 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 查询日志

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

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

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

9. 扩展性设计

9.1 消息模板

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

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

9.2 过滤规则

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

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

10. 实现计划

10.1 第一阶段：基础功能

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

10.2 第二阶段：事件集成

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

10.3 第三阶段：优化完善

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

11. 技术要点

11.1 计划任务收集

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

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

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

11.2 收集器架构

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

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 进度追踪

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

// 获取上次处理的最大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 后续优化方向

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

UserLog.md 11 KB History Raw