kknongchang_2506/app/Module/Cleanup/Docs/接口设计.md

Cleanup 模块接口设计

1. 接口概述

Cleanup 模块提供以下几类接口：

• 配置管理接口：管理清理配置
• 任务管理接口：创建和管理清理任务
• 执行控制接口：控制清理执行过程
• 统计查询接口：查询统计信息和日志

2. 服务层接口 (Services)

2.1 CleanupService

2.1.1 扫描数据表

/**
 * 扫描系统中的所有数据表
 *
 * @param bool $forceRefresh 是否强制刷新
 * @return array 扫描结果
 */
public static function scanTables(bool $forceRefresh = false): array

2.1.2 创建清理计划

/**
 * 创建清理计划
 *
 * @param array $planData 计划数据
 * @return array 创建结果
 */
public static function createCleanupPlan(array $planData): array

输入参数：

[
    'plan_name' => '自定义数据清理',
    'plan_type' => 4, // 自定义清理
    'target_selection' => [
        'selection_type' => 'custom',
        'tables' => [
            'kku_farm_users',
            'kku_item_users',
            'kku_pet_users',
            'kku_farm_logs'
        ]
    ],
    'global_conditions' => [
        'exclude_config_tables' => true,
        'time_limit' => '30_days_ago'
    ],
    'backup_config' => [
        'backup_type' => 'sql',
        'compression' => 'gzip'
    ],
    'description' => '清理指定表的测试数据'
]

其他选择方式示例：

// 按模块选择
'target_selection' => [
    'selection_type' => 'module',
    'modules' => ['Farm', 'GameItems'],
    'exclude_tables' => ['kku_farm_configs']
]

// 按分类选择
'target_selection' => [
    'selection_type' => 'category',
    'categories' => [1, 2], // 用户数据和日志数据
    'exclude_tables' => ['kku_user_configs']
]

// 混合选择
'target_selection' => [
    'selection_type' => 'mixed',
    'modules' => ['Farm'],
    'categories' => [2],
    'tables' => ['kku_pet_users'],
    'exclude_tables' => ['kku_farm_configs']
]

2.1.3 生成计划内容

/**
 * 为计划生成内容配置
 *
 * @param int $planId 计划ID
 * @param bool $autoGenerate 是否自动生成
 * @return array 生成结果
 */
public static function generatePlanContents(int $planId, bool $autoGenerate = true): array

返回数据结构：

[
    'total_tables' => 188,
    'scanned_tables' => 185,
    'new_tables' => 3,
    'tables' => [
        [
            'table_name' => 'kku_farm_users',
            'module_name' => 'Farm',
            'data_category' => 1, // 用户数据
            'record_count' => 1250,
            'table_size_mb' => 2.5,
            'has_time_field' => true,
            'time_fields' => ['created_at', 'updated_at'],
            'has_user_field' => true,
            'user_fields' => ['user_id']
        ]
    ]
]

2.1.4 创建清理任务

/**
 * 基于计划创建清理任务
 *
 * @param int $planId 计划ID
 * @param array $taskOptions 任务选项
 * @return array 创建结果
 */
public static function createCleanupTask(int $planId, array $taskOptions = []): array

输入参数：

[
    'task_name' => '农场模块清理_20241216_001', // 可选，默认自动生成
    'execute_immediately' => false,
    'backup_before_cleanup' => true,
    'override_conditions' => [], // 可选，覆盖计划的条件
]

2.1.5 预览清理结果

/**
 * 预览计划的清理结果
 *
 * @param int $planId 计划ID
 * @return array 预览结果
 */
public static function previewPlanCleanup(int $planId): array

返回数据结构：

[
    'total_tables' => 45,
    'total_records' => 125000,
    'estimated_size_mb' => 250.5,
    'estimated_time_seconds' => 120,
    'tables_preview' => [
        [
            'table_name' => 'kku_farm_users',
            'current_records' => 1250,
            'records_to_delete' => 1200,
            'size_to_free_mb' => 2.4,
            'cleanup_type' => 'DELETE',
            'conditions' => 'WHERE created_at < "2024-01-01"'
        ]
    ]
]

2.1.6 执行清理任务

/**
 * 执行清理任务
 *
 * @param int $taskId 任务ID
 * @param bool $dryRun 是否为预演模式
 * @return array 执行结果
 */
public static function executeCleanupTask(int $taskId, bool $dryRun = false): array

2.1.7 创建计划备份

/**
 * 为计划创建数据备份
 *
 * @param int $planId 计划ID
 * @param array $backupOptions 备份选项
 * @return array 备份结果
 */
