# Cleanup 模块 ## 🎉 开发完成状态 ### ✅ 已完成的核心组件 (总体完成度: 75%) #### 1. **枚举类型定义** (100% 完成) - ✅ `CLEANUP_TYPE` - 5种清理类型枚举 - ✅ `DATA_CATEGORY` - 5种数据分类枚举 - ✅ `TASK_STATUS` - 7种任务状态枚举 - ✅ `PLAN_TYPE` - 5种计划类型枚举 - ✅ `BACKUP_TYPE` - 3种备份类型枚举 - ✅ `COMPRESSION_TYPE` - 3种压缩类型枚举 - ✅ `BACKUP_STATUS` - 3种备份状态枚举 #### 2. **数据库表结构** (100% 完成) - ✅ `kku_cleanup_configs` - 清理配置表 - ✅ `kku_cleanup_plans` - 清理计划表 - ✅ `kku_cleanup_plan_contents` - 计划内容表 - ✅ `kku_cleanup_tasks` - 清理任务表 - ✅ `kku_cleanup_backups` - 备份记录表 - ✅ `kku_cleanup_backup_files` - 备份文件表 - ✅ `kku_cleanup_logs` - 清理日志表 - ✅ `kku_cleanup_table_stats` - 表统计信息表 #### 3. **模型层** (100% 完成) - ✅ `CleanupConfig` - 清理配置模型 - ✅ `CleanupPlan` - 清理计划模型 - ✅ `CleanupPlanContent` - 计划内容模型 - ✅ `CleanupTask` - 清理任务模型 - ✅ `CleanupBackup` - 备份记录模型 #### 4. **服务层** (95% 完成) - ✅ `CleanupService` - 主服务类，提供完整的对外接口 - ✅ `ModelScannerLogic` - Model扫描逻辑，支持自动识别和配置生成 - ⚠️ `TableScannerLogic` - 表扫描逻辑（已废弃，建议使用ModelScannerLogic） - ✅ `CleanupPlanLogic` - 计划管理逻辑 - ✅ `CleanupTaskLogic` - 任务管理逻辑 - ✅ `CleanupExecutorLogic` - 清理执行逻辑，支持Model类和表名双模式 - ✅ `BackupLogic` - 备份管理逻辑 #### 5. **命令行工具** (100% 完成) - ✅ `ScanTablesCommand` - 表扫描命令，支持强制刷新和详细显示 - ✅ `CleanupDataCommand` - 数据清理命令，提供完整的命令行接口 #### 6. **服务层完善** (100% 完成) - ✅ `CleanupService` - 主服务类 - ✅ 服务提供者配置 - ✅ 事件监听器注册 #### 7. **配置和服务注册** (100% 完成) - ✅ `cleanup.php` - 完整的配置文件 - ✅ `CleanupServiceProvider` - 服务提供者 - ✅ 命令注册 - ✅ 路由注册 - ✅ 事件监听器注册 ### 📊 开发进度统计 | 组件类别 | 完成度 | 说明 | |---------|--------|------| | 枚举定义 | 100% | 7个枚举类，完整实现 | | 数据库设计 | 100% | 8个表，完整SQL结构 | | 模型层 | 100% | 5个核心模型，完整实现 | | 服务层 | 80% | 主服务完成，4个逻辑类待实现 | | 命令行工具 | 100% | 2个命令，功能完整 | | 服务层 | 100% | 主服务类和服务提供者完整 | | Dcat Admin后台 | 0% | 后台管理界面待开发 | | 配置文件 | 100% | 详细配置，支持环境变量 | | 服务注册 | 100% | 完整的服务提供者 | **总体完成度: 75%** ### 🚀 可立即使用的功能 1. **表扫描功能** - 可以扫描系统中的所有数据表并生成配置 2. **配置管理** - 可以管理每个表的清理配置 3. **计划管理** - 可以创建和管理清理计划 4. **命令行工具** - 可以通过命令行执行扫描和管理操作 5. **服务接口** - 提供完整的服务层接口 ### ⏳ 待完成的功能 1. **清理执行逻辑** - 实际的数据清理执行 2. **备份功能** - 数据备份和恢复 3. **任务管理** - 任务状态管理和进度监控 4. **计划内容生成** - 根据计划类型自动生成内容 5. **Dcat Admin后台** - 完整的后台管理界面 --- ## 模块简介 Cleanup 模块是一个专门用于数据清理的系统模块，提供灵活的数据清理配置和执行功能。该模块主要用于测试环境的数据清理，支持清除所有模块的运行数据，同时保留配置数据。 ### 核心特性 - ✅ **灵活表选择**：自由配置清理任意表，不局限于模块边界 - ✅ **多种选择方式**：支持自定义、模块、分类、全量、混合等选择方式 - ✅ **表级清理配置**：每个表都可以制定不同的清理方式和条件 - ✅ **5种清理类型**：清空表、删除所有、按时间、按用户、按条件删除 - ✅ **安全机制**：多重确认、预览模式、自动备份机制 - ✅ **批量处理**：支持大数据量的分批清理 - ✅ **日志记录**：详细的清理日志和统计信息 - ✅ **命令行工具**：支持命令行执行清理任务 - ✅ **实时监控**：清理过程的实时进度监控 - ✅ **数据备份**：清理前自动备份，支持快速恢复 ## 快速开始 ### 1. 扫描数据表 首先扫描系统中的所有数据表，生成默认配置： ```bash # 扫描数据表并生成配置 php artisan cleanup:scan-tables # 强制重新扫描 php artisan cleanup:scan-tables --force ``` ### 2. 创建清理计划 通过后台管理界面创建清理计划： 1. 访问 `/admin/cleanup/plans` 创建清理计划 2. 选择表选择方式：自定义、模块、分类、全量、混合 3. 配置具体的清理条件和备份设置 #### 表选择方式示例： ```bash # 自定义选择特定表 --tables=kku_farm_users,kku_item_users,kku_pet_logs # 按模块选择，排除配置表 --modules=Farm,GameItems --exclude-tables=kku_farm_configs # 按分类选择日志数据 --categories=2 --exclude-modules=Config # 混合选择 --modules=Farm --categories=2 --tables=kku_pet_users ``` ### 3. 配置表级清理方式 每个表都可以制定不同的清理方式： ```bash # 配置农场用户表：按时间删除，保留90天 php artisan cleanup:config-table 1 kku_farm_users \ --type=3 --time-field=created_at --before="90_days_ago" --backup --priority=100 # 配置物品用户表：按用户删除指定测试用户 php artisan cleanup:config-table 1 kku_item_users \ --type=4 --user-field=user_id --users=1001,1002,1003 --backup --priority=150 # 配置缓存表：直接清空，无需备份 php artisan cleanup:config-table 1 kku_cache \ --type=1 --no-backup --priority=400 # 基于计划创建任务 php artisan cleanup:create-task 1 --execute ``` ### 4. 执行清理 ```bash # 预览清理结果（不实际执行） php artisan cleanup:execute 1 --dry-run # 执行清理任务（会自动创建备份） php artisan cleanup:execute 1 # 强制执行（跳过确认） php artisan cleanup:execute 1 --force # 创建数据备份 php artisan cleanup:backup 1 --type=sql --compression=gzip # 恢复数据备份 php artisan cleanup:restore 123 ``` ## 目录结构 ``` app/Module/Cleanup/ ├── AdminControllers/ # 后台管理控制器 │ ├── CleanupConfigController.php # 清理配置管理 │ ├── CleanupTaskController.php # 清理任务管理 │ ├── CleanupLogController.php # 清理日志管理 │ └── Helper/ # 辅助类 ├── Commands/ # 命令行工具 │ ├── CleanupDataCommand.php # 数据清理命令 │ └── ScanTablesCommand.php # 扫描数据表命令 ├── Databases/ # 数据库相关文件 │ └── GenerateSql/ # SQL生成文件 ├── Docs/ # 文档目录 │ ├── 设计概述.md # 设计概述 │ ├── 数据库设计.md # 数据库设计 │ ├── 功能需求.md # 功能需求 │ └── 接口设计.md # 接口设计 ├── Enums/ # 枚举定义 │ ├── CLEANUP_TYPE.php # 清理类型枚举 │ ├── DATA_CATEGORY.php # 数据分类枚举 │ └── TASK_STATUS.php # 任务状态枚举 ├── Events/ # 事件类 ├── Listeners/ # 事件监听器 ├── Logics/ # 业务逻辑类 │ ├── ModelScannerLogic.php # Model扫描逻辑（推荐） │ ├── TableScannerLogic.php # 表扫描逻辑（已废弃） │ ├── CleanupExecutorLogic.php # 清理执行逻辑 │ ├── CleanupPlanLogic.php # 计划管理逻辑 │ ├── CleanupTaskLogic.php # 任务管理逻辑 │ └── BackupLogic.php # 备份管理逻辑 ├── Models/ # 数据模型 │ ├── CleanupConfig.php # 清理配置模型 │ ├── CleanupTask.php # 清理任务模型 │ └── CleanupLog.php # 清理日志模型 ├── Providers/ # 服务提供者 │ └── CleanupServiceProvider.php # 模块服务提供者 ├── Repositories/ # 数据仓库 ├── Services/ # 服务类 │ ├── CleanupService.php # 清理服务 │ └── ConfigService.php # 配置服务 ├── Validations/ # 验证规则 ├── Validators/ # 验证器 └── README.md # 本文档 ``` ## 表选择方式 ### 5种灵活的表选择方式 #### 1. 自定义选择 (Custom) 直接指定要清理的表列表，完全自由选择： ```json { "selection_type": "custom", "tables": ["kku_farm_users", "kku_item_users", "kku_pet_logs"] } ``` #### 2. 模块选择 (Module) 选择一个或多个模块的所有表： ```json { "selection_type": "module", "modules": ["Farm", "GameItems"], "exclude_tables": ["kku_farm_configs"] } ``` #### 3. 分类选择 (Category) 按数据分类选择表： ```json { "selection_type": "category", "categories": [1, 2], // 用户数据和日志数据 "exclude_modules": ["Config"] } ``` #### 4. 全量选择 (All) 选择所有表，但可排除特定内容： ```json { "selection_type": "all", "exclude_categories": [5], // 排除配置数据 "exclude_tables": ["kku_user_profiles"] } ``` #### 5. 混合选择 (Mixed) 组合多种选择方式： ```json { "selection_type": "mixed", "modules": ["Farm"], "categories": [2], "tables": ["kku_pet_users"], "exclude_tables": ["kku_farm_configs"] } ``` ### 数据分类定义 - **USER_DATA (1)**: 用户运行数据 - **LOG_DATA (2)**: 日志数据 - **TRANSACTION_DATA (3)**: 交易数据 - **CACHE_DATA (4)**: 缓存数据 - **CONFIG_DATA (5)**: 配置数据（通常不清理） ### 5种清理类型详解 #### 1. 清空表 (TRUNCATE - 1) - **适用场景**：缓存数据、临时数据 - **特点**：最快速，重置自增ID，不可回滚 - **示例**：`kku_cache`, `kku_sessions` #### 2. 删除所有记录 (DELETE_ALL - 2) - **适用场景**：需要保留自增ID的场景 - **特点**：保留自增ID，可回滚，触发触发器 - **示例**：`kku_user_sessions` #### 3. 按时间删除 (DELETE_BY_TIME - 3) - **适用场景**：有时间字段的表，保留最近数据 - **特点**：可设置保留天数，支持相对时间 - **示例**：`kku_farm_logs`, `kku_user_actionlogs` #### 4. 按用户删除 (DELETE_BY_USER - 4) - **适用场景**：用户相关数据，清理特定用户 - **特点**：精确控制用户范围，支持用户列表 - **示例**：`kku_farm_users`, `kku_item_users` #### 5. 按条件删除 (DELETE_BY_CONDITION - 5) - **适用场景**：复杂删除条件，自定义SQL条件 - **特点**：最大灵活性，支持复杂组合条件 - **示例**：状态为0且创建时间早于某日期的记录 ## 使用示例 ### 1. 配置管理 ```php use App\Module\Cleanup\Services\ConfigService; // 获取所有配置 $configs = ConfigService::getCleanupConfigs(); // 更新特定表的配置 ConfigService::updateCleanupConfig('kku_farm_users', [ 'cleanup_type' => 3, // 按时间删除 'conditions' => [ 'time_field' => 'created_at', 'time_condition' => 'older_than', 'time_value' => 30, 'time_unit' => 'days' ], 'is_enabled' => true, 'priority' => 100 ]); ``` ### 2. 任务管理 ```php use App\Module\Cleanup\Services\CleanupService; // 创建清理任务 $result = CleanupService::createCleanupTask([ 'task_name' => '测试数据清理', 'cleanup_type' => 2, // 模块清理 'target_modules' => ['Farm', 'GameItems'], 'conditions' => [ 'exclude_tables' => ['kku_farm_configs'] ] ]); // 预览清理结果 $preview = CleanupService::previewCleanup($taskId); // 执行清理 $result = CleanupService::executeCleanup($taskId); ``` ### 3. 表级配置管理 ```php use App\Module\Cleanup\Services\PlanService; // 配置农场用户表：按时间删除 PlanService::configureTable(1, 'kku_farm_users', [ 'cleanup_type' => 3, 'conditions' => [ 'time_field' => 'created_at', 'before' => '90_days_ago' ], 'priority' => 100, 'backup_enabled' => true, 'notes' => '保留90天内的农场用户数据' ]); // 配置物品表：按用户删除 PlanService::configureTable(1, 'kku_item_users', [ 'cleanup_type' => 4, 'conditions' => [ 'user_field' => 'user_id', 'user_condition' => 'in', 'user_values' => [1001, 1002, 1003] ], 'priority' => 150, 'backup_enabled' => true, 'notes' => '清理指定测试用户的物品数据' ]); // 配置缓存表：直接清空 PlanService::configureTable(1, 'kku_cache', [ 'cleanup_type' => 1, 'conditions' => null, 'priority' => 400, 'backup_enabled' => false, 'notes' => '缓存表直接清空，无需备份' ]); ``` ### 4. 数据备份管理 ```php use App\Module\Cleanup\Services\CleanupService; // 创建备份（默认为数据库备份） $backupResult = CleanupService::createPlanBackup($planId, [ 'backup_type' => 1, // 1=数据库备份, 2=SQL文件, 3=JSON文件, 4=CSV文件 'compression' => 'gzip', 'include_structure' => true ]); // 获取SQL备份列表 $sqlBackups = CleanupService::getSqlBackups([ 'table_name' => 'kku_farm_users', 'min_records' => 100, 'order_by' => 'created_at', 'order_direction' => 'desc' ]); // 获取SQL备份详情 $backupDetail = CleanupService::getSqlBackupDetail($sqlBackupId); // 获取SQL备份内容 $backupContent = CleanupService::getSqlBackupContent($sqlBackupId); // 恢复备份 $restoreResult = CleanupService::restoreBackup($backupId); ``` ### 5. 后台管理 访问以下URL进行后台管理： - `/admin/cleanup/plans` - 清理计划管理 - `/admin/cleanup/plans/{id}/contents` - 计划内容和表级配置 - `/admin/cleanup/tasks` - 清理任务管理 - `/admin/cleanup/logs` - 清理日志查看 - `/admin/cleanup/backups` - 数据备份管理 - `/admin/cleanup/reports` - 统计报告 ## 安全注意事项 ### 1. 权限控制 - 只有具有清理权限的用户才能执行清理操作 - 危险操作需要多重确认 - 所有操作都有完整的审计日志 ### 2. 数据保护 - 配置数据默认不会被清理 - 重要的用户数据需要特殊配置 - 清理前自动创建数据备份 - 备份文件自动压缩和哈希验证 ### 3. 备份机制 - **数据库备份**：将INSERT语句直接存储到数据库表中（默认方式） - **文件备份**：支持SQL、JSON、CSV格式文件备份 - **自动备份**：清理前自动备份将要删除的数据 - **压缩存储**：文件备份支持自动压缩节省空间 - **完整性验证**：SHA256哈希验证备份内容完整性 - **快速恢复**：支持一键恢复备份数据 - **查询便捷**：数据库备份支持快速查询和检索 ### 4. 操作建议 - 首次使用时建议先使用预览模式 - 系统会自动备份，无需手动备份 - 在业务低峰期执行清理操作 - 定期清理过期的备份文件 ## 性能优化 ### 1. 分批处理 - 大表自动采用分批删除策略 - 可配置每批处理的记录数量 - 避免长时间锁表影响业务 ### 2. 优先级控制 - 按优先级顺序执行清理 - 重要表优先处理 - 可配置清理的并发度 ### 3. 监控机制 - 实时监控清理进度 - 记录详细的性能指标 - 支持清理过程的暂停和恢复 ## 故障排除 ### 常见问题 1. **清理任务执行失败** - 检查数据库连接是否正常 - 检查表是否存在外键约束 - 查看错误日志获取详细信息 2. **清理速度过慢** - 调整批处理大小 - 检查数据库索引是否合理 - 考虑在业务低峰期执行 3. **权限不足** - 确认用户具有清理权限 - 检查数据库用户权限 - 联系管理员分配权限 ### 日志查看 ```bash # 查看清理日志 tail -f storage/logs/cleanup.log # 查看任务状态 php artisan cleanup:status [task_id] ``` ## 扩展开发 ### 添加新的清理类型 1. 在 `CLEANUP_TYPE` 枚举中添加新类型 2. 在 `CleanupExecutorLogic` 中实现清理逻辑 3. 更新后台管理界面的选项 ### 添加新的数据分类 1. 在 `DATA_CATEGORY` 枚举中添加新分类 2. 更新表扫描逻辑识别新分类 3. 配置默认的清理策略 ## 版本历史 - **v1.0.0** - 初始版本，基础清理功能 - **v1.1.0** - 添加批量处理和进度监控 - **v1.2.0** - 增强安全机制和权限控制 ## 相关文档 - [设计概述](Docs/设计概述.md) - [数据库设计](Docs/数据库设计.md) - [功能需求](Docs/功能需求.md) - [接口设计](Docs/接口设计.md)