# 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)