## ADDED Requirements

### Requirement: 清理配置管理

系统 SHALL 允许管理员配置各表的数据保留天数。

#### Scenario: 创建清理配置

- **WHEN** 管理员创建清理配置，指定表名为 data_usage_records，保留天数为 90 天
- **THEN** 系统创建清理配置并返回配置ID

#### Scenario: 配置多表清理策略

- **WHEN** 管理员为不同表配置不同保留天数（data_usage_records 90天、operation_logs 180天、polling_alert_history 30天）
- **THEN** 系统保存各表的清理配置

#### Scenario: 表名重复

- **WHEN** 管理员创建清理配置，表名与已有配置重复
- **THEN** 系统返回错误，提示该表已有清理配置

#### Scenario: 保留天数无效

- **WHEN** 管理员创建清理配置，保留天数小于 1 或大于 3650（10年）
- **THEN** 系统返回错误，提示保留天数无效

### Requirement: 清理配置查询

系统 SHALL 提供接口查询清理配置列表和详情。

#### Scenario: 查询所有清理配置

- **WHEN** 管理员请求查询清理配置列表
- **THEN** 系统返回所有配置，包含配置ID、表名、保留天数、启用状态、最后清理时间

#### Scenario: 查询启用的配置

- **WHEN** 管理员请求查询启用的清理配置
- **THEN** 系统只返回状态为启用的配置

#### Scenario: 查询单个配置详情

- **WHEN** 管理员请求查询配置ID为 1 的详情
- **THEN** 系统返回配置的完整信息，包含历史清理记录

#### Scenario: 配置不存在

- **WHEN** 管理员请求查询不存在的配置ID
- **THEN** 系统返回错误，提示配置不存在

### Requirement: 清理配置更新

系统 SHALL 允许管理员更新清理配置。

#### Scenario: 更新保留天数

- **WHEN** 管理员更新配置，将保留天数从 90 天修改为 180 天
- **THEN** 系统更新配置，下次清理使用新保留天数

#### Scenario: 更新不存在的配置

- **WHEN** 管理员尝试更新不存在的配置ID
- **THEN** 系统返回错误，提示配置不存在

### Requirement: 清理配置删除

系统 SHALL 允许管理员删除清理配置（软删除）。

#### Scenario: 删除配置

- **WHEN** 管理员删除清理配置
- **THEN** 系统软删除配置，停止清理该表

#### Scenario: 删除不存在的配置

- **WHEN** 管理员尝试删除不存在的配置ID
- **THEN** 系统返回错误，提示配置不存在

### Requirement: 启用/禁用清理配置

系统 SHALL 提供接口快捷启用或禁用清理配置。

#### Scenario: 禁用配置

- **WHEN** 管理员禁用配置ID为 1 的配置
- **THEN** 系统更新配置状态为禁用，停止清理该表

#### Scenario: 启用配置

- **WHEN** 管理员启用配置ID为 1 的配置
- **THEN** 系统更新配置状态为启用，恢复清理该表

### Requirement: 定时清理任务

系统 SHALL 每日凌晨 2 点执行数据清理任务。

#### Scenario: 定时触发清理

- **WHEN** 每日凌晨 2 点
- **THEN** 系统自动触发清理任务（使用 Cron 定时任务）

#### Scenario: 遍历所有启用配置

- **WHEN** 清理任务执行
- **THEN** 系统从数据库读取所有启用的清理配置，逐个执行清理

#### Scenario: 跳过禁用配置

- **WHEN** 清理到某配置状态为禁用
- **THEN** 系统跳过该配置，继续清理下一个

### Requirement: 流量历史记录清理

系统 SHALL 清理 data_usage_records 表的过期数据。

#### Scenario: 计算清理截止时间

- **WHEN** 清理配置保留天数为 90 天
- **THEN** 系统计算截止时间为 NOW() - 90天

#### Scenario: 删除过期记录

- **WHEN** 执行清理，截止时间为 2024-01-01
- **THEN** 系统执行 `DELETE FROM data_usage_records WHERE recorded_at < '2024-01-01'`

#### Scenario: 分批删除

- **WHEN** 过期记录数量巨大（如 1000 万条）
- **THEN** 系统分批删除（每批 10 万条），避免长时间锁表，每批删除后 sleep 1秒

#### Scenario: 记录清理数量

- **WHEN** 清理完成
- **THEN** 系统记录本次清理删除的记录数量

### Requirement: 操作日志清理

系统 SHALL 清理 operation_logs 表的过期数据。

#### Scenario: 清理过期操作日志

- **WHEN** 执行清理，保留天数为 180 天
- **THEN** 系统删除 created_at < NOW() - 180天 的操作日志

#### Scenario: 保留关键操作日志

- **WHEN** 清理操作日志，某些关键操作（如删除账号、权限变更）需要永久保留
- **THEN** 系统在删除条件中排除这些操作类型

### Requirement: 告警历史清理

系统 SHALL 清理 polling_alert_history 表的过期数据。

#### Scenario: 清理过期告警历史

- **WHEN** 执行清理，保留天数为 30 天
- **THEN** 系统删除 triggered_at < NOW() - 30天 的告警历史

#### Scenario: 保留统计数据

