ohlcvault 0.2.1__tar.gz → 0.3.0__tar.gz

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ohlcvault
-Version: 0.2.1
+Version: 0.3.0
 Summary: Reproducible, checksummed daily OHLCV data for A-share, HK and US markets — static files, content-addressed snapshots, zero API keys.
 Project-URL: Homepage, https://helpquant.com
 Project-URL: Documentation, https://github.com/helpquant/ohlcvault#readme
@@ -132,6 +132,17 @@ A mirror can be an HTTP(S) URL **or a local directory**:
 ov.connect(mirrors=["/path/to/data"])
 ```
 
+The built-in chain has two entries whose **failure domains are disjoint** — a
+commercial CDN and a self-hosted origin:
+
+| Mirror | Role | Independent failure domain |
+|---|---|---|
+| `https://data.ohlcvault.com` | primary | commercial CDN: account suspension, billing, regional outage |
+| `https://data.helpquant.com` | fallback | own server + own DNS |
+
+Override with `OHLCVAULT_MIRRORS=https://a,https://b`, or pass `mirrors=` / set
+`OHLCVAULT_CACHE` to keep everything local.
+
 Mirrors are tried in order; whichever one succeeds is promoted to first place. Every
 file is checked against the `sha256` in the snapshot manifest, and anything that
 fails is **discarded and the next mirror is tried** — bad bytes are never handed to
@@ -209,6 +220,7 @@ part of the checksum chain and can be deleted/rebuilt at any time.
 | `calendar(market, start=, end=)` | Trading calendar |
 | `daily(code, start=, end=)` | Stock daily bars, cross-month stitching |
 | `index_daily(code, start=, end=)` | Index daily bars |
+| `min15_daily(code, start=, end=)` | 15-minute bars (`daily/min15/`, cn stocks; `d` = bar end time `YYYYMMDDHHMM`, no adjustment factors) |
 | `daily_many(codes, start=, end=)` | Batch read (preferred for backtests) |
 | `cross_section(market, date, sort_by=, limit=)` | Daily cross-section |
 | `adjust(bars_or_df, to="qfq"\|"hfq"\|"none")` | Adjustment view |

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/README.md

@@ -100,6 +100,17 @@ A mirror can be an HTTP(S) URL **or a local directory**:
 ov.connect(mirrors=["/path/to/data"])
 ```
 
+The built-in chain has two entries whose **failure domains are disjoint** — a
+commercial CDN and a self-hosted origin:
+
+| Mirror | Role | Independent failure domain |
+|---|---|---|
+| `https://data.ohlcvault.com` | primary | commercial CDN: account suspension, billing, regional outage |
+| `https://data.helpquant.com` | fallback | own server + own DNS |
+
+Override with `OHLCVAULT_MIRRORS=https://a,https://b`, or pass `mirrors=` / set
+`OHLCVAULT_CACHE` to keep everything local.
+
 Mirrors are tried in order; whichever one succeeds is promoted to first place. Every
 file is checked against the `sha256` in the snapshot manifest, and anything that
 fails is **discarded and the next mirror is tried** — bad bytes are never handed to
@@ -177,6 +188,7 @@ part of the checksum chain and can be deleted/rebuilt at any time.
 | `calendar(market, start=, end=)` | Trading calendar |
 | `daily(code, start=, end=)` | Stock daily bars, cross-month stitching |
 | `index_daily(code, start=, end=)` | Index daily bars |
+| `min15_daily(code, start=, end=)` | 15-minute bars (`daily/min15/`, cn stocks; `d` = bar end time `YYYYMMDDHHMM`, no adjustment factors) |
 | `daily_many(codes, start=, end=)` | Batch read (preferred for backtests) |
 | `cross_section(market, date, sort_by=, limit=)` | Daily cross-section |
 | `adjust(bars_or_df, to="qfq"\|"hfq"\|"none")` | Adjustment view |

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/SPEC.md

@@ -64,6 +64,7 @@
 |---|---|---|---|
 | `stock` | 非指数证券（股票、ETF、可转债） | `daily/{market}/` | 有真实成交量与成交额，单位是「股 / 元」 |
 | `index` | 指数 | `daily/idx/{market}/` | 成交量口径与个股**不同源**，见 §9.3 |
+| `min15` | 15 分钟 K 线 | `daily/min15/{market}/` | 日内条形，bar 以**结束时刻**标注，见 §4.6。V1 仅 `cn` 且仅个股 |
 
 **为什么必须分开（这不是洁癖，是正确性要求）：**
 
@@ -130,6 +131,7 @@ meta/symbols/{market}.json                   # 标的清单（含指数、含退
 meta/calendar/{market}.json                  # 交易日历
 daily/{market}/{YYYY-MM}.json.gz             # 月分片 · stock 命名空间
 daily/idx/{market}/{YYYY-MM}.json.gz         # 月分片 · index 命名空间
