quantdb-sdk 0.2.5__tar.gz → 0.2.7__tar.gz

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/CHANGELOG.md

@@ -3,6 +3,30 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [0.2.7] - 2026-07-29
+
+### Fixed
+- **V1 回退对纯 V2 数据集失效**：`query_kline` / `a_query_kline` 无日期范围时不再默认走 V1。`margin_trading`、`features_daily`、`l1_factors`、`l2_factors` 等 11 个纯 V2 数据集在 COS 上已无 V1 逐股票文件，V1 回退会 404。现在无范围时也走 V2 manifest 路径（manifest 列出的所有分区全量下载），仅在有日期范围时才做日历完整性校验。显式 `layout="v1"` 仍可直接走逐股票文件。
+- **异步客户端时区处理不一致**：`AsyncQuantDBClient._normalise_kline` 缺少 `tz_convert` 逻辑，与同步客户端行为不一致（相同输入可能产生不同的 `trade_date` 字符串），已对齐。
+
+## [0.2.6] - 2026-07-27
+
+### Fixed
+- **适配服务端 CDN 直连下载（302 跳转）**：异步客户端（httpx 默认不跟随重定向）此前在服务端开启 302 直连后所有下载/同步接口失效，现已修复。
+- **凭证保护**：同步客户端此前跟随 302 时会把 `X-API-Key` 透传给 CDN 域；现两个客户端统一改为「手动处理 302 + 无鉴权头裸请求直连 CDN」，凭证只发给 QuantDB 网关。
+- 302 响应中的 COS ETag 回填至 CDN 响应，保证进程内 ETag 缓存与 If-None-Match 304 逻辑不受影响。
+
+### Security (后端)
+- **一次性下载令牌**：302 直连模式改为两跳（`/download` → `/cdn-bridge?token=xxx` → CDN），令牌一次性消费，防止签名 URL 被重复使用或分享给他人免费下载。
+- **移除 `?direct=1` 请求级覆盖**：用户无法再通过请求参数强制走 302 模式，仅全局开关 `QUANTDB_DOWNLOAD_REDIRECT` 可控制。
+- 令牌有效期 90s，远小于 CDN 签名有效期 300s，窗口极小。
+
+### Data Architecture (COS)
+- **V2 数据集全面清理 V1 残留**：COS 上 11 个 V2 数据集已删除全部 V1 逐股票文件（~1.8 万对象），实现纯 V2 存储。ListObjects 分页效率提升 3-5 倍。
+- **L1 日频因子 V2 全量上线**：`l1_factors` 2565 个交易日分区（2016-01-04 ~ 至今），支持按日范围高效查询。
+- **L2 高频因子 V2 上线**：`l2_factors` 34 个交易日分区（2026-01-05 ~ 2026-02-27）。
+- **融资融券纯 V2**：`margin_trading` 已从 V1 迁移至纯 V2 按日分区（2563 个分区）。
+
 ## [0.2.5] - 2026-07-26
 
 ### Security

