首次提交：初始化项目代码

internal/domain/file/repository/file_repository.go

@@ -0,0 +1,144 @@
+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)
+}