- **WHEN** 清理告警历史后
- **THEN** 系统保留月度/年度统计数据（聚合表）

### Requirement: 手动触发清理

系统 SHALL 支持管理员手动触发清理任务。

#### Scenario: 手动清理单表

- **WHEN** 管理员请求手动清理 data_usage_records 表
- **THEN** 系统立即执行该表的清理任务，使用当前配置的保留天数

#### Scenario: 手动清理所有表

- **WHEN** 管理员请求手动清理所有表
- **THEN** 系统遍历所有启用的清理配置，逐个执行清理

#### Scenario: 手动清理异步执行

- **WHEN** 管理员触发手动清理
- **THEN** 系统返回任务ID，清理任务异步执行（Asynq 队列），管理员可查询进度

#### Scenario: 手动清理指定时间范围

- **WHEN** 管理员请求清理 2023-01-01 到 2023-12-31 的数据
- **THEN** 系统使用指定时间范围执行清理，忽略配置的保留天数

### Requirement: 清理任务监控

系统 SHALL 记录清理任务的执行情况。

#### Scenario: 记录清理开始

- **WHEN** 清理任务开始执行
- **THEN** 系统插入清理记录到 tb_data_cleanup_log 表，包含配置ID、表名、开始时间

#### Scenario: 记录清理完成

- **WHEN** 清理任务完成
- **THEN** 系统更新清理记录，包含删除记录数、结束时间、耗时

#### Scenario: 记录清理失败

- **WHEN** 清理任务因错误失败
- **THEN** 系统更新清理记录，标记状态为失败，记录错误信息

#### Scenario: 记录清理跳过

- **WHEN** 清理配置被禁用，跳过清理
- **THEN** 系统记录清理记录，标记状态为跳过

### Requirement: 清理进度查询

系统 SHALL 提供接口查询清理任务的进度。

#### Scenario: 查询正在执行的清理

- **WHEN** 管理员查询清理进度，清理任务正在执行
- **THEN** 系统返回当前清理的表名、已删除记录数、预计剩余时间

#### Scenario: 查询清理历史

- **WHEN** 管理员查询清理历史
- **THEN** 系统返回最近 30 次清理记录，包含表名、删除数量、耗时、状态

#### Scenario: 清理未开始

- **WHEN** 管理员查询清理进度，清理任务未开始
- **THEN** 系统返回状态为"未开始"

#### Scenario: 清理已完成

- **WHEN** 管理员查询清理进度，清理任务已完成
- **THEN** 系统返回状态为"已完成"，包含总删除数量、总耗时

### Requirement: 清理预览

系统 SHALL 提供接口预览清理将删除的数据量，不实际执行删除。

#### Scenario: 预览单表清理

- **WHEN** 管理员请求预览 data_usage_records 表的清理
- **THEN** 系统执行 `SELECT COUNT(*) FROM data_usage_records WHERE recorded_at < ?`，返回将删除的记录数

#### Scenario: 预览所有表清理

- **WHEN** 管理员请求预览所有表的清理
- **THEN** 系统返回各表将删除的记录数和占比

#### Scenario: 预览不同保留天数

- **WHEN** 管理员请求预览使用不同保留天数（如 30、60、90 天）的清理效果
- **THEN** 系统返回各保留天数对应的删除记录数

### Requirement: 清理安全防护

系统 SHALL 提供安全防护机制，避免误删重要数据。

#### Scenario: 防止清理最近数据

- **WHEN** 清理配置的保留天数为 7 天，少于最小保留天数（30 天）
- **THEN** 系统拒绝执行清理，返回错误

#### Scenario: 防止全表删除

- **WHEN** 计算清理截止时间大于当前时间（配置错误）
- **THEN** 系统拒绝执行清理，返回错误，提示配置异常

#### Scenario: 二次确认

- **WHEN** 管理员手动触发清理，预计删除数量超过 100 万
- **THEN** 系统要求管理员二次确认

#### Scenario: 备份提醒

- **WHEN** 执行清理前
- **THEN** 系统在日志中记录提醒，建议管理员确认已备份重要数据

### Requirement: 清理回滚

系统 SHALL 支持清理操作的回滚（如果数据已备份）。

#### Scenario: 记录清理详情

- **WHEN** 执行清理
- **THEN** 系统记录被删除数据的ID范围、时间范围，便于后续恢复

#### Scenario: 从备份恢复

- **WHEN** 管理员发现误删数据
- **THEN** 管理员可从数据库备份中恢复指定时间范围的数据

### Requirement: 日志记录

系统 SHALL 记录清理任务的详细日志。

#### Scenario: 记录清理开始日志

- **WHEN** 清理任务开始
- **THEN** 系统记录 Info 日志，包含配置ID、表名、保留天数、截止时间

#### Scenario: 记录清理完成日志

- **WHEN** 清理任务完成
- **THEN** 系统记录 Info 日志，包含删除记录数、耗时

#### Scenario: 记录清理失败日志

- **WHEN** 清理任务失败
- **THEN** 系统记录 Error 日志，包含错误详情

#### Scenario: 记录分批进度日志

- **WHEN** 清理大量数据，分批执行
- **THEN** 系统每批次记录 Debug 日志，包含已删除数量、剩余数量