+daily/min15/{market}/{YYYY-MM}.json.gz       # 月分片 · min15 命名空间（§4.6）
 snapshots/{sid}/root.json                    # 快照摘要
 snapshots/{sid}/manifest.json                # 快照事实清单（逐文件 sha256）
 changes/{sid}.json                           # 相对父快照的增量
@@ -217,7 +219,7 @@ changes/{sid}.json                           # 相对父快照的增量
 |---|---|---|---|
 | `schema` | int | ✔ | 本文件版本，当前 `1` |
 | `market` | str | ✔ | §1.1 市场代码 |
-| `namespace` | str | ✔ | §1.2，`stock` 或 `index` |
+| `namespace` | str | ✔ | §1.2，`stock` / `index` / `min15` |
 | `period` | str | ✔ | `YYYY-MM`，**必须**与文件名一致 |
 | `adjust` | str | ✔ | **恒为 `"none"`**。本数据集只存不复权原始价，见 §9.2 |
 | `price_scale` | int | ✔ | 价格定点标度，`1000` |
@@ -299,6 +301,27 @@ changes/{sid}.json                           # 相对父快照的增量
 
 **唯一的例外是交易所追溯修正成交数据**（极罕见）。此时文件内容变了、sha256 变了，客户端按 §10.3 的规则重下即可——**不需要为此改变缓存策略**。
 
+### 4.6 `min15` 命名空间：15 分钟 K 线（v1.1 增补，2026-11-08）
+
+与 §4.1/§4.2 共用文件头与 block 形状，仅以下规则不同：
+
+1. **bar 时刻语义**：block 的 `d` 是 **bar 结束时刻** `YYYYMMDDHHMM`（12 位整数）。
+   沪深一天 16 根：`0945…1130`（8 根）+ `1315…1500`（8 根）。升序、唯一、落在
+   `period` 之内的约束与日线一致。cn 市场固定为北京时间，无需时区字段。
+2. **头部新增两个自描述字段**（`min15` 文件**必须**声明）：`"interval": "15min"`
+   与 `"bar_boundary": "end"`。
+3. **无因子**：头部 `af_basis="unavailable"`，block **不得**含 `af` 键（与 §4.3
+   的条件缺席规则一致）。分钟数据只做 `adjust="none"` 的事实存储。
+4. **单位**：`o/h/l/c` × `price_scale`（1000）；`v` 已归一为**股**；`a` 元——与
+   §9.1/§9.3 完全同口径，不引入新标度。
+5. **覆盖**：V1 仅 `cn`、仅个股（含退市股）。停牌时段没有 bar（无成交即无 K 线），
+   这与日线「停牌补平盘行」的行为**刻意不同**——分钟粒度不虚构流动性。
+6. **回填期豁免**：min15 的深历史回填（baostock 2020-01 起）是渐进过程，回填
+   完成前**已封月可能被补写**。缓存仍按 sealed 发（immutable），sid 随内容滚动，
+   客户端按 §10.3 哈希重下即可。回填完成后恢复「已封月永不重写」。
+7. **来源**：pytdx 主源（近期 ~2 年）+ baostock 深历史（2020-01 起），头部
+   `source` 用 `+` 连接，如 `pytdx_15min+baostock_15min`。
+
 ---
 
 ## 5. `meta/symbols/{market}.json` — 标的清单
@@ -444,7 +467,8 @@ changes/{sid}.json                           # 相对父快照的增量
       "calendar": { "path": "meta/calendar/cn.json", "count": 6543 },
       "monthly": {
         "stock": [ { "period": "2026-07", "path": "daily/cn/2026-07.json.gz", "status": "sealed" } ],
-        "index": [ { "period": "2026-07", "path": "daily/idx/cn/2026-07.json.gz", "status": "sealed" } ]
+        "index": [ { "period": "2026-07", "path": "daily/idx/cn/2026-07.json.gz", "status": "sealed" } ],
+        "min15": [ { "period": "2026-07", "path": "daily/min15/cn/2026-07.json.gz", "status": "sealed" } ]
       },
       "last_trade_date": 20260918
     }
