ffdata 0.2.0__py3-none-any.whl

ffdata/local/store.py

@@ -0,0 +1,146 @@
+"""客户端本地 Parquet 数据集发现与受控过滤。
+
+本地查询仅支持服务端明确发布为数据集的 API，不允许执行任意 SQL 或读取 manifest
+之外的文件。
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+import polars as pl
+from ffdata_common.errors import DatasetError
+from ffdata_common.schemas import DatasetManifest
+
+
+def _date(value: Any) -> date | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    if isinstance(value, str):
+        for fmt in ("%Y%m%d", "%Y-%m-%d"):
+            try:
+                return datetime.strptime(value, fmt).date()
+            except ValueError:
+                pass
+    raise ValueError(f"invalid date value: {value!r}")
+
+
+def _codes(value: Any) -> tuple[str, ...] | None:
+    if value is None:
+        return None
+    values = [value] if isinstance(value, str) else list(value)
+    result: list[str] = []
+    seen: set[str] = set()
+    for item in values:
+        for piece in str(item).split(","):
+            code = piece.strip()
+            if not code:
+                raise ValueError("ts_code must contain non-empty strings")
+            if code not in seen:
+                seen.add(code)
+                result.append(code)
+    return tuple(result)
+
+
+class LocalStore:
+    """读取本地 manifest，并使用 Polars 懒扫描执行列裁剪和条件下推。"""
+
+    def __init__(self, root: Path):
+        self.root = root.expanduser().resolve()
+
+    def manifest(self, dataset: str) -> DatasetManifest | None:
+        path = self.root / dataset / "manifest.json"
+        if not path.is_file():
+            return None
+        try:
+            return DatasetManifest.model_validate_json(path.read_text(encoding="utf-8"))
+        except Exception as exc:
+            raise DatasetError(f"invalid local manifest for {dataset}: {exc}") from exc
+
+    def covers(self, dataset: str, params: dict[str, Any]) -> bool:
+        """判断本地数据集是否完整覆盖本次查询所需的日期范围。"""
+        manifest = self.manifest(dataset)
+        if manifest is None or not manifest.files:
+            return False
+        requested_start = _date(params.get("trade_date") or params.get("start_date"))
+        requested_end = _date(params.get("trade_date") or params.get("end_date"))
+        minimums = [_date(item.min_trade_date) for item in manifest.files if item.min_trade_date]
+        maximums = [_date(item.max_trade_date) for item in manifest.files if item.max_trade_date]
+        if requested_start is not None and minimums and requested_start < min(minimums):
+            return False
+        if requested_end is not None and maximums and requested_end > max(maximums):
+            return False
+        has_requested_range = requested_start is not None or requested_end is not None
+        if has_requested_range and not (minimums and maximums):
+            return False
+        return all((self.root / dataset / item.path).is_file() for item in manifest.files)
+
+    def query(
+        self,
+        dataset: str,
+        params: dict[str, Any],
+        *,
+        fields: list[str] | None = None,
+    ) -> pd.DataFrame:
+        """在 manifest 声明的 Parquet 分片上执行本地查询。"""
+        manifest = self.manifest(dataset)
+        if manifest is None:
+            raise DatasetError(
+                f"local dataset {dataset!r} is not installed; run ffdata dataset sync {dataset}"
+            )
+        paths = [str(self.root / dataset / item.path) for item in manifest.files]
+        missing = [path for path in paths if not Path(path).is_file()]
+        if missing:
+            raise DatasetError(f"local dataset has {len(missing)} missing files")
+        frame = pl.scan_parquet(paths)
+        schema_names = frame.collect_schema().names()
+        selected = fields or schema_names
+        unknown = set(selected).difference(schema_names)
+        if unknown:
+            raise ValueError(f"unknown fields: {sorted(unknown)}")
+
+        codes = _codes(params.get("ts_code"))
+        if codes is not None:
+            pure_codes = tuple(code.split(".", 1)[0] for code in codes)
+            frame = frame.filter(
+                pl.col("ts_code").str.replace(r"\.[A-Za-z]+$", "").is_in(pure_codes)
+            )
+        trade_date = _date(params.get("trade_date"))
+        start_date = _date(params.get("start_date"))
+        end_date = _date(params.get("end_date"))
+        if trade_date is not None:
+            frame = frame.filter(pl.col("trade_date") == trade_date)
+        if start_date is not None:
+            frame = frame.filter(pl.col("trade_date") >= start_date)
+        if end_date is not None:
+            frame = frame.filter(pl.col("trade_date") <= end_date)
+
+        sort_columns = [name for name in ("trade_date", "ts_code") if name in selected]
+        if sort_columns:
+            descending = [name == "trade_date" for name in sort_columns]
+            frame = frame.select(selected).sort(sort_columns, descending=descending)
+        else:
+            frame = frame.select(selected)
+        result = frame.collect().to_pandas()
+        if "trade_date" in result.columns:
+            result["trade_date"] = result["trade_date"].map(
+                lambda value: pd.Timestamp(value).strftime("%Y%m%d") if not pd.isna(value) else None
+            )
+        result.attrs.update(
+            {
+                "ffdata_source": "local",
+                "ffdata_version": manifest.version,
+                "ffdata_last_updated": manifest.published_at.isoformat(),
+            }
+        )
+        return result
+
+
+__all__ = ["LocalStore"]

ffdata/transport/__init__.py

@@ -0,0 +1,5 @@
+"""客户端远程传输实现。"""
+
+from .http import HttpTransport
+
+__all__ = ["HttpTransport"]

ffdata/transport/http.py

@@ -0,0 +1,175 @@
+"""客户端 HTTP 传输与协议解码。
+
+本模块只处理网络协议、鉴权头、Arrow/JSON 解码和文件下载，不包含任何业务 SQL。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pandas as pd
+from ffdata_common.codecs import arrow_stream_to_dataframe
+from ffdata_common.errors import (
+    AuthenticationError,
+    AuthorizationError,
+    QueryError,
+)
+from ffdata_common.protocol import ARROW_STREAM_MEDIA_TYPE
+from ffdata_common.schemas import DatasetManifest, DownloadPlan
+
+
+class HttpTransport:
+    """封装 ffdata HTTP 协议的同步传输客户端。"""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str | None,
+        timeout: float = 30.0,
+        client: httpx.Client | None = None,
+    ):
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+        self._client = client or httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers=headers,
+            timeout=timeout,
+            # 数据服务是本机或内网地址，默认不读取环境变量与 macOS 系统代理：
+            # 否则系统代理会把 127.0.0.1 请求转发出去，返回难以排查的 502。
+            # 确需经过代理时，请显式传入已配置代理的 http_client。
+            trust_env=False,
+        )
+        self._owns_client = client is None
+        if client is not None and headers:
+            self._client.headers.update(headers)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def query(
+        self,
+        api_name: str,
+        params: dict[str, Any],
+        *,
+        fields: list[str] | None = None,
+        response_format: str = "arrow",
+    ) -> pd.DataFrame:
+        """调用远程查询接口，并将 JSON 或 Arrow 响应还原为 DataFrame。"""
+        headers = (
+            {"Accept": ARROW_STREAM_MEDIA_TYPE}
+            if response_format == "arrow"
+            else {"Accept": "application/json"}
+        )
+        response = self._client.post(
+            "/v1/query",
+            json={
+                "api_name": api_name,
+                "params": params,
+                "fields": fields,
+                "format": response_format,
+            },
+            headers=headers,
+        )
+        self._raise_for_status(response)
+        if ARROW_STREAM_MEDIA_TYPE in response.headers.get("content-type", ""):
+            frame = arrow_stream_to_dataframe(response.content)
+        else:
+            payload = response.json()
+            frame = pd.DataFrame(payload["data"], columns=payload["columns"])
+            frame.attrs.update(payload.get("metadata", {}))
+        frame.attrs.update(
+            {
+                "ffdata_source": "remote",
+                "ffdata_request_id": response.headers.get("X-Request-ID"),
+                "ffdata_cache": response.headers.get("X-Cache"),
+            }
+        )
+        return frame
+
+    def api_catalog(self) -> list[dict[str, Any]]:
+        response = self._client.get("/v1/apis")
+        self._raise_for_status(response)
+        return response.json()["apis"]
+
+    def create_export(
+        self,
+        api_name: str,
+        params: dict[str, Any],
+        *,
+        fields: list[str] | None = None,
+    ) -> dict[str, Any]:
+        response = self._client.post(
+            "/v1/exports",
+            json={"api_name": api_name, "params": params, "fields": fields},
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def export_status(self, job_id: str) -> dict[str, Any]:
+        response = self._client.get(f"/v1/exports/{job_id}")
+        self._raise_for_status(response)
+        return response.json()
+
+    def download_export(self, job_id: str, destination: Path) -> Path:
+        response = self._client.get(f"/v1/exports/{job_id}/download")
+        self._raise_for_status(response)
+        temporary = destination.with_suffix(f"{destination.suffix}.partial")
+        temporary.parent.mkdir(parents=True, exist_ok=True)
+        temporary.write_bytes(response.content)
+        temporary.replace(destination)
+        return destination
+
+    def dataset_names(self) -> list[str]:
+        response = self._client.get("/v1/datasets")
+        self._raise_for_status(response)
+        return response.json()["datasets"]
+
+    def dataset_manifest(self, name: str) -> DatasetManifest:
+        response = self._client.get(f"/v1/datasets/{name}/manifest")
+        self._raise_for_status(response)
+        return DatasetManifest.model_validate(response.json())
+
+    def download_plan(
+        self,
+        name: str,
+        paths: list[str] | None,
+    ) -> DownloadPlan:
+        response = self._client.post(
+            f"/v1/datasets/{name}/download-plan",
+            json={"paths": paths},
+        )
+        self._raise_for_status(response)
+        return DownloadPlan.model_validate(response.json())
+
+    def download(self, url: str, destination: Path, *, offset: int = 0) -> None:
+        """按流式分块下载文件；存在偏移量时尝试使用 HTTP Range 续传。"""
+        headers = {"Range": f"bytes={offset}-"} if offset else {}
+        mode = "ab" if offset else "wb"
+        with self._client.stream("GET", url, headers=headers) as response:
+            self._raise_for_status(response)
+            if offset and response.status_code != 206:
+                mode = "wb"
+            with destination.open(mode) as output:
+                for chunk in response.iter_bytes(chunk_size=1024 * 1024):
+                    output.write(chunk)
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            detail = response.json().get("detail", response.text)
+        except ValueError:
+            detail = response.text
+        message = str(detail.get("message", detail)) if isinstance(detail, dict) else str(detail)
+        if response.status_code == 401:
+            raise AuthenticationError(message)
+        if response.status_code == 403:
+            raise AuthorizationError(message)
+        raise QueryError(f"HTTP {response.status_code}: {message}")
+
+
+__all__ = ["HttpTransport"]

ffdata-0.2.0.data/scripts/configure_ffdata.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# 配置 ffdata 客户端所需的服务地址与研究员 Token。
+# 请使用 source 执行本脚本，使环境变量立即对当前终端生效：
+#   source client/scripts/configure_ffdata.sh
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  printf '%s\n' "请使用 source 执行本脚本：source client/scripts/configure_ffdata.sh" >&2
+  exit 1
+fi
+
+printf '%s' 'ffdata 服务地址 [http://127.0.0.1:8000]: '
+IFS= read -r FFDATA_SETUP_BASE_URL
+FFDATA_SETUP_BASE_URL=${FFDATA_SETUP_BASE_URL:-http://127.0.0.1:8000}
+
+case "$FFDATA_SETUP_BASE_URL" in
+  http://*|https://*) ;;
+  *)
+    printf '%s\n' '服务地址必须以 http:// 或 https:// 开头。' >&2
+    return 1
+    ;;
+esac
+
+printf '%s' '研究员 Token（输入不回显）: '
+IFS= read -r -s FFDATA_SETUP_TOKEN
+printf '\n'
+if [[ -z "$FFDATA_SETUP_TOKEN" ]]; then
+  printf '%s\n' 'Token 不能为空。' >&2
+  return 1
+fi
+
+export FFDATA_BASE_URL="$FFDATA_SETUP_BASE_URL"
+export FFDATA_TOKEN="$FFDATA_SETUP_TOKEN"
+
+FFDATA_SETUP_PROFILE="$HOME/.bash_profile"
+FFDATA_SETUP_TEMP_FILE=$(mktemp "$HOME/.bash_profile.ffdata.XXXXXX")
+
+if [[ -f "$FFDATA_SETUP_PROFILE" ]]; then
+  awk '
+    /^# >>> ffdata environment >>>$/ { in_ffdata_block = 1; next }
+    /^# <<< ffdata environment <<</ { in_ffdata_block = 0; next }
+    !in_ffdata_block { print }
+  ' "$FFDATA_SETUP_PROFILE" > "$FFDATA_SETUP_TEMP_FILE"
+fi
+
+{
+  printf '\n# >>> ffdata environment >>>\n'
+  printf 'export FFDATA_BASE_URL=%q\n' "$FFDATA_BASE_URL"
+  printf 'export FFDATA_TOKEN=%q\n' "$FFDATA_TOKEN"
+  printf '# <<< ffdata environment <<<\n'
+} >> "$FFDATA_SETUP_TEMP_FILE"
+
+mv "$FFDATA_SETUP_TEMP_FILE" "$FFDATA_SETUP_PROFILE"
+chmod 600 "$FFDATA_SETUP_PROFILE"
+
+printf '%s\n' '当前终端已设置 FFDATA_BASE_URL 与 FFDATA_TOKEN。'
+printf '%s\n' "已写入 $FFDATA_SETUP_PROFILE（仅当前用户可读）。"
+printf '%s\n' '新的 Bash 终端会自动加载；使用其他 shell 时可执行：source ~/.bash_profile'
+
+unset FFDATA_SETUP_BASE_URL FFDATA_SETUP_TOKEN FFDATA_SETUP_PROFILE FFDATA_SETUP_TEMP_FILE

ffdata-0.2.0.dist-info/METADATA

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: ffdata
+Version: 0.2.0
+Summary: ffdata lightweight Python client for governed financial-data APIs
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pandas>=3.0.5
+Requires-Dist: polars>=1.43.2
+Requires-Dist: pyarrow>=21.0.0
+Requires-Dist: pydantic>=2.11.0
+
+# ffdata
+
+`ffdata` 是面向量化研究的轻量 Python 客户端。它只通过 HTTP 调用已部署的
+ffdata 数据服务，不包含服务端、JYDB SQL、数据库配置或后台管理实现。
+
+完整的客户端职责说明见 [客户端模块说明](../docs/模块说明/客户端.md)；安装、构建和升级见
+[客户端打包与交付](../docs/部署与运维/客户端打包与交付.md)；每个对外 API 的可运行案例见
+[使用案例](examples/README.md)。
+
+## 配置服务地址与 Token
+
+安装客户端 wheel 后运行：
+
+```bash
+source "$(dirname "$(command -v ffdata)")/configure_ffdata.sh"
+```
+
+脚本会交互式设置 `FFDATA_BASE_URL` 与 `FFDATA_TOKEN`，Token 输入不回显，并将两者写入
+`~/.bash_profile`（仅当前用户可读）。因此新的 Bash 终端及其他项目都能直接读取配置；若当前使用
+的是 zsh 等其他 shell，可执行 `source ~/.bash_profile` 加载。

ffdata-0.2.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+ffdata/__init__.py,sha256=rLbnK91_ZF9T9rBA9-gT7St7EJ0zhTOBZveMFki0ZkQ,4942
+ffdata/cli.py,sha256=vQ1R8g9dqgD30wy8qG7l108UF3r355wqCdLdipK31kQ,1448
+ffdata/client.py,sha256=uNypPELp0qLIBtENRCM2YZ1oNdG5pXujww7l1LNF_Ns,19493
+ffdata/datasets/__init__.py,sha256=t1NkXLsuyw7b5UTWtbVAWBSRROFlHGNTDLadf0ZEPxQ,107
+ffdata/datasets/manager.py,sha256=FH0ouWyGhTua560Ouqg1fAcSaLvxVVcPD4g-gpSrxLc,5197
+ffdata/local/__init__.py,sha256=NKNUhM4HVkuiTM9b_hSxTqhBEGdxZ_0A6G3h-OAzD7s,100
+ffdata/local/store.py,sha256=b7aNport6l3cSQZ9y4nDoJgL2TUOA-gV9HG8Ag3i6GQ,5778
+ffdata/transport/__init__.py,sha256=uooj8S_VGUh7jLgHI8GNNzt6bUOjfl5Xv9_DGA4mMN0,99
+ffdata/transport/http.py,sha256=B5MqYb8mMvQxJ2-vZPy0fEUD7xmnnvvpaL5Xqj250qw,6248
+ffdata-0.2.0.data/scripts/configure_ffdata.sh,sha256=vMMDc1_YudIdpydC6uGx4dSAWxphJAHJFxw7OWTU5EM,2053
+ffdata_common/__init__.py,sha256=jD-XcZhKLg8hIt4lGBf3s-ZFZi6xplYWs8BLsS0DwDc,190
+ffdata_common/errors.py,sha256=yG4OVtMkvAC3kVobzcm96v4K7GUP0_X6yuyjsMQ840E,649
+ffdata_common/protocol.py,sha256=kqM528ONKX8EDOA0kACt5_k822OO3StqDH26A2dmuBc,466
+ffdata_common/codecs/__init__.py,sha256=Kimr8uanvW0bpb39t9sgKD-chISBmKiSEBKM0hKL42s,189
+ffdata_common/codecs/arrow.py,sha256=cDD0rKhkHhr8Z3X8UlzMu7o0j_7XiX51gxozH4MFHaY,850
+ffdata_common/schemas/__init__.py,sha256=6qLqx4wIFPAiitdwAAnKcl6cCRFl-rVOiTYmJ4P_m4M,222
+ffdata_common/schemas/manifest.py,sha256=3YYmiomaLbt0xQ31hB2pDOyNrZ3BJZhkmcxqdCxe-TA,1248
+ffdata-0.2.0.dist-info/METADATA,sha256=b3UqbZ445FoXc0LTjK_TIl02qNm0jSiU7AUtbMXN_Ng,1285
+ffdata-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ffdata-0.2.0.dist-info/entry_points.txt,sha256=y7Zq6cjvgRMfHG-Zg4ai84Eb5Jh1hLXkiAiyj-oVxKo,43
+ffdata-0.2.0.dist-info/top_level.txt,sha256=S5PVYKegE0abWMnxlOdG3ba2Wh0yjdNCjbYa77wyvoU,21
+ffdata-0.2.0.dist-info/RECORD,,

ffdata-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ffdata-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ffdata = ffdata.cli:main

ffdata-0.2.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+ffdata
+ffdata_common

ffdata_common/__init__.py

@@ -0,0 +1,6 @@
+"""客户端、服务端与数据任务共享的协议契约。"""
+
+from .errors import FfdataError
+from .protocol import LOCAL_DATASET_APIS
+
+__all__ = ["FfdataError", "LOCAL_DATASET_APIS"]

ffdata_common/codecs/__init__.py

@@ -0,0 +1,5 @@
+"""跨进程数据编码与解码工具。"""
+
+from .arrow import arrow_stream_to_dataframe, dataframe_to_arrow_stream
+
+__all__ = ["arrow_stream_to_dataframe", "dataframe_to_arrow_stream"]

ffdata_common/codecs/arrow.py

@@ -0,0 +1,26 @@
+"""DataFrame 与 Arrow IPC Stream 之间的转换工具。"""
+
+from __future__ import annotations
+
+import io
+
+import pandas as pd
+import pyarrow as pa
+
+
+def dataframe_to_arrow_stream(frame: pd.DataFrame) -> bytes:
+    """将 DataFrame 编码为不包含索引的 Arrow IPC 字节流。"""
+    table = pa.Table.from_pandas(frame, preserve_index=False)
+    sink = pa.BufferOutputStream()
+    with pa.ipc.new_stream(sink, table.schema) as writer:
+        writer.write_table(table, max_chunksize=50_000)
+    return sink.getvalue().to_pybytes()
+
+
+def arrow_stream_to_dataframe(content: bytes) -> pd.DataFrame:
+    """将 Arrow IPC 字节流完整还原为 pandas DataFrame。"""
+    with pa.ipc.open_stream(io.BytesIO(content)) as reader:
+        return reader.read_all().to_pandas()
+
+
+__all__ = ["arrow_stream_to_dataframe", "dataframe_to_arrow_stream"]

ffdata_common/errors.py

@@ -0,0 +1,30 @@
+"""客户端和服务端共享的公共异常层次。"""
+
+
+class FfdataError(Exception):
+    """所有 ffdata 公共异常的基类。"""
+
+
+class AuthenticationError(FfdataError):
+    """API Token 缺失或无效。"""
+
+
+class AuthorizationError(FfdataError):
+    """当前用户没有访问目标 API 或数据集的权限。"""
+
+
+class QueryError(FfdataError):
+    """远程服务拒绝查询或查询执行失败。"""
+
+
+class DatasetError(FfdataError):
+    """本地数据集不存在、不完整或已经损坏。"""
+
+
+__all__ = [
+    "AuthenticationError",
+    "AuthorizationError",
+    "DatasetError",
+    "FfdataError",
+    "QueryError",
+]

ffdata_common/protocol.py

@@ -0,0 +1,18 @@
+"""跨进程共享的媒体类型、协议版本和本地数据集映射常量。"""
+
+ARROW_STREAM_MEDIA_TYPE = "application/vnd.apache.arrow.stream"
+PARQUET_MEDIA_TYPE = "application/vnd.apache.parquet"
+
+LOCAL_DATASET_APIS = {
+    "stock_daily": "stock_daily",
+    "stock_adjusting_factor": "stock_adjusting_factor",
+}
+
+PROTOCOL_VERSION = "1"
+
+__all__ = [
+    "ARROW_STREAM_MEDIA_TYPE",
+    "LOCAL_DATASET_APIS",
+    "PARQUET_MEDIA_TYPE",
+    "PROTOCOL_VERSION",
+]

ffdata_common/schemas/__init__.py

@@ -0,0 +1,5 @@
+"""跨客户端、服务端和任务共享的数据结构。"""
+
+from .manifest import DatasetFile, DatasetManifest, DownloadFile, DownloadPlan
+
+__all__ = ["DatasetFile", "DatasetManifest", "DownloadFile", "DownloadPlan"]

ffdata_common/schemas/manifest.py

@@ -0,0 +1,52 @@
+"""版本化本地数据集的 manifest 与下载计划契约。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DatasetFile(BaseModel):
+    """manifest 中单个 Parquet 分片的路径、大小、哈希和日期范围。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    size: int = Field(ge=0)
+    sha256: str = Field(min_length=64, max_length=64)
+    min_trade_date: str | None = None
+    max_trade_date: str | None = None
+
+
+class DatasetManifest(BaseModel):
+    """描述一个已发布数据集版本及其全部受控文件。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    dataset: str
+    version: str
+    schema_version: int = 1
+    published_at: datetime
+    latest_trade_date: str | None = None
+    files: list[DatasetFile]
+
+
+class DownloadFile(BaseModel):
+    """下载计划中的文件元数据和临时访问地址。"""
+
+    path: str
+    size: int
+    sha256: str
+    url: str
+
+
+class DownloadPlan(BaseModel):
+    """服务端针对指定版本生成的文件下载计划。"""
+
+    dataset: str
+    version: str
+    files: list[DownloadFile]
+
+
+__all__ = ["DatasetFile", "DatasetManifest", "DownloadFile", "DownloadPlan"]