{quantdb_sdk-0.2.5/quantdb_sdk.egg-info → quantdb_sdk-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.2.5
+Version: 0.2.7
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
@@ -90,12 +90,17 @@ client = QuantDBClient(username="admin", password="admin123")
 
 ## V1 / V2 数据布局
 
-COS 同时保留 V1（按股票历史文件）和 V2（按交易日全市场分区）。所有下载相关接口均可传入
-`layout="auto" | "v1" | "v2"`。默认 `auto` 的规则是：给出 K 线日期范围时优先 V2；若任一
-交易日没有 V2 分区，则整次请求回退 V1，绝不混合两种口径；未给日期范围时读取 V1 全历史文件。
+QuantDB 数据采用两种物理布局：V1（按股票的全历史文件 `{Symbol}.parquet`）和 V2（按交易日的全市场分区 `dt=YYYYMMDD/data.parquet`）。
+所有下载相关接口均可传入 `layout="auto" | "v1" | "v2"`。
+
+**V2 数据集**（COS 纯 V2，零 V1 残留）：daily_unadjusted / daily_forward / daily_backward / index_daily / valuation / technical_indicators / market_sentiment / features_daily / l1_factors / l2_factors / margin_trading
+
+**V1 数据集**（纯 V1，无 V2 分区）：min1_kline / min5_kline / tick_data / 财务七表 / 基础板块
+
+默认 `auto` 始终优先 V2：有日期范围时聚合 V2 多日分区，若覆盖不完整则回退 V1（仅对仍保留 V1 文件的数据集有效）；无日期范围时走 V2 全量（manifest 列出的所有分区），跳过完整性校验。
 
 ```python
-# 按日期范围优先 V2；覆盖不完整时自动回退 V1
+# 始终优先 V2 按日分区；有范围且覆盖不完整时自动回退 V1
 df = client.query_kline("600519.SH", start_date="2026-07-01", end_date="2026-07-24")
 
 # 强制指定物理布局；layout="v2" 缺日时会明确报错

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/README.md

@@ -43,65 +43,70 @@ print(df.head())
 client = QuantDBClient(username="admin", password="admin123")
 ```
 
-## 核心功能
+## 核心功能
 
 - **数据查询**：K 线、Tick 通过下载 Parquet 切片后客户端解析（消耗流量）；股票列表、交易日历、元数据走网关 JSON（不计流量）。
 - **数据下载**：Parquet 文件下载或直读 DataFrame，计入订阅流量。
 - **本地分析**：基于 DuckDB 对本地 Parquet 执行 SQL。
 - **账户管理**：查询用户信息、用量、API Key、订阅与订单。
-- **异步客户端**：基于 httpx，适用于 asyncio 量化框架。
-
-## V1 / V2 数据布局
-
-COS 同时保留 V1（按股票历史文件）和 V2（按交易日全市场分区）。所有下载相关接口均可传入
-`layout="auto" | "v1" | "v2"`。默认 `auto` 的规则是：给出 K 线日期范围时优先 V2；若任一
-交易日没有 V2 分区，则整次请求回退 V1，绝不混合两种口径；未给日期范围时读取 V1 全历史文件。
-
-```python
-# 按日期范围优先 V2；覆盖不完整时自动回退 V1
-df = client.query_kline("600519.SH", start_date="2026-07-01", end_date="2026-07-24")
-
-# 强制指定物理布局；layout="v2" 缺日时会明确报错
-latest = client.download_file("1", "daily_forward", trade_date="2026-07-24", layout="v2")
-history = client.download_file("1", "daily_forward", symbol="600519.SH", layout="v1")
-
-# 以发布清单为 cursor 做原子化增量同步（含 V2 patch）
-result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
-
-# 财务、ETF/可转债等尚无 V2 release 的数据集自动按 V1 Manifest 增量同步，
-# 使用 ETag + size 校验；也可从命令行执行：
-# quantdb sync qdb_xxx balance --save-dir D:/quantdb-data
-financial = client.sync_dataset("balance", save_dir="D:/quantdb-data")
-```
-
-### 加速批量下载：建议从 8 个工作线程开始
-
-`sync_dataset()` 单次调用会按发布顺序串行下载，以保证本地 SQLite 同步状态和 release cursor 一致。
-当需要下载多个独立标的或文件时，可由调用方并行调度；建议先使用 **8 个工作线程**，再结合网络带宽、磁盘写入能力和账户流量配额调整。
-
-```python
-from concurrent.futures import ThreadPoolExecutor
-from quantdb_sdk import QuantDBClient
-
-API_KEY = "qdb_xxx..."
-symbols = ["600519.SH", "000001.SZ", "600036.SH"]
-
-def download_one(symbol: str) -> str:
-    # 每个 worker 使用独立客户端，避免跨线程共享 HTTP Session。
-    with_client = QuantDBClient(api_key=API_KEY)
-    return with_client.download_file(
-        "1", "daily_forward", symbol=symbol, save_dir="D:/quantdb-data"
-    )
-
-with ThreadPoolExecutor(max_workers=8) as pool:
-    files = list(pool.map(download_one, symbols))
-```
-
-不要对相同 `save_dir` 并行调用多个 `sync_dataset()`：它们会共同写入 `quantdb_sync.sqlite`，可能产生锁竞争。批量同步本身仍建议一次一个数据集执行。
-
-## 流量说明
-
-免费注册用户获赠 100 MB 一次性体验流量；订阅用户每月含 30 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。
+- **异步客户端**：基于 httpx，适用于 asyncio 量化框架。
+
+## V1 / V2 数据布局
+
+QuantDB 数据采用两种物理布局：V1（按股票的全历史文件 `{Symbol}.parquet`）和 V2（按交易日的全市场分区 `dt=YYYYMMDD/data.parquet`）。
+所有下载相关接口均可传入 `layout="auto" | "v1" | "v2"`。
+
+**V2 数据集**（COS 纯 V2，零 V1 残留）：daily_unadjusted / daily_forward / daily_backward / index_daily / valuation / technical_indicators / market_sentiment / features_daily / l1_factors / l2_factors / margin_trading
+
+**V1 数据集**（纯 V1，无 V2 分区）：min1_kline / min5_kline / tick_data / 财务七表 / 基础板块
+
+默认 `auto` 始终优先 V2：有日期范围时聚合 V2 多日分区，若覆盖不完整则回退 V1（仅对仍保留 V1 文件的数据集有效）；无日期范围时走 V2 全量（manifest 列出的所有分区），跳过完整性校验。
+
+```python
+# 始终优先 V2 按日分区；有范围且覆盖不完整时自动回退 V1
+df = client.query_kline("600519.SH", start_date="2026-07-01", end_date="2026-07-24")
+
+# 强制指定物理布局；layout="v2" 缺日时会明确报错
+latest = client.download_file("1", "daily_forward", trade_date="2026-07-24", layout="v2")
+history = client.download_file("1", "daily_forward", symbol="600519.SH", layout="v1")
+
+# 以发布清单为 cursor 做原子化增量同步（含 V2 patch）
+result = client.sync_dataset("daily_forward", save_dir="D:/quantdb-data")
+
+# 财务、ETF/可转债等尚无 V2 release 的数据集自动按 V1 Manifest 增量同步，
+# 使用 ETag + size 校验；也可从命令行执行：
+# quantdb sync qdb_xxx balance --save-dir D:/quantdb-data
+financial = client.sync_dataset("balance", save_dir="D:/quantdb-data")
+```
+
+### 加速批量下载：建议从 8 个工作线程开始
+
+`sync_dataset()` 单次调用会按发布顺序串行下载，以保证本地 SQLite 同步状态和 release cursor 一致。
+当需要下载多个独立标的或文件时，可由调用方并行调度；建议先使用 **8 个工作线程**，再结合网络带宽、磁盘写入能力和账户流量配额调整。
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from quantdb_sdk import QuantDBClient
+
+API_KEY = "qdb_xxx..."
+symbols = ["600519.SH", "000001.SZ", "600036.SH"]
+
+def download_one(symbol: str) -> str:
+    # 每个 worker 使用独立客户端，避免跨线程共享 HTTP Session。
+    with_client = QuantDBClient(api_key=API_KEY)
+    return with_client.download_file(
+        "1", "daily_forward", symbol=symbol, save_dir="D:/quantdb-data"
+    )
+
+with ThreadPoolExecutor(max_workers=8) as pool:
+    files = list(pool.map(download_one, symbols))
+```
+
+不要对相同 `save_dir` 并行调用多个 `sync_dataset()`：它们会共同写入 `quantdb_sync.sqlite`，可能产生锁竞争。批量同步本身仍建议一次一个数据集执行。
+
+## 流量说明
+
+免费注册用户获赠 100 MB 一次性体验流量；订阅用户每月含 30 GB 下载流量，超出部分按 ¥1/GB 从账户余额扣减。余额不足时下载会被拦截。
 
 ## 文档
 

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantdb-sdk"
-version = "0.2.5"
+version = "0.2.7"
 description = "QuantDB 量化数据平台官方 Python SDK"
 readme = "README.md"
 license = {text = "MIT"}

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/quantdb_sdk/__init__.py

@@ -5,7 +5,7 @@ try:
     # 注意：此处用 PyPI 包名（连字符）查找版本号，不是模块名（下划线）
     __version__ = version("quantdb-sdk")
 except ImportError:
-    __version__ = "0.2.5"
+    __version__ = "0.2.6"
 
 from .async_client import AsyncQuantDBClient
 from .client import DuckDBWarehouse, QuantDBClient

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/quantdb_sdk/_utils.py

@@ -5,6 +5,7 @@
 
 import os
 import re
+from datetime import date
 from typing import Dict, Optional
 from urllib.parse import unquote, urlparse
 
@@ -20,7 +21,7 @@ SYNC_DATASET_CATEGORIES: Dict[str, str] = {
     "holder_num": "3", "pershare_index": "3", "dividend_factors": "3",
     "etf_pcf": "4", "convertible_bond": "4",
     "valuation": "5", "technical_indicators": "5", "market_sentiment": "5",
-    "features_daily": "6", "l1_l2_factors": "6", "l2_factors": "6",
+    "features_daily": "6", "l1_factors": "6", "l1_l2_factors": "6", "l2_factors": "6",
 }
 
 
@@ -97,6 +98,29 @@ def safe_join(root: str, relative_path: str) -> str:
     return target
 
 
+def normalise_tick_trade_date(trade_date: str) -> str:
+    """规范化 Tick 交易日为 ``YYYY-MM-DD``，拒绝含糊或非法输入。"""
+    value = str(trade_date).strip()
+    if re.fullmatch(r"\d{8}", value):
+        value = f"{value[:4]}-{value[4:6]}-{value[6:]}"
+    if not re.fullmatch(r"\d{4}-\d{2}-\d{2}", value):
+        raise ValueError("trade_date 必须为 YYYY-MM-DD 或 YYYYMMDD")
+    try:
+        date.fromisoformat(value)
+    except ValueError as exc:
+        raise ValueError("trade_date 不是有效交易日日期") from exc
+    return value
+
+
+def tick_shard_relative_path(symbol: str, trade_date: str) -> str:
+    """返回 Tick 平铺 shard 的规范相对路径。"""
+    clean_symbol = str(symbol).strip().upper()
+    if not re.fullmatch(r"[A-Z0-9]+\.[A-Z0-9]+", clean_symbol):
+        raise ValueError("Tick symbol 必须为类似 600519.SH 的代码")
+    yyyymmdd = normalise_tick_trade_date(trade_date).replace("-", "")
+    return f"1_kline_data/tick_data/{clean_symbol.replace('.', '_')}_{yyyymmdd}.parquet"
+
+
 def validate_api_host(api_host: str) -> str:
     """Require HTTPS except for local development/test loopback endpoints."""
     host = api_host.rstrip("/")

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/quantdb_sdk/async_client.py

@@ -5,6 +5,7 @@ import io
 import os
 import re
 import sqlite3
+from contextlib import asynccontextmanager
 from typing import Any, Dict, List, Optional, Literal
 
 import httpx
@@ -12,7 +13,7 @@ import pandas as pd
 
 from ._utils import (
     SYNC_DATASET_CATEGORIES, bytes_to_gb, check_download_size, default_download_dir,
-    max_download_bytes, parse_filename_from_content_disposition, safe_filename, safe_join,
+    max_download_bytes, normalise_tick_trade_date, parse_filename_from_content_disposition, safe_filename, safe_join,
     validate_api_host,
 )
 from .errors import (
@@ -25,6 +26,9 @@ from .errors import (
     ValidationError,
 )
 
+# 维护提示：每次发版必须与 pyproject.toml 版本号同步
+_USER_AGENT = "QuantDB-Python-SDK/0.2.7"
+
 
 class AsyncQuantDBClient:
     """QuantDB 异步客户端。
@@ -41,7 +45,7 @@ class AsyncQuantDBClient:
     ):
         self.api_host = validate_api_host(api_host)
         self.timeout = timeout
-        headers = {"User-Agent": "QuantDB-Python-SDK/0.2.5"}
+        headers = {"User-Agent": _USER_AGENT}
         if api_key:
             headers["X-API-Key"] = api_key
         elif token:
@@ -53,17 +57,49 @@ class AsyncQuantDBClient:
             headers=headers,
             timeout=httpx.Timeout(timeout, connect=5.0),
         )
+        # 裸客户端：跟随 302 直连 CDN 用，不携带任何鉴权头，避免凭证泄露给 CDN 域。
+        self._bare_client = httpx.AsyncClient(
+            headers={"User-Agent": _USER_AGENT},
+            timeout=httpx.Timeout(timeout, connect=5.0),
+        )
         # 进程内 parquet ETag 缓存：同对象（ETag 未变）不重复下载，避免重复计费。
         self._cache: Dict[str, Dict[str, Any]] = {}
 
     async def close(self) -> None:
         """关闭底层 httpx 客户端。"""
         await self.client.aclose()
+        await self._bare_client.aclose()
 
     def clear_cache(self) -> None:
         """清空进程内 Parquet 缓存（强制下次重新下载最新数据）。"""
         self._cache.clear()
 
+    @asynccontextmanager
+    async def _download_stream(self, params: Dict[str, Any], headers: Optional[Dict[str, str]] = None):
+        """下载专用流式请求：手动处理服务端 302 CDN 直连跳转。
+
+        服务端开启 CDN 直连后，/api/v1/data/download 预扣流量成功时返回
+        302 -> CDN 签名 URL。httpx 默认不跟随重定向；这里用不带鉴权头的
+        裸客户端直连 Location，鉴权头不会泄露给 CDN 域。
+        """
+        async with self.client.stream(
+            "GET", f"{self.api_host}/api/v1/data/download", params=params, headers=headers
+        ) as resp:
+            if resp.status_code not in (301, 302, 303, 307, 308):
+                yield resp
+                return
+            location = resp.headers.get("Location", "")
+            etag = resp.headers.get("ETag", "")
+            if not location:
+                raise ServerError("下载重定向缺少 Location 头")
+        async with self._bare_client.stream("GET", location) as cdn_resp:
+            if cdn_resp.status_code != 200:
+                raise ServerError(f"CDN 直连下载失败：HTTP {cdn_resp.status_code}")
+            # 网关 302 响应携带 COS ETag；若 CDN 响应缺失则回填，保证缓存逻辑一致。
+            if etag and not cdn_resp.headers.get("ETag"):
+                cdn_resp.headers["ETag"] = etag
+            yield cdn_resp
+
     @staticmethod
     def _validate_layout(layout: str) -> Literal["auto", "v1", "v2"]:
         if layout not in {"auto", "v1", "v2"}:
@@ -78,6 +114,8 @@ class AsyncQuantDBClient:
     def _normalise_kline(df: pd.DataFrame, start_date: Optional[str], end_date: Optional[str], fields: str, limit: Optional[int]) -> pd.DataFrame:
         if "time" in df.columns:
             dt = pd.to_datetime(df["time"], errors="coerce")
+            if getattr(dt.dt, "tz", None) is not None:
+                dt = dt.dt.tz_convert(None)
         elif "trade_date" in df.columns:
             dt = pd.to_datetime(df["trade_date"], errors="coerce")
         else:
@@ -242,22 +280,34 @@ class AsyncQuantDBClient:
         limit: Optional[int] = None,
         layout: Literal["auto", "v1", "v2"] = "auto",
     ) -> pd.DataFrame:
-        """查询 K 线数据（下载 COS parquet 切片后客户端解析，消耗下载流量，异步）。"""
+        """查询 K 线数据（下载 COS parquet 切片后客户端解析，消耗下载流量，异步）。
+
+        ``auto`` 始终优先 V2 全市场日分区；仅当提供了日期范围且 V2 覆盖不完整时，
+        整次回退 V1 股票历史文件。未提供日期范围时走 V2 全量（manifest 列出的
+        所有分区），跳过日历完整性校验。显式 ``v1`` 直接走逐股票文件；显式
+        ``v2`` 不会静默回退。
+        """
         layout = self._validate_layout(layout)
         sub_category = f"daily_{adj_type}"
-        if layout == "v1" or (layout == "auto" and not (start_date or end_date)):
+        has_range = bool(start_date or end_date)
+        if layout == "v1":
             return self._normalise_kline(await self.a_load_as_df("1", sub_category, symbol, layout="v1"), start_date, end_date, fields, limit)
         files = await self.a_query_manifest("1", sub_category, layout="v2")
         selected = [f for f in files if (not start_date or f.get("trade_date", "") >= start_date) and (not end_date or f.get("trade_date", "") <= end_date)]
-        calendar = await self.a_query_calendar(start_date, end_date)
-        expected = set()
-        if not calendar.empty:
-            date_col = next((c for c in ("trade_date", "date", "cal_date") if c in calendar.columns), None)
-            open_col = next((c for c in ("is_open", "is_trading_day", "open") if c in calendar.columns), None)
-            if date_col:
-                rows = calendar if not open_col else calendar[calendar[open_col].astype(str).isin(["1", "True", "true"])]
-                expected = set(pd.to_datetime(rows[date_col], errors="coerce").dropna().dt.strftime("%Y-%m-%d"))
-        if not selected or (expected and not expected.issubset({f.get("trade_date") for f in selected})):
+        # 仅在有日期范围时校验完整性；无范围时 manifest 列出什么就下什么。
+        complete = bool(selected)
+        if has_range:
+            calendar = await self.a_query_calendar(start_date, end_date)
+            expected = set()
+            if not calendar.empty:
+                date_col = next((c for c in ("trade_date", "date", "cal_date") if c in calendar.columns), None)
+                open_col = next((c for c in ("is_open", "is_trading_day", "open") if c in calendar.columns), None)
+                if date_col:
+                    rows = calendar if not open_col else calendar[calendar[open_col].astype(str).isin(["1", "True", "true"])]
+                    expected = set(pd.to_datetime(rows[date_col], errors="coerce").dropna().dt.strftime("%Y-%m-%d"))
+            found = {f.get("trade_date") for f in selected}
+            complete = bool(selected) and (not expected or expected.issubset(found))
+        if not complete:
             if layout == "auto":
                 return self._normalise_kline(await self.a_load_as_df("1", sub_category, symbol, layout="v1"), start_date, end_date, fields, limit)
             raise NotFoundError("V2 日切片在请求日期范围内覆盖不完整；请改用 layout='auto' 或 'v1'")
@@ -277,6 +327,7 @@ class AsyncQuantDBClient:
         layout: Literal["auto", "v1", "v2"] = "auto",
     ) -> pd.DataFrame:
         """查询 Tick 分笔数据（下载 COS parquet 切片后客户端解析，消耗下载流量，异步）。"""
+        trade_date = normalise_tick_trade_date(trade_date)
         df = await self.a_load_as_df("1", "tick_data", symbol, trade_date=trade_date, layout=layout)
         ts_col = "ts" if "ts" in df.columns else ("time" if "time" in df.columns else None)
         if ts_col and (start_ts or end_ts):
@@ -398,9 +449,7 @@ class AsyncQuantDBClient:
         if object_key:
             params["object_key"] = object_key
 
-        async with self.client.stream(
-            "GET", f"{self.api_host}/api/v1/data/download", params=params
-        ) as resp:
+        async with self._download_stream(params) as resp:
             if resp.status_code != 200:
                 body = await resp.aread()
                 # 构造一个完整的 httpx.Response 用于错误解析，然后立即抛出
@@ -467,9 +516,7 @@ class AsyncQuantDBClient:
         req_headers = {}
         if cached and cached.get("etag"):
             req_headers["If-None-Match"] = cached["etag"]
-        async with self.client.stream(
-            "GET", f"{self.api_host}/api/v1/data/download", params=params, headers=req_headers
-        ) as resp:
+        async with self._download_stream(params, headers=req_headers) as resp:
             if resp.status_code == 304 and cached:
                 return cached["df"]
             if resp.status_code != 200:
@@ -567,7 +614,7 @@ class AsyncQuantDBClient:
                         if old and old[0] == obj.get("etag") and old[1] == obj.get("sha256") and os.path.exists(old[3]) and (expected_size is None or os.path.getsize(old[3]) == expected_size): continue
                         os.makedirs(os.path.dirname(target), exist_ok=True)
                         tmp, digest = target + ".part", hashlib.sha256()
-                        async with self.client.stream("GET", f"{self.api_host}/api/v1/data/download", params={"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v2", "object_key": key}) as resp:
+                        async with self._download_stream({"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v2", "object_key": key}) as resp:
                             if resp.status_code != 200:
                                 body = await resp.aread(); self._check_response(httpx.Response(resp.status_code, content=body)); raise QuantDBError("下载失败")
                             try:
@@ -592,10 +639,16 @@ class AsyncQuantDBClient:
                 expected_size = obj.get("size")
                 old = state.execute("SELECT etag,size,path FROM objects WHERE key=?", (key,)).fetchone()
                 if old and old[0] == obj.get("etag") and os.path.exists(old[2]) and (expected_size is None or os.path.getsize(old[2]) == expected_size): continue
+                download_params = {"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")}
+                if dataset == "tick_data":
+                    trade_date = obj.get("trade_date")
+                    if not trade_date:
+                        raise ServerError("Tick manifest 缺少 trade_date")
+                    download_params["trade_date"] = normalise_tick_trade_date(trade_date)
                 os.makedirs(os.path.dirname(target), exist_ok=True)
                 tmp, written_size = target + ".part", 0
                 try:
-                    async with self.client.stream("GET", f"{self.api_host}/api/v1/data/download", params={"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")}) as resp:
+                    async with self._download_stream(download_params) as resp:
                         if resp.status_code != 200:
                             body = await resp.aread(); self._check_response(httpx.Response(resp.status_code, content=body)); raise QuantDBError("下载失败")
                         with open(tmp, "wb") as fh:

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/quantdb_sdk/client.py

@@ -13,11 +13,11 @@ import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
-from ._utils import (
-    SYNC_DATASET_CATEGORIES, bytes_to_gb, check_download_size, default_download_dir,
-    max_download_bytes, parse_filename_from_content_disposition, safe_filename, safe_join,
-    validate_api_host,
-)
+from ._utils import (
+    SYNC_DATASET_CATEGORIES, bytes_to_gb, check_download_size, default_download_dir,
+    max_download_bytes, normalise_tick_trade_date, parse_filename_from_content_disposition, safe_filename, safe_join,
+    validate_api_host,
+)
 from .errors import (
     AuthError,
     InsufficientTrafficError,
@@ -28,6 +28,9 @@ from .errors import (
     ValidationError,
 )
 
+# 维护提示：每次发版必须与 pyproject.toml 版本号同步
+_USER_AGENT = "QuantDB-Python-SDK/0.2.7"
+
 
 class QuantDBClient:
     """QuantDB 同步客户端。
@@ -45,14 +48,12 @@ class QuantDBClient:
         timeout: tuple = (5, 60),
         max_retries: int = 2,
     ):
-        self.api_host = validate_api_host(api_host)
+        self.api_host = validate_api_host(api_host)
         self.timeout = timeout
         self.token: Optional[str] = None
         self.headers: Dict[str, str] = {}
         self.session = requests.Session()
-        # User-Agent 中的版本与 pyproject.toml 同步，用于服务端日志归因
-        # 维护提示：每次版本号变化必须同步改这里（init 里的 __version__ 走 metadata 自动同步）
-        self.session.headers.update({"User-Agent": "QuantDB-Python-SDK/0.2.5"})
+        self.session.headers.update({"User-Agent": _USER_AGENT})
 
         if api_key:
             self.headers = {"X-API-Key": api_key}
@@ -98,6 +99,7 @@ class QuantDBClient:
         json: Optional[dict] = None,
         stream: bool = False,
         headers: Optional[dict] = None,
+        allow_redirects: bool = True,
     ) -> requests.Response:
         url = f"{self.api_host}{path}"
         resp = self.session.request(
@@ -108,6 +110,7 @@ class QuantDBClient:
             stream=stream,
             timeout=self.timeout,
             headers=headers,
+            allow_redirects=allow_redirects,
         )
         return resp
 
@@ -115,6 +118,38 @@ class QuantDBClient:
         resp = self._request("GET", path, params=params)
         return self._check_response(resp)
 
+    def _download_stream(self, params: dict, headers: Optional[dict] = None) -> requests.Response:
+        """下载专用流式请求：手动处理服务端 302 CDN 直连跳转。
+
+        服务端开启 CDN 直连后，/api/v1/data/download 预扣流量成功时返回
+        302 -> CDN 签名 URL。requests 自动跟随会把自定义 X-API-Key 头
+        透传给 CDN 域，故禁用自动跟随，改用不带鉴权头的裸请求直连。
+        """
+        resp = self._request(
+            "GET", "/api/v1/data/download", params=params, stream=True,
+            headers=headers, allow_redirects=False,
+        )
+        if resp.status_code not in (301, 302, 303, 307, 308):
+            return resp
+        location = resp.headers.get("Location", "")
+        etag = resp.headers.get("ETag", "")
+        resp.close()
+        if not location:
+            raise ServerError("下载重定向缺少 Location 头")
+        cdn_resp = requests.get(
+            location,
+            stream=True,
+            timeout=self.timeout,
+            headers={"User-Agent": _USER_AGENT},
+        )
+        if cdn_resp.status_code != 200:
+            cdn_resp.close()
+            raise ServerError(f"CDN 直连下载失败：HTTP {cdn_resp.status_code}")
+        # 网关 302 响应携带 COS ETag；若 CDN 响应缺失则回填，保证客户端缓存逻辑一致。
+        if etag and not cdn_resp.headers.get("ETag"):
+            cdn_resp.headers["ETag"] = etag
+        return cdn_resp
+
     def _post(self, path: str, json: Optional[dict] = None) -> dict:
         resp = self._request("POST", path, json=json)
         return self._check_response(resp)
@@ -302,29 +337,33 @@ class QuantDBClient:
     ) -> pd.DataFrame:
         """查询 K 线数据（下载 COS parquet 切片后客户端解析，消耗下载流量）。
 
-        ``auto`` 在提供日期范围时优先 V2 全市场日分区；如 V2 覆盖不完整，
-        整次回退 V1 股票历史文件。未提供日期范围时直接使用 V1，以保持旧版
-        ``query_kline`` 的全历史语义。显式 ``v2`` 不会静默回退。
+        ``auto`` 始终优先 V2 全市场日分区；仅当提供了日期范围且 V2 覆盖不完整时，
+        整次回退 V1 股票历史文件。未提供日期范围时走 V2 全量（manifest 列出的
+        所有分区），跳过日历完整性校验。显式 ``v1`` 直接走逐股票文件；显式
+        ``v2`` 不会静默回退。
         """
         layout = self._validate_layout(layout)
         sub_category = f"daily_{adj_type}"
         has_range = bool(start_date or end_date)
-        if layout == "v1" or (layout == "auto" and not has_range):
+        if layout == "v1":
             return self._normalise_kline(self.load_as_df("1", sub_category, symbol, layout="v1"), start_date, end_date, fields, limit)
 
         files = self.query_manifest("1", sub_category, layout="v2")
         selected = [f for f in files if (not start_date or f.get("trade_date", "") >= start_date) and (not end_date or f.get("trade_date", "") <= end_date)]
-        # 日历是 V2 完整性的权威。无法得到日历或任一开市日缺分区时，auto 回退 V1；v2 明确报错。
-        calendar = self.query_calendar(start_date, end_date)
-        expected = set()
-        if not calendar.empty:
-            date_col = next((c for c in ("trade_date", "date", "cal_date") if c in calendar.columns), None)
-            open_col = next((c for c in ("is_open", "is_trading_day", "open") if c in calendar.columns), None)
-            if date_col:
-                rows = calendar if not open_col else calendar[calendar[open_col].astype(str).isin(["1", "True", "true"])]
-                expected = set(pd.to_datetime(rows[date_col], errors="coerce").dropna().dt.strftime("%Y-%m-%d"))
-        found = {f.get("trade_date") for f in selected}
-        complete = bool(selected) and (not expected or expected.issubset(found))
+        # 日历是 V2 完整性的权威。仅在有日期范围时校验完整性；无范围时 manifest
+        # 列出什么就下什么，不要求日历覆盖。auto 在覆盖不完整时回退 V1；v2 明确报错。
+        complete = bool(selected)
+        if has_range:
+            calendar = self.query_calendar(start_date, end_date)
+            expected = set()
+            if not calendar.empty:
+                date_col = next((c for c in ("trade_date", "date", "cal_date") if c in calendar.columns), None)
+                open_col = next((c for c in ("is_open", "is_trading_day", "open") if c in calendar.columns), None)
+                if date_col:
+                    rows = calendar if not open_col else calendar[calendar[open_col].astype(str).isin(["1", "True", "true"])]
+                    expected = set(pd.to_datetime(rows[date_col], errors="coerce").dropna().dt.strftime("%Y-%m-%d"))
+            found = {f.get("trade_date") for f in selected}
+            complete = bool(selected) and (not expected or expected.issubset(found))
         if not complete:
             if layout == "auto":
                 return self._normalise_kline(self.load_as_df("1", sub_category, symbol, layout="v1"), start_date, end_date, fields, limit)
@@ -350,6 +389,7 @@ class QuantDBClient:
         下载 trade_date 当日该 symbol 的 tick parquet，按 start_ts/end_ts 过滤时间、按 fields 选列。
         start_ts/end_ts 可传完整时间戳或 "HH:MM:SS"（自动补 trade_date 日期）。
         """
+        trade_date = normalise_tick_trade_date(trade_date)
         df = self.load_as_df("1", "tick_data", symbol, trade_date=trade_date, layout=layout)
         # 时间过滤
         ts_col = "ts" if "ts" in df.columns else ("time" if "time" in df.columns else None)
@@ -486,38 +526,36 @@ class QuantDBClient:
         if object_key:
             params["object_key"] = object_key
 
-        resp = self._request(
-            "GET", "/api/v1/data/download", params=params, stream=True
-        )
+        resp = self._download_stream(params)
         if resp.status_code != 200:
             self._check_response(resp)
 
         fallback = f"{sub_category}.parquet"
         if symbol:
             fallback = f"{sub_category}_{symbol}.parquet"
-        filename = safe_filename(
-            parse_filename_from_content_disposition(resp.headers.get("Content-Disposition", ""), fallback),
-            safe_filename(fallback),
-        )
+        filename = safe_filename(
+            parse_filename_from_content_disposition(resp.headers.get("Content-Disposition", ""), fallback),
+            safe_filename(fallback),
+        )
 
         save_path = os.path.join(save_dir, filename)
         tmp_path = save_path + ".part"
-        maximum = max_download_bytes()
-        check_download_size(resp.headers.get("Content-Length"), maximum)
-        written = 0
-        try:
-            with open(tmp_path, "wb") as f:
-                for chunk in resp.iter_content(chunk_size=8192):
-                    if chunk:
-                        written += len(chunk)
-                        if written > maximum:
-                            raise ServerError(f"下载文件超过大小限制（{maximum} 字节）")
-                        f.write(chunk)
-            os.replace(tmp_path, save_path)
-        except Exception:
-            if os.path.exists(tmp_path):
-                os.remove(tmp_path)
-            raise
+        maximum = max_download_bytes()
+        check_download_size(resp.headers.get("Content-Length"), maximum)
+        written = 0
+        try:
+            with open(tmp_path, "wb") as f:
+                for chunk in resp.iter_content(chunk_size=8192):
+                    if chunk:
+                        written += len(chunk)
+                        if written > maximum:
+                            raise ServerError(f"下载文件超过大小限制（{maximum} 字节）")
+                        f.write(chunk)
+            os.replace(tmp_path, save_path)
+        except Exception:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+            raise
         return os.path.abspath(save_path)
 
     def load_as_df(
@@ -554,7 +592,7 @@ class QuantDBClient:
         headers = {}
         if cached and cached.get("etag"):
             headers["If-None-Match"] = cached["etag"]
-        resp = self._request("GET", "/api/v1/data/download", params=params, headers=headers, stream=True)
+        resp = self._download_stream(params, headers=headers)
         if resp.status_code == 304 and cached:
             return cached["df"]
         if resp.status_code != 200:
@@ -563,16 +601,16 @@ class QuantDBClient:
         # 命中缓存（ETag 未变）：复用已解析的 df，不重复消耗解析
         if cached and etag and cached.get("etag") == etag:
             return cached["df"]
-        maximum = max_download_bytes()
-        check_download_size(resp.headers.get("Content-Length"), maximum)
-        payload, written = io.BytesIO(), 0
-        for chunk in resp.iter_content(chunk_size=1024 * 1024):
-            if chunk:
-                written += len(chunk)
-                if written > maximum:
-                    raise ServerError(f"下载文件超过大小限制（{maximum} 字节）")
-                payload.write(chunk)
-        df = pd.read_parquet(payload)
+        maximum = max_download_bytes()
+        check_download_size(resp.headers.get("Content-Length"), maximum)
+        payload, written = io.BytesIO(), 0
+        for chunk in resp.iter_content(chunk_size=1024 * 1024):
+            if chunk:
+                written += len(chunk)
+                if written > maximum:
+                    raise ServerError(f"下载文件超过大小限制（{maximum} 字节）")
+                payload.write(chunk)
+        df = pd.read_parquet(payload)
         if etag:
             self._cache[cache_key] = {"etag": etag, "df": df}
         return df
@@ -589,12 +627,12 @@ class QuantDBClient:
 
         若文件不存在会先自动下载。
 
-        ``sql`` 仅接受 WHERE 条件字符串；SDK 固定查询下载的单个 Parquet 文件。
+        ``sql`` 仅接受 WHERE 条件字符串；SDK 固定查询下载的单个 Parquet 文件。
 
         安全限制：
             - 不允许分号（;），防止多语句注入
             - 不允许注释（-- 或 /* */），防止注释注入
-            - 不允许子查询、JOIN、外部表函数或任何数据修改语句
+            - 不允许子查询、JOIN、外部表函数或任何数据修改语句
         """
         file_path = self.download_file(
             category_id=category_id,
@@ -611,19 +649,19 @@ class QuantDBClient:
 
         # 安全检查：拒绝危险字符和关键字
         dangerous_keywords = [
-            ";", "--", "/*", "*/", "select", "from", "join", "union", "drop",
-            "delete", "insert", "update", "alter", "create", "exec", "execute",
-            "attach", "copy", "pragma", "install", "load", "read_", "http", "glob",
+            ";", "--", "/*", "*/", "select", "from", "join", "union", "drop",
+            "delete", "insert", "update", "alter", "create", "exec", "execute",
+            "attach", "copy", "pragma", "install", "load", "read_", "http", "glob",
         ]
         sql_upper = sql.upper()
         for kw in dangerous_keywords:
             if kw in sql_upper:
                 raise ValidationError(
                     f"SQL 包含危险关键字 '{kw}'，已被拒绝。"
-                    "query_local 仅支持针对已下载文件的 WHERE 条件。"
-                )
-        sql = f"SELECT * FROM '{clean_path}' WHERE {sql}"
-        return duckdb.query(sql).df()
+                    "query_local 仅支持针对已下载文件的 WHERE 条件。"
+                )
+        sql = f"SELECT * FROM '{clean_path}' WHERE {sql}"
+        return duckdb.query(sql).df()
 
     def get_local_warehouse(self, save_dir: Optional[str] = None) -> "DuckDBWarehouse":
         """获取 DuckDB 本地数据仓库实例，用于离线多表 SQL JOIN 查询。"""
@@ -656,12 +694,12 @@ class QuantDBClient:
                     for obj in release.get("objects", []):
                         key = self._normalise_release_key(obj["key"])
                         relative_path = obj.get("relative_path") or key
-                        target = safe_join(root, relative_path)
+                        target = safe_join(root, relative_path)
                         expected_size = obj.get("size")
                         old = state.execute("SELECT etag, sha256, size, path FROM objects WHERE key=?", (key,)).fetchone()
                         if old and old[0] == obj.get("etag") and old[1] == obj.get("sha256") and os.path.exists(old[3]) and (expected_size is None or os.path.getsize(old[3]) == expected_size):
                             continue
-                        resp = self._request("GET", "/api/v1/data/download", params={"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v2", "object_key": key}, stream=True)
+                        resp = self._download_stream({"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v2", "object_key": key})
                         if resp.status_code != 200:
                             self._check_response(resp)
                         os.makedirs(os.path.dirname(target), exist_ok=True)
@@ -694,12 +732,20 @@ class QuantDBClient:
             manifest = self._get("/api/v1/data/download/manifest", {"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1"})
             for obj in manifest.get("files", []):
                 key, relative_path = obj["key"], obj.get("relative_path") or obj["key"]
-                target = safe_join(root, relative_path)
+                target = safe_join(root, relative_path)
                 expected_size = obj.get("size")
                 old = state.execute("SELECT etag, size, path FROM objects WHERE key=?", (key,)).fetchone()
                 if old and old[0] == obj.get("etag") and os.path.exists(old[2]) and (expected_size is None or os.path.getsize(old[2]) == expected_size):
                     continue
-                resp = self._request("GET", "/api/v1/data/download", params={"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")}, stream=True)
+                download_params = {"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")}
+                # Tick manifest 的每个对象都是独立交易日 shard。不能省略日期，
+                # 否则后端会回退下载该股票的最新 shard，造成历史同步错位。
+                if dataset == "tick_data":
+                    trade_date = obj.get("trade_date")
+                    if not trade_date:
+                        raise ServerError("Tick manifest 缺少 trade_date")
+                    download_params["trade_date"] = normalise_tick_trade_date(trade_date)
+                resp = self._download_stream(download_params)
                 if resp.status_code != 200: self._check_response(resp)
                 os.makedirs(os.path.dirname(target), exist_ok=True)
                 tmp = target + ".part"

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7/quantdb_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.2.5
+Version: 0.2.7
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT
@@ -90,12 +90,17 @@ client = QuantDBClient(username="admin", password="admin123")
 
 ## V1 / V2 数据布局
 
-COS 同时保留 V1（按股票历史文件）和 V2（按交易日全市场分区）。所有下载相关接口均可传入
-`layout="auto" | "v1" | "v2"`。默认 `auto` 的规则是：给出 K 线日期范围时优先 V2；若任一
-交易日没有 V2 分区，则整次请求回退 V1，绝不混合两种口径；未给日期范围时读取 V1 全历史文件。
+QuantDB 数据采用两种物理布局：V1（按股票的全历史文件 `{Symbol}.parquet`）和 V2（按交易日的全市场分区 `dt=YYYYMMDD/data.parquet`）。
+所有下载相关接口均可传入 `layout="auto" | "v1" | "v2"`。
+
+**V2 数据集**（COS 纯 V2，零 V1 残留）：daily_unadjusted / daily_forward / daily_backward / index_daily / valuation / technical_indicators / market_sentiment / features_daily / l1_factors / l2_factors / margin_trading
+
+**V1 数据集**（纯 V1，无 V2 分区）：min1_kline / min5_kline / tick_data / 财务七表 / 基础板块
+
+默认 `auto` 始终优先 V2：有日期范围时聚合 V2 多日分区，若覆盖不完整则回退 V1（仅对仍保留 V1 文件的数据集有效）；无日期范围时走 V2 全量（manifest 列出的所有分区），跳过完整性校验。
 
 ```python
-# 按日期范围优先 V2；覆盖不完整时自动回退 V1
+# 始终优先 V2 按日分区；有范围且覆盖不完整时自动回退 V1
 df = client.query_kline("600519.SH", start_date="2026-07-01", end_date="2026-07-24")
 
 # 强制指定物理布局；layout="v2" 缺日时会明确报错

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/quantdb_sdk.egg-info/SOURCES.txt

@@ -18,4 +18,5 @@ quantdb_sdk.egg-info/requires.txt
 quantdb_sdk.egg-info/top_level.txt
 tests/test_async_client.py
 tests/test_client.py
-tests/test_technical_indicators.py
+tests/test_technical_indicators.py
+tests/test_update_pipeline.py

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/tests/test_async_client.py

@@ -83,6 +83,23 @@ async def test_a_sync_financial_v1_validates_manifest_size(tmp_path):
     assert (tmp_path / "3_financial_data" / "balance" / "600000.SH.parquet").read_bytes() == payload
 
 
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_sync_tick_uses_manifest_trade_date(tmp_path):
+    payload = b"tick-parquet"
+    respx.get(f"{API_HOST}/api/v1/data/releases").mock(return_value=httpx.Response(200, json={"releases": []}))
+    respx.get(f"{API_HOST}/api/v1/data/download/manifest").mock(return_value=httpx.Response(200, json={"files": [{
+        "key": "1_kline_data/tick_data/600519_SH_20260720.parquet",
+        "relative_path": "1_kline_data/tick_data/600519_SH_20260720.parquet",
+        "symbol": "600519.SH", "trade_date": "2026-07-20", "etag": "tick-etag", "size": len(payload),
+    }]}))
+    route = respx.get(f"{API_HOST}/api/v1/data/download").mock(return_value=httpx.Response(200, content=payload))
+    async with AsyncQuantDBClient(api_host=API_HOST, api_key="test-key") as client:
+        result = await client.a_sync_dataset("tick_data", str(tmp_path))
+    assert result["downloaded"] == ["1_kline_data/tick_data/600519_SH_20260720.parquet"]
+    assert parse_qs(urlparse(str(route.calls[0].request.url)).query)["trade_date"] == ["2026-07-20"]
+
+
 @pytest.mark.asyncio
 @respx.mock
 async def test_a_auth_error_raises_auth_error():

{quantdb_sdk-0.2.5 → quantdb_sdk-0.2.7}/tests/test_client.py

@@ -9,7 +9,7 @@ import responses
 
 from quantdb_sdk import AuthError, InsufficientTrafficError, QuantDBClient
 from quantdb_sdk.errors import ServerError
-from quantdb_sdk._utils import safe_join
+from quantdb_sdk._utils import normalise_tick_trade_date, safe_join, tick_shard_relative_path
 
 
 API_HOST = "http://localhost:5000"
@@ -55,6 +55,15 @@ def test_safe_join_rejects_path_traversal(tmp_path):
         safe_join(str(tmp_path), "../../outside.parquet")
 
 
+def test_tick_shard_path_is_flat_and_date_is_normalised():
+    assert normalise_tick_trade_date("20260720") == "2026-07-20"
+    assert tick_shard_relative_path("600519.SH", "2026-07-20") == (
+        "1_kline_data/tick_data/600519_SH_20260720.parquet"
+    )
+    with pytest.raises(ValueError):
+        normalise_tick_trade_date("2026-99-20")
+
+
 @responses.activate
 def test_download_file_uses_safe_fallback_for_malicious_filename(tmp_path):
     responses.get(
@@ -130,6 +139,25 @@ def test_sync_financial_v1_validates_manifest_size(tmp_path):
     assert (tmp_path / "3_financial_data" / "balance" / "600000.SH.parquet").read_bytes() == payload
 
 
+@responses.activate
+def test_sync_tick_uses_manifest_trade_date(tmp_path):
+    payload = b"tick-parquet"
+    responses.get(f"{API_HOST}/api/v1/data/releases", json={"releases": []}, status=200)
+    responses.get(
+        f"{API_HOST}/api/v1/data/download/manifest",
+        json={"files": [{
+            "key": "1_kline_data/tick_data/600519_SH_20260720.parquet",
+            "relative_path": "1_kline_data/tick_data/600519_SH_20260720.parquet",
+            "symbol": "600519.SH", "trade_date": "2026-07-20", "etag": "tick-etag", "size": len(payload),
+        }]}, status=200,
+    )
+    responses.get(f"{API_HOST}/api/v1/data/download", body=payload, status=200)
+    result = QuantDBClient(api_host=API_HOST, api_key="test-key").sync_dataset("tick_data", str(tmp_path))
+    assert result["downloaded"] == ["1_kline_data/tick_data/600519_SH_20260720.parquet"]
+    params = parse_qs(urlparse(responses.calls[-1].request.url).query)
+    assert params["trade_date"] == ["2026-07-20"]
+
+
 @responses.activate
 def test_sync_v1_size_failure_does_not_keep_partial_file(tmp_path):
     responses.get(f"{API_HOST}/api/v1/data/releases", json={"releases": []}, status=200)

quantdb_sdk-0.2.7/tests/test_update_pipeline.py

@@ -0,0 +1,42 @@
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+
+MODULE = Path(__file__).resolve().parents[1] / "pipeline" / "update_pipeline.py"
+SPEC = importlib.util.spec_from_file_location("update_pipeline", MODULE)
+pipeline = importlib.util.module_from_spec(SPEC)
+assert SPEC and SPEC.loader
+sys.modules[SPEC.name] = pipeline
+SPEC.loader.exec_module(pipeline)
+
+
+def test_manual_tasks_are_not_automatic():
+    names = {task.name for task in pipeline.AUTO_TASKS}
+    assert "tick" not in names
+    assert "l2" not in names
+    assert pipeline.MANUAL_TASKS == {"tick", "l2"}
+
+
+def test_dry_run_writes_machine_readable_manifest(tmp_path, monkeypatch):
+    monkeypatch.setattr(pipeline, "DATA_ROOT", tmp_path)
+    monkeypatch.setattr(pipeline, "RUNS_DIR", tmp_path / "_meta" / "update_runs")
+    args = type("Args", (), {"tasks": "market", "resume": None, "dry_run": True, "no_publish": True})()
+    assert pipeline.run(args) == 0
+    manifests = list((tmp_path / "_meta" / "update_runs").glob("*.json"))
+    assert len(manifests) == 1
+    data = json.loads(manifests[0].read_text(encoding="utf-8"))
+    assert data["status"] == "dry_run"
+    assert data["tasks"][0]["name"] == "market"
+    assert data["tasks"][0]["strategy"] == "always_full"
+
+
+def test_dry_run_keeps_dependencies_plannable(tmp_path, monkeypatch):
+    monkeypatch.setattr(pipeline, "DATA_ROOT", tmp_path)
+    monkeypatch.setattr(pipeline, "RUNS_DIR", tmp_path / "_meta" / "update_runs")
+    args = type("Args", (), {"tasks": None, "resume": None, "dry_run": True, "no_publish": True})()
+    assert pipeline.run(args) == 0
+    manifest = next((tmp_path / "_meta" / "update_runs").glob("*.json"))
+    statuses = {task["name"]: task["status"] for task in json.loads(manifest.read_text(encoding="utf-8"))["tasks"]}
+    assert "skipped_dependency" not in statuses.values()