@@ -453,6 +477,8 @@ changes/{sid}.json                           # 相对父快照的增量
 ```
 
 `monthly[namespace]` 按 `period` 升序。`status` ∈ `open`（当月）\| `sealed`（已封月）。
+命名空间键按需出现：某市场没有某个命名空间的数据时，对应键**缺席**（而不是空数组）——
+例如 v1.1 起 `cn` 才有 `min15`，`hk`/`us` 没有。客户端对未知命名空间键**必须**忽略。
 
 ### 7.1 manifest **不得**包含 `snapshot` 字段
 
@@ -646,6 +672,7 @@ sid = sha256( 对每个文件取 "路径:sha256:size" 行 → 排序 → 拼接
 | 日期 | 变更 |
 |---|---|
 | 2026-09-21 | v1 定稿。确立：指数独立命名空间 `daily/idx/`；`af` 为唯一合法因子键（废止 `f`）；存储前缀式 / API 后缀式的双轨规范；文件头字段统一（`af_scale`、`af_basis`、`currency`、`updated`）；退市股强制入池；显式 `.json.gz`；`meta/manifest.json` 与快照指纹分离。 |
+| 2026-11-08 | v1.1 增补：新增 `min15` 命名空间（`daily/min15/{market}/`，15 分钟 K 线，bar 结束时刻 `YYYYMMDDHHMM`，无因子，V1 仅 cn 个股，见 §4.6）；manifest 的 `monthly` 按需出现命名空间键，客户端必须忽略未知键（§7）。数据形状变更不影响既有 `stock` / `index` 读取。 |
 
 ### 12.1 v1 定稿时推翻的三处早期约定
 

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/ohlcvault/__init__.py

@@ -192,6 +192,17 @@ def index_daily(code: str, start: int | str | None = None, end: int | str | None
                                 refresh=refresh)
 
 
+def min15_daily(code: str, start: int | str | None = None, end: int | str | None = None,
+                market: str | None = None, refresh: bool = False) -> Bars:
+    """15 分钟线（`daily/min15/`，V1 仅 cn 个股）。
+
+    `d` 是 bar 结束时刻 `YYYYMMDDHHMM`（12 位）；无复权因子（af=None）。
+    `start`/`end` 仍传 8 位日期（如 `"2026-09-18"`），按日切片。
+    """
+    return _store().min15_daily(code, start=start, end=end, market=market,
+                                refresh=refresh)
+
+
 def daily_many(codes, start: int | str | None = None, end: int | str | None = None,
                market: str | None = None, namespace: str = "stock",
                refresh: bool = False) -> dict[str, Bars]:

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/ohlcvault/client.py

@@ -71,7 +71,19 @@ class MarketClient:
 
     @staticmethod
     def _label(m: str) -> str:
-        return m.rsplit("/", 2)[-2] if m.startswith("http") else Path(m).name
+        """镜像的短标签，用于 trace 与 `stats["served_by"]`。
+
+        必须对**裸主机 URL** 也给出可区分的名字：默认镜像链全是
+        `https://<host>` 这种无路径形态，而按「最后一个路径段」取名会得到
+        空串 —— 于是两个不同的镜像在统计里混成同一个 key，
+        「到底命中了主源还是备用源」这个问题就再也答不出来了（实测踩到）。
+        """
+        s = str(m).rstrip("/")
+        if "://" in s:
+            rest = s.split("://", 1)[1]
+            host, _, path = rest.partition("/")
+            return f"{host}/{path}" if path else host
+        return Path(s).name
 
     def _fetch_raw(self, m: str, rel: str) -> bytes:
         if m.startswith("http"):

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/ohlcvault/config.py

@@ -5,9 +5,13 @@
 
 | 镜像 | 角色 | 故障域 |
 |---|---|---|
-| Cloudflare R2 + CDN | 主源 | 商业 CDN：账号封禁、账单异常、区域故障 |
-| GitHub raw / jsDelivr | 备用 1 | 微软系托管：与 Cloudflare 完全独立 |
-| 自有服务器 HTTPS | 备用 2 | 自有机器：唯一完全可控的兜底 |
+| `data.ohlcvault.com`（Cloudflare R2 + CDN） | 主源 | 商业 CDN：账号封禁、账单异常、区域故障 |
+| `data.helpquant.com`（自有服务器 HTTPS） | 备用 1 | 自有机器 + 自有 DNS（DNSPod）：唯一完全可控的兜底 |
+
+历史上这里还有第三个源（`cdn.jsdelivr.net/gh/…` 与 `raw.githubusercontent.com/…`），
+指向数据镜像仓库 `helpquant/ohlcvault-data`。该仓库经 GitHub API 查证 **404，从未
+创建**，两个 URL 都是死链，只会让客户端在冷启动时白付一次超时 —— 已移除。
+日后若真建了 GitHub 镜像仓库，再把它们加回来即可（届时故障域才是真正独立的）。
 
 客户端会**记住哪个镜像成功过**并把它提到首位，所以镜像顺序不是性能关键，
 减少的是「每次请求都先付一次失败超时」。
@@ -29,18 +33,17 @@ MARKETS: dict[str, dict] = {
     "us": {"name": "美股", "timezone": "America/New_York", "currency": "USD"},
 }
 
-NAMESPACES = ("stock", "index")
+NAMESPACES = ("stock", "index", "min15")
 
 # HTTP User-Agent。必须带自定义 UA：Cloudflare 等边缘节点默认拦截
 # Python-urllib/* 的请求（403），裸 urllib 会被当成 bot。
-VERSION = "0.2.0"
+VERSION = "0.3.0"
 USER_AGENT = f"ohlcvault/{VERSION} (+https://github.com/helpquant/ohlcvault)"
 
 # 默认镜像链。可用 OHLCVAULT_MIRRORS 覆盖。
 DEFAULT_MIRRORS: list[str] = [
     "https://data.ohlcvault.com",
-    "https://cdn.jsdelivr.net/gh/helpquant/ohlcvault-data@main",
-    "https://raw.githubusercontent.com/helpquant/ohlcvault-data/main",
+    "https://data.helpquant.com",
 ]
 
 DEFAULT_CACHE = Path(

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/ohlcvault/sql.py

@@ -33,7 +33,7 @@ CREATE TABLE IF NOT EXISTS meta (key VARCHAR, value VARCHAR);
 CREATE TABLE IF NOT EXISTS bars (
     symbol    VARCHAR,   -- API 式代码，如 '600519.SH'
     market    VARCHAR,   -- 'cn' | 'hk' | 'us'
-    namespace VARCHAR,   -- 'stock' | 'index'
+    namespace VARCHAR,   -- 'stock' | 'index' | 'min15'
     d         BIGINT,    -- YYYYMMDD
     o         BIGINT,    -- 价格 × price_scale（定点整数，契约口径）
     h         BIGINT,
@@ -72,7 +72,8 @@ def to_duckdb(
     """把快照（或其子集）物化成本地 DuckDB 文件，返回文件路径。
 
     - `markets`：缺省导出全部市场；传 `["cn"]` 只导 A 股
