# 系统架构与技术实现

> 定位：描述本仓库（OKX 币本位期权实例）的整体架构、运行时、模块划分与关键技术实现。  
> 配套文档：  
> - 业务主链：[系统分析-期权主链条.md](./系统分析-期权主链条.md)  
> - 盈亏规格：[规格-期权交易账户盈亏结算.md](./规格-期权交易账户盈亏结算.md)  
> - 操作说明：[../使用说明.md](../使用说明.md)  
> - 部署：[../部署文档.md](../部署文档.md) · 实盘：[实盘说明.md](./实盘说明.md)

---

## 1. 系统定位

| 项 | 说明 |
|----|------|
| 角色 | 单交易所实例客户端（OKX），可独立使用，也可挂中控 `crypto_okx_hub` |
| 主业务 | **币本位期权**：USDT → 买 ETH/BTC → 开期权 → 平仓 → 卖回 → 按交易户 USDT 差分冻结盈亏 |
| 非目标 | 不再以永续实盘下单 / USDC 期权开仓 / 对冲计划为主路径（相关代码多已下线或残留） |

三条控制面：

```text
┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ 浏览器面板   │     │ 本机监控守护线程  │     │ 中控 Hub        │
│ /options    │     │ options-monitor  │     │ /api/hub/*      │
│ /api/options│     │ 目标/翻倍/条件单  │     │ 快照/条件单/全平 │
└──────┬──────┘     └────────┬─────────┘     └────────┬────────┘
       │                     │                        │
       └─────────────────────┼────────────────────────┘
                             ▼
                    Flask app.py（单进程）
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
         SQLite         ccxt.okx        模拟 SimBroker
       (crypto.db)    （实盘/公开行情）   （本地撮合）
```

---

## 2. 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 语言 / 运行时 | Python **3.10+** | 见 `README.md` / `requirements.txt` |
| Web 框架 | Flask ≥3、<4 | `threaded=True`；Jinja2 模板 |
| WSGI | Werkzeug | 开发/PM2 直跑 `app.py` |
| 交易所 SDK | **ccxt** ≥4.2（`ccxt.okx`） | 期权 `defaultType=option`；可配 SOCKS |
| HTTP / 代理 | requests、PySocks | `OKX_SOCKS_PROXY` |
| 持久化 | **SQLite** 单文件 | 默认 `DB_PATH=crypto.db` |
| 进程管理 | **PM2** | `ecosystem.config.cjs`：单实例、内存上限约 800M |
| 前端 | **原生 JS/CSS** | 无 React/Vue/`package.json`；静态资源在 `lib/common/static/` |
| 图像 | Pillow | 复盘/日记配图等 |

部署约定（见部署文档）：常见路径 `/opt/crypto_okx`，端口 **`APP_PORT=5004`**（代码未配时 fallback 5000）。

---

## 3. 仓库与目录结构

```text
crypto_okx/
├── app.py                 # 应用入口：装配路由、线程、交易所句柄
├── ecosystem.config.cjs   # PM2
├── requirements.txt
├── .env / .env.example
├── crypto.db              # 运行时 SQLite（勿提交）
├── deploy/                # 安装 / 更新 / doctor 脚本
├── docs/                  # 规格、架构、实盘说明
├── templates/             # Flask 默认模板目录（少量）
├── static/                # 上传等（如 images）
└── lib/
    ├── paths.py           # 仓库根、静态/模板路径
    ├── options/           # 期权交易、监控、复盘、结算（核心）
    ├── exchange/          # OKX 期权 API 封装、账本适配
    ├── sim/               # 模拟钱包与 API hook
    ├── hub/               # 中控 Bridge 鉴权与路由
    ├── env/               # .env 读写、schema、配置页白名单
    ├── instance/          # 壳层 UI、设置、embed、备份、仪表盘
    ├── account_ledger/    # 资金流水同步
    ├── market/            # 行情、K 线、精度
    ├── trade/             # 入场模型/风控等（关键位等周边）
    ├── key_monitor/       # 关键位监控
    └── common/            # 公共工具 + static 前端资源
```

原则：**业务按包 install/register 挂到 Flask**，避免全部逻辑堆在 `app.py`；`app.py` 仍保留登录、部分关键位与全局交易所对象。

---

## 4. 启动与装配顺序

### 4.1 引导流程

