crypto_monitor/docs/lib-structure.md

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 集中维护资源目录，避免硬编码：

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（与重构前相同）：

_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.<子包>.<模块> 形式导入，例如：

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 末尾：

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 路径，或从根目录运行）：

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 — 总览与部署
• 策略交易说明.md
• manual_trading_hub/使用说明.md