"""存储服务抽象（扩展接口 2：本地文件 → MinIO/S3）。"""

from typing import Protocol, runtime_checkable


@runtime_checkable
class StorageService(Protocol):
    """文件存储统一接口。所有业务代码通过此接口读写文件，禁止直接 open()/Path()。"""

    def save(self, key: str, data: bytes) -> str:
        """保存数据，返回实际存储路径。"""
        ...

    def read(self, key: str) -> bytes:
        """读取数据。"""
        ...

    def delete(self, key: str) -> None:
        """删除文件。"""
        ...

    def exists(self, key: str) -> bool:
        """文件是否存在。"""
        ...

    def get_size(self, key: str) -> int:
        """获取文件大小（字节）。"""
        ...