```text
load_env_file(.env) → os.environ
  → Flask(__name__) + Session（含中控 iframe SameSite=None/Secure）
  → attach_embed_templates / install_common_static
  → 构建 ccxt.okx（永续句柄 + options 句柄，可带代理）
  → 初始化 SQLite 核心表
  → register_trade_records_api
  → register_instance_dashboard_routes   # 仪表盘缓存线程
  → install_account_ledger               # 账本同步线程
  → register_instance_settings_routes
  → start_backup_scheduler               # 定时备份线程
  → install_sim_trading                  # 模拟模式 + hooks
  → install_options_trading              # 期权路由 + options-monitor
  → install_options_review
  → install_instance_data_stats          # 资金采样线程
  → register_hub_bridge_routes
  → register_embed_routes                # /embed + live push
  → __main__: key-monitor 后台线程 + app.run(threaded=True)
```

### 4.2 期权模块装配（要点）

`install_options_trading`（`lib/options/options_register.py`）：

1. `_build_cfg(app_module)`：注入 DB、交易所、预算、报价/下单回调等。  
2. `register_options_routes`：页面与 `/api/options/*`。  
3. `_register_options_hub_bridge`：把 `options_snapshot_fn` 等写入 `app.config["HUB_CTX"]`。  
4. `_start_monitor_thread`：若 `OKX_OPTIONS_ENABLED`，拉起 `options-monitor`。

---

## 5. 运行时架构

### 5.1 进程模型

| 单元 | 数量 | 说明 |
|------|------|------|
| PM2 应用 `crypto_okx` | 1 | `python app.py`，`PYTHONPATH` 指向仓库根 |
| Flask 请求线程 | 多 | `threaded=True` |
| 守护线程 | 多个 | 见下表（均为 daemon） |

### 5.2 守护线程一览

| 线程（逻辑名） | 启动位置 | 职责 |
|----------------|----------|------|
| `background_task` / 关键位监控 | `app.py` `__main__` | 按 `MONITOR_POLL_SECONDS` 轮询关键位规则 |
| `options-monitor` | `options_register` | 目标位平仓、翻倍出场、条件单 tick、持仓同步、卖回扫尾 |
| `okx-backup-scheduler` | `backup_lib` | 定时备份 |
| `account-ledger-okx` | `account_ledger` | 交易所资金流水同步 |
| `instance-dashboard-poll` | dashboard cache | 仪表盘数据缓存 |
| `instance-cash-sample` | data stats | 资金样本 |
| `instance-live-push` | embed live | SSE/推送类 |

短生命周期线程：日记/复盘异步出图（`journal-chart-*`、`options-review-chart-*`）。

### 5.3 配置三层

```text
① .env 文件（启动 load + env 页写入）
② os.environ（进程环境）
③ SQLite app_runtime_settings
     · trading.mode = sim | live
     · display.*     导航显示偏好
     · env.<KEY>     热更新覆盖（runtime_config_lib）
```

读取顺序（热更场景）：运行时覆盖 → 环境变量 → 代码默认（`env_ui_manifest._RUNTIME_ENV_DEFAULTS`）。  
部分键改后需 **保存并重启**（见 `env_schema` 的 restart 标记）。

---

## 6. 分层架构

```text
┌──────────────────────────────────────────────────────────┐
│ 表现层  Jinja 模板 + vanilla JS（options_panel.js 等）     │
├──────────────────────────────────────────────────────────┤
│ 接入层  Flask routes（options_register / hub / settings） │
├──────────────────────────────────────────────────────────┤
│ 领域编排  coin_open / close_exec / cond_order / monitor   │
│           account_pnl / stats / review                    │
├──────────────────────────────────────────────────────────┤
│ 基础设施  okx_options_lib(ccxt) · SQLite · sim broker     │
│           env_file · wechat_notify · backup               │
└──────────────────────────────────────────────────────────┘
```

| 层 | 代表路径 | 职责边界 |
|----|----------|----------|
| 表现 | `lib/options/templates/*`、`lib/common/static/options_*.js` | 交互、轮询、展示口径 |
| 接入 | `options_register.py`、`hub_bridge_register.py`、`instance_settings_register.py` | HTTP、鉴权、参数归一 |
| 编排 | `options_coin_open_lib.py`、`options_close_exec_lib.py`、`options_monitor_lib.py` | 多步业务流程、状态机 |
| 领域规则 | `options_margin_mode_lib.py`、`options_close_gate_lib.py`、`options_account_pnl_lib.py` | 预算、门控、结算真源 |
| 基础设施 | `okx_options_lib.py`、`options_db.py`、`sim/*` | IO 与持久化 |

---

## 7. 核心业务技术实现

### 7.1 币本位开仓流水线

