fiuai-s3 0.1.1__tar.gz → 0.2.1__tar.gz

{fiuai_s3-0.1.1 → fiuai_s3-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiuai-s3
-Version: 0.1.1
+Version: 0.2.1
 Summary: 一个支持阿里云OSS和MinIO的对象存储抽象包
 Project-URL: Homepage, https://github.com/fiuai-sz/fiuai-s3
 Project-URL: Repository, https://github.com/fiuai-sz/fiuai-s3.git
@@ -286,6 +286,60 @@ S3_Client.delete_file("test.txt")
 files = S3_Client.list_files(prefix="test/")
 ```
 
+### 单据文件管理（推荐业务用法）
+
+支持业务身份（auth_tenant_id, auth_company_id, doc_id）在实例初始化时注入（可为空），各操作方法参数可选，若不传则使用实例属性，若传则覆盖。
+
+#### 初始化带业务身份
+```python
+from fiuai_s3 import ObjectStorageFactory
+from fiuai_s3.object_storage import StorageConfig
+
+config = StorageConfig(
+    provider="minio",
+    bucket_name="dev",
+    endpoint="http://127.0.0.1:19000",
+    access_key="devdevdev",
+    secret_key="devdevdev"
+)
+# 业务身份可选
+S3_Client = ObjectStorageFactory.create_storage(
+    config,
+    auth_tenant_id="t1",
+    auth_company_id="c1",
+    doc_id="d1"
+)
+```
+
+#### 上传单据文件
+```python
+# 方法参数可选，优先级高于实例属性
+S3_Client.upload_doc_file(
+    filename="发票.pdf",
+    data=b"...文件内容...",
+    tags={"业务类型": "发票", "年份": "2024"}
+    # auth_tenant_id、auth_company_id、doc_id 可不传，使用实例属性
+)
+```
+
+#### 下载单据文件
+```python
+data = S3_Client.download_doc_file(
+    filename="发票.pdf"
+    # auth_tenant_id、auth_company_id、doc_id 可不传，使用实例属性
+)
+```
+
+#### 列出单据下所有文件
+```python
+files = S3_Client.list_doc_files()
+```
+
+- 存储路径自动为：`bucketname/auth_tenant_id/auth_company_id/doc_id/filename`
+- tags会自动打到对象存储（Alicloud用OSS Tagging，Minio用metadata）
+- 支持实例初始化时设置默认auth_tenant_id、auth_company_id、doc_id，调用时可覆盖
+- 缺失必要参数会抛出异常
+
 ## 配置参数
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |

{fiuai_s3-0.1.1 → fiuai_s3-0.2.1}/README.md

@@ -61,6 +61,60 @@ S3_Client.delete_file("test.txt")
 files = S3_Client.list_files(prefix="test/")
 ```
 
+### 单据文件管理（推荐业务用法）
+
+支持业务身份（auth_tenant_id, auth_company_id, doc_id）在实例初始化时注入（可为空），各操作方法参数可选，若不传则使用实例属性，若传则覆盖。
+
+#### 初始化带业务身份
+```python
+from fiuai_s3 import ObjectStorageFactory
+from fiuai_s3.object_storage import StorageConfig
+
+config = StorageConfig(
+    provider="minio",
+    bucket_name="dev",
+    endpoint="http://127.0.0.1:19000",
+    access_key="devdevdev",
+    secret_key="devdevdev"
+)
+# 业务身份可选
+S3_Client = ObjectStorageFactory.create_storage(
+    config,
+    auth_tenant_id="t1",
+    auth_company_id="c1",
+    doc_id="d1"
+)
+```
+
+#### 上传单据文件
+```python
+# 方法参数可选，优先级高于实例属性
+S3_Client.upload_doc_file(
+    filename="发票.pdf",
+    data=b"...文件内容...",
+    tags={"业务类型": "发票", "年份": "2024"}
+    # auth_tenant_id、auth_company_id、doc_id 可不传，使用实例属性
+)
+```
+
+#### 下载单据文件
+```python
+data = S3_Client.download_doc_file(
+    filename="发票.pdf"
+    # auth_tenant_id、auth_company_id、doc_id 可不传，使用实例属性
+)
+```
+
+#### 列出单据下所有文件
+```python
+files = S3_Client.list_doc_files()
+```
+
+- 存储路径自动为：`bucketname/auth_tenant_id/auth_company_id/doc_id/filename`
+- tags会自动打到对象存储（Alicloud用OSS Tagging，Minio用metadata）
+- 支持实例初始化时设置默认auth_tenant_id、auth_company_id、doc_id，调用时可覆盖
+- 缺失必要参数会抛出异常
+
 ## 配置参数
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |

{fiuai_s3-0.1.1 → fiuai_s3-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fiuai-s3"
-version = "0.1.1"
+version = "0.2.1"
 description = "一个支持阿里云OSS和MinIO的对象存储抽象包"
 readme = "README.md"
 authors = [

fiuai_s3-0.2.1/src/fiuai_s3/alicloud/alicloud_storage.py

@@ -0,0 +1,152 @@
+# -- coding: utf-8 --
+# Project: object_storage
+# Created Date: 2025-05-01
+# Author: liming
+# Email: lmlala@aliyun.com
+# Copyright (c) 2025 FiuAI
+
+import os
+import logging
+from typing import List, Optional
+import oss2
+from ..object_storage import ObjectStorage, StorageConfig
+from oss2.headers import OSS_OBJECT_TAGGING
+
+logger = logging.getLogger(__name__)
+
+# 设置oss2的日志级别为WARNING，关闭INFO级别的日志
+oss2.set_stream_logger(level=logging.WARNING)
+
+class AliCloudStorage(ObjectStorage):
+    """阿里云OSS存储实现"""
+    
+    def __init__(self, config: StorageConfig, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None):
+        """初始化阿里云OSS客户端
+        
+        Args:
+            config: 存储配置对象
+            auth_tenant_id: 业务租户ID（可为空，后续操作可覆盖）
+            auth_company_id: 业务公司ID（可为空，后续操作可覆盖）
+            doc_id: 单据ID（可为空，后续操作可覆盖）
+        """
+        super().__init__(config, auth_tenant_id, auth_company_id, doc_id)
+        self.auth = oss2.Auth(config.access_key, config.secret_key)
+        self.bucket = oss2.Bucket(
+            auth=self.auth,
+            endpoint=config.endpoint,
+            bucket_name=config.bucket_name
+        )
+        
+    def upload_file(self, object_key: str, data: bytes) -> bool:
+        """上传文件到阿里云OSS
+        
+        Args:
+            object_key: 对象存储中的key
+            data: 文件数据
+        Returns:
+            bool: 是否上传成功
+        """
+        try:
+            self.bucket.put_object(object_key, data)
+            logger.info(f"文件上传成功: {object_key}")
+            return True
+        except Exception as e:
+            logger.error(f"文件上传失败: {str(e)}")
+            return False
+            
+    def download_file(self, object_key: str) -> bytes:
+        """从阿里云OSS下载文件
+        
+        Args:
+            object_key: 对象存储中的key
+            
+        Returns:
+            bytes: 文件内容
+        """
+        try:
+            return self.bucket.get_object(object_key).read()
+        except Exception as e:
+            logger.error(f"文件下载失败: {str(e)}")
+            return None
+            
+    def delete_file(self, object_key: str) -> bool:
+        """删除阿里云OSS中的文件
+        
+        Args:
+            object_key: 对象存储中的key
+            
+        Returns:
+            bool: 是否删除成功
+        """
+        try:
+            self.bucket.delete_object(object_key)
+            logger.info(f"文件删除成功: {object_key}")
+            return True
+        except Exception as e:
+            logger.error(f"文件删除失败: {str(e)}")
+            return False
+            
+    def list_files(self, prefix: Optional[str] = None) -> List[str]:
+        """列出阿里云OSS中的文件
+        
+        Args:
+            prefix: 文件前缀过滤
+            
+        Returns:
+            List[str]: 文件key列表
+        """
+        try:
+            files = []
+            for obj in oss2.ObjectIterator(self.bucket, prefix=prefix):
+                files.append(obj.key)
+            return files
+        except Exception as e:
+            logger.error(f"列出文件失败: {str(e)}")
+            return [] 
+
+    def _build_doc_path(self, filename: str, auth_tenant_id: Optional[str], auth_company_id: Optional[str], doc_id: Optional[str]) -> str:
+        tenant_id = auth_tenant_id or self.auth_tenant_id
+        company_id = auth_company_id or self.auth_company_id
+        docid = doc_id or self.doc_id
+        if not (tenant_id and company_id and docid):
+            raise ValueError("auth_tenant_id、auth_company_id、doc_id 不能为空")
+        return f"{tenant_id}/{company_id}/{docid}/{filename}"
+
+    def upload_doc_file(self, filename: str, data: bytes, tags: Optional[dict] = None, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> bool:
+        try:
+            object_key = self._build_doc_path(filename, auth_tenant_id, auth_company_id, doc_id)
+            headers = None
+            if tags:
+                # 构造tagging字符串
+                tagging = "&".join([f"{oss2.urlquote(str(k))}={oss2.urlquote(str(v))}" for k, v in tags.items()])
+                headers = {OSS_OBJECT_TAGGING: tagging}
+            self.bucket.put_object(object_key, data, headers=headers)
+            logger.info(f"单据文件上传成功: {object_key}")
+            return True
+        except Exception as e:
+            logger.error(f"单据文件上传失败: {str(e)}")
+            return False
+
+    def download_doc_file(self, filename: str, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> bytes:
+        try:
+            object_key = self._build_doc_path(filename, auth_tenant_id, auth_company_id, doc_id)
+            return self.bucket.get_object(object_key).read()
+        except Exception as e:
+            logger.error(f"单据文件下载失败: {str(e)}")
+            return None
+
+    def list_doc_files(self, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> list:
+        try:
+            tenant_id = auth_tenant_id or self.auth_tenant_id
+            company_id = auth_company_id or self.auth_company_id
+            docid = doc_id or self.doc_id
+            if not (tenant_id and company_id and docid):
+                raise ValueError("auth_tenant_id、auth_company_id、doc_id 不能为空")
+            prefix = f"{tenant_id}/{company_id}/{docid}/"
+            files = []
+            for obj in oss2.ObjectIterator(self.bucket, prefix=prefix):
+                files.append(obj.key.split(prefix, 1)[-1])
+            return files
+        except Exception as e:
+            logger.error(f"列出单据文件失败: {str(e)}")
+            return [] 

{fiuai_s3-0.1.1 → fiuai_s3-0.2.1}/src/fiuai_s3/minio/minio_storage.py

@@ -17,13 +17,16 @@ logger = logging.getLogger(__name__)
 class MinioStorage(ObjectStorage):
     """MinIO存储实现"""
     
-    def __init__(self, config: StorageConfig):
+    def __init__(self, config: StorageConfig, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None):
         """初始化MinIO客户端
         
         Args:
             config: 存储配置对象
+            auth_tenant_id: 业务租户ID（可为空，后续操作可覆盖）
+            auth_company_id: 业务公司ID（可为空，后续操作可覆盖）
+            doc_id: 单据ID（可为空，后续操作可覆盖）
         """
-        super().__init__(config)
+        super().__init__(config, auth_tenant_id, auth_company_id, doc_id)
         
         # 处理endpoint格式
         endpoint = self._format_endpoint(config.endpoint)
@@ -148,4 +151,64 @@ class MinioStorage(ObjectStorage):
             return files
         except S3Error as e:
             logger.error(f"列出文件失败: {str(e)}")
+            return [] 
+
+    def _build_doc_path(self, filename: str, auth_tenant_id: Optional[str], auth_company_id: Optional[str], doc_id: Optional[str]) -> str:
+        tenant_id = auth_tenant_id or self.auth_tenant_id
+        company_id = auth_company_id or self.auth_company_id
+        docid = doc_id or self.doc_id
+        if not (tenant_id and company_id and docid):
+            raise ValueError("auth_tenant_id、auth_company_id、doc_id 不能为空")
+        return f"{tenant_id}/{company_id}/{docid}/{filename}"
+
+    def upload_doc_file(self, filename: str, data: bytes, tags: Optional[dict] = None, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> bool:
+        try:
+            object_key = self._build_doc_path(filename, auth_tenant_id, auth_company_id, doc_id)
+            extra_headers = None
+            extra_tags = None
+            if tags:
+                extra_tags = "&".join([f"{k}={v}" for k, v in tags.items()])
+            self.client.put_object(
+                bucket_name=self.bucket_name,
+                object_name=object_key,
+                data=BytesIO(data),
+                length=len(data),
+                metadata=tags if tags else None
+            )
+            logger.info(f"单据文件上传成功: {object_key}")
+            return True
+        except S3Error as e:
+            logger.error(f"单据文件上传失败: {str(e)}")
+            return False
+
+    def download_doc_file(self, filename: str, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> bytes:
+        try:
+            object_key = self._build_doc_path(filename, auth_tenant_id, auth_company_id, doc_id)
+            response = self.client.get_object(
+                bucket_name=self.bucket_name,
+                object_name=object_key
+            )
+            return response.read()
+        except S3Error as e:
+            logger.error(f"单据文件下载失败: {str(e)}")
+            return None
+
+    def list_doc_files(self, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> list:
+        try:
+            tenant_id = auth_tenant_id or self.auth_tenant_id
+            company_id = auth_company_id or self.auth_company_id
+            docid = doc_id or self.doc_id
+            if not (tenant_id and company_id and docid):
+                raise ValueError("auth_tenant_id、auth_company_id、doc_id 不能为空")
+            prefix = f"{tenant_id}/{company_id}/{docid}/"
+            files = []
+            objects = self.client.list_objects(
+                bucket_name=self.bucket_name,
+                prefix=prefix
+            )
+            for obj in objects:
+                files.append(obj.object_name.split(prefix, 1)[-1])
+            return files
+        except S3Error as e:
+            logger.error(f"列出单据文件失败: {str(e)}")
             return [] 

{fiuai_s3-0.1.1 → fiuai_s3-0.2.1}/src/fiuai_s3/object_storage.py

@@ -7,7 +7,7 @@
 
 from abc import ABC, abstractmethod
 from typing import Optional, List, Dict, Any
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, ConfigDict
 import logging
 from uuid import uuid4
 
@@ -23,15 +23,28 @@ class StorageConfig(BaseModel):
     temp_dir: str = Field("temp/", description="临时目录")
     use_https: bool = Field(False, description="是否使用HTTPS")
     
-    class Config:
-        arbitrary_types_allowed = True
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
 class ObjectStorage(ABC):
-    """对象存储抽象基类"""
+    """对象存储抽象基类
     
-    def __init__(self, config: StorageConfig):
+    支持业务身份（auth_tenant_id, auth_company_id, doc_id）在实例初始化时注入（可为空），
+    各操作方法参数可选，若不传则使用实例属性，若传则覆盖。
+    """
+    
+    def __init__(self, config: StorageConfig, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None):
+        """
+        Args:
+            config: 存储配置对象
+            auth_tenant_id: 业务租户ID（可为空，后续操作可覆盖）
+            auth_company_id: 业务公司ID（可为空，后续操作可覆盖）
+            doc_id: 单据ID（可为空，后续操作可覆盖）
+        """
         self.config = config
         self._id = str(uuid4())
+        self.auth_tenant_id = auth_tenant_id
+        self.auth_company_id = auth_company_id
+        self.doc_id = doc_id
     
     @abstractmethod
     def upload_file(self, object_key: str, data: bytes) -> bool:
@@ -82,6 +95,49 @@ class ObjectStorage(ABC):
         """
         pass
 
+    @abstractmethod
+    def upload_doc_file(self, filename: str, data: bytes, tags: Optional[Dict[str, str]] = None, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> bool:
+        """
+        上传单据文件，自动拼接存储路径并打tag
+        Args:
+            filename: 文件名
+            data: 文件内容
+            tags: 标签字典
+            auth_tenant_id: 租户ID（可选，若不传则用实例属性）
+            auth_company_id: 公司ID（可选，若不传则用实例属性）
+            doc_id: 单据ID（可选，若不传则用实例属性）
+        Returns:
+            bool: 是否上传成功
+        """
+        pass
+
+    @abstractmethod
+    def download_doc_file(self, filename: str, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> bytes:
+        """
+        下载单据文件，自动拼接存储路径
+        Args:
+            filename: 文件名
+            auth_tenant_id: 租户ID（可选，若不传则用实例属性）
+            auth_company_id: 公司ID（可选，若不传则用实例属性）
+            doc_id: 单据ID（可选，若不传则用实例属性）
+        Returns:
+            bytes: 文件内容
+        """
+        pass
+
+    @abstractmethod
+    def list_doc_files(self, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> List[str]:
+        """
+        列出单据下所有文件
+        Args:
+            auth_tenant_id: 租户ID（可选，若不传则用实例属性）
+            auth_company_id: 公司ID（可选，若不传则用实例属性）
+            doc_id: 单据ID（可选，若不传则用实例属性）
+        Returns:
+            List[str]: 文件名列表
+        """
+        pass
+
 class ObjectStorageFactory:
     """对象存储工厂类"""
     
@@ -149,26 +205,27 @@ class ObjectStorageFactory:
         return cls._instance
     
     @classmethod
-    def create_storage(cls, config: StorageConfig) -> ObjectStorage:
+    def create_storage(cls, config: StorageConfig, auth_tenant_id: Optional[str] = None, auth_company_id: Optional[str] = None, doc_id: Optional[str] = None) -> ObjectStorage:
         """创建新的对象存储实例
         
         Args:
             config: 存储配置对象
-            
+            auth_tenant_id: 业务租户ID（可为空，后续操作可覆盖）
+            auth_company_id: 业务公司ID（可为空，后续操作可覆盖）
+            doc_id: 单据ID（可为空，后续操作可覆盖）
         Returns:
             ObjectStorage: 对象存储实例
-            
         Raises:
             ValueError: 不支持的存储提供商
         """
         provider = config.provider.lower()
-            
+        
         if provider == "alicloud":
             from .alicloud.alicloud_storage import AliCloudStorage
-            return AliCloudStorage(config)
+            return AliCloudStorage(config, auth_tenant_id, auth_company_id, doc_id)
         elif provider == "minio":
             from .minio.minio_storage import MinioStorage
-            return MinioStorage(config)
+            return MinioStorage(config, auth_tenant_id, auth_company_id, doc_id)
         else:
             raise ValueError(f"不支持的存储提供商: {provider}")
 

fiuai_s3-0.1.1/src/fiuai_s3/alicloud/alicloud_storage.py

@@ -1,101 +0,0 @@
-# -- coding: utf-8 --
-# Project: object_storage
-# Created Date: 2025-05-01
-# Author: liming
-# Email: lmlala@aliyun.com
-# Copyright (c) 2025 FiuAI
-
-import os
-import logging
-from typing import List, Optional
-import oss2
-from ..object_storage import ObjectStorage, StorageConfig
-
-logger = logging.getLogger(__name__)
-
-# 设置oss2的日志级别为WARNING，关闭INFO级别的日志
-oss2.set_stream_logger(level=logging.WARNING)
-
-class AliCloudStorage(ObjectStorage):
-    """阿里云OSS存储实现"""
-    
-    def __init__(self, config: StorageConfig):
-        """初始化阿里云OSS客户端
-        
-        Args:
-            config: 存储配置对象
-        """
-        super().__init__(config)
-        self.auth = oss2.Auth(config.access_key, config.secret_key)
-        self.bucket = oss2.Bucket(
-            auth=self.auth,
-            endpoint=config.endpoint,
-            bucket_name=config.bucket_name
-        )
-        
-    def upload_file(self, object_key: str, data: bytes) -> bool:
-        """上传文件到阿里云OSS
-        
-        Args:
-            object_key: 对象存储中的key
-            data: 文件数据
-        Returns:
-            bool: 是否上传成功
-        """
-        try:
-            self.bucket.put_object(object_key, data)
-            logger.info(f"文件上传成功: {object_key}")
-            return True
-        except Exception as e:
-            logger.error(f"文件上传失败: {str(e)}")
-            return False
-            
-    def download_file(self, object_key: str) -> bytes:
-        """从阿里云OSS下载文件
-        
-        Args:
-            object_key: 对象存储中的key
-            
-        Returns:
-            bytes: 文件内容
-        """
-        try:
-            return self.bucket.get_object(object_key).read()
-        except Exception as e:
-            logger.error(f"文件下载失败: {str(e)}")
-            return None
-            
-    def delete_file(self, object_key: str) -> bool:
-        """删除阿里云OSS中的文件
-        
-        Args:
-            object_key: 对象存储中的key
-            
-        Returns:
-            bool: 是否删除成功
-        """
-        try:
-            self.bucket.delete_object(object_key)
-            logger.info(f"文件删除成功: {object_key}")
-            return True
-        except Exception as e:
-            logger.error(f"文件删除失败: {str(e)}")
-            return False
-            
-    def list_files(self, prefix: Optional[str] = None) -> List[str]:
-        """列出阿里云OSS中的文件
-        
-        Args:
-            prefix: 文件前缀过滤
-            
-        Returns:
-            List[str]: 文件key列表
-        """
-        try:
-            files = []
-            for obj in oss2.ObjectIterator(self.bucket, prefix=prefix):
-                files.append(obj.key)
-            return files
-        except Exception as e:
-            logger.error(f"列出文件失败: {str(e)}")
-            return []