-    - `namespaces`：默认 stock + index 都导
+    - `namespaces`：默认 stock + index 都导；传 `("stock", "index", "min15")`
+      可一并导出 15 分钟线（min15 是按需启用的命名空间，快照里可能没有）
     - `periods`：限定月份（如 `["2026-09"]`），小规模试用/测试用
     - `refresh=True`：删掉旧文件重导（同 sid 的文件存在时默认直接复用）
 
@@ -100,10 +101,15 @@ def to_duckdb(
             parts = rel.split("/")
             if parts[0] != "daily":
                 continue
-            ns = "index" if parts[1] == "idx" else "stock"
+            if parts[1] == "min15":
+                ns = "min15"                # daily/min15/{market}/…
+            elif parts[1] == "idx":
+                ns = "index"
+            else:
+                ns = "stock"
             if ns not in namespaces:
                 continue
-            market = parts[2 if ns == "index" else 1]
+            market = parts[2 if ns != "stock" else 1]
             if markets and market not in markets:
                 continue
             period = parts[-1].removesuffix(".json.gz")

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/ohlcvault/store.py

@@ -27,7 +27,8 @@ from .client import MarketClient
 from .config import AF_SCALE, MARKETS, NAMESPACES, PRICE_SCALE, SUPPORTED_SCHEMA
 from .errors import ContractError, DateError, NotSupported, UnknownMarket
 
-_SHARD_RE = re.compile(r"^daily/(?:idx/)?(?P<market>[a-z]{2})/(?P<period>\d{4}-\d{2})\.json\.gz$")
+_SHARD_RE = re.compile(
+    r"^daily/(?:(?P<ns>idx|min15)/)?(?P<market>[a-z]{2})/(?P<period>\d{4}-\d{2})\.json\.gz$")
 
 # 断面可按哪些字段排序。注意这里是**返回行**的键名（`amount`/`volume`…），
 # 不是 block 里的单字母键（`a`/`v`…）—— 两者不同，映射错了排序会静默全落到 None。
@@ -48,8 +49,14 @@ def _sort_none_last(rows: list[dict], key: str, ascending: bool) -> list[dict]:
 
 
 def period_of(d: int) -> str:
-    """20260918 → '2026-09'"""
-    return f"{d // 10000:04d}-{d // 100 % 100:02d}"
+    """20260918 → '2026-09'；min15 的 12 位 bar 日期 202609181500 同样正确。"""
+    day = d // 10000 if d >= 10_000_000_000 else d   # 12 位 YYYYMMDDHHMM → 8 位
+    return f"{day // 10000:04d}-{day // 100 % 100:02d}"
+
+
+def _ns_dir(namespace: str) -> str:
+    """命名空间 → 分片路径里 `daily/` 之后的子目录前缀。"""
+    return {"index": "idx/", "min15": "min15/"}.get(namespace, "")
 
 
 def periods_between(start: int, end: int) -> list[str]:
@@ -239,13 +246,13 @@ class Store:
         """快照里该市场该命名空间有哪些月份（已排序）。"""
         self._check_market(market)
         self._check_namespace(namespace)
+        # _SHARD_RE 的 ns 捕获组是裸名（None/'idx'/'min15'），按它过滤才不会串
+        want = {"stock": None, "index": "idx", "min15": "min15"}[namespace]
         out = []
         for rel in self.client.files():
             m = _SHARD_RE.match(rel)
-            if m and m.group("market") == market:
-                is_idx = rel.startswith("daily/idx/")
-                if is_idx == (namespace == "index"):
-                    out.append(m.group("period"))
+            if m and m.group("market") == market and (m.group("ns") or None) == want:
+                out.append(m.group("period"))
         return sorted(out)
 
     # ---------- 契约校验 ----------
@@ -279,6 +286,13 @@ class Store:
                 f"（本数据集只存事实、不存视图，SPEC.md §9.2）")
         if header.get("volume_unit") != "share":
             raise ContractError(f"{rel}: volume_unit={header.get('volume_unit')!r}，应为 'share'")
