nutricare-data-packages 0.1.0__tar.gz

nutricare_data_packages-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: nutricare-data-packages
+Version: 0.1.0
+Summary: Nutricare data access package
+Author: Nutricare Team
+Project-URL: Homepage, https://example.com
+Project-URL: Repository, https://example.com/nutricare-data-packages
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pymongo>=4.0.0
+
+# nutricare-data-packages
+
+Nutricare 的数据访问基础包，封装 MongoDB 仓储与本地存储抽象基类。
+
+## 安装
+
+```bash
+pip install nutricare-data-packages
+```
+
+## 快速使用
+
+```python
+from pathlib import Path
+
+from nutricare_data_packages import MetadataStore, StorageBase
+
+store = MetadataStore(
+    mongodb_url="mongodb://localhost:27017",
+    db_name="nutricare",
+    auth_source="admin",
+)
+
+class ReportStorage(StorageBase):
+    @property
+    def storage_subdir(self) -> str:
+        return "reports"
+
+    def _write_impl(self, relative_path: str, data: bytes) -> Path:
+        target = self.resolve_path(relative_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+        return target
+```
+
+## 本地构建与发布
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+## 说明
+
+- 包名（pip 安装名）：`nutricare-data-packages`
+- 导入名（Python import）：`nutricare_data_packages`

nutricare_data_packages-0.1.0/README.md

@@ -0,0 +1,48 @@
+# nutricare-data-packages
+
+Nutricare 的数据访问基础包，封装 MongoDB 仓储与本地存储抽象基类。
+
+## 安装
+
+```bash
+pip install nutricare-data-packages
+```
+
+## 快速使用
+
+```python
+from pathlib import Path
+
+from nutricare_data_packages import MetadataStore, StorageBase
+
+store = MetadataStore(
+    mongodb_url="mongodb://localhost:27017",
+    db_name="nutricare",
+    auth_source="admin",
+)
+
+class ReportStorage(StorageBase):
+    @property
+    def storage_subdir(self) -> str:
+        return "reports"
+
+    def _write_impl(self, relative_path: str, data: bytes) -> Path:
+        target = self.resolve_path(relative_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+        return target
+```
+
+## 本地构建与发布
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+## 说明
+
+- 包名（pip 安装名）：`nutricare-data-packages`
+- 导入名（Python import）：`nutricare_data_packages`

nutricare_data_packages-0.1.0/nutricare_data_packages/__init__.py

@@ -0,0 +1,47 @@
+"""Nutricare data packages."""
+
+from .metadata_storage import (
+    INDEX_KEYS,
+    KEY_CONTENT_HASH,
+    KEY_CREATED_AT,
+    KEY_MD5,
+    KEY_METADATA,
+    KEY_MIME_TYPE,
+    KEY_PHASH,
+    KEY_RELATIVE_PATH,
+    KEY_SIZE,
+    KEY_STATUS,
+    KEY_STORAGE_SUBDIR,
+    KEY_TASK_ID,
+    KEY_TICKET_ID,
+    KEY_UPDATED_AT,
+    METADATA_COLLECTION,
+    MetadataStore,
+    make_document,
+    make_filter,
+)
+from .mongo_repository_base import MongoRepositoryBase
+from .storage_base import StorageBase
+
+__all__ = [
+    "MongoRepositoryBase",
+    "MetadataStore",
+    "StorageBase",
+    "METADATA_COLLECTION",
+    "INDEX_KEYS",
+    "KEY_STORAGE_SUBDIR",
+    "KEY_RELATIVE_PATH",
+    "KEY_TICKET_ID",
+    "KEY_TASK_ID",
+    "KEY_SIZE",
+    "KEY_CONTENT_HASH",
+    "KEY_MD5",
+    "KEY_PHASH",
+    "KEY_MIME_TYPE",
+    "KEY_STATUS",
+    "KEY_METADATA",
+    "KEY_CREATED_AT",
+    "KEY_UPDATED_AT",
+    "make_document",
+    "make_filter",
+]

