package com.agent.management.service;

import java.util.List;
import java.util.Map;

/**
 * 数据库 schema 探索 + SQL 查询服务
 */
public interface SchemaExplorerService {

    /**
     * 列出数据源下所有 schema/catalog
     */
    List<String> listSchemas(Long datasourceId);

    /**
     * 列出指定 schema 下的所有表
     */
    List<TableSummary> listTables(Long datasourceId, String schema);

    /**
     * 描述表字段
     */
    List<ColumnSpec> describeTable(Long datasourceId, String schema, String table);
    List<ForeignKeySpec> listForeignKeys(Long datasourceId, String schema, String table);

    /**
     * 表行数统计（近似值）
     */
    long countRows(Long datasourceId, String schema, String table);

    /**
     * 执行白名单 SQL 查询
     *
     * @param sql           已通过 SqlGuard 校验
     * @param limitOverride 自定义行数限制（<=maxRows）
     * @return 查询结果（列名 + 数据行）
     */
    QueryResult executeQuery(Long datasourceId, String sql, Integer limitOverride);

    default void explainQuery(Long datasourceId, String sql) {
        executeQuery(datasourceId, "EXPLAIN " + sql, 1);
    }

    /**
     * 预览表数据（自动生成安全 SELECT）
     *
     * @param table 表名
     * @param schema catalog/schema（可选）
     * @param limit 最大返回行数（<=maxRows）
     * @return 查询结果（列名 + 数据行）
     */
    QueryResult previewTableData(Long datasourceId, String schema, String table, Integer limit);

    // ===== DTO =====
    record TableSummary(String name, String type, String remarks) {}
    record ColumnSpec(String name, String type, int size, boolean nullable, String remarks) {}
    record ForeignKeySpec(String name, String sourceTable, String sourceColumn, String targetTable, String targetColumn) {}
    record QueryResult(List<String> columns, List<List<Object>> rows, long executionTimeMs) {}
}
