junhong_cmp_fiber/openspec/changes/archive/2026-02-10-polling-system-implementation/specs/data-cleanup/spec.md

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 日志，包含已删除数量、剩余数量