futu-rs 0.1.2

# futu-rs

富途 OpenAPI 的非官方 Rust SDK，用于对接 [FutuOpenD](https://openapi.futunn.com/futu-api-doc/) 网关程序，实现行情获取与交易下单等功能。

## 功能特性

- 基于 TCP 自定义协议与 OpenD 通信
- 使用 Protobuf 进行协议序列化/反序列化
- 支持 RSA + AES 加密通信
- 异步架构（基于 Tokio）
- 自动心跳保活（KeepAlive）
- 支持行情订阅与推送
- 支持模拟/真实交易

## 支持的功能模块

| 模块 | 说明 | 状态 |
|------|------|------|
| 基础连接 | InitConnect、KeepAlive、加密握手 | 🚧 |
| 行情 | 订阅/退订、实时报价、K 线、逐笔、经纪队列 | 🚧 |
| 交易 | 下单、改单、撤单、查询持仓/订单/成交 | 🚧 |
| 账户 | 获取账户列表、资金数据 | 🚧 |

## 协议概要

futu-rs 实现了富途 OpenD 底层 TCP 二进制协议：

```text
+----+----------+-----+-----+----------+---------+----------+----------+
| FT | ProtoID  | Fmt | Ver | SerialNo | BodyLen | SHA1(20) | Rsv(8)   |
| 2B |   4B     | 1B  | 1B  |   4B     |   4B    |   20B    |   8B     |
+----+----------+-----+-----+----------+---------+----------+----------+
|                          Body (Protobuf)                              |
+-----------------------------------------------------------------------+
```

- 小端字节序
- 协议头固定 44 字节
- 协议体使用 Protobuf 编码（`nProtoFmtType = 0`）
- 包体 SHA1 校验保证数据完整性

## 快速开始

### 前置条件

1. 安装并启动 [FutuOpenD](https://openapi.futunn.com/futu-api-doc/opend/opend-cmd.html)
2. Rust 1.70+
3. Protobuf 编译器（`protoc`）

### 安装

在 `Cargo.toml` 中添加：

```toml
[dependencies]
futu-rs = { git = "https://github.com/tensorchen/futu-rs" }
```

### 示例

```rust
use futu_rs::client::FutuClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 连接本地 OpenD（默认端口 11111）
    let mut client = FutuClient::connect("127.0.0.1:11111").await?;

    // 初始化连接
    client.init_connect("futu-rs", 300).await?;

    // 获取全局状态
    let state = client.get_global_state().await?;
    println!("Market HK: {:?}", state);

    // 获取股票快照
    let snapshots = client.get_security_snapshot(&["HK.00700"]).await?;
    for snap in &snapshots {
        println!("{}: last_price={}", snap.code, snap.last_price);
    }

    Ok(())
}
```

## 项目结构

```
futu-rs/
├── proto/              # 富途 Protobuf 定义文件
├── src/
│   ├── lib.rs          # 库入口
│   ├── client.rs       # FutuClient 连接与请求管理
│   ├── codec.rs        # 协议编解码（协议头 + Protobuf）
│   ├── crypto.rs       # RSA / AES 加解密
│   ├── error.rs        # 错误类型定义
│   ├── protocol.rs     # 协议常量与辅助函数
│   └── pb/             # protoc 生成的 Rust 代码
├── examples/           # 使用示例
├── Cargo.toml
├── build.rs            # Protobuf 编译脚本
└── README.md
```

## 核心依赖

| Crate | 用途 |
|-------|------|
| `tokio` | 异步运行时 |
| `prost` | Protobuf 编解码 |
| `bytes` | 高效字节操作 |
| `rsa` | RSA 加解密 |
| `aes` | AES-ECB 加解密 |
| `sha1` | 包体校验 |
| `anyhow` / `thiserror` | 错误处理 |

## 开发

```bash
# 构建
cargo build

# 运行示例
cargo run --example basic

# 运行测试
cargo test
```

## 注意事项

- 需要本地或远程运行 FutuOpenD 网关
- 浮点数据（价格、百分比）传输存在精度问题，SDK 内部会做四舍五入处理
- 实盘交易建议开启加密通信
- 使用前需在富途牛牛 APP 完成开户及 OpenAPI 权限开通

## 参考

- [Futu API 官方文档](https://openapi.futunn.com/futu-api-doc/)
- [底层协议介绍](https://openapi.futunn.com/futu-api-doc/ftapi/protocol.html)
- [Protobuf 协议定义](https://github.com/FutunnOpen/py-futu-api/tree/master/futu/common/pb)