public static function createPlanBackup(int $planId, array $backupOptions = []): array

输入参数：

[
    'backup_type' => 'sql', // sql, json, csv
    'compression' => 'gzip', // gzip, zip, none
    'include_structure' => true, // 是否包含表结构
    'batch_size' => 1000 // 分批处理大小
]

返回数据结构：

[
    'backup_id' => 123,
    'backup_name' => 'cleanup_backup_20241216_143022',
    'backup_path' => '/storage/app/cleanup/backups/2024/12/16/backup_143022_abc123.sql.gz',
    'backup_size' => 2048576, // 字节
    'tables_count' => 15,
    'records_count' => 125000,
    'status' => 'completed'
]

2.1.8 恢复数据备份

/**
 * 恢复数据备份
 *
 * @param int $backupId 备份ID
 * @param array $restoreOptions 恢复选项
 * @return array 恢复结果
 */
public static function restoreBackup(int $backupId, array $restoreOptions = []): array

2.2 PlanService

2.2.1 获取清理计划列表

/**
 * 获取清理计划列表
 *
 * @param array $filters 筛选条件
 * @return array 计划列表
 */
public static function getCleanupPlans(array $filters = []): array

2.2.2 获取计划详情

/**
 * 获取计划详情包含内容
 *
 * @param int $planId 计划ID
 * @return array 计划详情
 */
public static function getPlanWithContents(int $planId): array

2.2.3 更新计划内容

/**
 * 更新计划的内容配置
 *
 * @param int $planId 计划ID
 * @param array $contents 内容配置
 * @return bool 更新结果
 */
public static function updatePlanContents(int $planId, array $contents): bool

内容配置示例：

[
    [
        'table_name' => 'kku_farm_users',
        'cleanup_type' => 3, // 按时间删除
        'conditions' => [
            'time_field' => 'created_at',
            'before' => '90_days_ago'
        ],
        'priority' => 100,
        'backup_enabled' => true,
        'notes' => '保留90天内的农场用户数据'
    ],
    [
        'table_name' => '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' => '清理指定测试用户的物品数据'
    ],
    [
        'table_name' => 'kku_cache',
        'cleanup_type' => 1, // 清空表
        'conditions' => null,
        'priority' => 400,
        'backup_enabled' => false,
        'notes' => '缓存表直接清空'
    ]
]

2.2.4 配置单个表

/**
 * 配置单个表的清理方式
 *
 * @param int $planId 计划ID
 * @param string $tableName 表名
 * @param array $config 表配置
 * @return bool 配置结果
 */
public static function configureTable(int $planId, string $tableName, array $config): bool

2.2.5 批量配置表

/**
 * 批量配置多个表的清理方式
 *
 * @param int $planId 计划ID
 * @param array $configTemplate 配置模板
 * @param array $tableNames 表名列表
 * @return array 配置结果
 */
public static function batchConfigureTables(int $planId, array $configTemplate, array $tableNames): array

2.3 ConfigService

2.3.1 获取清理配置

/**
 * 获取表的清理配置
 *
 * @param string|null $tableName 表名，为空则获取所有
 * @return array 配置列表
 */
public static function getCleanupConfigs(?string $tableName = null): array

2.3.2 更新清理配置

/**
 * 更新清理配置
 *
 * @param string $tableName 表名
 * @param array $configData 配置数据
 * @return bool 更新结果
 */
public static function updateCleanupConfig(string $tableName, array $configData): bool

2.3.3 批量更新配置

/**
 * 批量更新清理配置
 *
 * @param array $configs 配置数组
 * @return array 更新结果
 */
public static function batchUpdateConfigs(array $configs): array

2.4 BackupService

2.4.1 获取备份列表

/**
 * 获取备份列表
 *
 * @param array $filters 筛选条件
 * @return array 备份列表
 */
public static function getBackupList(array $filters = []): array

2.4.2 验证备份完整性

/**
 * 验证备份文件完整性
 *
 * @param int $backupId 备份ID
 * @return bool 验证结果
 */
public static function verifyBackupIntegrity(int $backupId): bool

2.4.3 清理过期备份

/**
 * 清理过期备份文件
 *
 * @param int $retentionDays 保留天数
 * @return int 清理的备份数量
 */
public static function cleanExpiredBackups(int $retentionDays = 30): int

3. 后台管理接口 (AdminControllers)

3.1 CleanupPlanController

3.1.1 计划列表页面

/**
 * GET /admin/cleanup/plans
 * 显示清理计划列表
 */
public function index(Content $content): Content

3.1.2 创建计划页面

