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

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

@@ -3,6 +3,12 @@
 所有 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
@@ -10,6 +16,17 @@
 - **凭证保护**：同步客户端此前跟随 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.6/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.6
+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.6 → 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.6 → quantdb_sdk-0.2.7}/pyproject.toml

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

{quantdb_sdk-0.2.6 → 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.6 → 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.6 → quantdb_sdk-0.2.7}/quantdb_sdk/async_client.py

@@ -13,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 (
@@ -27,7 +27,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.2.6"
+_USER_AGENT = "QuantDB-Python-SDK/0.2.7"
 
 
 class AsyncQuantDBClient:
@@ -114,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:
@@ -278,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'")
@@ -313,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):
@@ -624,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._download_stream({"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.6 → quantdb_sdk-0.2.7}/quantdb_sdk/client.py

@@ -15,7 +15,7 @@ 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,
+    max_download_bytes, normalise_tick_trade_date, parse_filename_from_content_disposition, safe_filename, safe_join,
     validate_api_host,
 )
 from .errors import (
@@ -29,7 +29,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.2.6"
+_USER_AGENT = "QuantDB-Python-SDK/0.2.7"
 
 
 class QuantDBClient:
@@ -337,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)
@@ -385,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)
@@ -732,7 +737,15 @@ class QuantDBClient:
                 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._download_stream({"category_id": SYNC_DATASET_CATEGORIES[dataset], "sub_category": dataset, "layout": "v1", "symbol": obj.get("symbol", "")})
+                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.6 → 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.6
+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.6 → 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.6 → 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.6 → 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()