mirror of
https://ghfast.top/https://github.com/aeroxw/easy_tdx_max.git
synced 2026-09-12 13:24:18 +08:00
docs: 新增 architecture/development，重写 docs/index.md 全量索引
- architecture.md：七层架构图 + 源码树 + 分层要点（越层直调/协议层无 IO/ e2e_mock 替身/__main__ 三形态/平台差异） - development.md：环境初始化/测试三层分布/静态检查/开发流程四阶段 （需求 Issue→开发测试→提交 CI→发布 release+CHANGELOG）/文档规范 - index.md：人类目录（分类+每文件一句描述+历史归档标注）+ 完整 toctree （38 个 md 全部入树，消除 ReadTheDocs orphan 页面） Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
awayings
@@ -0,0 +1,54 @@
|
||||
# 架构
|
||||
|
||||
<img src="./easy-tdx-architecture.png" alt="easy-tdx 七层架构总览：接口 → 服务 → 领域 → 持久 → 网关 → 协议 → 外部源" />
|
||||
|
||||
七层分层，请求自上而下、数据（pandas DataFrame）自下而上：**① 用户接口层**（Web UI / CLI / Python API / 桌面 EXE）→ **② Web 服务层**（FastAPI + SSE 实时推送 + 异步任务）→ **③ 领域层**（回测 / 指标 / 缠论 / 因子 / 选股 / 组合，纯计算零网络）→ **④ 数据持久层**（DuckDB K 线仓库 + 通达信本地 vipdoc 文件）→ **⑤ 客户端网关层**（8 个客户端 + 健康分 / 故障转移）→ **⑥ 协议层**（通达信二进制协议编解码）→ **⑦ 外部数据源**（通达信服务器 / 中金所 / 新浪 / 巨潮 / LLM）。虚线为旁路直连（HTTP 数据源 / 本地文件 / CLI 与 Python API 越层直调）。
|
||||
|
||||
🖼️ 交互版架构图（可缩放平移、悬停查看 38 个模块的职责详情、一键导出 PNG）：[architecture.html](./architecture.html)
|
||||
|
||||
## 源码树
|
||||
|
||||
```
|
||||
src/easy_tdx/
|
||||
├── client.py # TdxClient / AsyncTdxClient（标准协议）
|
||||
├── unified.py # UnifiedTdxClient（统一入口）
|
||||
├── config.py # 服务器地址、端口、超时配置
|
||||
├── indicator.py # 技术指标计算（34 个，基于 MyTT）
|
||||
├── MyTT.py # 麦语言技术指标算法库
|
||||
├── mac/
|
||||
│ ├── client.py # MacClient / AsyncMacClient（MAC 协议）
|
||||
│ ├── enums.py # Period, Adjust, Category, ExMarket, SortType, ...
|
||||
│ ├── models.py # MacBar, MacQuoteField, MacTick, BoardInfo, ...
|
||||
│ └── commands/ # MAC 命令（build_request + parse_response，无 IO）
|
||||
├── ex/
|
||||
│ ├── client.py # ExTdxClient / AsyncExTdxClient（标准协议扩展市场）
|
||||
│ ├── mac_client.py # MacExClient / AsyncMacExClient（MAC 协议扩展市场）
|
||||
│ └── transport/ # ExTdxConnection（端口 7727）
|
||||
├── transport/
|
||||
│ ├── sync.py # TdxConnection + ping_host / ping_all
|
||||
│ └── async_.py # AsyncTdxConnection（asyncio）
|
||||
├── commands/ # 标准协议命令（无 IO）
|
||||
├── codec/ # price / volume / datetime / frame / bitmap 编解码
|
||||
├── chanlun/ # 缠论技术分析（K线合并/分型/笔/线段/中枢/买卖点/背驰）
|
||||
├── factor/ # 因子引擎（Factor ABC/19内置因子/截面计算/因子分析/预处理管道）
|
||||
├── portfolio/ # 组合管理（4优化器/风险模型/再平衡引擎）
|
||||
├── backtest/ # 回测引擎（Strategy基类/向量化引擎/多因子组合/滑点模型/执行仿真/归因分析）
|
||||
├── screen/ # 策略选股扫描（scan信号扫描/rank回测排名/并发扫描/增量缓存）
|
||||
├── realtime/ # 实时数据推送框架（EventBus/事件驱动/asyncio）
|
||||
├── web/ # Web API（FastAPI REST + WebSocket）
|
||||
├── models/ # 纯 dataclass，无业务逻辑
|
||||
├── offline/ # 离线数据读写模块（读取 + 写入同步）
|
||||
└── cli/ # easy-tdx CLI（click）
|
||||
```
|
||||
|
||||
commands 层不依赖 transport，可独立单测。
|
||||
|
||||
## 分层要点
|
||||
|
||||
- **协议层无 IO**：`commands/`、`codec/`、`mac/commands/` 只做编解码，可完全离线单测（`tests/fixtures/` 的 hex dump 即其测试镜像）。
|
||||
- **领域层零网络**：`backtest/`、`chanlun/`、`factor/`、`portfolio/`、`screen/` 只吃 DataFrame，不碰网络——这是回测/扫描可在无行情连接时运行的基础。
|
||||
- **网关层统一入口**：`unified.py` 封装 8 个客户端（标准/MAC × 同步/异步 × 常规/扩展），带健康分与故障转移；上层（Web、CLI）优先走它。
|
||||
- **越层直调**：CLI 与 Python API 不经过 Web 服务层，直接调网关/领域层；HTTP 数据源（新浪/巨潮/中金所）与本地文件直读是旁路。因此同一功能常有三处入口（CLI 命令 / Python API / REST 端点），改领域逻辑三处受益；改协议/网关时注意 Web 层的替身切入点（`web/e2e_mock.py` 在 `EASY_TDX_E2E_MOCK=1` 下替换全部客户端）。
|
||||
- **CLI 薄封装**：`cli/cmd_*.py` 每个文件一个 click 命令组，业务全部在领域/网关层；领域模块内也有 CLI（`backtest/cli.py`、`screen/cli.py`），由 `cli/__init__.py` 汇总注册。入口链：`easy-tdx` 命令 → `_editable_guard:main`（可编辑安装失效时打印修复指引）→ CLI。
|
||||
- **`python -m easy_tdx` 三种形态**（`__main__.py`）：开发态无参默认等价 `easy-tdx serve`；打包态双击走托盘（uvicorn 后台线程 + 主线程 pystray 托盘）；multiprocessing 子进程拦截保护（Windows spawn 下防止子进程重复启动 uvicorn，一键寻优/screen 扫描等多进程功能依赖它）。
|
||||
- **离线数据平台差异**：`.day` 文件路径分隔符 / GBK 文件名 / 时区行为在 Windows 与 Linux 不同，CI 有 Windows matrix 覆盖，改 `offline/` 时留意。
|
||||
@@ -0,0 +1,87 @@
|
||||
# 开发环境与流程
|
||||
|
||||
本文档是开发者的完整工作流参考。命令速查亦见 [CLAUDE.md](../CLAUDE.md)。
|
||||
|
||||
## 环境初始化
|
||||
|
||||
```bash
|
||||
git clone git@github.com:awayings/easy_tdx.git && cd easy_tdx
|
||||
uv sync --all-extras # 建 .venv 并装全部 extras（普通 uv sync 只装基础依赖）
|
||||
```
|
||||
|
||||
CI 不用 uv，走 `pip install -e ".[dev]"` + `pip install -r requirements-dev.txt`。改依赖时两套流程都要考虑：pyproject.toml 只写下界+上界，`uv.lock` 与 `requirements-dev.txt` 才是可复现锁（dev 工具链锁定版本必须兼容 Python 3.10，CI 矩阵跑 3.10/3.12/3.13）。
|
||||
|
||||
前端：`cd web-ui && npm ci && npm run build`（`build` = vue-tsc 类型检查 + vite build）。**`pip install -e .` 要求 `web-ui/dist` 存在**（hatchling `force-include` 把它打进 wheel 的 `easy_tdx/web/dist/`），所以改前端后、跑 Python 测试/安装前必须先构建。
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
python -m pytest tests/unit/ -v # 单元测试（无需网络，全部 mock）
|
||||
XMTDX_LIVE=1 python -m pytest tests/integration/ -v # 集成测试（连真实通达信服务器，默认 skip）
|
||||
python -m pytest tests/unit/ --cov src/easy_tdx --cov-fail-under=60 # 覆盖率门槛 60
|
||||
```
|
||||
|
||||
三层测试分布：
|
||||
|
||||
| 层 | 位置 | 跑在哪 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 单元 | `tests/unit/` | CI（6 格矩阵）+ 本地 | 全 mock：`tests/fixtures/` 真实协议 hex dump + JSON 对照，`tests/golden/` 期望输出 |
|
||||
| 集成 | `tests/integration/` | **仅本地** | `XMTDX_LIVE=1` 才执行，连真实 TDX 服务器 smoke test |
|
||||
| 前端 E2E | `web-ui/e2e/*.spec.ts` | CI frontend job + 本地 | Playwright，`EASY_TDX_E2E_MOCK=1` 后端合成行情，不连真实服务器 |
|
||||
|
||||
- `tests/conftest.py` 默认设 `EASY_TDX_NO_TASK_DB=1`，防单测污染 `~/.easy_tdx/tasks.db`；需要测试存储的用例用 `EASY_TDX_CONFIG_DIR` 指向 `tmp_path` 显式重开。
|
||||
- `tests/unit/test_ai_llm.py` 依赖 LLM API key 轮询，CI 用 `--ignore` 跳过，本地有 mock 可跑。
|
||||
- `asyncio_mode = "auto"`：async 测试无需 `@pytest.mark.asyncio`。
|
||||
|
||||
## 静态检查
|
||||
|
||||
```bash
|
||||
mypy src/ # strict 模式（pyproject 配置）
|
||||
ruff check src/ tests/ # E/F/I/UP 规则
|
||||
ruff format --check src/ tests/
|
||||
```
|
||||
|
||||
mypy/ruff 均排除 `src/easy_tdx/exchange_margin.py`；`MyTT.py` 有手写 `MyTT.pyi` stub 保持 strict 检查。
|
||||
|
||||
本地一键门禁（等价 CI 三 job 的本地版）：
|
||||
|
||||
```bash
|
||||
bash scripts/verify_ci.sh # ruff → format → mypy → pytest（排除 integration）→ 前端 build + E2E
|
||||
bash scripts/verify_ci.sh --fast # 只跑静态检查
|
||||
# 可选：ln -s ../../scripts/verify_ci.sh .git/hooks/pre-push
|
||||
```
|
||||
|
||||
## 开发流程
|
||||
|
||||
### a. 需求（Issue）
|
||||
|
||||
- 功能/缺陷先在 GitHub Issues 提出；代码注释与提交说明中引用编号（如 `#58`、`审计 #9`）。
|
||||
- 复杂功能先写设计文档再动手（历史范本：`docs/board-overview-design.md`、`docs/hotspot-rolling-design.md`，以及 `docs/superpowers/` 下的 specs）。
|
||||
- 功能变更时同步评估文档更新（见「文档规范」）。
|
||||
|
||||
### b. 开发与测试
|
||||
|
||||
- 新功能/修复按 TDD 习惯先写红测试再实现；单元测试必须零网络、零真实服务器依赖。
|
||||
- 命令形态变更时 `easy-tdx --help` 自检；Web 路由变更时 `/docs` Swagger 自检。
|
||||
|
||||
### c. 提交与 CI
|
||||
|
||||
- 提交信息带前缀（`feat:` / `fix:` / `test:` / `docs:` / `refactor:`，可带作用域如 `feat(web):`），中文描述。push/PR 到 `main` 触发 `ci.yml`：
|
||||
- test job：ubuntu/windows × py3.10/3.12/3.13 六格矩阵跑单测（覆盖率 ≥60）+ ruff + format
|
||||
- mypy job：strict 模式（py3.13）
|
||||
- frontend job：vue-tsc + Playwright mock E2E
|
||||
- **集成测试不进 CI**（依赖真实 TDX 服务器），发布前本地 `XMTDX_LIVE=1` 手动跑一遍。
|
||||
|
||||
### d. 发布版本
|
||||
|
||||
1. 收敛时打一个聚合提交 `release: vX.Y.Z — 中文一句话摘要`，同一提交内包含：代码与测试改动 + `pyproject.toml` 版本号 bump + `CHANGELOG.md` 新增版本小节。
|
||||
2. CHANGELOG 遵循 Keep a Changelog（zh-CN）：`## [X.Y.Z] — 日期` 倒序最新在前，先一段加粗导语再按主题分 `###` 小节，条目带文件链接，测试小节报数字验收（如「全量 1820 通过，ruff / mypy / vue-tsc 全绿」）。**无 Unreleased 区，CHANGELOG 在 release 提交时写入**。
|
||||
3. 打 tag 推送即自动发布：`git tag vX.Y.Z && git push origin vX.Y.Z`，触发两个独立 workflow——`publish.yml`（PyPI trusted publishing，OIDC 无 token）与 `release.yml`（Windows EXE via PyInstaller + GitHub Release，正文含 SHA256/SmartScreen 说明；GitHub release notes 自动生成，**不读取 CHANGELOG.md**）。
|
||||
4. 版本单一来源是 `pyproject.toml`（前端品牌区版本来自后端 `GET /api/v1/meta`）；文档一律不写死版本号。
|
||||
|
||||
## 文档规范
|
||||
|
||||
- **大小限制**：每份文档约 500 行为上限，超限必须拆分，通过 [index.md](./index.md) 与 README 文档导航串联。过大文件不可新增。
|
||||
- **类型两分**：教程（how-to，代码示例）与参考（速查/字段/命令表）原则上分开成文。
|
||||
- **可达性标准**：任何文档变更必须以「[README.md](../README.md) + [docs/index.md](./index.md) 可达的文件」为标准——新文件必须同时进 README 文档导航与 index.md；删除/改名必须同步修复全部链接。
|
||||
- **禁止硬编码版本横幅**：版本信息以 `pyproject.toml` 与 `CHANGELOG.md` 为准；功能引入说明里的版本标注（如「v1.29.1」）除外。
|
||||
+103
-5
@@ -1,16 +1,114 @@
|
||||
# easy-tdx 文档
|
||||
# easy-tdx 文档索引
|
||||
|
||||
本索引是文档的目录目录：**新增或删除文档必须同步更新本文件与 README 文档导航**（见 [development.md](./development.md) 的文档规范）。每份文档 ≤500 行，超限拆分；教程（how-to）与参考（速查）分开成文。
|
||||
|
||||
## 开始
|
||||
|
||||
- [README](../README.md) — 项目门面：功能总览、30 秒上手、安装、文档导航（ReadTheDocs 落地页即其包含）
|
||||
|
||||
## CLI 参考
|
||||
|
||||
- [cli.md](./cli.md) — 全部命令速查表 + 按域导航
|
||||
- [cli-market.md](./cli-market.md) — 行情数据：报价 / K线 / 分时 / 板块 / 资金 / 中金所 / 扩展市场
|
||||
- [cli-finance.md](./cli-finance.md) — 财务与公告：巨潮公告检索 / 财报三表 / 通达信 F10
|
||||
- [cli-indicators.md](./cli-indicators.md) — 技术指标与公式：34 指标 / 通达信公式 / 捉妖 / 乖离率
|
||||
- [cli-backtest.md](./cli-backtest.md) — 回测与寻优：backtest / optimize / portfolio / run-all（含参数表）
|
||||
- [cli-screen.md](./cli-screen.md) — 选股扫描：全市场信号扫描 / 强势股排名
|
||||
- [chanlun.md](./chanlun.md) — 缠论分析（CLI + Python，含完整输出示例）
|
||||
|
||||
## 本地数据
|
||||
|
||||
- [data-local.md](./data-local.md) — K 线仓库（DuckDB）与 vipdoc 离线读写（CLI + Python 合一操作手册）
|
||||
|
||||
## Web
|
||||
|
||||
- [web-api.md](./web-api.md) — REST + WebSocket + SSE 端点与示例、帧规范
|
||||
- [web-ui.md](./web-ui.md) — 行情终端与回测工作台零代码操作手册
|
||||
- [packaging.md](./packaging.md) — Windows EXE 打包（PyInstaller）与分发
|
||||
|
||||
## Python API
|
||||
|
||||
- [python-api.md](./python-api.md) — 教程：连接管理 / MAC 协议 / 统一客户端 / 离线 / 缠论 / 公告 / 财报 / 实时轮询
|
||||
- [api_reference.md](./api_reference.md) — 参考：TdxClient 标准协议方法速查 + MAC 客户端方法表
|
||||
- [field_mapping.md](./field_mapping.md) — 参考：数据模型字段 ↔ 中文含义 ↔ 类型 + 枚举（标准 + MAC）
|
||||
|
||||
## 回测与量化
|
||||
|
||||
- [backtest_usage.md](./backtest_usage.md) — 回测引擎使用手册（策略 / 配置 / 结果）
|
||||
- [backtest-examples.md](./backtest-examples.md) — 完整示例集 + 注意事项
|
||||
- [quantitative-guide.md](./quantitative-guide.md) — 因子引擎与组合管理（基础）
|
||||
- [quantitative-advanced.md](./quantitative-advanced.md) — 滑点模型 / 执行仿真 / 归因分析 / 完整工作流
|
||||
|
||||
## 指标深度
|
||||
|
||||
- [indicator-zhuoyao.md](./indicator-zhuoyao.md) — 捉妖大师（ZHUOYAO）多周期 ROC 共振详解
|
||||
- [indicator-bias-signal.md](./indicator-bias-signal.md) — 30 日乖离率信号（BIAS_SIGNAL）详解
|
||||
|
||||
## 开发者
|
||||
|
||||
- [architecture.md](./architecture.md) — 七层架构图 / 源码树 / 分层要点
|
||||
- [development.md](./development.md) — 环境初始化 / 测试 / CI / 发布流程 / 文档规范
|
||||
|
||||
## 协议与逆向
|
||||
|
||||
- [protocol-reverse-engineering.md](./protocol-reverse-engineering.md) — 通达信二进制协议逆向过程
|
||||
- [protocol-unknown-fields.md](./protocol-unknown-fields.md) — 未知字段研究日志（活文档）
|
||||
|
||||
## 历史归档（已实施 / 规划完成，供追溯）
|
||||
|
||||
- [board-overview-design.md](./board-overview-design.md) — 行业/概念总览页设计稿（已上线）
|
||||
- [hotspot-rolling-design.md](./hotspot-rolling-design.md) — 市场热点滚动页设计稿（已上线）
|
||||
- [market-insights-roadmap.md](./market-insights-roadmap.md) — 盘面洞察功能路线图（已收尾）
|
||||
- [upgrade-plan-2026H2.md](./upgrade-plan-2026H2.md) — 2026 H2 升级计划（全部阶段完成）
|
||||
- [superpowers/](superpowers/) — 回测/因子/组合引擎的计划与设计存档（v1.11–v1.15 时代，非现行文档）
|
||||
|
||||
## HTML 资产（仅 GitHub 可交互，ReadTheDocs 不发布）
|
||||
|
||||
- [architecture.html](./architecture.html) — 38 模块交互式架构图（可缩放平移、导出 PNG）
|
||||
- [回测系统完全上手手册.html](./回测系统完全上手手册.html) — 零基础图文回测手册（13 章）
|
||||
|
||||
---
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
:caption: 目录
|
||||
:maxdepth: 1
|
||||
:caption: 文档目录
|
||||
|
||||
readme
|
||||
cli
|
||||
cli-market
|
||||
cli-finance
|
||||
cli-indicators
|
||||
cli-backtest
|
||||
cli-screen
|
||||
chanlun
|
||||
data-local
|
||||
web-api
|
||||
web-ui
|
||||
python-api
|
||||
api_reference
|
||||
field_mapping
|
||||
backtest_usage
|
||||
backtest-examples
|
||||
quantitative-guide
|
||||
protocol-reverse-engineering
|
||||
protocol-unknown-fields
|
||||
quantitative-advanced
|
||||
indicator-zhuoyao
|
||||
indicator-bias-signal
|
||||
architecture
|
||||
development
|
||||
packaging
|
||||
protocol-reverse-engineering
|
||||
protocol-unknown-fields
|
||||
board-overview-design
|
||||
hotspot-rolling-design
|
||||
market-insights-roadmap
|
||||
upgrade-plan-2026H2
|
||||
superpowers/plans/2026-06-09-backtest-engine
|
||||
superpowers/plans/2026-06-12-v1.11.0-factor-engine
|
||||
superpowers/plans/2026-06-12-v1.12.0-factor-analysis
|
||||
superpowers/plans/2026-06-12-v1.13.0-portfolio
|
||||
superpowers/plans/2026-06-12-v1.14.0-slippage-execution
|
||||
superpowers/plans/2026-06-12-v1.15.0-attribution
|
||||
superpowers/specs/2026-06-09-backtest-engine-design
|
||||
superpowers/specs/2026-06-12-advanced-backtest-design
|
||||
superpowers/specs/2026-06-12-quantitative-factor-engine-design
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user