eth_hedge_sim/docs/代码结构.md

比特骆驼自动化对冲系统 — 代码结构

产品名：比特骆驼自动化对冲系统 · 工程目录：eth_hedge_sim
本文描述目标仓库目录与模块职责。当前阶段以文档为准；业务代码按阶段逐步添加。
可从 crypto_monitor 复制 有用片段到本仓库后改造；禁止修改 现网仓库内文件。

---

1. 根目录总览

eth_hedge_sim/                   # 产品：比特骆驼自动化对冲系统
├── README.md
├── .gitignore
├── .env.example                 # 策略机示例；真 .env 不上库
├── .env.control.example         # 中控示例；真 .env.control 不上库
├── requirements.txt
├── docs/
│   ├── 开发方案.md
│   ├── 代码结构.md              # 本文件
│   ├── 中控Fleet说明.md         # 本地中控安装 / 配对 / 监控
│   └── 更新说明.md
├── deploy/                      # 策略机部署 + manage.sh 菜单
│   ├── manage.sh                # 1策略机 / 2中控 / 4更新策略 / 5更新中控
│   ├── ecosystem.config.cjs
│   └── pull_and_restart.sh
├── backend/                     # 策略机 API
│   └── app/api/fleet.py         # 中控专用：status/start/pause/update/issue-login
├── frontend/                    # 策略机 Web
├── control/                     # 本地中控（独立进程 :5160）
│   ├── backend/app/             # FastAPI：机器清单、Token、代理启停/更新
│   ├── frontend/                # 监控区 + 系统设置（Tab）
│   └── deploy/
│       ├── ecosystem.config.cjs # PM2 eth-hedge-control
│       └── update.sh
└── scripts/
    ├── deploy_remote.py         # SSH 更新策略机
    └── deploy_control.py        # SSH/本机更新中控

中控详细用法见 中控 Fleet 说明。

---

1b. 中控模块职责（control/）

路径	职责
control/backend/app/main.py	中控入口，托管前端 dist
control/backend/app/api/nodes.py	机器 CRUD、探活、启停/更新/免密登录 URL
control/backend/app/api/auth_routes.py	登录、改密、局域网免登、login-meta
control/backend/app/envfile.py	.env.control 补缺（不覆盖已有值）
control/backend/app/lan.py	私网 IP 判断
control/frontend/src/pages/Monitor.tsx	监控卡片 / 详情弹层
control/frontend/src/pages/Settings.tsx	账户 / 添加机 / 列表 Tab

策略机侧配对接口：backend/app/api/fleet.py + 设置页「中控 API Token」。

---

1. 根目录总览（策略机为主，续）

eth_hedge_sim/
├── backend/                     # API + 行情 + 策略 + 本地撮合
│   ├── app/
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── api/                 # HTTP 路由（含 fleet）
│   │   ├── strategy/
│   │   ├── sim/
│   │   ├── live/
│   │   └── models/
│   ├── data/
│   └── tests/
├── frontend/                    # 策略机 Web
│   └── src/pages/
│       ├── Plan.tsx
│       ├── Trades.tsx
│       ├── Stats.tsx
│       └── Settings.tsx         # 含中控 Token
└── ...

下文原「根目录总览」中较旧的骨架示意仍保留模块职责描述；以本节 + 中控说明 为准补充 control/。

---

2. 后端模块职责

2.1 backend/app/market/ — 行情（OKX 实盘只读）

market/
├── okx_rest.py          # 合约列表、到期、启动对齐
├── okx_ws.py            # 永续 + 期权盘口订阅
├── instruments.py       # 解析「次日 16:00」到期、ATM 行权价
├── book_cache.py        # 买一/卖一/深度内存缓存
└── types.py             # Quote / Depth 结构

职责：

• 只拉行情，不调用交易接口。
• 对外提供：永续买卖一、Call/Put 买卖一与深度、标记价。
• 可选：行情快照落盘，供 P4 回放。

可参考现网 OKX WS/REST 实现，复制后改成本模块 API。

2.2 backend/app/sim/ — 本地模拟

sim/
├── matcher.py           # 撮合：永续市价；期权吃买卖一；滑点=1×f；双边手续费
├── ledger.py            # 虚拟资金、占用、流水
├── liquidity.py         # 买一深度是否覆盖 2 ETH
└── pricing.py           # 成交价公式（含 f）

成交价口径（与开发方案一致）：

腿	动作	基准	成交价
永续	开多 / 平空	卖一	基准 × (1+f)
永续	开空 / 平多	买一	基准 × (1-f)
期权	买入	卖一	基准 × (1+f)
期权	卖出	买一	基准 × (1-f)

另扣：手续费 = 名义 × f。

2.3 backend/app/strategy/ — 自动对冲

