docs: 建立 MkDocs 文档站与 AI 层文档
- 新增 MkDocs + Material 文档站(19 页):入门、CLI、场景示例、FAQ、 Contributing、Changelog、API 参考(mkdocstrings 自动渲染)、内部原理 (架构 / 协议 / 三池路由 / 缓存) - 新增 docs/llms.txt:面向 LLM 的结构化摘要(枚举取值、方法速查、常见陷阱) - 新增 scripts/check_docs.py:校验文档与 api.py 公开方法清单是否漂移 - 新增根 CHANGELOG.md 作为版本记录唯一来源,docs/changelog.md 用 snippet 引入 - 新增 .github/workflows/docs.yml:push main 自动构建并部署 GitHub Pages - 修正文档口径:TdxData 公开方法 53 个(51 数据方法 + start/close); API_REFERENCE 版本号 v0.3.2 -> v0.4.0 - pyproject.toml 新增 docs 依赖组;.gitignore 忽略 site/
This commit is contained in:
1 parent
02ec5b6e33
commit
c4dd61665b
26 files changed
+2934
-1
No files matched your search
@@ -0,0 +1,108 @@
|
||||
# 架构总览
|
||||
|
||||
## 分层
|
||||
|
||||
调用链是单向的,每一层只依赖它下面的一层——想加新接口时先想清楚「这属于哪一层」。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["api.py — TdxData<br/>唯一对外入口,51 个公开方法"] --> B["router.py<br/>按命令选通道"]
|
||||
B --> C["pool/ — 动态连接池<br/>标准池 / MAC 池 / EX 池"]
|
||||
B --> D["scheduler/ — 并发分页调度<br/>Paginator"]
|
||||
C --> E["protocol/ — 协议层<br/>帧 / 变长整数 / 价格 / 日期 / 命令"]
|
||||
E --> F["TCP 通达信服务器<br/>7709 标准+MAC · 7727 EX"]
|
||||
A --> G["cache/ — 双层 TTL 缓存<br/>Memory LRU → Disk SQLite"]
|
||||
A --> H["codec/ — 解析与序列化<br/>缓存载荷 / 服务器文件"]
|
||||
H --> I["models/ — dataclass + 枚举"]
|
||||
```
|
||||
|
||||
## 目录
|
||||
|
||||
```
|
||||
src/pytdxdata/
|
||||
├── api.py # 统一接口 TdxData(对外唯一入口)
|
||||
├── router.py # 标准 / MAC / EX 通道选路
|
||||
├── config.py # 服务器清单加载(servers.json)
|
||||
├── indicator.py # 技术指标(纯函数,无依赖)
|
||||
├── server_probe.py # 服务器探测,可 python -m 运行
|
||||
├── protocol/ # 协议层
|
||||
│ ├── frame.py # 标准帧
|
||||
│ ├── mac_frame.py # MAC 帧
|
||||
│ ├── _binary.py # 变长整数等底层字节工具
|
||||
│ ├── price.py # 自定义浮点价格还原
|
||||
│ ├── volume.py # 成交量差分还原
|
||||
│ ├── datetime_.py # 日期 / 时间编码
|
||||
│ └── commands/ # 16 个命令模块
|
||||
├── pool/ # 连接池
|
||||
│ ├── connection.py # 单连接(含重连)
|
||||
│ ├── pool.py # 标准 / MAC 动态池
|
||||
│ ├── ex_pool.py # EX 池
|
||||
│ ├── health.py # 健康分与选路
|
||||
│ └── probe_cache.py # 探测结果缓存
|
||||
├── scheduler/
|
||||
│ └── paginator.py # 并发分页调度(3 连接并行)
|
||||
├── cache/
|
||||
│ ├── key.py # 缓存键规范化
|
||||
│ ├── ttl.py # TTL 分级策略
|
||||
│ ├── memory.py # 内存 LRU
|
||||
│ ├── disk.py # 磁盘 SQLite(WAL)
|
||||
│ └── manager.py # 两级协同 + single-flight
|
||||
├── models/ # dataclass + 枚举(单文件,无子模块)
|
||||
└── codec/ # 缓存载荷序列化 + 服务器文件解析
|
||||
├── payload.py # 缓存载荷 pickle + zlib
|
||||
├── block.py # 板块 .dat
|
||||
├── industry.py # tdxhy.cfg
|
||||
└── financial.py # gpcw.txt / gpcw*.zip
|
||||
```
|
||||
|
||||
## 一次 `get_kline` 的完整路径
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 调用方
|
||||
participant A as api.py
|
||||
participant C as cache/
|
||||
participant R as router.py
|
||||
participant P as pool/
|
||||
participant S as scheduler/
|
||||
|
||||
U->>A: get_kline(SH, 600000, DAY, count=2400)
|
||||
A->>A: 规范化缓存键
|
||||
A->>C: 查缓存
|
||||
alt 命中
|
||||
C-->>A: list[SecurityBar]
|
||||
A-->>U: 直接返回(0 网络 0 解析)
|
||||
else 未命中
|
||||
A->>C: 登记 single-flight
|
||||
A->>R: 选通道
|
||||
R-->>A: 标准通道
|
||||
A->>S: 分页(count=2400 → 3 页)
|
||||
S->>P: 并发取 3 个连接
|
||||
P->>P: 健康分 + EWMA 延迟选路
|
||||
P-->>S: 3 个连接
|
||||
S->>S: 并行拉取 → 按序拼接
|
||||
S-->>A: 完整 bars
|
||||
A->>C: 写入内存 + 磁盘
|
||||
A-->>U: 返回
|
||||
end
|
||||
```
|
||||
|
||||
关键点:
|
||||
|
||||
- **缓存查在选路之前**——命中就完全不走网络,所以重复请求是 0.016s 量级
|
||||
- **single-flight 在缓存层**——同一个键的并发请求会合并成一次回源,其余等待结果
|
||||
- **分页与选路分离**——`scheduler` 只管拆分与拼接,不知道通道差异;`pool` 只管给连接
|
||||
|
||||
## 三个设计约束
|
||||
|
||||
| 约束 | 原因 |
|
||||
|---|---|
|
||||
| **零运行时依赖** | 用 `socket` / `zlib` / `struct` / `sqlite3` / `asyncio` 全部搞定,避免依赖地狱和版本冲突 |
|
||||
| **返回 `list[dataclass]`** | 不让调用方被 pandas 绑架;需要 DataFrame 自己转一行 |
|
||||
| **API 向后兼容** | 新增能力用新方法名(`get_block_parsed` 而不是改 `get_block_info` 的返回类型),老代码永不失效 |
|
||||
|
||||
## 下一步
|
||||
|
||||
- [协议与命令](protocol.md) — 最底层在做什么
|
||||
- [通道与数据源](routing.md) — 为什么有的请求走不同的服务器
|
||||
- [连接池与缓存](cache-pool.md) — 性能来自哪里
|
||||
Reference in new issue
Block a user