nutricare_data_packages-0.1.0/nutricare_data_packages/metadata_storage.py

@@ -0,0 +1,237 @@
+# 元数据存储 - 定义 doc_metadata 表结构、存储与更新方法
+
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from pymongo.collection import Collection
+from pymongo.cursor import Cursor
+from pymongo.results import DeleteResult, InsertOneResult, UpdateResult
+
+from .mongo_repository_base import MongoRepositoryBase
+
+# ---------------------------------------------------------------------------
+# 集合名与表结构：字段名常量与说明
+# ---------------------------------------------------------------------------
+
+# 元数据集合名（MongoDB collection）
+METADATA_COLLECTION = "doc_metadata"
+
+# 唯一键：存储子目录 + 相对路径，用于 upsert
+KEY_STORAGE_SUBDIR = "storage_subdir"
+KEY_RELATIVE_PATH = "relative_path"
+
+# 文档字段
+KEY_TICKET_ID = "ticket_id"
+KEY_TASK_ID = "task_id"
+KEY_SIZE = "size"
+KEY_CONTENT_HASH = "content_hash"
+KEY_MD5 = "md5"
+KEY_PHASH = "phash"
+KEY_MIME_TYPE = "mime_type"
+KEY_STATUS = "status"
+KEY_METADATA = "metadata"
+KEY_CREATED_AT = "created_at"
+KEY_UPDATED_AT = "updated_at"
+
+# 建议唯一索引：(storage_subdir, relative_path)
+INDEX_KEYS = [KEY_STORAGE_SUBDIR, KEY_RELATIVE_PATH]
+
+
+def _now_utc() -> datetime:
+    """当前 UTC 时间。"""
+    return datetime.now(timezone.utc)
+
+
+def make_document(
+    *,
+    storage_subdir: str,
+    relative_path: str,
+    size: Optional[int] = None,
+    content_hash: Optional[str] = None,
+    md5: Optional[str] = None,
+    phash: Optional[str] = None,
+    mime_type: Optional[str] = None,
+    ticket_id: Optional[str] = None,
+    task_id: Optional[str] = None,
+    status: Optional[str] = None,
+    metadata: Optional[dict[str, Any]] = None,
+    created_at: Optional[datetime] = None,
+    updated_at: Optional[datetime] = None,
+) -> dict[str, Any]:
+    """
+    构造符合元数据表结构的文档（不包含 _id）。
+    用于存储前校验与统一时间戳。
+    """
+    now = _now_utc()
+    doc: dict[str, Any] = {
+        KEY_STORAGE_SUBDIR: storage_subdir.strip(),
+        KEY_RELATIVE_PATH: relative_path.replace("\\", "/").strip().lstrip("/"),
+        KEY_CREATED_AT: created_at or now,
+        KEY_UPDATED_AT: updated_at or now,
+    }
+    if size is not None:
+        doc[KEY_SIZE] = size
+    if content_hash is not None and str(content_hash).strip():
+        doc[KEY_CONTENT_HASH] = content_hash.strip()
+    if md5 is not None and str(md5).strip():
+        doc[KEY_MD5] = md5.strip()
+    if phash is not None and str(phash).strip():
+        doc[KEY_PHASH] = phash.strip()
+    if mime_type is not None and str(mime_type).strip():
+        doc[KEY_MIME_TYPE] = mime_type.strip()
+    if ticket_id is not None and str(ticket_id).strip():
+        doc[KEY_TICKET_ID] = ticket_id.strip()
+    if task_id is not None and str(task_id).strip():
+        doc[KEY_TASK_ID] = task_id.strip()
+    if status is not None and str(status).strip():
+        doc[KEY_STATUS] = status.strip()
+    if metadata is not None and isinstance(metadata, dict):
+        doc[KEY_METADATA] = metadata
+    return doc
+
+
+def make_filter(storage_subdir: str, relative_path: str) -> dict[str, Any]:
+    """按存储子目录 + 相对路径构造查询条件。"""
+    return {
+        KEY_STORAGE_SUBDIR: storage_subdir.strip(),
+        KEY_RELATIVE_PATH: relative_path.replace("\\", "/").strip().lstrip("/"),
+    }
+
+
+class MetadataStore:
+    """
+    元数据存储：基于 METADATA_COLLECTION 的增删改查封装。
+    通过连接参数在内部实例化 MongoRepositoryBase。
+    """
+
+    def __init__(
+        self,
+        *,
+        mongodb_url: str,
+        db_name: str,
+        auth_source: Optional[str] = None,
+    ) -> None:
+        if not mongodb_url or not str(mongodb_url).strip():
+            raise ValueError("mongodb_url 不能为空")
+        if not db_name or not str(db_name).strip():
+            raise ValueError("db_name 不能为空")
+        self._repo = MongoRepositoryBase(
+            mongodb_url=mongodb_url.strip(),
+            db_name=db_name.strip(),
+            collection_name=METADATA_COLLECTION,
+            auth_source=auth_source,
+        )
+        self._coll = self._repo.collection
+
+    @property
+    def collection(self) -> Collection:
+        """底层集合。"""
+        return self._coll
+
+    def save(
+        self,
+        *,
+        storage_subdir: str,
+        relative_path: str,
+        size: Optional[int] = None,
+        content_hash: Optional[str] = None,
+        md5: Optional[str] = None,
+        phash: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        ticket_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+        status: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> InsertOneResult | UpdateResult:
+        """
+        存储一条元数据。若 (storage_subdir, relative_path) 已存在则更新，否则插入。
+        更新时自动刷新 updated_at，插入时设置 created_at / updated_at。
+        """
+        doc = make_document(
+            storage_subdir=storage_subdir,
+            relative_path=relative_path,
+            size=size,
+            content_hash=content_hash,
+            md5=md5,
+            phash=phash,
+            mime_type=mime_type,
+            ticket_id=ticket_id,
+            task_id=task_id,
+            status=status,
+            metadata=metadata,
+        )
+        flt = make_filter(storage_subdir, relative_path)
+        existing = self._coll.find_one(flt)
+        if existing:
+            update_doc = {
+                "$set": {
+                    KEY_UPDATED_AT: _now_utc(),
+                    **{k: v for k, v in doc.items() if k not in (KEY_CREATED_AT,)},
+                }
+            }
+            return self._coll.update_one(flt, update_doc)
+        return self._coll.insert_one(doc)
+
+    def update_by_path(
+        self,
+        storage_subdir: str,
+        relative_path: str,
+        *,
+        size_bytes: Optional[int] = None,
+        content_hash: Optional[str] = None,
+        md5: Optional[str] = None,
+        phash: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        ticket_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+        status: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> UpdateResult:
+        """
+        按 (storage_subdir, relative_path) 更新部分字段。
+        """
+        flt = make_filter(storage_subdir, relative_path)
+        set_payload: dict[str, Any] = {KEY_UPDATED_AT: _now_utc()}
+        if size_bytes is not None:
+            set_payload[KEY_SIZE] = size_bytes
+        if content_hash is not None:
+            set_payload[KEY_CONTENT_HASH] = content_hash.strip() if content_hash else None
+        if md5 is not None:
+            set_payload[KEY_MD5] = md5.strip() if md5 else None
+        if phash is not None:
+            set_payload[KEY_PHASH] = phash.strip() if phash else None
+        if mime_type is not None:
+            set_payload[KEY_MIME_TYPE] = mime_type.strip() if mime_type else None
+        if ticket_id is not None:
+            set_payload[KEY_TICKET_ID] = ticket_id.strip() if ticket_id else None
+        if task_id is not None:
+            set_payload[KEY_TASK_ID] = task_id.strip() if task_id else None
+        if status is not None:
+            set_payload[KEY_STATUS] = status.strip() if status else None
+        if metadata is not None:
+            set_payload[KEY_METADATA] = metadata
+        return self._coll.update_one(flt, {"$set": set_payload})
+
+    def update_one(
+        self, filter: dict[str, Any], update: dict[str, Any], **kwargs: Any
+    ) -> UpdateResult:
+        """透传底层 update_one，便于自定义更新。"""
+        return self._coll.update_one(filter, update, **kwargs)
+
+    def find_by_path(
+        self, storage_subdir: str, relative_path: str
+    ) -> Optional[dict[str, Any]]:
+        """按 (storage_subdir, relative_path) 查询单条元数据。"""
+        return self._coll.find_one(make_filter(storage_subdir, relative_path))
+
+    def list_by_storage_subdir(
+        self, storage_subdir: str, **kwargs: Any
+    ) -> Cursor[dict[str, Any]]:
+        """按 storage_subdir 查询该子目录下所有元数据（返回 Cursor）。"""
+        return self._coll.find({KEY_STORAGE_SUBDIR: storage_subdir.strip()}, **kwargs)
+
+    def delete_by_path(
+        self, storage_subdir: str, relative_path: str
+    ) -> DeleteResult:
+        """按 (storage_subdir, relative_path) 删除一条元数据。"""
+        return self._coll.delete_one(make_filter(storage_subdir, relative_path))

nutricare_data_packages-0.1.0/nutricare_data_packages/mongo_repository_base.py

@@ -0,0 +1,98 @@
+# MongoDB 连接与数据库访问（基类：子类需传入连接参数与集合名）
+
+from typing import Any, Optional
+
+from pymongo import MongoClient
+from pymongo.collection import Collection
+from pymongo.cursor import Cursor
+from pymongo.results import DeleteResult, InsertOneResult, InsertManyResult, UpdateResult
+
+
+class MongoRepositoryBase:
+    """
+    MongoDB 集合访问的基类。
+
+    子类继承后，在实例化时必须传入：
+    - 数据库连接参数：mongodb_url、db_name，以及可选的 auth_source
+    - 集合名称：collection_name
+
+    示例：
+        class MyRepo(MongoRepositoryBase):
+            def __init__(self):
+                super().__init__(
+                    mongodb_url="mongodb://localhost:27017",
+                    db_name="mydb",
+                    collection_name="my_coll",
+                    auth_source="admin",  # 可选
+                )
+    """
+
+    def __init__(
+        self,
+        *,
+        mongodb_url: str,
+        db_name: str,
+        collection_name: str,
+        auth_source: Optional[str] = None,
+    ) -> None:
+        if not mongodb_url or not str(mongodb_url).strip():
+            raise ValueError("mongodb_url 不能为空")
+        if not db_name or not str(db_name).strip():
+            raise ValueError("db_name 不能为空")
+        if not collection_name or not str(collection_name).strip():
+            raise ValueError("collection_name 不能为空")
+        kwargs: dict[str, Any] = {}
+        if auth_source and str(auth_source).strip():
+            kwargs["authSource"] = auth_source.strip()
+        self._client = MongoClient(mongodb_url.strip(), **kwargs)
+        self._db = self._client[db_name.strip()]
+        self._coll = self._db[collection_name.strip()]
+
+    @property
+    def collection(self) -> Collection:
+        """当前集合。"""
+        return self._coll
+
+    def find(self, filter: Optional[dict[str, Any]] = None, **kwargs: Any) -> Cursor:
+        """查询多条。filter 为 None 时查全部。"""
+        return self._coll.find(filter or {}, **kwargs)
+
+    def find_one(
+        self, filter: Optional[dict[str, Any]] = None, **kwargs: Any
+    ) -> Optional[dict[str, Any]]:
+        """查询单条。"""
+        return self._coll.find_one(filter or {}, **kwargs)
+
+    def insert_one(self, document: dict[str, Any], **kwargs: Any) -> InsertOneResult:
+        """新增一条。"""
+        return self._coll.insert_one(document, **kwargs)
+
+    def insert_many(
+        self, documents: list[dict[str, Any]], **kwargs: Any
+    ) -> InsertManyResult:
+        """新增多条。"""
+        return self._coll.insert_many(documents, **kwargs)
+
+    def update_one(
+        self, filter: dict[str, Any], update: dict[str, Any], **kwargs: Any
+    ) -> UpdateResult:
+        """修改一条。"""
+        return self._coll.update_one(filter, update, **kwargs)
+
+    def update_many(
+        self, filter: dict[str, Any], update: dict[str, Any], **kwargs: Any
+    ) -> UpdateResult:
+        """修改多条。"""
+        return self._coll.update_many(filter, update, **kwargs)
+
+    def delete_one(self, filter: dict[str, Any], **kwargs: Any) -> DeleteResult:
+        """删除一条。"""
+        return self._coll.delete_one(filter, **kwargs)
+
+    def delete_many(self, filter: dict[str, Any], **kwargs: Any) -> DeleteResult:
+        """删除多条。"""
+        return self._coll.delete_many(filter, **kwargs)
+
+    def aggregate(self, pipeline: list[dict[str, Any]], **kwargs: Any) -> Any:
+        """聚合查询。"""
+        return self._coll.aggregate(pipeline, **kwargs)

nutricare_data_packages-0.1.0/nutricare_data_packages/storage_base.py

@@ -0,0 +1,193 @@
+# 本地存储基类 - 约定存储位置与规则，子类继承后按约束执行
+
+from abc import ABC, abstractmethod
+import re
+import threading
+from pathlib import Path
+from typing import Optional
+
+from pymongo.collection import Collection
+from pymongo.results import InsertOneResult, UpdateResult
+
+from .metadata_storage import MetadataStore
+
+DOCUMENTS_DIR = "/data/documents"
+
+# 默认允许的相对路径：字母、数字、下划线、短横线、点、斜杠，禁止 ..
+_RELATIVE_PATH_PATTERN = re.compile(r"^[a-zA-Z0-9_.\-/]+$")
+
+
+class StorageBase(ABC):
+    """
+    本地存储的顶级基类。
+
+    约定：
+    1. 存储位置：根路径为 DOCUMENTS_DIR，子类通过 storage_subdir 指定子目录。
+    2. 存储规则：所有路径均为相对于「根路径/storage_subdir」的相对路径，禁止路径穿越（..）、绝对路径及非法字符。
+    3. 子类继承本类后，必须通过 self._resolve(relative_path) 解析路径，不得绕过约束直接写文件。
+    4. 子类必须实现 storage_subdir，指定存储子目录名。
+    5. 基类中实例化元数据集合 METADATA_COLLECTION，子类可通过 metadata_collection 或 _metadata_repo 访问。
+    """
+
+    @property
+    @abstractmethod
+    def storage_subdir(self) -> str:
+        """子类必须实现：指定存储子目录名（不可为空）。"""
+        ...
+
+    def __init__(
+        self,
+        *,
+        mongodb_url: str,
+        db_name: str,
+        auth_source: Optional[str] = None,
+    ) -> None:
+        self._root = self._init_root()
+        self._metadata_repo = MetadataStore(
+            mongodb_url=mongodb_url,
+            db_name=db_name,
+            auth_source=auth_source,
+        )
+
+    @property
+    def metadata_collection(self) -> Collection:
+        """元数据集合（METADATA_COLLECTION）实例，用于文档元数据的增删改查。"""
+        return self._metadata_repo.collection
+
+    def _init_root(self) -> Path:
+        """根据配置与 storage_subdir 初始化存储根路径。"""
+        if not (self.storage_subdir and self.storage_subdir.strip()):
+            raise ValueError("子类必须指定非空的 storage_subdir")
+        root = Path(DOCUMENTS_DIR).resolve()
+        root = root / self.storage_subdir.strip()
+        root.mkdir(parents=True, exist_ok=True)
+        return root
+
+    def _resolve(self, relative_path: str) -> Path:
+        """
+        将相对路径解析为绝对路径，并校验存储规则。
+
+        规则：
+        - 路径必须相对于当前存储根（_root），不得包含 .. 或绝对路径。
+        - 仅允许字母、数字、下划线、短横线、点、斜杠（子类可覆盖 _check_relative_path 放宽或收紧）。
+
+        :param relative_path: 相对于存储根的路径，如 "20260228_013509_pubmed/main.py"
+        :return: 解析后的绝对路径
+        :raises ValueError: 路径非法（穿越根目录或不符合命名规则）
+        """
+        relative_path = relative_path.replace("\\", "/").strip().lstrip("/")
+        self._check_relative_path(relative_path)
+        full = (self._root / relative_path).resolve()
+        try:
+            full.relative_to(self._root.resolve())
+        except ValueError:
+            raise ValueError("路径不允许超出存储根目录") from None
+        return full
+
+    def _check_relative_path(self, relative_path: str) -> None:
+        """
+        校验相对路径是否符合存储规则。子类可覆盖以自定义规则。
+
+        默认：不允许空、不允许 ".."、不允许绝对路径形态、仅允许安全字符。
+        """
+        if not relative_path:
+            raise ValueError("相对路径不能为空")
+        if ".." in relative_path:
+            raise ValueError("相对路径不允许包含 ..")
+        if Path(relative_path).is_absolute() or relative_path.startswith("/"):
+            raise ValueError("相对路径不能为绝对路径")
+        if not _RELATIVE_PATH_PATTERN.match(relative_path):
+            raise ValueError("相对路径仅允许字母、数字、下划线、短横线、点和斜杠")
+
+    def get_root(self) -> Path:
+        """返回当前存储根目录的绝对路径。"""
+        return self._root
+
+    def resolve_path(self, relative_path: str) -> Path:
+        """
+        公开方法：解析相对路径为绝对路径（遵守存储规则）。
+        子类在实现读写时应使用此方法或 _resolve 获取目标路径。
+        """
+        return self._resolve(relative_path)
+
+    def write_metadata(
+        self,
+        *,
+        relative_path: str,
+        size: Optional[int] = None,
+        content_hash: Optional[str] = None,
+        md5: Optional[str] = None,
+        phash: Optional[str] = None,
+        mime_type: Optional[str] = None,
+        status: Optional[str] = None,
+        metadata: Optional[dict[str, object]] = None,
+    ) -> InsertOneResult | UpdateResult:
+        """
+        写入一条文件元数据（按 storage_subdir + relative_path upsert）。
+        ticket_id 与 task_id 从当前线程上下文中获取，缺失则抛出异常。
+        """
+        thread = threading.current_thread()
+        ticket_id = getattr(thread, "ticket_id", None)
+        task_id = getattr(thread, "task_id", None)
+        if (not ticket_id or not str(ticket_id).strip()) and (
+            thread.name and thread.name.startswith("collection-")
+        ):
+            fallback_id = thread.name.split("collection-", 1)[1].strip()
+            if fallback_id:
+                ticket_id = fallback_id
+        if not task_id or not str(task_id).strip():
+            task_id = ticket_id
+        if not ticket_id or not str(ticket_id).strip():
+            raise ValueError("线程上下文缺少 ticket_id")
+        if not task_id or not str(task_id).strip():
+            raise ValueError("线程上下文缺少 task_id")
+
+        normalized = relative_path.replace("\\", "/").strip().lstrip("/")
+        self._check_relative_path(normalized)
+        return self._metadata_repo.save(
+            storage_subdir=self.storage_subdir,
+            relative_path=normalized,
+            size=size,
+            content_hash=content_hash,
+            md5=md5,
+            phash=phash,
+            mime_type=mime_type,
+            ticket_id=ticket_id,
+            task_id=task_id,
+            status=status,
+            metadata=metadata,
+        )
+
+    def _ensure_metadata_exists(self, relative_path: str) -> None:
+        """
+        写入文件前校验元数据是否存在，不存在则抛异常。
+        """
+        normalized = relative_path.replace("\\", "/").strip().lstrip("/")
+        self._check_relative_path(normalized)
+        doc = self._metadata_repo.find_by_path(self.storage_subdir, normalized)
+        if not doc:
+            raise ValueError(f"未找到对应元数据，禁止写入文件: {normalized}")
+
+    def write(self, relative_path: str, data: bytes) -> Path:
+        """
+        将数据写入相对路径。
+        基类默认在写入前校验对应元数据已存在，再委托给子类实现实际写入。
+
+        :param relative_path: 相对于存储根的路径
+        :param data: 字节内容
+        :return: 写入后的绝对路径
+        """
+        self._ensure_metadata_exists(relative_path)
+        return self._write_impl(relative_path, data)
+
+    @abstractmethod
+    def _write_impl(self, relative_path: str, data: bytes) -> Path:
+        """子类实现：执行实际写入逻辑（无需重复元数据存在校验）。"""
+        ...
+
+    def exists(self, relative_path: str) -> bool:
+        """判断相对路径对应的文件或目录是否存在。子类可直接使用，也可覆盖。"""
+        try:
+            return self._resolve(relative_path).exists()
+        except ValueError:
+            return False

nutricare_data_packages-0.1.0/nutricare_data_packages.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: nutricare-data-packages
+Version: 0.1.0
+Summary: Nutricare data access package
+Author: Nutricare Team
+Project-URL: Homepage, https://example.com
+Project-URL: Repository, https://example.com/nutricare-data-packages
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pymongo>=4.0.0
+
+# nutricare-data-packages
+
+Nutricare 的数据访问基础包，封装 MongoDB 仓储与本地存储抽象基类。
+
+## 安装
+
+```bash
+pip install nutricare-data-packages
+```
+
+## 快速使用
+
+```python
+from pathlib import Path
+
+from nutricare_data_packages import MetadataStore, StorageBase
+
+store = MetadataStore(
+    mongodb_url="mongodb://localhost:27017",
+    db_name="nutricare",
+    auth_source="admin",
+)
+
+class ReportStorage(StorageBase):
+    @property
+    def storage_subdir(self) -> str:
+        return "reports"
+
+    def _write_impl(self, relative_path: str, data: bytes) -> Path:
+        target = self.resolve_path(relative_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+        return target
+```
+
+## 本地构建与发布
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+## 说明
+
+- 包名（pip 安装名）：`nutricare-data-packages`
+- 导入名（Python import）：`nutricare_data_packages`

nutricare_data_packages-0.1.0/nutricare_data_packages.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+nutricare_data_packages/__init__.py
+nutricare_data_packages/metadata_storage.py
+nutricare_data_packages/mongo_repository_base.py
+nutricare_data_packages/storage_base.py
+nutricare_data_packages.egg-info/PKG-INFO
+nutricare_data_packages.egg-info/SOURCES.txt
+nutricare_data_packages.egg-info/dependency_links.txt
+nutricare_data_packages.egg-info/requires.txt
+nutricare_data_packages.egg-info/top_level.txt

nutricare_data_packages-0.1.0/nutricare_data_packages.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nutricare_data_packages-0.1.0/nutricare_data_packages.egg-info/requires.txt

@@ -0,0 +1 @@
+pymongo>=4.0.0

nutricare_data_packages-0.1.0/nutricare_data_packages.egg-info/top_level.txt

@@ -0,0 +1 @@
+nutricare_data_packages

nutricare_data_packages-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nutricare-data-packages"
+version = "0.1.0"
+description = "Nutricare data access package"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  { name = "Nutricare Team" }
+]
+dependencies = [
+  "pymongo>=4.0.0"
+]
+
+[project.urls]
+Homepage = "https://example.com"
+Repository = "https://example.com/nutricare-data-packages"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["nutricare_data_packages*"]

nutricare_data_packages-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+