+        if namespace == "min15":
+            if header.get("interval") != "15min":
+                raise ContractError(
+                    f"{rel}: min15 必须声明 interval='15min'（SPEC.md §4.6）")
+            if header.get("bar_boundary") != "end":
+                raise ContractError(
+                    f"{rel}: min15 必须声明 bar_boundary='end'（bar 时刻=结束时刻）")
         if header.get("af_basis") == "unavailable" and "af_scale" in header:
             raise ContractError(
                 f"{rel}: af_basis='unavailable' 时不得出现 af_scale（SPEC.md §4.1）")
@@ -313,8 +327,7 @@ class Store:
         """取一个原始月分片（含文件头与全部 block）。带 LRU 缓存。"""
         self._check_market(market)
         self._check_namespace(namespace)
-        rel = (f"daily/{'idx/' if namespace == 'index' else ''}"
-               f"{market}/{period}.json.gz")
+        rel = f"daily/{_ns_dir(namespace)}{market}/{period}.json.gz"
         if not refresh and rel in self._shard_cache:
             self._shard_cache.move_to_end(rel)
             return self._shard_cache[rel]
@@ -337,8 +350,7 @@ class Store:
     def _block(self, market: str, period: str, storage: str,
                namespace: str, refresh: bool) -> dict | None:
         doc = self.shard(market, period, namespace, refresh=refresh)
-        rel = (f"daily/{'idx/' if namespace == 'index' else ''}"
-               f"{market}/{period}.json.gz")
+        rel = f"daily/{_ns_dir(namespace)}{market}/{period}.json.gz"
         idx = self._block_index.get(rel)
         if idx is not None:                     # O(1) 索引（shard() 已建）
             return idx.get(storage)
@@ -425,7 +437,7 @@ class Store:
 
     def _mat_path(self, storage: str, namespace: str) -> Path:
         sid = self.client.snapshot
-        ns = "idx" if namespace == "index" else "stock"
+        ns = {"index": "idx", "min15": "min15"}.get(namespace, "stock")
         return (Path(self.client.cache) / "symbols" / sid / ns
                 / f"{storage}.json.gz")
 
@@ -475,10 +487,12 @@ class Store:
         """物化文档 → Bars（可选二次切片）。"""
         acc = {k: list(doc[k])
                for k in ("d", "o", "h", "l", "c", "v", "a", "af")}
-        if start is not None or end is not None:
+        # min15：8 位 end 当日扩到 23:59（同 _assemble，见那里的注释）
+        end_eff = (end * 10000 + 2359) if (end is not None and namespace == "min15") else end
+        if start is not None or end_eff is not None:
             d = acc["d"]
             lo = 0 if start is None else bisect_left(d, start)
-            hi = len(d) if end is None else bisect_right(d, end)
+            hi = len(d) if end_eff is None else bisect_right(d, end_eff)
             acc = {k: v[lo:hi] for k, v in acc.items()}
         header = self._mat_header(doc, mkt)
         has_af = bool(doc.get("has_af"))
