dekun
5797d49d8a
统一 strategy、key_monitor、trade、hub 等共用库到 lib/ 子包，并补充 lib-structure 文档，便于四所与中控维护。 Co-authored-by: Cursor <cursoragent@cursor.com>
148 lines
5.7 KiB
Markdown
148 lines
5.7 KiB
Markdown
# lib/ 共用模块结构
|
||
|
||
四所实例与中控共用的 Python 库、模板与静态资源统一放在仓库根目录的 **`lib/`** 下。部署单元（`crypto_monitor_*`、`manual_trading_hub`）仍保持独立目录与 PM2 配置不变。
|
||
|
||
**重构前快照 Git 标签**：`pre-lib-modularization`（可用 `git checkout pre-lib-modularization` 查看旧布局）。
|
||
|
||
---
|
||
|
||
## 顶层目录
|
||
|
||
```
|
||
crypto_monitor/
|
||
├── crypto_monitor_binance/ # 四所：各自 app + .env + PM2
|
||
├── crypto_monitor_gate/
|
||
├── crypto_monitor_gate_bot/
|
||
├── crypto_monitor_okx/
|
||
├── manual_trading_hub/ # 中控 + 子代理 agent
|
||
│
|
||
├── lib/ # 共用模块（本说明）
|
||
│ ├── strategy/
|
||
│ ├── key_monitor/
|
||
│ ├── trade/
|
||
│ ├── hub/
|
||
│ ├── ai/
|
||
│ ├── instance/
|
||
│ ├── exchange/
|
||
│ ├── common/
|
||
│ └── paths.py
|
||
│
|
||
├── brand/ # 各所共用图标
|
||
├── docs/
|
||
├── deploy/
|
||
├── scripts/
|
||
├── tests/
|
||
├── requirements.txt
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## lib/ 子包说明
|
||
|
||
| 子包 | 职责 | 主要模块 |
|
||
|------|------|----------|
|
||
| **`lib/strategy/`** | 策略交易（顺势加仓、趋势回调、快照与记录） | `strategy_register.py`、`strategy_trend_register.py`、`strategy_db.py`、`strategy_roll_*`、`strategy_trend_*` |
|
||
| **`lib/strategy/templates/`** | 策略页 Jinja 模板（原 `strategy_templates/`） | `strategy_trading_page.html`、`strategy_roll_panel.html` 等 |
|
||
| **`lib/key_monitor/`** | 关键位监控、斐波、假突破、止盈止损方案 | `key_monitor_lib.py`、`fib_key_monitor_lib.py`、`key_sl_tp_lib.py` 等 |
|
||
| **`lib/trade/`** | 下单监控展示、计仓、账户风控、手动 SL/TP | `order_monitor_display_lib.py`、`position_sizing_lib.py`、`account_risk_lib.py` 等 |
|
||
| **`lib/hub/`** | 中控 API、K 线、归档、计仓器、SSO/Bridge | `hub_bridge.py`、`hub_kline_store.py`、`hub_trades_lib.py` 等 |
|
||
| **`lib/ai/`** | AI 复盘与文本生成 | `ai_client.py`、`ai_review_lib.py` |
|
||
| **`lib/instance/`** | 中控 iframe 嵌入、导航、复盘图表 | `instance_embed_lib.py`、`focus_chart_lib.py`、`journal_chart_lib.py` |
|
||
| **`lib/instance/templates/`** | 嵌入页片段（原 `embed_templates/`） | `embed_page_fragment.html` |
|
||
| **`lib/exchange/`** | 特定交易所工具 | `gate_transfer_lib.py`、`okx_orders_lib.py` 等 |
|
||
| **`lib/common/`** | 跨功能小工具 | `form_submit_lib.py`、`wechat_notify_lib.py` 等 |
|
||
| **`lib/common/static/`** | 四所与中控共用的 JS/CSS（原根目录 `static/`） | `instance_theme.js`、`strategy_roll.js` 等 |
|
||
|
||
> **说明**：`hub_*` 命名表示「中控侧能力或行情聚合」，但部分模块（如 `hub_volume_rank_lib`、`hub_market_info_lib`）四所 `app.py` 也会调用，并非中控独占。
|
||
|
||
---
|
||
|
||
## 路径辅助函数
|
||
|
||
`lib/paths.py` 集中维护资源目录，避免硬编码：
|
||
|
||
```python
|
||
from lib.paths import strategy_templates_dir, embed_templates_dir, common_static_dir
|
||
|
||
strategy_templates_dir() # .../lib/strategy/templates
|
||
embed_templates_dir() # .../lib/instance/templates
|
||
common_static_dir() # .../lib/common/static
|
||
```
|
||
|
||
可选传入 `repo_root`（字符串或 `Path`），默认使用 `lib/` 的上级目录即仓库根。
|
||
|
||
---
|
||
|
||
## Python 导入约定
|
||
|
||
各部署目录在启动时将 **仓库根** 加入 `sys.path`（与重构前相同）：
|
||
|
||
```python
|
||
_REPO_ROOT = os.path.dirname(BASE_DIR) # 或 Path(__file__).resolve().parent.parent
|
||
if _REPO_ROOT not in sys.path:
|
||
sys.path.insert(0, _REPO_ROOT)
|
||
```
|
||
|
||
之后使用 **`lib.<子包>.<模块>`** 形式导入，例如：
|
||
|
||
```python
|
||
from lib.strategy.strategy_db import init_strategy_tables
|
||
from lib.key_monitor.key_monitor_lib import check_key_monitors
|
||
from lib.hub.hub_bridge import install_on_app
|
||
from lib.ai.ai_client import ai_review
|
||
```
|
||
|
||
策略注册仍在各所 `app.py` 末尾：
|
||
|
||
```python
|
||
from lib.strategy.strategy_register import install_strategy_trading
|
||
from lib.strategy.strategy_trend_register import install_strategy_trend
|
||
|
||
install_strategy_trading(app, _REPO_ROOT, app_module=sys.modules[__name__])
|
||
install_strategy_trend(app, _REPO_ROOT, app_module=sys.modules[__name__])
|
||
```
|
||
|
||
---
|
||
|
||
## 静态资源与 URL
|
||
|
||
- 四所页面仍通过 **`/static/...`** 访问共用脚本；`hub_bridge.install_instance_theme_static` 从 `lib/common/static/` 提供部分根级静态路由。
|
||
- 各所目录下 **`static/`**（图标、上传图片等）仍为实例私有，未迁入 `lib/`。
|
||
- 中控 `manual_trading_hub/hub.py` 通过 `_REPO_ROOT / "lib" / "common" / "static"` 挂载与四所共用的 badge、复盘 JS 等。
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
在仓库根执行（需将根目录置于 Python 路径，或从根目录运行）：
|
||
|
||
```bash
|
||
cd /opt/crypto_monitor
|
||
python -m unittest discover -s tests -p "test_*.py"
|
||
```
|
||
|
||
测试文件内统一 `from lib.<子包>.<模块> import ...`。使用 `@patch` 时目标写完整模块路径，例如 `lib.hub.hub_calculator_lib._resolve_market`。
|
||
|
||
---
|
||
|
||
## 迁移脚本
|
||
|
||
一次性迁移由 `scripts/migrate_to_lib.py` 完成（移动文件 + 批量改写 import）。**不要在已迁移后的仓库上重复执行**。
|
||
|
||
---
|
||
|
||
## 后续可选整理
|
||
|
||
- 四所 `app.py` 体量接近，可逐步抽取公共 `exchange_app` 基座（改动面大，单独规划）。
|
||
- `manual_trading_hub/okx_orders_lib.py` 为 agent 本地副本，可与 `lib/exchange/okx_orders_lib.py` 合并去重。
|
||
- 可引入 `pyproject.toml` + `pip install -e .`，替代 `sys.path.insert`（长期维护更规范）。
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [README.md](../README.md) — 总览与部署
|
||
- [策略交易说明.md](../策略交易说明.md)
|
||
- [manual_trading_hub/使用说明.md](../manual_trading_hub/使用说明.md)
|