**入口：** `POST /api/options/open` → `open_coin_option_buy_full`  
**尺寸归一：** `_normalize_size_mode`（币本位保留 `budget_full` / `compound_full`；USDC 遗留才落到 `sheets`）

```text
门禁（模式 / 条件单锁 / 持仓上限 / 可卖币拒开）
  → compute_coin_budget_usdt + plan_coin_open_by_budget
  → fetch_trading_usdt → trading_usdt_before
  → spot_market_buy_coin_with_usdt（× SPOT_BUY_BUFFER）
       → options_spot_bridge = bought*
  → place_option_limit_order（IOC @ 卖一）+ wait fill
       失败 → 回滚卖币
       成功 → bridge=holding，写入 options_trades(open, pnl_settled=0)
  → 可选 upsert 目标位 / 翻倍出场 / 企微通知
```

关键文件：

- `lib/options/options_coin_open_lib.py`  
- `lib/options/options_spot_bridge_lib.py`  
- `lib/options/options_margin_mode_lib.py`  
- `lib/options/options_position_limit_lib.py`  
- `lib/options/options_account_pnl_lib.py`

### 7.2 平仓与自动出场

| 通道 | 实现 | 门控 |
|------|------|------|
| 手动 / Hub 全平 | `close_option_by_bid1`（`require_recycle_gate=False`） | 流动性 |
| 目标位 | `run_options_target_closes` → `close_option_by_bid_depth` | `options_close_gate_lib`（倍数 + 持续秒数） |
| 翻倍出场 | `run_options_profit_exits` → `close_option_by_bid_profit_exit` | 回收 ≥ 权利金×(1+mult) |

平仓后：`settle_closed_pnl`（币/费用侧）→ `maybe_sell_spot_after_close` → `try_settle_after_sellback`：

```text
realized_pnl_usdt = trading_usdt_after − trading_usdt_before
pnl_settled = 1   # 冻结，业务路径不再改写
```

### 7.3 监控循环

`options_monitor_loop`（`options_monitor_lib.py`）周期性执行，大致包括：

- 同步交易所持仓 ↔ 本地 `options_trades`（纠偏误关仓等）  
- 跑目标位 / 翻倍 / 条件单 tick  
- 平仓后卖回扫尾、推动账户结算  
- 历史盈亏回填（**跳过已冻结 U**）

轮询间隔受期权相关 poll env / 内部 sleep 控制；与关键位监控线程相互独立。

### 7.4 模拟盘技术实现

| 组件 | 文件 | 作用 |
|------|------|------|
| 模式 | `sim/mode_lib.py` | `trading.mode` ∈ {sim, live}；启动默认 `SIM_DEFAULT_MODE` |
| 撮合 | `sim/broker_lib.py` | `SimBroker`：公开买卖一进本地钱包/仓位 |
| 注入 | `sim/hooks.py` | `apply_sim_hooks` / `patch_options_cfg`：把下单、划转等切到模拟实现 |
| 表 | `sim/db_lib.py` | `sim_wallets`、`sim_option_positions`、`sim_ledger_entries` 等 |

实盘闸门：`LIVE_TRADING_ENABLED`；模拟下即使有密钥也不应向交易所发真实期权单（由 hook 拦截）。

### 7.5 复盘与统计（只读结算真源）

```text
options_trades（closed + settled）
  → review sync → options_review_*
  → stats：compute_options_stats_auto / header_options_stats_for_window
```

- 复盘：`options_review_lib.py` + `options_review_register.py`  
- 统计：`options_stats_lib.py`  
- 规则：未 `pnl_settled` 不计已实现；有账户快照的新单只读冻结 U  

---

## 8. 交易所集成

### 8.1 ccxt 句柄

`app.py` 构建：

- `exchange`：通用 OKX（行情/部分账户）  
- `exchange_options`：`defaultType=option`  

期权细节封装：`lib/exchange/okx_options_lib.py`

| 能力 | 示例 |
|------|------|
| 期权链 | `build_option_chain` |
| 报价 | `quote_option_contract` |
| 下单/撤单/等成交 | `place_option_limit_order`、`wait_option_order_full_fill` |
| 持仓/余额 | `fetch_option_positions`、`fetch_options_balances` |
| 划转 | `transfer_ccy` |
| 流动性 | `option_buy_liquidity_ok`、买一深度裁剪 |

凭证：`OKX_API_KEY` / `SECRET` / `PASSPHRASE`（遗留 `OKX_OPTIONS_API_*` 可回填）。  
代理：`build_okx_ccxt_proxies()` ← `OKX_SOCKS_PROXY`。

