package repository

import "io"

// FileInfo contains metadata for a file.
// FileInfo 包含文件的元数据。
//
// Fields:
//   - Key: The storage key/path of the file.
//   - Size: The file size in bytes.
//   - LastModified: The timestamp when the file was last modified.
//
// 字段:
//   - Key: 文件的存储键/路径。
//   - Size: 文件大小（字节）。
//   - LastModified: 文件最后修改的时间戳。
type FileInfo struct {
	Key          string
	Size         int64
	LastModified string
}

// FileRepository defines the interface for file storage operations.
// FileRepository 定义了文件存储操作的接口。
//
// This interface follows the Dependency Inversion Principle (DIP),
// where the application layer depends on this abstraction rather than concrete implementations.
//
// 此接口遵循依赖倒置原则（DIP），应用层依赖于这个抽象而非具体实现。
type FileRepository interface {
	// Upload uploads a file to the object storage.
	// Upload 将文件上传到对象存储。
	//
	// Parameters:
	//   - bucket: The target bucket name.
	//   - objectName: The unique name/path for the object.
	//   - reader: The file content reader.
	//   - size: The size of the file in bytes.
	//   - contentType: The MIME type of the file.
	//
	// Returns:
	//   - error: An error if the operation fails.
	//
	// 参数:
	//   - bucket: 目标桶名称。
	//   - objectName: 对象的唯一名称/路径。
	//   - reader: 文件内容读取器。
	//   - size: 文件大小（字节）。
	//   - contentType: 文件的 MIME 类型。
	//
	// 返回值:
	//   - error: 如果操作失败则返回错误。
	Upload(bucket, objectName string, reader io.Reader, size int64, contentType string) error

	// List retrieves a list of files under the specified prefix with metadata.
	// List 获取指定前缀下的文件列表及其元数据。
	//
	// Parameters:
	//   - bucket: The bucket name.
	//   - prefix: The prefix/path to filter files.
	//
	// Returns:
	//   - []FileInfo: A list of file information including key, size, and last modified time.
	//   - error: An error if the operation fails.
	//
	// 参数:
	//   - bucket: 桶名称。
	//   - prefix: 用于过滤文件的前缀/路径。
	//
	// 返回值:
	//   - []FileInfo: 文件信息列表，包含键、大小和最后修改时间。
	//   - error: 如果操作失败则返回错误。
	List(bucket, prefix string) ([]FileInfo, error)

	// PresignDownload generates a pre-signed URL for downloading a file.
	// PresignDownload 生成用于下载文件的预签名 URL。
	//
	// Parameters:
	//   - bucket: The bucket name.
	//   - objectName: The name/path of the object.
	//
	// Returns:
	//   - string: The pre-signed download URL.
	//   - error: An error if the operation fails.
	//
	// Note:
	//   - The URL is time-limited and doesn't require authentication.
	//
	// 参数:
	//   - bucket: 桶名称。
	//   - objectName: 对象的名称/路径。
	//
	// 返回值:
	//   - string: 预签名下载 URL。
	//   - error: 如果操作失败则返回错误。
	//
	// 注意:
	//   - URL 有时间限制且不需要认证。
	PresignDownload(bucket, objectName string) (string, error)

	// Delete removes a file from the object storage.
	// Delete 从对象存储中删除文件。
	//
	// Parameters:
	//   - bucket: The bucket name.
	//   - objectName: The name/path of the object to delete.
	//
	// Returns:
	//   - error: An error if the operation fails.
	//
	// 参数:
	//   - bucket: 桶名称。
	//   - objectName: 要删除的对象的名称/路径。
	//
	// 返回值:
	//   - error: 如果操作失败则返回错误。
	Delete(bucket, objectName string) error

	// GetObject retrieves a file as a readable stream from the object storage.
	// GetObject 从对象存储中获取文件的可读流。
	//
	// Parameters:
	//   - bucket: The bucket name.
	//   - objectName: The name/path of the object.
	//
	// Returns:
	//   - io.ReadCloser: A readable stream of the file content. Caller must close it.
	//   - int64: The file size in bytes.
	//   - string: The Content-Type of the file.
	//   - error: An error if the operation fails.
	//
	// 参数:
	//   - bucket: 桶名称。
	//   - objectName: 对象的名称/路径。
	//
	// 返回值:
	//   - io.ReadCloser: 文件内容的可读流。调用方必须关闭它。
	//   - int64: 文件大小（字节）。
	//   - string: 文件的 Content-Type。
	//   - error: 如果操作失败则返回错误。
	GetObject(bucket, objectName string) (io.ReadCloser, int64, string, error)

	GetObjectInfo(bucket, objectName string) (int64, string, error)
}