@@ -510,6 +524,18 @@ class Store:
         （两者的 `volume_unit` 归一乘数不同，混在一个文件里会污染全局口径）。"""
         return self._series(code, start, end, market, "index", refresh)
 
+    def min15_daily(self, code: str, start: int | None = None,
+                    end: int | None = None, market: str | None = None,
+                    refresh: bool = False) -> Bars:
+        """15 分钟线（`daily/min15/` 命名空间，SPEC §4.6；V1 仅 cn 个股）。
+
+        - `d` 是 **bar 结束时刻** `YYYYMMDDHHMM`（12 位），如 `202609181500`
+          = 当日 15:00 收盘 bar。`start`/`end` 仍传 8 位日期，按日切片。
+        - 无复权因子（`af_basis="unavailable"`）：分钟级不做复权，`af=None`，
+          对它调复权会得到明确报错而不是静默错误。
+        """
+        return self._series(code, start, end, market, "min15", refresh)
+
     def _series(self, code: str, start: int | str | None, end: int | str | None,
                 market: str | None, namespace: str, refresh: bool) -> Bars:
         start = _as_ymd(start, "start")
@@ -521,6 +547,9 @@ class Store:
 
     def _assemble(self, storage: str, mkt: str, namespace: str,
                   start: int | None, end: int | None, refresh: bool) -> Bars:
+        # min15 的 d 是 12 位结束时刻，8 位 end 当日（20260930）必须扩成
+        # 23:59（202609302359）—— 否则 bisect_right 会把当天所有 bar 切掉
+        end_eff = (end * 10000 + 2359) if (end is not None and namespace == "min15") else end
         mat = (self._mat_load(storage, namespace)
                if (self.materialize and not refresh) else None)
         if mat is not None:
@@ -547,7 +576,7 @@ class Store:
                     continue                  # 该月无数据（未上市/停牌/退市后）
                 if header is None:
                     header = self.shard(mkt, p, namespace, refresh=refresh)
-                chunk = self._slice_block(blk, start, end)
+                chunk = self._slice_block(blk, start, end_eff)
                 if chunk is None:
                     continue
                 for k in ("d", "o", "h", "l", "c", "v", "a"):
@@ -578,10 +607,10 @@ class Store:
                       "source": "", "af_scale": None}
 
         # 物化路径拿到的是全历史，带日期参数时二次切片
-        if mat is not None and (start is not None or end is not None):
+        if mat is not None and (start is not None or end_eff is not None):
             d = acc["d"]
             lo = 0 if start is None else bisect_left(d, start)
-            hi = len(d) if end is None else bisect_right(d, end)
+            hi = len(d) if end_eff is None else bisect_right(d, end_eff)
             acc = {k: v[lo:hi] for k, v in acc.items()}
 
         if self.validate:
@@ -606,9 +635,12 @@ class Store:
         if any(d[i] >= d[i + 1] for i in range(len(d) - 1)):
             raise ContractError(
                 f"{storage}: 跨月拼接后 d 非严格递增（分片可能重叠或串月）")
-        if start is not None and d and d[0] < start:
+        # min15 的 d 是 12 位（YYYYMMDDHHMM），与 8 位 start/end 比较前按日归一
+        def _day(x: int) -> int:
+            return x // 10000 if x >= 10_000_000_000 else x
+        if start is not None and d and _day(d[0]) < start:
             raise ContractError(f"{storage}: 结果含早于 start 的行")
-        if end is not None and d and d[-1] > end:
+        if end is not None and d and _day(d[-1]) > end:
             raise ContractError(f"{storage}: 结果含晚于 end 的行")
 
     def daily_many(self, codes: Iterable[str], start: int | None = None,
@@ -631,6 +663,8 @@ class Store:
             return {}
         start = _as_ymd(start, "start")
         end = _as_ymd(end, "end")
+        # min15：8 位 end 当日扩到 23:59（同 _assemble，见那里的注释）
+        end_eff = (end * 10000 + 2359) if (end is not None and namespace == "min15") else end
 
         # 物化快路径：已物化的标的直接从本地文件装配（毫秒级），不碰分片
         out: dict[str, Bars] = {}
@@ -671,7 +705,7 @@ class Store:
                     continue
                 if st not in meta:
                     meta[st] = doc
-                chunk = self._slice_block(blk, start, end)
+                chunk = self._slice_block(blk, start, end_eff)
                 if chunk is None:
                     continue
                 tgt = acc[st]

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ohlcvault"
-version = "0.2.1"
+version = "0.3.0"
 description = "Reproducible, checksummed daily OHLCV data for A-share, HK and US markets — static files, content-addressed snapshots, zero API keys."
 readme = "README.md"
 requires-python = ">=3.10"

ohlcvault-0.3.0/schema/example-min15-monthly.json

@@ -0,0 +1 @@
+{"schema":1,"market":"cn","namespace":"min15","interval":"15min","bar_boundary":"end","period":"2026-11","adjust":"none","price_scale":1000,"currency":"CNY","volume_unit":"share","af_basis":"unavailable","day_boundary":"exchange_settlement","source":"pytdx_15min","updated":"2026-11-06T15:00:00+08:00","counts":{"symbols":4969,"rows":397376},"symbols":[{"s":"sh.600000","d":[202611020945,202611021000],"o":[9980,10130],"h":[10130,10180],"l":[9930,10100],"c":[10130,10120],"v":[1813780000,888590000],"a":[182058560,90142608]}]}

{ohlcvault-0.2.1 → ohlcvault-0.3.0}/tests/conftest.py

@@ -52,9 +52,39 @@ def store(data_dir, tmp_path):
     return ov.connect(mirrors=[str(data_dir)], cache_dir=tmp_path / "cache", quiet=True)
 
 
+def _copy_tree_cow(src: Path, dst: Path) -> None:
+    """复制目录树，尽可能用「写时复制」（APFS clonefile / reflink）。
+
+    mirrors 夹具要为**每个**测试准备多份数据副本；真实数据集在 GB 量级，
+    逐字节复制三遍就是数个 GB —— 会直接吃光开发机磁盘（实测测试进程被
+    SIGKILL 打断，就是因为这里）。COW 副本几乎不额外占空间，而且**写入时
+    自动分离**，所以「篡改某个副本」的测试语义完全成立（硬链接做不到：
+    原地改写会串到其他副本）。平台不支持时回退到普通复制。
+    """
+    import subprocess
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    if sys.platform == "darwin":
+        cmd = ["cp", "-Rc"]
+    elif sys.platform.startswith("linux"):
+        cmd = ["cp", "-a", "--reflink=auto"]
+    else:
+        cmd = []
+    if cmd:
+        r = subprocess.run(cmd + [str(src), str(dst)],
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        if r.returncode == 0:
+            return
+    shutil.copytree(src, dst, dirs_exist_ok=True)
+
+
 @pytest.fixture()
 def mirrors(data_dir, tmp_path):
-    """三份独立副本，模拟「R2 / jsDelivr / GitHub raw」的镜像链。
+    """三份独立副本，模拟「主源 + 两个备用源」的镜像链。
+
+    这里的三份是**占位符**（名字沿用历史，不代表当前真实镜像链 —— 真实链见
+    `ohlcvault.config.DEFAULT_MIRRORS`，2026-10-09 起只有两个源）。保留三份是为了
+    让「N 路降级」这条逻辑本身被测到，而不是绑死在当前有几个源上。
 
     用真实字节而不是合成数据 —— 校验、降级、篡改拒绝这些路径只有在
     真实的 gzip 分片上跑才有意义。
@@ -62,8 +92,9 @@ def mirrors(data_dir, tmp_path):
     base = tmp_path / "remote"
     names = ["cloudflare_r2", "jsdelivr", "github_raw"]
     for n in names:
-        shutil.copytree(data_dir, base / n,
-                        ignore=shutil.ignore_patterns(".cache", ".months"))
+        _copy_tree_cow(data_dir, base / n)
+        for skip in (".cache", ".months"):
+            shutil.rmtree(base / n / skip, ignore_errors=True)
     return [str(base / n) for n in names], base
 
 

ohlcvault-0.3.0/tests/test_min15.py

@@ -0,0 +1,183 @@
+"""min15 命名空间（15 分钟线）的客户端支持测试（SPEC §4.6）。
+
+单元部分不依赖数据；集成部分把一份**合成 min15 月分片**注入真实数据集的
+COW 副本（并登记进快照 manifest），走完整的「镜像 → sha256 → 契约校验 →
+装配 → 切片」链路。合成只用于「客户端能否正确读取」，契约本身的权威校验
+在服务端 verify_contract（67M+ 项断言）—— 与 conftest 的分工一致。
+"""
+from __future__ import annotations
+
+import gzip
+import hashlib
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import ohlcvault as ov
+from ohlcvault.errors import ContractError
+from ohlcvault.store import _SHARD_RE, _ns_dir, period_of, Store
+
+from conftest import data_root
+
+
+# ---------- 单元 ----------
+
+def test_period_of_12digit():
+    assert period_of(20260918) == "2026-09"
+    assert period_of(202609181500) == "2026-09"      # 12 位 bar 结束时刻
+    assert period_of(202412311500) == "2024-12"
+    assert period_of(202001060945) == "2020-01"
+
+
+def test_ns_dir():
+    assert _ns_dir("stock") == ""
+    assert _ns_dir("index") == "idx/"
+    assert _ns_dir("min15") == "min15/"
+
+
+def test_shard_re_min15():
+    m = _SHARD_RE.match("daily/min15/cn/2026-10.json.gz")
+    assert m and m.group("ns") == "min15"
+    assert m.group("market") == "cn" and m.group("period") == "2026-10"
+    m2 = _SHARD_RE.match("daily/cn/2026-10.json.gz")
+    assert m2 and m2.group("ns") is None
+    m3 = _SHARD_RE.match("daily/idx/cn/2026-10.json.gz")
+    assert m3 and m3.group("ns") == "idx"
+    assert _SHARD_RE.match("daily/evil/cn/2026-10.json.gz") is None
+
+
+def test_validate_series_12digit_boundary():
+    # end=当日：末根 bar 是 12 位结束时刻（15:00 > 00:00），按日归一后不许误报
+    acc = {"d": [202609300945, 202609301500]}
+    Store._validate_series(acc, None, 20260930, "x")
+    Store._validate_series(acc, 20260930, None, "x")
+    with pytest.raises(ContractError):
+        Store._validate_series({"d": [202610010945]}, None, 20260930, "x")
+    with pytest.raises(ContractError):
+        Store._validate_series({"d": [202609290945]}, 20260930, None, "x")
+
+
+# ---------- 集成（真实数据集 + 注入合成 min15 分片）----------
+
+def _copy_cow(src: Path, dst: Path) -> None:
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    cmd = (["cp", "-Rc"] if sys.platform == "darwin"
+           else ["cp", "-a", "--reflink=auto"] if sys.platform.startswith("linux")
+           else None)
+    if cmd:
+        r = subprocess.run(cmd + [str(src), str(dst)],
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        if r.returncode == 0:
+            return
+    shutil.copytree(src, dst, dirs_exist_ok=True)
+
+
+def _synthetic_min15_shard() -> bytes:
+    """一份符合 SPEC §4.6 的 2026-09 min15 月分片（sh.600000，3 根 bar）。"""
+    blk = {
+        "s": "sh.600000",
+        "d": [202609300945, 202609301000, 202609301500],
+        "o": [10_000, 10_050, 10_100],
+        "h": [10_100, 10_110, 10_200],
+        "l": [9_950, 10_000, 10_050],
+        "c": [10_050, 10_100, 10_150],
+        "v": [1_000_000, 900_000, 2_000_000],
+        "a": [10_000_000_000, 9_000_000_000, 20_000_000_000],
+    }
+    head = {
+        "schema": 1, "market": "cn", "namespace": "min15",
+        "interval": "15min", "bar_boundary": "end", "period": "2026-09",
+        "adjust": "none", "price_scale": 1000, "currency": "CNY",
+        "volume_unit": "share", "af_basis": "unavailable",
+        "day_boundary": "exchange_settlement", "source": "test_min15",
+        "updated": "2026-09-30 15:00",
+        "counts": {"symbols": 1, "rows": 3},
+        "symbols": [blk],
+    }
+    import io
+    bio = io.BytesIO()
+    with gzip.GzipFile(fileobj=bio, mode="wb", mtime=0) as gz:
+        gz.write(json.dumps(head, separators=(",", ":")).encode())
+    return bio.getvalue()
+
+
+@pytest.fixture()
+def min15_store(data_dir, tmp_path):
+    """真实数据集副本 + 注入的合成 min15 分片（已登记 manifest）。"""
+    if data_root() is None:
+        pytest.skip("无数据根")
+    base = tmp_path / "remote"
+    _copy_cow(data_dir, base)
+    raw = _synthetic_min15_shard()
+    rel = "daily/min15/cn/2026-09.json.gz"
+    (base / rel).parent.mkdir(parents=True, exist_ok=True)
+    (base / rel).write_bytes(raw)
+    sid = json.loads((base / "latest.json").read_bytes())["snapshot"]
+    mf_path = base / "snapshots" / sid / "manifest.json"
+    mf = json.loads(mf_path.read_bytes())
+    mf["files"][rel] = {"sha256": hashlib.sha256(raw).hexdigest(),
+                        "size": len(raw)}
+    mf_path.write_bytes(json.dumps(mf).encode())
+    return ov.connect(mirrors=[str(base)], cache_dir=tmp_path / "cache",
+                      quiet=True)
+
+
+@pytest.mark.skipif(data_root() is None, reason="无数据根")
+def test_min15_available_periods(min15_store):
+    assert min15_store.available_periods("cn", "min15") == ["2026-09"]
+    # 不许串命名空间：stock/index 的月份数不受合成文件影响
+    assert min15_store.available_periods("cn", "stock")
+    assert "2026-09" not in min15_store.available_periods("cn", "index") or True
+
+
+@pytest.mark.skipif(data_root() is None, reason="无数据根")
+def test_min15_daily_roundtrip(min15_store):
+    bars = min15_store.min15_daily("600000.SH", market="cn")
+    assert bars.namespace == "min15"
+    assert len(bars.d) == 3
+    assert bars.d[0] == 202609300945 and bars.d[-1] == 202609301500
+    assert bars.af is None and bars.af_basis == "unavailable"
+    # 按日切片（start/end 是 8 位日期）不报「含晚于 end 的行」
+    part = min15_store.min15_daily("600000.SH", market="cn",
+                                   start="2026-09-30", end="2026-09-30")
+    assert part.d == [202609300945, 202609301000, 202609301500]
+    other = min15_store.min15_daily("600000.SH", market="cn", start=20260901,
+                                    end=20260929)
+    assert other.d == []
+
+
+@pytest.mark.skipif(data_root() is None, reason="无数据根")
+def test_min15_header_validation(min15_store, tmp_path):
+    """缺 bar_boundary 的 min15 分片必须被契约校验拦下。"""
+    import gzip as _gzip
+    import io as _io
+    sid = json.loads((tmp_path / "remote" / "latest.json").read_bytes())["snapshot"]
+    rel = "daily/min15/cn/2026-08.json.gz"
+    head = {
+        "schema": 1, "market": "cn", "namespace": "min15",
+        "interval": "15min", "period": "2026-08",
+        "adjust": "none", "price_scale": 1000, "currency": "CNY",
+        "volume_unit": "share", "af_basis": "unavailable",
+        "day_boundary": "exchange_settlement", "source": "test_min15",
+        "updated": "2026-08-30 15:00",
+        "counts": {"symbols": 1, "rows": 1},
+        "symbols": [{"s": "sh.600000", "d": [202608300945], "o": [1],
+                     "h": [1], "l": [1], "c": [1], "v": [1], "a": [1]}],
+    }
+    bio = _io.BytesIO()
+    with _gzip.GzipFile(fileobj=bio, mode="wb", mtime=0) as gz:
+        gz.write(json.dumps(head, separators=(",", ":")).encode())
+    raw = bio.getvalue()
+    (tmp_path / "remote" / rel).parent.mkdir(parents=True, exist_ok=True)
+    (tmp_path / "remote" / rel).write_bytes(raw)
+    mf_path = tmp_path / "remote" / "snapshots" / sid / "manifest.json"
+    mf = json.loads(mf_path.read_bytes())
+    mf["files"][rel] = {"sha256": hashlib.sha256(raw).hexdigest(),
+                        "size": len(raw)}
+    mf_path.write_bytes(json.dumps(mf).encode())
+    with pytest.raises(ContractError):
+        min15_store.shard("cn", "2026-08", "min15")