/**
 * GET /admin/cleanup/plans/create
 * 显示计划创建表单
 */
public function create(Content $content): Content

3.1.3 计划详情页面

/**
 * GET /admin/cleanup/plans/{id}
 * 显示计划详情和内容
 */
public function show($id, Content $content): Content

3.1.4 编辑计划页面

/**
 * GET /admin/cleanup/plans/{id}/edit
 * 显示计划编辑表单
 */
public function edit($id, Content $content): Content

3.1.5 计划内容管理

/**
 * GET /admin/cleanup/plans/{id}/contents
 * 显示计划内容配置页面
 */
public function contents($id, Content $content): Content

3.1.6 更新计划内容

/**
 * PUT /admin/cleanup/plans/{id}/contents
 * 更新计划内容配置
 */
public function updateContents($id, Request $request): JsonResponse

3.1.7 预览计划清理结果

/**
 * POST /admin/cleanup/plans/{id}/preview
 * 预览计划的清理结果
 */
public function preview($id): JsonResponse

3.1.8 表配置管理

/**
 * GET /admin/cleanup/plans/{id}/tables/{table}/config
 * 获取表的配置
 */
public function getTableConfig($id, $table): JsonResponse

/**
 * PUT /admin/cleanup/plans/{id}/tables/{table}/config
 * 更新表的配置
 */
public function updateTableConfig($id, $table, Request $request): JsonResponse

/**
 * POST /admin/cleanup/plans/{id}/tables/batch-config
 * 批量配置表
 */
public function batchConfigTables($id, Request $request): JsonResponse

3.1.9 为计划创建备份

/**
 * POST /admin/cleanup/plans/{id}/backup
 * 为计划创建备份
 */
public function createBackup($id, Request $request): JsonResponse

3.2 CleanupConfigController

3.2.1 配置列表页面

/**
 * GET /admin/cleanup/configs
 * 显示清理配置列表
 */
public function index(Content $content): Content

3.2.2 配置编辑页面

/**
 * GET /admin/cleanup/configs/{id}/edit
 * 显示配置编辑表单
 */
public function edit($id, Content $content): Content

3.2.3 批量操作

/**
 * POST /admin/cleanup/configs/batch
 * 批量更新配置
 */
public function batch(Request $request): JsonResponse

3.2.4 扫描表操作

/**
 * POST /admin/cleanup/configs/scan
 * 扫描数据表并生成配置
 */
public function scanTables(Request $request): JsonResponse

3.3 CleanupTaskController

3.3.1 任务列表页面

/**
 * GET /admin/cleanup/tasks
 * 显示清理任务列表
 */
public function index(Content $content): Content

3.3.2 基于计划创建任务

/**
 * POST /admin/cleanup/plans/{planId}/tasks
 * 基于计划创建清理任务
 */
public function createFromPlan($planId, Request $request): JsonResponse

3.3.3 任务详情页面

/**
 * GET /admin/cleanup/tasks/{id}
 * 显示任务详情
 */
public function show($id, Content $content): Content

3.3.4 执行清理任务

/**
 * POST /admin/cleanup/tasks/{id}/execute
 * 执行清理任务
 */
public function execute($id, Request $request): JsonResponse

3.3.5 获取任务进度

/**
 * GET /admin/cleanup/tasks/{id}/progress
 * 获取任务执行进度
 */
public function progress($id): JsonResponse

3.3.6 停止任务执行

/**
 * POST /admin/cleanup/tasks/{id}/stop
 * 停止任务执行
 */
public function stop($id): JsonResponse

3.4 CleanupLogController

3.4.1 日志列表页面

/**
 * GET /admin/cleanup/logs
 * 显示清理日志列表
 */
public function index(Content $content): Content

3.4.2 日志详情页面

/**
 * GET /admin/cleanup/logs/{id}
 * 显示日志详情
 */
public function show($id, Content $content): Content

3.4.3 统计报告页面

/**
 * GET /admin/cleanup/reports
 * 显示统计报告
 */
public function reports(Content $content): Content

3.5 CleanupBackupController

3.5.1 备份列表页面

/**
 * GET /admin/cleanup/backups
 * 显示备份列表
 */
public function index(Content $content): Content

3.4.2 备份详情页面

/**
 * GET /admin/cleanup/backups/{id}
 * 显示备份详情
 */
public function show($id, Content $content): Content

3.4.3 创建备份

/**
 * POST /admin/cleanup/backups
 * 创建数据备份
 */
public function store(Request $request): JsonResponse

3.4.4 下载备份文件

