package com.easyagents.federation.sql.federation;

import com.easyagents.federation.sql.source.SourceId;

/**
 * 为联邦编译提供轻量、无数据库查询副作用的表统计快照。
 *
 * <p>实现必须直接返回已冻结快照，不得在编译热路径执行 {@code COUNT(*)}。统计数据变化时，
 * 快照版本必须同步变化，使节点本地计划缓存自然隔离旧成本计划。</p>
 */
@FunctionalInterface
public interface FederationTableStatisticsProvider {

    /**
     * 捕获一次编译使用的不可变统计快照。
     *
     * @return 同时冻结版本、数据与有效期的快照
     */
    FederationStatisticsSnapshot snapshot();

    /**
     * 查询当前快照中的一张物理表统计。
     *
     * <p>编译器会先捕获一次 {@link #snapshot()} 并复用，调用方仅应将本方法用于诊断读取。</p>
     *
     * @param sourceId 物理数据源标识
     * @param schema 物理 Schema 名称
     * @param table 物理表名称
     * @return 统计快照；没有可信统计时返回 {@code null}
     */
    default FederationTableStatistics statistics(
        SourceId sourceId,
        String schema,
        String table
    ) {
        return snapshot().statistics(sourceId, schema, table);
    }

    /**
     * 返回当前统计快照版本。
     *
     * @return 非空版本字符串
     */
    default String snapshotVersion() {
        return snapshot().version();
    }

    /**
     * 返回不提供外部统计的实现。
     *
     * @return 空统计 Provider
     */
    static FederationTableStatisticsProvider none() {
        return FederationStatisticsSnapshot::empty;
    }
}
