using TakeoutSaaS.Module.Storage.Models;

namespace TakeoutSaaS.Module.Storage.Abstractions;

/// <summary>
/// 对象存储提供商统一抽象。
/// </summary>
public interface IObjectStorageProvider
{
    /// <summary>
    /// 当前提供商类型。
    /// </summary>
    StorageProviderKind Kind { get; }

    /// <summary>
    /// 上传文件到对象存储。
    /// </summary>
    Task<StorageUploadResult> UploadAsync(StorageUploadRequest request, CancellationToken cancellationToken = default);

    /// <summary>
    /// 生成预签名直传参数（PUT 或表单直传）。
    /// </summary>
    Task<StorageDirectUploadResult> CreateDirectUploadAsync(StorageDirectUploadRequest request, CancellationToken cancellationToken = default);

    /// <summary>
    /// 生成带过期时间的访问链接。
    /// </summary>
    Task<string> GenerateDownloadUrlAsync(string objectKey, TimeSpan expires, CancellationToken cancellationToken = default);

    /// <summary>
    /// 生成公共访问地址（可结合 CDN）。
    /// </summary>
    string BuildPublicUrl(string objectKey);
}