### 8.2 账户模式约束

程序现货侧按 **合约模式 + cash** 假设编写；跨币种/组合保证金易触发 `tdMode` / `51010`。详见实盘说明。

---

## 9. 数据模型（SQLite）

单库文件，多模块 `CREATE TABLE IF NOT EXISTS`。

### 9.1 期权核心

| 表 | 用途 |
|----|------|
| `options_trades` | 开平流水；`trading_usdt_before/after`、`realized_pnl_usdt`、`pnl_settled` |
| `options_spot_bridge` | 买币/持币/待卖回/关闭 |
| `options_target_monitors` | 指数目标位 |
| `options_cond_orders` | 中控条件单状态机 |
| `options_exchange_pnl_freeze` | 实盘历史盈亏冻结辅助 |
| `options_transfer_log` / `options_convert_log` | 划转等日志 |
| `options_history_hidden` | 历史隐藏 |

### 9.2 复盘

`options_review_trades`、`options_review_entries`、`options_review_sync_state`、`options_review_hidden`

### 9.3 模拟

`sim_wallets`、`sim_option_positions`、`sim_option_orders`、`sim_ledger_entries` 等

### 9.4 实例壳层

`app_runtime_settings`、`key_monitors`、`trade_records`、`account_ledger_*`、`instance_cash_samples` 等

连接约定：业务路径多处 `sqlite3.connect(DB_PATH, timeout=…)` + `Row` factory；长事务与网络 IO 应拆分，避免「持锁等交易所」导致面板超时（历史踩坑点）。

---

## 10. 鉴权与中控 Bridge

### 10.1 站点登录

| 项 | 实现 |
|----|------|
| 账号 | `APP_USERNAME` / `APP_PASSWORD` |
| Session | `session["logged_in"]`；`APP_SESSION_DAYS`；`FLASK_SECRET_KEY` |
| 装饰器 | `login_required`；`/api/*` 未登录返回 JSON 401 |
| 可关闭 | `APP_AUTH_DISABLED`（仅受信环境） |

为支持中控 iframe：Cookie `SameSite=None` + `Secure`（按配置）。

### 10.2 Hub 鉴权（`lib/hub/hub_bridge_auth.py`）

| 机制 | 用途 |
|------|------|
| `HUB_BRIDGE_TOKEN` | M2M：`X-Hub-Token` 或 `Bearer`；`hmac.compare_digest` |
| 短时 SSO | `/hub_sso?token=` → 建站内 session（TTL ~120s） |
| 长时 embed | `embed_sso`（约 7 天）应对 iframe 第三方 Cookie 限制 |
| 自动生成 | env 页首次打开可 `ensure_hub_bridge_token` 写入 `.env` |
| CSP | `HUB_EMBED_FRAME_ANCESTORS` → `frame-ancestors` |

### 10.3 Hub API 面（`hub_bridge_register.py`）

| 方法 | 路径 | 作用 |
|------|------|------|
| GET | `/api/hub/options/snapshot` | 持仓/资金/条件单/流动性摘要 |
| GET | `/api/hub/options/stats` | 窗口统计 |
| POST | `/api/hub/options/close` | 买一限价**全平** |
| GET/POST | `/api/hub/options/cond_orders` | 条件单 |
| POST | `.../cancel` · `.../exit` | 取消 / 改出场 |
| GET | `/api/hub/version` | 在线与版本 |
| POST | `/api/hub/update` | 远程 pull + PM2 重启 |
| GET | `/api/hub/backup/*` | 备份列表/下载 |

快照构建：`options_hub_lib.build_options_hub_snapshot`。

---

## 11. 前端技术实现

### 11.1 资源加载

`install_common_static` 将 `lib/common/static/` 下白名单文件挂到 `/static/<name>`。  
模板通过 `ChoiceLoader` 合并：`lib/instance/templates`、`lib/options/templates`、`lib/sim/templates` 等。

### 11.2 期权前端模块

| 文件 | 职责 |
|------|------|
| `options_panel.js` | 链、报价、下单尺寸模式、开平仓、轮询 |
| `options_position_cards.js` | 持仓卡 UI |
| `options_expiry_countdown.js` | 到期倒计时 |
| `options_settings.js` | 设置内期权相关 |
| `options_review.js` | 复盘页 |
| `options_data_stats.js` | 统计展示 |
| `hub_embed_auth.js` | 嵌入鉴权辅助 |
| `instance_settings_prefs.js` | 导航显示等偏好 |

