TeamAAS-2.5/TeamAAS.Base/TeamAAS.Database/Interfaces/IDatabase.cs

using System;
using System.Collections.Generic;
using System.Data;
using System.Threading.Tasks;
using TeamAAS.Database.Models;

namespace TeamAAS.Database.Interfaces
{
    /// <summary>
    /// 数据库操作统一接口。
    /// 所有数据库提供者（MySQL、SQLite、SQL Server 等）均需实现此接口。
    /// </summary>
    public interface IDatabase : IDisposable
    {
        /// <summary>
        /// 数据库唯一标识
        /// </summary>
        Guid Id { get; }

        /// <summary>
        /// 数据库名称（显示用）
        /// </summary>
        string Name { get; set; }

        /// <summary>
        /// 数据库类型标识（如 "mysql"、"sqlite"）
        /// </summary>
        string ProviderType { get; }

        /// <summary>
        /// 是否已连接
        /// </summary>
        bool IsConnected { get; }

        /// <summary>
        /// 当前连接字符串（敏感信息已脱敏）
        /// </summary>
        string ConnectionString { get; }

        /// <summary>
        /// 打开数据库连接
        /// </summary>
        bool Open();

        /// <summary>
        /// 异步打开数据库连接
        /// </summary>
        Task<bool> OpenAsync();

        /// <summary>
        /// 关闭数据库连接
        /// </summary>
        void Close();

        /// <summary>
        /// 异步关闭数据库连接
        /// </summary>
        Task CloseAsync();

        /// <summary>
        /// 测试连接是否可用
        /// </summary>
        (bool Success, string Message) TestConnection();

        /// <summary>
        /// 异步测试连接
        /// </summary>
        Task<(bool Success, string Message)> TestConnectionAsync();

        /// <summary>
        /// 执行非查询 SQL（INSERT/UPDATE/DELETE/CREATE 等）
        /// </summary>
        /// <param name="sql">SQL 语句</param>
        /// <param name="parameters">参数字典（可选）</param>
        /// <returns>受影响行数</returns>
        int ExecuteNonQuery(string sql, IDictionary<string, object> parameters = null);

        /// <summary>
        /// 异步执行非查询 SQL
        /// </summary>
        Task<int> ExecuteNonQueryAsync(string sql, IDictionary<string, object> parameters = null);

        /// <summary>
        /// 执行查询，返回 DataTable
        /// </summary>
        /// <param name="sql">SQL 查询语句</param>
        /// <param name="parameters">参数字典（可选）</param>
        /// <returns>查询结果表</returns>
        DataTable ExecuteQuery(string sql, IDictionary<string, object> parameters = null);

        /// <summary>
        /// 异步执行查询，返回 DataTable
        /// </summary>
        Task<DataTable> ExecuteQueryAsync(string sql, IDictionary<string, object> parameters = null);

        /// <summary>
        /// 执行查询，返回首行首列的值
        /// </summary>
        /// <param name="sql">SQL 查询语句</param>
        /// <param name="parameters">参数字典（可选）</param>
        /// <returns>首行首列值，无结果时返回 null</returns>
        object ExecuteScalar(string sql, IDictionary<string, object> parameters = null);

        /// <summary>
        /// 异步执行查询，返回首行首列的值
        /// </summary>
        Task<object> ExecuteScalarAsync(string sql, IDictionary<string, object> parameters = null);

        /// <summary>
        /// 执行事务内的多条 SQL
        /// </summary>
        /// <param name="sqlCommands">SQL 语句列表</param>
        /// <returns>是否全部执行成功</returns>
        bool ExecuteTransaction(IEnumerable<string> sqlCommands);

        /// <summary>
        /// 异步执行事务
        /// </summary>
        Task<bool> ExecuteTransactionAsync(IEnumerable<string> sqlCommands);

        /// <summary>
        /// 获取所有表名
        /// </summary>
        List<string> GetTableNames();

        /// <summary>
        /// 异步获取所有表名
        /// </summary>
        Task<List<string>> GetTableNamesAsync();

        /// <summary>
        /// 获取指定表的列信息
        /// </summary>
        /// <param name="tableName">表名</param>
        /// <returns>列信息列表</returns>
        List<ColumnInfo> GetTableSchema(string tableName);

        /// <summary>
        /// 异步获取表结构
        /// </summary>
        Task<List<ColumnInfo>> GetTableSchemaAsync(string tableName);

        /// <summary>
        /// 初始化连接配置
        /// </summary>
        /// <param name="config">数据库配置</param>
        void Configure(DatabaseConfig config);
    }
}