strategy/
├── clock.py             # 业务窗：D 16:00～D+1 08:00；次数≤3
├── signal.py            # Call 卖一 vs Put 卖一 → 方向
├── exits.py             # 权利金覆盖 / 30 点
├── sizing.py            # 永续 1 ETH、期权 2 ETH（写死）
├── group.py             # 组 ID：G-YYYYMMDD-NN
└── engine.py            # 状态机：空仓→开仓→盯盘→全平→下一组

状态机要点：

• 同时最多 1 组。
• 平完才允许下一组；达 3 次或过 08:00 则停开。
• 每组锁定 initial_premium。

2.4 backend/app/live/ — 实盘（P5）

live/
├── okx_trade.py         # 永续市价单；期权吃一对应下单
└── adapter.py           # 与 sim.matcher 相同接口，便于切换

默认关闭；仅 MODE=LIVE 且设置页确认后启用。

2.5 backend/app/api/ + ws/

api/
├── plan.py              # 当前组、策略启停、紧急全平
├── trades.py            # 组列表、组成交明细
├── stats.py             # 汇总统计
└── settings.py          # 读写配置（脱敏）

ws/
└── push.py              # market.snapshot / group.updated / fill.created / strategy.state

2.6 backend/app/models/ — 数据

建议表：

表	用途
groups	组头：方向、开平时间、初始权利金、平仓原因、盈亏
fills	成交：腿、价、量、滑点、手续费
positions	当前仓（最多一组两腿）
ledger_entries	资金流水
settings	配置 KV
market_ticks	可选行情快照

---

3. 前端结构

frontend/src/pages/
├── Plan.tsx       # 自动对冲计划（主盘）
├── Trades.tsx     # 交易记录（按组）
├── Stats.tsx      # 统计
└── Settings.tsx   # 系统设置

frontend/src/components/
├── Nav.tsx                # 四项导航
├── GroupBadge.tsx         # 组 ID + 状态色
├── PerpOrderBook.tsx      # 永续盘口
├── OptionOrderBook.tsx    # Call/Put；卖一选向高亮、买一平仓
├── PositionBar.tsx        # 1 ETH + 2 ETH、浮盈、触发进度
└── EquityChart.tsx        # 统计页曲线

导航文案固定：

1. 自动对冲计划
2. 交易记录
3. 统计
4. 系统设置

---

4. 部署相关文件

目标环境：Ubuntu 22.04 + PM2。目录默认 /opt/eth_hedge_sim。

4.1 deploy/ecosystem.config.cjs（示意）

module.exports = {
  apps: [
    {
      name: 'eth-hedge-api',
      cwd: '/opt/eth_hedge_sim/backend',
      script: 'uvicorn',
      args: 'app.main:app --host 0.0.0.0 --port 8100',
      interpreter: 'python3',
      env: { MODE: 'SIM' },
    },
    // 若前端独立静态服务可再加 eth-hedge-web；也可由 nginx 指到 frontend/dist
  ],
};

4.2 deploy/pull_and_restart.sh（原则）

• 仅 cd /opt/eth_hedge_sim && git pull
• 安装依赖 / frontend build
• pm2 startOrReload deploy/ecosystem.config.cjs --update-env
• 禁止 pm2 restart all，禁止 调用现网 crypto_monitor 的部署脚本

---

5. 进程与端口（建议，可改）

服务	端口	PM2 名
API + WS	8100	eth-hedge-api
前端（若独立）	8101 或 nginx 反代	eth-hedge-web

与现网端口、进程名全部错开。

---

6. 配置与密钥

.env.example          # 提交到 git
.env                  # 仅服务器 / 本机，gitignore

关键项：

• MODE=SIM|LIVE
• OKX_API_KEY / SECRET / PASSPHRASE（SIM 阶段只读权限即可）
• FEE_RATE（滑点自动 = 1 × FEE_RATE）
• INITIAL_EQUITY
• MAX_ROUNDS=3
• OPEN_HHMM=16:00 / STOP_OPEN_HHMM=08:00
• TZ=Asia/Shanghai

---

7. 从现网复制代码时的规则

允许	禁止
复制 OKX 行情订阅、签名、深度解析到本仓库	修改现网 crypto_monitor 仓库内任何文件
复制「买一流动性检查」思路后重写	把本项目塞进现网 monorepo 一起 PM2
新建本仓库的 .env	默认使用现网交易 Key 做模拟（模拟不需要交易权限）

复制后在本仓库内自由修改；现网保持原样。

---

8. 建议落地顺序（与开发方案分期对应）

1. 建 git 远程 → clone 到本机该目录与服务器 /opt/eth_hedge_sim
2. P0：market/ 通行情
3. P1：sim/ 手动开平
4. P2：strategy/ 自动化
5. P3：frontend/ 四页
6. deploy/ PM2 上独立机
7. P5：live/ 实盘开关

---

9. 当前仓库已有文件

eth_hedge_sim/
└── docs/
    ├── 开发方案.md
    └── 代码结构.md

负责人创建远程仓库后，将本目录作为首批提交即可；业务代码按上表目录逐步添加。