zjp-CN · jackluo2012 · Dec 27, 2025 · Dec 27, 2025 · Dec 27, 2025 · Dec 27, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,113 @@
 # Changelog
 
+## [Unreleased]
+
+## v0.5.0 (2025-12-27)
+
+### 新增功能 (Features)
+
+#### 核心功能模块（完全对标 pytdx）
+
+1. **SecurityQuotes** - 实时行情数据
+   - ✅ 支持股票实时行情（`get_security_quotes`）
+   - ✅ 支持指数实时行情（上证指数、深证成指、沪深300等）
+   - ✅ 可同时获取多只股票/指数的行情快照
+   - ✅ 返回字段：当前价、今开、最高、最低、成交量、成交额、买卖五档等
+
+2. **FinanceInfo** - 财务信息（32个财务字段）
+   - ✅ 基本信息：股票代码、上市日期、更新日期、所属省份、所属行业
+   - ✅ 股本结构：总股本、流通股本、国家股、法人股、B股、H股、职工股
+   - ✅ 资产负债：总资产、流动资产、固定资产、无形资产、净资产
+   - ✅ 利润表：主营收入、主营利润、营业利润、净利润
+   - ✅ 现金流：经营现金流、总现金流
+   - ✅ 对应 pytdx 的 `get_finance_info`
+
+3. **Transaction** - 逐笔成交数据
+   - ✅ tick-level 成交数据
+   - ✅ 返回字段：时间、价格、成交量、成交号、买卖方向
+   - ✅ 支持分页获取历史逐笔数据
+   - ✅ 对应 pytdx 的 `get_transaction_data`
+
+4. **MinuteTime** - 分时数据
+   - ✅ 当日分时成交数据（240个数据点）
+   - ✅ 返回字段：时间(HH:MM)、价格、成交量
+   - ✅ 对应 pytdx 的 `get_minute_time_data`
+
+5. **SecurityList** - 股票列表
+   - ✅ 获取所有股票代码和名称
+   - ✅ 支持分页查询（每次1000只）
+   - ✅ 对应 pytdx 的 `get_security_list`
+
+6. **IndexQuotes** - 指数行情
+   - ✅ 上证指数(000001)、深证成指(399001)、沪深300(000300)等
+   - ✅ 由 SecurityQuotes 模块统一支持
+   - ✅ 对应 pytdx 的指数行情功能
+
+#### 示例程序和测试
+
+- 新增 `test_security_quotes.rs` - 股票和指数行情示例
+- 新增 `test_finance_info.rs` - 财务信息示例
+- 新增 `test_transaction.rs` - 逐笔成交示例
+- 新增 `test_minute_time.rs` - 分时数据示例
+- 新增 `test_security_list.rs` - 股票列表示例
+- 新增 `test_index_quotes.rs` - 指数行情示例
+
+### Bug 修复
+
+#### 关键Bug修复：SecurityQuotes 发送长度问题
+
+- **问题描述**：`send()` 方法返回整个582字节缓冲区而非实际需要长度，导致所有 SecurityQuotes 调用失败（"failed to fill whole buffer"）
+- **影响范围**：影响所有使用 SecurityQuotes 的功能（股票和指数行情）
+- **修复方案**：重写 `send()` 方法，只返回实际需要的字节数（22 + stocks.len() * 7）
+- **验证结果**：
+  - 单元测试：29/29 通过
+  - 实际数据验证：股票、指数行情全部正常
+
+### 文档更新
+
+- README.md 新增"rustdx 库使用"章节，包含：
+  - 8大核心功能对照表
+  - 6个详细使用示例（股票行情、指数行情、K线、财务、分时、逐笔）
+  - 市场代码说明
+  - 超时设置说明
+  - 完整示例程序列表
+
+### 测试验证
+
+- 单元测试：29/29 通过
+- 功能验证：
+  - 上证指数(000001): 3963.68 (+0.02%) ✅
+  - 深证成指(399001): 13603.89 (+0.01%) ✅
+  - 沪深300(000300): 4657.24 (+0.00%) ✅
+  - 平安银行财务数据：32个字段全部获取 ✅
+  - 逐笔成交数据：正常解析 ✅
+  - 分时数据：240个数据点 ✅
+
+### pytdx 功能完整性
+
+rustdx 现已**完全实现** pytdx 的核心功能：
+
+| 功能 | rustdx 模块 | pytdx 对应 | 状态 |
+|------|------------|-----------|------|
+| 日K线 | `Kline` | `get_security_bars` | ✅ |
+| 除权数据 | `Xdxr` | `get_xdxr` | ✅ |
+| 股票行情 | `SecurityQuotes` | `get_security_quotes` | ✅ |
+| 股票列表 | `SecurityList` | `get_security_list` | ✅ |
+| 分时数据 | `MinuteTime` | `get_minute_time_data` | ✅ |
+| 逐笔成交 | `Transaction` | `get_transaction_data` | ✅ |
+| 财务信息 | `FinanceInfo` | `get_finance_info` | ✅ |
+| 指数行情 | `SecurityQuotes` | `get_index_quotes` | ✅ |
+
+### 代码统计
+
+- 新增模块：3个（finance_info, transaction, minute_time）
+- 修改模块：2个（quotes 修复bug, mod.rs 导出）
+- 新增示例程序：6个
+- 新增Python验证脚本：6个
+- 代码行数：+1297行
+
+---
+
 ## v0.4.0 (2023-02-21)
 
 rustdx-cmd：

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,10 +1,10 @@
 [package]
