//! 设备日志保留策略协程
//!
//! 业务背景：`device_logs` 是**只增不减**的表 —— `status_post` 每台柜子每 60 秒写一条，
//! 加上 `bat_in`/`bat_out`/停电/回执等事件，量级随时间线性增长且**原本没有任何清理策略**，
//! 长期会把 RDS 撑满（磁盘告警、备份变慢、查询变慢）。
//!
//! 本协程按**保留天数**定期分批删除过期日志：
//! - **分批 `DELETE ... LIMIT`**：避免一条大删除造成长事务、锁表、主从延迟；
//! - 单轮有**最大批数上限**：防止积压过多时一轮跑太久；
//! - 所有异常只记日志，**绝不让循环退出**（清理是运维保障，不能反过来拖垮服务）。
//!
//! 依赖索引 `device_logs(created_at)`（由 `db::migrate` 幂等创建）—— 否则每次删除都会全表扫描。

use std::time::Duration;

use sqlx::MySqlPool;

/// 日志保留天数：超过该天数的 `device_logs` 会被清理。
///
/// 取 90 天的理由：设备日志主要服务于"最近出了什么问题"的排障，
/// 3 个月足够回溯；再久的数据排障价值低，但存储成本持续累积。
const RETENTION_DAYS: i64 = 90;

/// 单批删除行数：控制单条 SQL 的影响行数，避免长事务
const BATCH_LIMIT: i64 = 5000;

/// 单轮最多删多少批：积压很多时一轮也不会跑太久，剩下的等下一轮
const MAX_BATCHES_PER_ROUND: usize = 20;

/// 执行间隔：6 小时一次即可（保留策略对时效性不敏感，低频更省资源）
const SCAN_INTERVAL_SECS: u64 = 6 * 3600;

/// 启动设备日志保留协程（由 main.rs 以 tokio::spawn 启动，常驻运行）
pub async fn start(pool: MySqlPool) {
    tracing::info!(
        "[log_retention] 启动设备日志清理，保留 {} 天，执行间隔 {}s，单批 {} 行",
        RETENTION_DAYS,
        SCAN_INTERVAL_SECS,
        BATCH_LIMIT
    );

    loop {
        // 单轮失败不退出：记 error 后等下一个周期继续
        if let Err(e) = purge_once(&pool).await {
            tracing::error!("[log_retention] 本轮清理失败，等待下轮重试: {}", e);
        }
        tokio::time::sleep(Duration::from_secs(SCAN_INTERVAL_SECS)).await;
    }
}

/// 单轮清理：分批删除 `created_at` 早于 `NOW() - RETENTION_DAYS` 的日志。
///
/// 返回删掉的总行数（便于日志与测试断言）；SQL 失败向上抛，由调用方记录并继续循环。
async fn purge_once(pool: &MySqlPool) -> Result<u64, sqlx::Error> {
    let mut total: u64 = 0;

    for _ in 0..MAX_BATCHES_PER_ROUND {
        // 阈值交给 MySQL 计算（created_at 也是 MySQL 写的），避免本地时区换算偏差；
        // 用 TIMESTAMPADD 而非 INTERVAL 字面量，确保阈值能以 ? 绑定（不拼 SQL）。
        let affected = sqlx::query(
            "DELETE FROM device_logs \
             WHERE created_at < TIMESTAMPADD(DAY, ?, NOW()) \
             LIMIT ?",
        )
        .bind(-RETENTION_DAYS)
        .bind(BATCH_LIMIT)
        .execute(pool)
        .await?
        .rows_affected();

        total += affected;

        // 本批不足一批 → 已删完，提前结束
        if affected < BATCH_LIMIT as u64 {
            break;
        }

        // 批间短暂让出，避免长时间占满数据库连接
        tokio::time::sleep(Duration::from_millis(200)).await;
    }

    if total > 0 {
        tracing::info!(
            "[log_retention] 已清理过期设备日志 {} 行（保留 {} 天）",
            total,
            RETENTION_DAYS
        );
    } else {
        tracing::debug!("[log_retention] 无过期设备日志需要清理");
    }

    Ok(total)
}

#[cfg(test)]
mod tests {
    use super::*;

    /// 保留策略的常量约束：必须是正数、批大小与批数上限在合理区间，
    /// 避免误改成 0 天（清空全部）或超大值（一次锁表）
    #[test]
    fn test_retention_constants_are_sane() {
        assert!(RETENTION_DAYS > 0, "保留天数必须为正，否则会清空全部日志");
        assert!(BATCH_LIMIT > 0 && BATCH_LIMIT <= 50_000, "单批行数需在合理区间");
        assert!(MAX_BATCHES_PER_ROUND > 0, "每轮至少允许一批");
        assert!(SCAN_INTERVAL_SECS >= 60, "清理间隔不应过于频繁");
    }
}