carrotquant-data 1.2.2__tar.gz → 1.3.0__tar.gz

{carrotquant_data-1.2.2 → carrotquant_data-1.3.0}/PKG-INFO

@@ -1,11 +1,12 @@
-Metadata-Version: 2.5
+Metadata-Version: 2.4
 Name: carrotquant-data
-Version: 1.2.2
+Version: 1.3.0
 Summary: 高性能、轻量级 A 股与指数金融数据增量同步与持久化流水线
 Author-email: Carrot <11172391+CRThu@users.noreply.github.com>
 Requires-Python: >=3.12
+Description-Content-Type: text/markdown
 Requires-Dist: baostock>=0.9.1
-Requires-Dist: curl-cffi>=0.7.4
+Requires-Dist: curl_cffi>=0.7.4
 Requires-Dist: fastapi>=0.135.1
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: polars>=1.39.0
@@ -15,38 +16,39 @@ Requires-Dist: tdxpy>=0.2.7
 Requires-Dist: tenacity>=9.1.4
 Requires-Dist: typer>=0.24.1
 Requires-Dist: uvicorn>=0.41.0
-Description-Content-Type: text/markdown
 
-# CarrotQuant.Data
+# CarrotQuant Data (`carrotquant-data`)
 
-![Python Version](https://img.shields.io/badge/python-%3E%3D3.12-blue)
-![License](https://img.shields.io/badge/license-Apache%202.0-blue)
+[![PyPI version](https://img.shields.io/pypi/v/carrotquant-data.svg)](https://pypi.org/project/carrotquant-data/)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.12-blue)](https://pypi.org/project/carrotquant-data/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
-CarrotQuant.Data 是一个为量化交易体系设计的轻量级、模块化的本地数据同步与管理工具。它致力于从各类免费数据源（如 Baostock、东方财富等）获取金融数据，并将数据清洗、转换为统一格式（支持 CSV, Parquet 等），持久化到本地存储中以供各类量化研究和回测使用。
+**CarrotQuant Data** (`carrotquant-data`) 是专为量化交易与回测设计的本地金融数据同步与管理工具，支持多源拉取、增量同步与高效列式存储。
 
-## 🌟 核心特性 (Features)
+## 🛠️ 特性 (Features)
 
-- **多数据源支持**：内置 [Baostock](http://baostock.com/)、东方财富、[通达信 (tdxpy)](https://github.com/rainx/tdxPy) 等金融数据源引擎，易于弹性拓展更多的数据源提供商。
-- **灵活的存储格式**：原生支持 `csv` 和基于列式存储的高效 `parquet` 格式，以满足不同体量的数据读写需求。
-- **增量与全量同步**：基于时间戳水位线的同步机制，支持从断点智能续接（增量拉取），以及强制全量覆盖更新刷新数据。
-- **现代化多通道接入支持**：
-  - **React Web 终端**：现代暗黑极速金融终端 (`web/`)，基于 Bun + Vite 6 + React 19 + TradingView Lightweight Charts (3-Pane 单屏无滚动图表) + 拼音/代码/名称通用搜索组件 `SearchInput` + **独立 `数据矩阵` 视图 + 数据中心与 Loguru SSE 日志流视窗与悬浮 Widget**。
-  - **Python SDK**：简单直观的 `import cqdata` API，支持高性能跨年份数据切片读取 (`cqdata.read`)、`columns` 按需字段选择、格式识别与元数据探查。
-  - **命令行工具 (CLI)**：统一的 `cqdata` 命令行工具，提供数据同步 (`cqdata sync`)、数据表探索 (`cqdata tables`)、元数据查询 (`cqdata info`) 与 HTTP 服务启动 (`cqdata server`)。
-  - **REST API 服务**：基于 FastAPI 的 REST API，为远程微服务与 Web 终端提供 HTTP 数据切片、SSE 实时日志流与同步触发。
-- **优秀的底层性能**：使用 [Polars](https://pola.rs/) 库进行高性能的数据加工和清洗。
+- **多数据源支持**：内置 [Baostock](http://baostock.com/)、东方财富、[通达信 (tdxpy)](https://github.com/rainx/tdxPy) 等金融数据源驱动，支持灵活扩展。
+- **灵活的存储格式**：原生支持 `csv` 与列式存储 `parquet` 格式。
+- **增量与全量同步**：基于时间戳水位线机制，支持断点续接（增量拉取）与全量覆盖更新。
+- **多接入方式**：
+  - **React Web 终端**：基于 Bun + Vite + React 19 构建，集成 TradingView Lightweight Charts (3-Pane 图表)、多维搜索与数据管理面板。
+  - **Python SDK**：直观的 `import cq.data` API，支持高性能跨年份数据切片读取 (`cq.data.read`)、`columns` 按需投影与元数据探查。
+  - **命令行工具 (CLI)**：统一的 `cqdata` 命令行工具，提供数据同步 (`cqdata sync`)、数据表探索 (`cqdata tables`) 与服务启动 (`cqdata server`)。
+  - **REST API 服务**：基于 FastAPI 的 HTTP 服务，支持数据切片、任务调度与 SSE 实时日志流。
+- **列式数据处理**：使用 [Polars](https://pola.rs/) 进行高效的数据清洗与结构转换。
 
 ## 📁 目录结构 (Project Structure)
 
 ```text
 CarrotQuant.Data/
-├── cqdata/           # 核心代码包 (支持 import cqdata)
-│   ├── entrypoints/  # 接入层 (python_api, cli, rest_api)
-│   ├── config/       # 配置管理模块
-│   ├── provider/     # 数据源驱动 (BaostockProvider, EastMoneyProvider, TDXProvider)
-│   ├── service/      # 核心业务逻辑 (DataReader, MetadataReader, SyncManager 等)
-│   ├── storage/      # 本地持久化存储 (CSVStorage, ParquetStorage)
-│   └── utils/        # 通用工具箱
+├── cq/
+│   └── data/         # 核心代码包 (import cq.data)
+│       ├── entrypoints/  # 接入层 (python_api, cli, rest_api)
+│       ├── config/       # 配置管理模块
+│       ├── provider/     # 数据源驱动 (BaostockProvider, EastMoneyProvider, TDXProvider)
+│       ├── service/      # 核心业务逻辑 (DataReader, MetadataReader, SyncManager 等)
+│       ├── storage/      # 本地持久化存储 (CSVStorage, ParquetStorage)
+│       └── utils/        # 通用工具箱
 ├── web/              # React Web 金融终端 (Bun + Vite 6 + React 19 + TradingView 3-Pane)
 │   ├── src/          # 视图 View、组件 Component、Hooks 与转换服务
 │   └── package.json
@@ -64,14 +66,14 @@ CarrotQuant.Data/
 
 ```mermaid
 graph TB
-    subgraph Entrypoints["接入层 (cqdata/entrypoints)"]
+    subgraph Entrypoints["接入层 (cq/data/entrypoints)"]
         PYTHON_API["python_api.py<br/>(Python SDK)"]
         CLI["cli.py<br/>(Typer CLI)"]
         REST["rest_api.py<br/>(FastAPI REST)"]
         WIZARD["wizard.py<br/>(交互向导)"]
     end
 
-    subgraph Service["业务逻辑层 (cqdata/service)"]
+    subgraph Service["业务逻辑层 (cq/data/service)"]
         SM["SyncManager<br/>同步总调度"]
         DR["DataReader<br/>切片与按列投影"]
         MR["MetadataReader<br/>探查与过滤 API"]
@@ -79,14 +81,14 @@ graph TB
         MM["MetadataManager<br/>元数据 IO"]
     end
 
-    subgraph Provider["采集层 (cqdata/provider)"]
+    subgraph Provider["采集层 (cq/data/provider)"]
         PM["ProviderManager"]
         BP["BaostockProvider"]
         EP["EastMoneyProvider"]
         TDX_PROV["TDXProvider"]
     end
 
-    subgraph Storage["存储层 (cqdata/storage)"]
+    subgraph Storage["存储层 (cq/data/storage)"]
         SF["StorageFactory"]
         CSV["CSVStorage"]
         PQ["ParquetStorage"]
@@ -137,22 +139,31 @@ graph TB
 
 ## 🛠️ 安装指南 (Installation)
 
-环境要求：**Python >= 3.12**。本项目推荐使用现代化的 Python 包管理器 [uv](https://github.com/astral-sh/uv) 进行极速安装与管理。
+环境要求：**Python >= 3.12**（支持 Python 3.12 / 3.13 / 3.14+）。
+
+### 1. 通过 PyPI 安装 (推荐)
+```bash
+# 推荐使用 pip 直接安装
+pip install carrotquant-data
+
+# 或使用 uv 安装
+uv add carrotquant-data
+```
 
-1. **克隆项目并安装**
-    ```bash
-    git clone https://github.com/CRThu/CarrotQuant.Data.git
-    cd CarrotQuant.Data
+### 2. 源码克隆与本地开发安装
+```bash
+git clone https://github.com/CRThu/carrotquant-data.git
+cd carrotquant-data
 
-    # 可选：可编辑模式挂载命令行 cqdata
-    uv pip install -e .
-    ```
+# 可编辑模式挂载命令行 cqdata
+uv pip install -e .
+```
 
 ## ⚙️ 配置说明 (Configuration)
 
 CarrotQuant.Data 秉承 **“显式胜于隐式 (Explicit is better than implicit)”** 的配置契约，支持以下显式加载与覆盖方式（优先级从高到低）：
 
-1. **代码程序化修改**：直接设置单例属性 `cqdata.settings.data_dir = "/path/to/data"` 或调用 `cqdata.configure("/path/to/config.yaml")`（最高优先级）。
+1. **代码程序化修改**：直接设置单例属性 `cq.data.settings.data_dir = "/path/to/data"` 或调用 `cq.data.configure("/path/to/config.yaml")`（最高优先级）。
 2. **环境变量 `CQDATA_DATA_DIR`**：如 `export CQDATA_DATA_DIR="/my/data/path"`（适合 Docker / CLI / 自动化部署）。
 3. **环境变量 `CQDATA_CONFIG_PATH`**：指定自定义 YAML 配置文件路径，如 `export CQDATA_CONFIG_PATH="/path/to/config.yaml"`。
 4. **内置默认配置**：默认存储路径 `data_dir = "data"`，默认日志 `log_dir = "logs"`, `log_level = "INFO"`。
@@ -175,30 +186,30 @@ defaults:
 
 ## 🚀 快速开始 (Quick Start)
 
-### 方式一：使用 Python SDK (`import cqdata`) - 推荐
+### 方式一：使用 Python SDK (`import cq.data`) - 推荐
 
 在量化研究与 Python 策略脚本中直接读取本地清洗好的数据：
 
 ```python
-import cqdata
+import cq.data
 
 # 0. (可选) 从 YAML 配置文件加载全局配置
-cqdata.configure("./config.yaml")
+cq.data.configure("./config.yaml")
 
 # 或者直接修改属性
-cqdata.settings.data_dir = "./custom_data"
+cq.data.settings.data_dir = "./custom_data"
 
 # 1. OOP 便捷读取 (界面极简，干净清爽)
-df_kline = cqdata.ashare.kline.get(symbols="sh.600000", start_date="2024-01-01")
+df_kline = cq.data.ashare.kline.get(symbols="sh.600000", start_date="2024-01-01")
 
 # 2. 查阅代码清单、时间跨度、Schema 映射与物理总行数
-symbols = cqdata.list_symbols("ashare.kline.1d.raw.baostock")
-start_dt, end_dt = cqdata.get_time_range("ashare.kline.1d.raw.baostock")
-schema = cqdata.get_schema("ashare.kline.1d.raw.baostock")         # {'timestamp': 'Int64', ...}
-total_rows = cqdata.get_row_count("ashare.kline.1d.raw.baostock") # 13570685
+symbols = cq.data.list_symbols("ashare.kline.1d.raw.baostock")
+start_dt, end_dt = cq.data.get_time_range("ashare.kline.1d.raw.baostock")
+schema = cq.data.get_schema("ashare.kline.1d.raw.baostock")         # {'timestamp': 'Int64', ...}
+total_rows = cq.data.get_row_count("ashare.kline.1d.raw.baostock") # 13570685
 
 # 3. 统一切片读取 K 线时序数据 (支持 columns 按需挑选列，极节省内存)
-df = cqdata.read(
+df = cq.data.read(
     table_id="ashare.kline.1d.raw.baostock",
     symbols=["sh.600000", "sz.000001"],
     start_date="2024-01-01",
@@ -208,13 +219,13 @@ df = cqdata.read(
 print(df)
 
 # 4. 统一切片读取板块/龙虎榜事件数据
-events_df = cqdata.read(
+events_df = cq.data.read(
     table_id="ashare.concept.eastmoney",
     symbols=["sh.600000"]
 )
 
 # 5. 代码中触发全自动数据同步
-cqdata.sync(table_ids=["ashare.kline.1d.raw.baostock"], formats=["parquet"])
+cq.data.sync(table_ids=["ashare.kline.1d.raw.baostock"], formats=["parquet"])
 ```
 
 ### 方式二：使用统一 CLI 命令行工具 (`cqdata`)
@@ -285,15 +296,21 @@ cqdata server --port 8888 --open
 | `/` | GET | 内置托管的 React Web 金融终端主界面 |
 | `/api/v1/health` | GET | 系统健康检查与服务运行状态探针 |
 | `/api/v1/tables` | GET | 列出本地所有数据表总览 (平铺列表，含 `category` 属性) |
+| `/api/v1/tables/detailed` | GET | 获取所有数据表及其各存储格式 (Parquet / CSV) 独立物理元数据 |
 | `/api/v1/tables/{table_id}/formats` | GET | 获取指定表已存储的物理格式列表 (`['parquet', 'csv']`) |
 | `/api/v1/tables/{table_id}/symbols` | GET | 获取指定表已下载的股票/证券代码列表 |
 | `/api/v1/tables/{table_id}/time_range` | GET | 获取指定表的时间跨度 tuple `(start_datetime, end_datetime)` |
 | `/api/v1/tables/{table_id}/schema` | GET | 获取指定表的字段列名与类型字典 |
 | `/api/v1/tables/{table_id}/row_count` | GET | 获取指定表的记录总条数/行数 |
-| `/api/v1/query` | GET | 统一切片查询接口（支持 `symbols`, `start_date`, `end_date`, `columns`, `page`, `page_size`），按 `table_id` 自动智能路由，输出 `columns` 表头与 `data` 二维 List 矩阵 |
+| `/api/v1/tables/{table_id}/boards` | GET | 聚合板块概念/行业列表及各板块成分股计数，支持关键词搜索 |
+| `/api/v1/query` | GET | 统一切片查询接口（支持 `symbols`, `board_code`, `start_date`, `end_date`, `columns`, `page`, `page_size`），按 `table_id` 自动智能路由 |
 | `/api/v1/sync` | POST | 异步触发后台数据同步任务 |
-| `/api/v1/tasks` | GET | 查询活跃同步任务状态 |
-| `/api/v1/filesystem/list` | GET | 通用本地文件与目录探查接口 (为 Web 文件探查器 Modal 提供支持) |
+| `/api/v1/tasks` | GET | 查询当前正在运行的同步任务列表 |
+| `/api/v1/sync/status` | GET | 获取所有同步任务的详细进度状态（含百分比、当前代码与错误信息） |
+| `/api/v1/logs/stream` | GET | SSE (Server-Sent Events) 实时系统与数据同步日志流 |
+| `/api/v1/tdx/check` | GET | 检查通达信本地 `vipdoc` 目录有效性与代码统计 |
+| `/api/v1/tdx/download` | POST | 后台从通达信官方服务器下载全量 `hsjday.zip` 日线包并自动解压 |
+| `/api/v1/filesystem/list` | GET | 本地文件与目录探查接口 (供 Web 文件选择器使用) |
 
 ### 方式五：前端 UI 开发与热重载调试 (`web/`)
 

{carrotquant_data-1.2.2 → carrotquant_data-1.3.0}/README.md

@@ -1,33 +1,35 @@
-# CarrotQuant.Data
+# CarrotQuant Data (`carrotquant-data`)
 
-![Python Version](https://img.shields.io/badge/python-%3E%3D3.12-blue)
-![License](https://img.shields.io/badge/license-Apache%202.0-blue)
+[![PyPI version](https://img.shields.io/pypi/v/carrotquant-data.svg)](https://pypi.org/project/carrotquant-data/)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.12-blue)](https://pypi.org/project/carrotquant-data/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
-CarrotQuant.Data 是一个为量化交易体系设计的轻量级、模块化的本地数据同步与管理工具。它致力于从各类免费数据源（如 Baostock、东方财富等）获取金融数据，并将数据清洗、转换为统一格式（支持 CSV, Parquet 等），持久化到本地存储中以供各类量化研究和回测使用。
+**CarrotQuant Data** (`carrotquant-data`) 是专为量化交易与回测设计的本地金融数据同步与管理工具，支持多源拉取、增量同步与高效列式存储。
 
-## 🌟 核心特性 (Features)
+## 🛠️ 特性 (Features)
 
-- **多数据源支持**：内置 [Baostock](http://baostock.com/)、东方财富、[通达信 (tdxpy)](https://github.com/rainx/tdxPy) 等金融数据源引擎，易于弹性拓展更多的数据源提供商。
-- **灵活的存储格式**：原生支持 `csv` 和基于列式存储的高效 `parquet` 格式，以满足不同体量的数据读写需求。
-- **增量与全量同步**：基于时间戳水位线的同步机制，支持从断点智能续接（增量拉取），以及强制全量覆盖更新刷新数据。
-- **现代化多通道接入支持**：
-  - **React Web 终端**：现代暗黑极速金融终端 (`web/`)，基于 Bun + Vite 6 + React 19 + TradingView Lightweight Charts (3-Pane 单屏无滚动图表) + 拼音/代码/名称通用搜索组件 `SearchInput` + **独立 `数据矩阵` 视图 + 数据中心与 Loguru SSE 日志流视窗与悬浮 Widget**。
-  - **Python SDK**：简单直观的 `import cqdata` API，支持高性能跨年份数据切片读取 (`cqdata.read`)、`columns` 按需字段选择、格式识别与元数据探查。
-  - **命令行工具 (CLI)**：统一的 `cqdata` 命令行工具，提供数据同步 (`cqdata sync`)、数据表探索 (`cqdata tables`)、元数据查询 (`cqdata info`) 与 HTTP 服务启动 (`cqdata server`)。
-  - **REST API 服务**：基于 FastAPI 的 REST API，为远程微服务与 Web 终端提供 HTTP 数据切片、SSE 实时日志流与同步触发。
-- **优秀的底层性能**：使用 [Polars](https://pola.rs/) 库进行高性能的数据加工和清洗。
+- **多数据源支持**：内置 [Baostock](http://baostock.com/)、东方财富、[通达信 (tdxpy)](https://github.com/rainx/tdxPy) 等金融数据源驱动，支持灵活扩展。
+- **灵活的存储格式**：原生支持 `csv` 与列式存储 `parquet` 格式。
+- **增量与全量同步**：基于时间戳水位线机制，支持断点续接（增量拉取）与全量覆盖更新。
+- **多接入方式**：
+  - **React Web 终端**：基于 Bun + Vite + React 19 构建，集成 TradingView Lightweight Charts (3-Pane 图表)、多维搜索与数据管理面板。
+  - **Python SDK**：直观的 `import cq.data` API，支持高性能跨年份数据切片读取 (`cq.data.read`)、`columns` 按需投影与元数据探查。
+  - **命令行工具 (CLI)**：统一的 `cqdata` 命令行工具，提供数据同步 (`cqdata sync`)、数据表探索 (`cqdata tables`) 与服务启动 (`cqdata server`)。
+  - **REST API 服务**：基于 FastAPI 的 HTTP 服务，支持数据切片、任务调度与 SSE 实时日志流。
+- **列式数据处理**：使用 [Polars](https://pola.rs/) 进行高效的数据清洗与结构转换。
 
 ## 📁 目录结构 (Project Structure)
 
 ```text
 CarrotQuant.Data/
-├── cqdata/           # 核心代码包 (支持 import cqdata)
-│   ├── entrypoints/  # 接入层 (python_api, cli, rest_api)
-│   ├── config/       # 配置管理模块
-│   ├── provider/     # 数据源驱动 (BaostockProvider, EastMoneyProvider, TDXProvider)
-│   ├── service/      # 核心业务逻辑 (DataReader, MetadataReader, SyncManager 等)
-│   ├── storage/      # 本地持久化存储 (CSVStorage, ParquetStorage)
-│   └── utils/        # 通用工具箱
+├── cq/
+│   └── data/         # 核心代码包 (import cq.data)
+│       ├── entrypoints/  # 接入层 (python_api, cli, rest_api)
+│       ├── config/       # 配置管理模块
+│       ├── provider/     # 数据源驱动 (BaostockProvider, EastMoneyProvider, TDXProvider)
+│       ├── service/      # 核心业务逻辑 (DataReader, MetadataReader, SyncManager 等)
+│       ├── storage/      # 本地持久化存储 (CSVStorage, ParquetStorage)
+│       └── utils/        # 通用工具箱
 ├── web/              # React Web 金融终端 (Bun + Vite 6 + React 19 + TradingView 3-Pane)
 │   ├── src/          # 视图 View、组件 Component、Hooks 与转换服务
 │   └── package.json
@@ -45,14 +47,14 @@ CarrotQuant.Data/
 
 ```mermaid
 graph TB
-    subgraph Entrypoints["接入层 (cqdata/entrypoints)"]
+    subgraph Entrypoints["接入层 (cq/data/entrypoints)"]
         PYTHON_API["python_api.py<br/>(Python SDK)"]
         CLI["cli.py<br/>(Typer CLI)"]
         REST["rest_api.py<br/>(FastAPI REST)"]
         WIZARD["wizard.py<br/>(交互向导)"]
     end
 
-    subgraph Service["业务逻辑层 (cqdata/service)"]
+    subgraph Service["业务逻辑层 (cq/data/service)"]
         SM["SyncManager<br/>同步总调度"]
         DR["DataReader<br/>切片与按列投影"]
         MR["MetadataReader<br/>探查与过滤 API"]
@@ -60,14 +62,14 @@ graph TB
         MM["MetadataManager<br/>元数据 IO"]
     end
 
-    subgraph Provider["采集层 (cqdata/provider)"]
+    subgraph Provider["采集层 (cq/data/provider)"]
         PM["ProviderManager"]
         BP["BaostockProvider"]
         EP["EastMoneyProvider"]
         TDX_PROV["TDXProvider"]
     end
 
-    subgraph Storage["存储层 (cqdata/storage)"]
+    subgraph Storage["存储层 (cq/data/storage)"]
         SF["StorageFactory"]
         CSV["CSVStorage"]
         PQ["ParquetStorage"]
@@ -118,22 +120,31 @@ graph TB
 
 ## 🛠️ 安装指南 (Installation)
 
-环境要求：**Python >= 3.12**。本项目推荐使用现代化的 Python 包管理器 [uv](https://github.com/astral-sh/uv) 进行极速安装与管理。
+环境要求：**Python >= 3.12**（支持 Python 3.12 / 3.13 / 3.14+）。
 
-1. **克隆项目并安装**
-    ```bash
-    git clone https://github.com/CRThu/CarrotQuant.Data.git
-    cd CarrotQuant.Data
+### 1. 通过 PyPI 安装 (推荐)
+```bash
+# 推荐使用 pip 直接安装
+pip install carrotquant-data
+
+# 或使用 uv 安装
+uv add carrotquant-data
+```
 
-    # 可选：可编辑模式挂载命令行 cqdata
-    uv pip install -e .
-    ```
+### 2. 源码克隆与本地开发安装
+```bash
+git clone https://github.com/CRThu/carrotquant-data.git
+cd carrotquant-data
+
+# 可编辑模式挂载命令行 cqdata
+uv pip install -e .
+```
 
 ## ⚙️ 配置说明 (Configuration)
 
 CarrotQuant.Data 秉承 **“显式胜于隐式 (Explicit is better than implicit)”** 的配置契约，支持以下显式加载与覆盖方式（优先级从高到低）：
 
-1. **代码程序化修改**：直接设置单例属性 `cqdata.settings.data_dir = "/path/to/data"` 或调用 `cqdata.configure("/path/to/config.yaml")`（最高优先级）。
+1. **代码程序化修改**：直接设置单例属性 `cq.data.settings.data_dir = "/path/to/data"` 或调用 `cq.data.configure("/path/to/config.yaml")`（最高优先级）。
 2. **环境变量 `CQDATA_DATA_DIR`**：如 `export CQDATA_DATA_DIR="/my/data/path"`（适合 Docker / CLI / 自动化部署）。
 3. **环境变量 `CQDATA_CONFIG_PATH`**：指定自定义 YAML 配置文件路径，如 `export CQDATA_CONFIG_PATH="/path/to/config.yaml"`。
 4. **内置默认配置**：默认存储路径 `data_dir = "data"`，默认日志 `log_dir = "logs"`, `log_level = "INFO"`。
@@ -156,30 +167,30 @@ defaults:
 
 ## 🚀 快速开始 (Quick Start)
 
-### 方式一：使用 Python SDK (`import cqdata`) - 推荐
+### 方式一：使用 Python SDK (`import cq.data`) - 推荐
 
 在量化研究与 Python 策略脚本中直接读取本地清洗好的数据：
 
 ```python
-import cqdata
+import cq.data
 
 # 0. (可选) 从 YAML 配置文件加载全局配置
-cqdata.configure("./config.yaml")
+cq.data.configure("./config.yaml")
 
 # 或者直接修改属性
-cqdata.settings.data_dir = "./custom_data"
+cq.data.settings.data_dir = "./custom_data"
 
 # 1. OOP 便捷读取 (界面极简，干净清爽)
-df_kline = cqdata.ashare.kline.get(symbols="sh.600000", start_date="2024-01-01")
+df_kline = cq.data.ashare.kline.get(symbols="sh.600000", start_date="2024-01-01")
 
 # 2. 查阅代码清单、时间跨度、Schema 映射与物理总行数
-symbols = cqdata.list_symbols("ashare.kline.1d.raw.baostock")
-start_dt, end_dt = cqdata.get_time_range("ashare.kline.1d.raw.baostock")
-schema = cqdata.get_schema("ashare.kline.1d.raw.baostock")         # {'timestamp': 'Int64', ...}
-total_rows = cqdata.get_row_count("ashare.kline.1d.raw.baostock") # 13570685
+symbols = cq.data.list_symbols("ashare.kline.1d.raw.baostock")
+start_dt, end_dt = cq.data.get_time_range("ashare.kline.1d.raw.baostock")
+schema = cq.data.get_schema("ashare.kline.1d.raw.baostock")         # {'timestamp': 'Int64', ...}
+total_rows = cq.data.get_row_count("ashare.kline.1d.raw.baostock") # 13570685
 
 # 3. 统一切片读取 K 线时序数据 (支持 columns 按需挑选列，极节省内存)
-df = cqdata.read(
+df = cq.data.read(
     table_id="ashare.kline.1d.raw.baostock",
     symbols=["sh.600000", "sz.000001"],
     start_date="2024-01-01",
@@ -189,13 +200,13 @@ df = cqdata.read(
 print(df)
 
 # 4. 统一切片读取板块/龙虎榜事件数据
-events_df = cqdata.read(
+events_df = cq.data.read(
     table_id="ashare.concept.eastmoney",
     symbols=["sh.600000"]
 )
 
 # 5. 代码中触发全自动数据同步
-cqdata.sync(table_ids=["ashare.kline.1d.raw.baostock"], formats=["parquet"])
+cq.data.sync(table_ids=["ashare.kline.1d.raw.baostock"], formats=["parquet"])
 ```
 
 ### 方式二：使用统一 CLI 命令行工具 (`cqdata`)
@@ -266,15 +277,21 @@ cqdata server --port 8888 --open
 | `/` | GET | 内置托管的 React Web 金融终端主界面 |
 | `/api/v1/health` | GET | 系统健康检查与服务运行状态探针 |
 | `/api/v1/tables` | GET | 列出本地所有数据表总览 (平铺列表，含 `category` 属性) |
+| `/api/v1/tables/detailed` | GET | 获取所有数据表及其各存储格式 (Parquet / CSV) 独立物理元数据 |
 | `/api/v1/tables/{table_id}/formats` | GET | 获取指定表已存储的物理格式列表 (`['parquet', 'csv']`) |
 | `/api/v1/tables/{table_id}/symbols` | GET | 获取指定表已下载的股票/证券代码列表 |
 | `/api/v1/tables/{table_id}/time_range` | GET | 获取指定表的时间跨度 tuple `(start_datetime, end_datetime)` |
 | `/api/v1/tables/{table_id}/schema` | GET | 获取指定表的字段列名与类型字典 |
 | `/api/v1/tables/{table_id}/row_count` | GET | 获取指定表的记录总条数/行数 |
-| `/api/v1/query` | GET | 统一切片查询接口（支持 `symbols`, `start_date`, `end_date`, `columns`, `page`, `page_size`），按 `table_id` 自动智能路由，输出 `columns` 表头与 `data` 二维 List 矩阵 |
+| `/api/v1/tables/{table_id}/boards` | GET | 聚合板块概念/行业列表及各板块成分股计数，支持关键词搜索 |
+| `/api/v1/query` | GET | 统一切片查询接口（支持 `symbols`, `board_code`, `start_date`, `end_date`, `columns`, `page`, `page_size`），按 `table_id` 自动智能路由 |
 | `/api/v1/sync` | POST | 异步触发后台数据同步任务 |
-| `/api/v1/tasks` | GET | 查询活跃同步任务状态 |
-| `/api/v1/filesystem/list` | GET | 通用本地文件与目录探查接口 (为 Web 文件探查器 Modal 提供支持) |
+| `/api/v1/tasks` | GET | 查询当前正在运行的同步任务列表 |
+| `/api/v1/sync/status` | GET | 获取所有同步任务的详细进度状态（含百分比、当前代码与错误信息） |
+| `/api/v1/logs/stream` | GET | SSE (Server-Sent Events) 实时系统与数据同步日志流 |
+| `/api/v1/tdx/check` | GET | 检查通达信本地 `vipdoc` 目录有效性与代码统计 |
+| `/api/v1/tdx/download` | POST | 后台从通达信官方服务器下载全量 `hsjday.zip` 日线包并自动解压 |
+| `/api/v1/filesystem/list` | GET | 本地文件与目录探查接口 (供 Web 文件选择器使用) |
 
 ### 方式五：前端 UI 开发与热重载调试 (`web/`)