/**
 * GET /admin/cleanup/backups/{id}/download
 * 下载备份文件
 */
public function download($id): Response

3.4.5 恢复备份

/**
 * POST /admin/cleanup/backups/{id}/restore
 * 恢复备份数据
 */
public function restore($id, Request $request): JsonResponse

3.4.6 验证备份

/**
 * POST /admin/cleanup/backups/{id}/verify
 * 验证备份完整性
 */
public function verify($id): JsonResponse

3.4.7 删除备份

/**
 * DELETE /admin/cleanup/backups/{id}
 * 删除备份文件
 */
public function destroy($id): JsonResponse

4. 命令行接口 (Commands)

4.1 CleanupDataCommand

# 扫描数据表
php artisan cleanup:scan-tables [--force]

# 创建清理计划
php artisan cleanup:create-plan [plan_name] [--type=] [--modules=] [--categories=] [--tables=]

# 查看计划详情
php artisan cleanup:show-plan [plan_id]

# 为计划生成内容
php artisan cleanup:generate-contents [plan_id] [--auto]

# 配置表的清理方式
php artisan cleanup:config-table [plan_id] [table_name] [--type=] [--conditions=] [--priority=] [--backup]

# 批量配置表
php artisan cleanup:batch-config [plan_id] [--template=] [--tables=]

# 基于计划创建任务
php artisan cleanup:create-task [plan_id] [--name=] [--execute]

# 执行清理任务
php artisan cleanup:execute [task_id] [--dry-run] [--force]

# 查看任务状态
php artisan cleanup:task-status [task_id]

# 为计划创建备份
php artisan cleanup:backup-plan [plan_id] [--type=sql] [--compression=gzip]

# 恢复数据备份
php artisan cleanup:restore-backup [backup_id] [--force]

# 验证备份完整性
php artisan cleanup:verify-backup [backup_id]

# 清理过期备份
php artisan cleanup:clean-backups [--days=30]

# 清理历史日志
php artisan cleanup:clean-logs [--days=30]

4.2 命令参数说明

4.2.1 cleanup:scan-tables

• --force: 强制重新扫描所有表

4.2.2 cleanup:create-plan

• --type: 清理类型 (1:全量, 2:模块, 3:分类, 4:自定义)
• --modules: 目标模块列表 (逗号分隔)
• --categories: 目标分类列表 (逗号分隔)
• --tables: 目标表列表 (逗号分隔)
• --exclude-tables: 排除表列表 (逗号分隔)
• --exclude-modules: 排除模块列表 (逗号分隔)

4.2.3 cleanup:config-table

• plan_id: 计划ID
• table_name: 表名
• --type: 清理类型 (1:清空表, 2:删除所有, 3:按时间, 4:按用户, 5:按条件)
• --time-field: 时间字段名（type=3时使用）
• --before: 时间条件（type=3时使用）
• --user-field: 用户字段名（type=4时使用）
• --users: 用户ID列表（type=4时使用，逗号分隔）
• --conditions: JSON格式的自定义条件（type=5时使用）
• --priority: 优先级（数字）
• --backup: 启用备份
• --no-backup: 禁用备份

4.2.4 cleanup:batch-config

• plan_id: 计划ID
• --template: 配置模板JSON文件路径
• --tables: 表名列表（逗号分隔）
• --type: 批量设置的清理类型
• --backup: 批量启用备份

4.2.5 cleanup:create-task

• plan_id: 计划ID
• --name: 任务名称（可选，默认自动生成）
• --execute: 创建后立即执行

4.2.4 cleanup:execute

• task_id: 任务ID
• --dry-run: 预演模式，不实际执行
• --force: 强制执行，跳过确认

5. 数据传输对象 (DTOs)

5.1 CleanupPlanDto

class CleanupPlanDto extends BaseDto
{
    public int $id;
    public string $planName;
    public int $planType;
    public ?array $targetSelection;
    public ?array $globalConditions;
    public ?array $backupConfig;
    public bool $isTemplate;
    public bool $isEnabled;
    public ?string $description;
    public ?int $createdBy;
    public string $createdAt;
    public string $updatedAt;
}

5.2 CleanupPlanContentDto

class CleanupPlanContentDto extends BaseDto
{
    public int $id;
    public int $planId;
    public string $tableName;
    public int $cleanupType;
    public ?array $conditions;
    public int $priority;
    public int $batchSize;
    public bool $isEnabled;
    public bool $backupEnabled;
    public ?string $notes;
    public string $createdAt;
    public string $updatedAt;
}

5.3 CleanupTaskDto