-name        = "rustdx"
-version     = "0.4.2"
+name        = "rustdx-complete"
+version     = "0.5.0"
 edition     = "2021"
 license     = "MIT"
-description = "受 pytdx 启发的 A 股数据获取库"
-repository  = "https://github.com/zjp-CN/rustdx"
+description = "功能完整的 A 股数据获取库，完全对标 pytdx"
+repository  = "https://github.com/jackluo2012/rustdx"
 authors     = ["zjp <jiping_zhou@foxmail.com>"]
 exclude     = [
                 "assets", "examples", "benches", "tests", "old", "tests-integration",

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 [<img alt="github" src="https://img.shields.io/github/license/zjp-CN/rustdx?color=blue" height="20">](https://github.com/zjp-CN/rustdx)
 [<img alt="github" src="https://img.shields.io/github/issues/zjp-CN/rustdx?color=db2043" height="20">](https://github.com/zjp-CN/rustdx/issues)
-[<img alt="crates.io" src="https://img.shields.io/crates/v/rustdx?style=flat&color=fc8d62&logo=rust&label=rustdx" height="20">](https://crates.io/crates/rustdx)
+[<img alt="crates.io" src="https://img.shields.io/crates/v/rustdx-complete?style=flat&color=fc8d62&logo=rust&label=rustdx-complete" height="20">](https://crates.io/crates/rustdx-complete)
 [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-rustdx-66c2a5?style=flat&labelColor=555555&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/rustdx)
 [<img alt="crates.io" src="https://img.shields.io/crates/v/rustdx-cmd?style=flat&color=fc8d62&logo=rust&label=rustdx-cmd" height="20">](https://crates.io/crates/rustdx-cmd)
 [<img alt="build status" src="https://github.com/zjp-CN/rustdx/workflows/Release%20CI/badge.svg" height="20">](https://github.com/zjp-CN/rustdx/actions)
@@ -16,6 +16,174 @@
 1. 一个 Rust 通用库 [rustdx](https://crates.io/crates/rustdx)；
 2. 一个命令行工具 [rustdx-cmd](https://crates.io/crates/rustdx-cmd)。
 
+## rustdx 库使用
+
+rustdx 是一个功能完整的 A 股数据获取库，完全对标 pytdx 的核心功能。
+
+### 功能特性
+
+| 功能 | rustdx 模块 | pytdx 对应 | 说明 |
+|------|------------|-----------|------|
+| 日K线 | `Kline` | `get_security_bars` | 支持多种周期（日/周/月/分钟） |
+| 除权数据 | `Xdxr` | `get_xdxr` | 股票除权除息信息 |
+| 实时行情 | `SecurityQuotes` | `get_security_quotes` | 股票和指数实时快照 |
+| 股票列表 | `SecurityList` | `get_security_list` | 获取所有股票代码 |
+| 分时数据 | `MinuteTime` | `get_minute_time_data` | 当日分时成交数据 |
+| 逐笔成交 | `Transaction` | `get_transaction_data` | tick-level 成交数据 |
+| 财务信息 | `FinanceInfo` | `get_finance_info` | 32个财务基本面数据 |
+| 指数行情 | `SecurityQuotes` | `get_index_quotes` | 上证指数、深证成指等 |
+
+### 安装
+
+```toml
+[dependencies]
+rustdx-complete = "0.5.0"
+```
+
+### 使用示例
+
+#### 获取股票实时行情
+
+```rust
+use rustdx::tcp::{Tcp, Tdx};
+use rustdx::tcp::stock::SecurityQuotes;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut tcp = Tcp::new()?;
+
+    // 获取多只股票的实时行情
+    let mut quotes = SecurityQuotes::new(vec![
+        (0, "000001"),  // 平安银行（深市）
+        (1, "600000"),  // 浦发银行（沪市）
+    ]);
+
+    quotes.recv_parsed(&mut tcp)?;
+
+    for quote in quotes.result() {
+        println!("{}: {} - 当前价: {}", quote.code, quote.name, quote.price);
+    }
+
+    Ok(())
+}
+```
+
+#### 获取指数行情
+
+```rust
+use rustdx::tcp::{Tcp, Tdx};
+use rustdx::tcp::stock::SecurityQuotes;
+
+let mut tcp = Tcp::new()?;
+
+// 获取主要指数行情
+let mut quotes = SecurityQuotes::new(vec![
+    (1, "000001"),  // 上证指数
+    (0, "399001"),  // 深证成指
+    (1, "000300"),  // 沪深300
+]);
+
+quotes.recv_parsed(&mut tcp)?;
+
+for quote in quotes.result() {
+    println!("{}: {} (涨跌: {}%)", quote.code, quote.price, quote.change_percent);
+}
+```
+
+#### 获取日线数据
+
+```rust
+use rustdx::tcp::{Tcp, Tdx};
+use rustdx::tcp::stock::Kline;
+
+let mut tcp = Tcp::new()?;
+let mut kline = Kline::new(1, "600000", 9, 0, 10); // 沪市、浦发银行、日线、从0开始获取10条
+
+kline.recv_parsed(&mut tcp)?;
+
+for bar in kline.result() {
+    println!("{} : 开({}) 高({}) 低({}) 收({})",
+        bar.dt, bar.open, bar.high, bar.low, bar.close);
+}
+```
+
+#### 获取财务信息
+
+```rust
+use rustdx::tcp::{Tcp, Tdx};
+use rustdx::tcp::stock::FinanceInfo;
+
+let mut tcp = Tcp::new()?;
+let mut finance = FinanceInfo::new(0, "000001"); // 深市、平安银行
+
+finance.recv_parsed(&mut tcp)?;
+
+let info = &finance.result()[0];
+println!("股票代码: {}", info.code);
+println!("总股本: {:.0} 股", info.zongguben);
+println!("净资产: {:.0} 元", info.jingzichan);
+println!("净利润: {:.0} 元", info.jinglirun);
+```
+
+#### 获取分时数据
+
+```rust
+use rustdx::tcp::{Tcp, Tdx};
+use rustdx::tcp::stock::MinuteTime;
+
+let mut tcp = Tcp::new()?;
+let mut minute = MinuteTime::new(0, "000001", 0); // 深市、平安银行、从第0条开始
+
+minute.recv_parsed(&mut tcp)?;
+
+for data in minute.result().iter().take(10) { // 只打印前10条
+    println!("{} : 价格={} 成交量={}", data.time, data.price, data.vol);
+}
+```
+
+#### 获取逐笔成交
+
+```rust
+use rustdx::tcp::{Tcp, Tdx};
+use rustdx::tcp::stock::Transaction;
+
+let mut tcp = Tcp::new()?;
+let mut transaction = Transaction::new(0, "000001", 0); // 深市、平安银行、从第0条开始
+
+transaction.recv_parsed(&mut tcp)?;
+
+for data in transaction.result().iter().take(5) { // 只打印前5笔
+    println!("{} : 价格={} 成交量={} 买卖方向={}",
+        data.time, data.price, data.vol, data.buyorsell);
+}
+```
+
+### 市场代码说明
+
+- `0` = 深市（深圳证券交易所）
+- `1` = 沪市（上海证券交易所）
+
+### 超时设置
+
+默认 TCP 超时时间为 5 秒。如果网络环境较差，可以调整 `src/tcp/mod.rs` 中的 `TIMEOUT` 常量。
+
+### 完整示例程序
+
+项目 `examples/` 目录下提供了完整的使用示例：
+
+- `test_security_quotes.rs` - 股票和指数行情
+- `test_kline.rs` - K线数据
+- `test_finance_info.rs` - 财务信息
+- `test_minute_time.rs` - 分时数据
+- `test_transaction.rs` - 逐笔成交
+- `test_security_list.rs` - 股票列表
+
+运行示例：
+```bash
+cargo run --example test_security_quotes
+```
+
+---
+
 命令行工具（统计数据基于笔者的单核 CPU Ubuntu 系统 release build，以实际速度为准）：
 1. 解析所有最新股票列表的历史 A 股数据（包含复权数据）不到 30s ，解析后的 csv 大小 1G 多；
 2. 将解析后的 csv 数据插入到 ClickHouse （20s，表 268 M） 或 MongoDB （7 分钟，表超过 700 M）；