交互模式：REST 轮询为主（链/持仓/报价）；无独立 Node 构建步骤。

### 11.3 关键 API 前缀

| 前缀 | 模块 |
|------|------|
| `/api/options/*` | 交易面板 |
| `/api/options/review/*` | 复盘 |
| `/api/sim/*` | 模拟资金 |
| `/api/settings/*` | env/显示/密码等 |
| `/api/hub/*` | 中控 |
| `/api/admin/*` | 重启等 |
| `/embed`、`/hub_sso` | 嵌入与 SSO |

---

## 12. 部署与运维技术点

| 项 | 实现 |
|----|------|
| 进程 | PM2 `ecosystem.config.cjs`，`instances: 1` |
| 更新 | 本机脚本 / 中控 `POST /api/hub/update`（git pull + restart） |
| 备份 | `backup_lib` 定时 + 设置页手动；中控可下载 |
| 代理 | `OKX_SOCKS_PROXY`；SSH 动态转发不由 PM2 托管 |
| 日志 | PM2 日志 + Werkzeug；可静音 access log |
| 健康 | `deploy/lib/doctor.sh`；中控看 `/api/hub/version` |

---

## 13. 关键设计决策（实现层）

| 决策 | 原因 | 落点 |
|------|------|------|
| 单进程 + 多守护线程 | 部署简单、与 SQLite 单写者模型匹配 | PM2 instances=1 |
| 盈亏真源=交易户 USDT 差分 | 与钱包可对账、避免指数重算漂移 | `options_account_pnl_lib` |
| 一次一仓默认 | 差分对账前提 | `OKX_OPTIONS_MAX_ACTIVE_POSITIONS=1` |
| 现货桥表 | 买币/卖回与期权生命周期解耦可重试 | `options_spot_bridge` |
| Sim hook 而非第二套 UI | 同一面板切模拟/实盘 | `sim/hooks.py` |
| Hub Token + SSO 双通道 | 机器调用与 iframe 人机登录分离 | `hub_bridge_auth` |
| 前端无框架 | 运维机交付简单、无构建链 | `lib/common/static` |
| USDC 开仓下线 | 主路径币本位 | margin mode 固定 coin |

---

## 14. 扩展与修改指引

1. **新开仓入口**：必须接条件单锁、持仓上限、可卖币检查、before 快照。  
2. **新统计展示**：只消费 `pnl_settled` 冻结值；勿在展示层重算账户差分。  
3. **新自动平仓**：明确是否走 close_gate；与手动通道权限分开。  
4. **改 env 默认**：同步代码默认、`env_ui_manifest` 文案与 `_RUNTIME_ENV_DEFAULTS`。  
5. **避免在持 DB 锁时调交易所**：网络与写库分阶段，防止面板 API 超时。  
6. **中控协议变更**：同步 `hub_bridge_register`、快照 `version` 与中控仓库解析逻辑。

---

## 15. 关键文件索引

| 主题 | 路径 |
|------|------|
| 入口 | `app.py` |
| 路径常量 | `lib/paths.py` |
| 期权路由/监控启动 | `lib/options/options_register.py` |
| 监控循环 | `lib/options/options_monitor_lib.py` |
| 开仓 | `lib/options/options_coin_open_lib.py` |
| 现货桥 | `lib/options/options_spot_bridge_lib.py` |
| 平仓执行 | `lib/options/options_close_exec_lib.py` |
| 账户结算 | `lib/options/options_account_pnl_lib.py` |
| 条件单 | `lib/options/options_cond_order_lib.py` |
| Hub 快照 | `lib/options/options_hub_lib.py` |
| Hub 路由/鉴权 | `lib/hub/hub_bridge_register.py`、`hub_bridge_auth.py` |
| 交易所 | `lib/exchange/okx_options_lib.py` |
| 模拟 | `lib/sim/register.py`、`hooks.py`、`broker_lib.py` |
| Env UI | `lib/env/env_ui_manifest.py`、`env_schema.py` |
| 静态资源注册 | `lib/instance/instance_static_lib.py` |
| PM2 | `ecosystem.config.cjs` |

---

## 16. 文档关系

```text
使用说明.md          ← 操作员怎么用
实盘说明.md          ← 交易所前置与实盘开关
规格-…盈亏结算.md    ← 盈亏产品规则（真源）
系统分析-期权主链条.md ← 业务功能链与数据流
本文                   ← 软件架构与技术实现
部署文档.md           ← 安装运维
```