class CleanupTaskDto extends BaseDto
{
    public int $id;
    public string $taskName;
    public int $planId;
    public ?int $backupId;
    public int $status;
    public float $progress;
    public ?string $currentStep;
    public int $totalTables;
    public int $processedTables;
    public int $totalRecords;
    public int $deletedRecords;
    public int $backupSize;
    public float $executionTime;
    public float $backupTime;
    public ?string $startedAt;
    public ?string $backupCompletedAt;
    public ?string $completedAt;
    public ?string $errorMessage;
    public ?int $createdBy;
    public string $createdAt;
    public string $updatedAt;
}

5.4 CleanupConfigDto

class CleanupConfigDto extends BaseDto
{
    public int $id;
    public string $tableName;
    public string $moduleName;
    public int $dataCategory;
    public int $defaultCleanupType;
    public ?array $defaultConditions;
    public bool $isEnabled;
    public int $priority;
    public int $batchSize;
    public ?string $description;
    public ?string $lastCleanupAt;
    public string $createdAt;
    public string $updatedAt;
}

5.5 CleanupLogDto

class CleanupLogDto extends BaseDto
{
    public int $id;
    public int $taskId;
    public string $tableName;
    public string $operationType;
    public int $recordsBefore;
    public int $recordsAfter;
    public int $recordsAffected;
    public float $executionTime;
    public ?array $conditionsUsed;
    public ?string $sqlStatement;
    public int $status;
    public ?string $errorMessage;
    public string $createdAt;
}

5.6 CleanupBackupDto

class CleanupBackupDto extends BaseDto
{
    public int $id;
    public int $planId;
    public ?int $taskId;
    public string $backupName;
    public int $backupType;
    public int $compressionType;
    public string $backupPath;
    public int $backupSize;
    public int $originalSize;
    public int $tablesCount;
    public int $recordsCount;
    public int $backupStatus;
    public ?string $backupHash;
    public ?array $backupConfig;
    public ?string $startedAt;
    public ?string $completedAt;
    public ?string $expiresAt;
    public ?string $errorMessage;
    public ?int $createdBy;
    public string $createdAt;
    public string $updatedAt;
}

5.7 CleanupBackupFileDto

class CleanupBackupFileDto extends BaseDto
{
    public int $id;
    public int $backupId;
    public string $tableName;
    public string $filePath;
    public int $fileSize;
    public int $recordsCount;
    public ?string $fileHash;
    public ?array $backupConditions;
    public string $createdAt;
}

6. 错误码定义

6.1 配置相关错误

• CLEANUP_CONFIG_NOT_FOUND (10001): 清理配置不存在
• CLEANUP_CONFIG_INVALID (10002): 清理配置无效
• CLEANUP_TABLE_NOT_EXISTS (10003): 数据表不存在

6.2 计划相关错误

• CLEANUP_PLAN_NOT_FOUND (11001): 清理计划不存在
• CLEANUP_PLAN_NAME_EXISTS (11002): 计划名称已存在
• CLEANUP_PLAN_INVALID (11003): 计划配置无效
• CLEANUP_PLAN_CONTENT_EMPTY (11004): 计划内容为空
• CLEANUP_PLAN_DISABLED (11005): 计划已禁用

6.3 任务相关错误

• CLEANUP_TASK_NOT_FOUND (20001): 清理任务不存在
• CLEANUP_TASK_RUNNING (20002): 任务正在执行中
• CLEANUP_TASK_FAILED (20003): 任务执行失败
• CLEANUP_TASK_PLAN_MISMATCH (20004): 任务与计划不匹配

6.4 权限相关错误

• CLEANUP_PERMISSION_DENIED (30001): 没有清理权限
• CLEANUP_DANGEROUS_OPERATION (30002): 危险操作需要确认

6.5 执行相关错误

• CLEANUP_EXECUTION_FAILED (40001): 清理执行失败
• CLEANUP_SQL_ERROR (40002): SQL执行错误
• CLEANUP_TIMEOUT (40003): 清理超时
• CLEANUP_BACKUP_REQUIRED (40004): 需要先创建备份

6.6 备份相关错误

• BACKUP_CREATE_FAILED (50001): 备份创建失败
• BACKUP_NOT_FOUND (50002): 备份文件不存在
• BACKUP_CORRUPTED (50003): 备份文件损坏
• BACKUP_RESTORE_FAILED (50004): 备份恢复失败
• BACKUP_STORAGE_FULL (50005): 备份存储空间不足
• BACKUP_PERMISSION_DENIED (50006): 备份文件权限不足
• BACKUP_PLAN_MISMATCH (50007): 备份与计划不匹配