# eth_hedge_sim — 代码结构

> 本文描述目标仓库目录与模块职责。当前阶段以文档为准；业务代码按阶段逐步添加。  
> 可从 `crypto_monitor` **复制** 有用片段到本仓库后改造；**禁止修改** 现网仓库内文件。

---

## 1. 根目录总览

```text
eth_hedge_sim/
├── README.md
├── .gitignore
├── .env.example                 # 无密钥的示例；真 .env 不上库
├── package.json                 # 若前端/Node；或改用 Python 则 requirements.txt
├── requirements.txt             # 后端若用 Python
├── docs/
│   ├── 开发方案.md              # 业务与部署方案（本文档姐妹篇）
│   └── 代码结构.md              # 本文件
├── deploy/
│   ├── ecosystem.config.cjs     # PM2：仅本项目进程
│   └── pull_and_restart.sh      # git pull + 构建 + pm2 reload（不碰现网）
├── backend/                     # API + 行情 + 策略 + 本地撮合
│   ├── app/
│   │   ├── main.py              # 或 index.ts：进程入口
│   │   ├── config.py
│   │   ├── api/                 # HTTP 路由
│   │   ├── ws/                  # 向前端推送
│   │   ├── market/              # OKX 只读行情
│   │   ├── strategy/            # 自动对冲状态机
│   │   ├── sim/                 # 本地撮合与账本
│   │   ├── live/                # 实盘适配器（后期，默认关闭）
│   │   ├── models/              # DB 模型 / schema
│   │   └── services/            # 组、统计、设置等应用服务
│   ├── data/                    # 本地 SQLite 等（gitignore 数据文件）
│   └── tests/
├── frontend/                    # OKX 风格 Web
│   ├── index.html
│   ├── package.json
│   ├── src/
│   │   ├── main.tsx
│   │   ├── App.tsx
│   │   ├── layouts/             # 导航壳
│   │   ├── pages/
│   │   │   ├── Plan.tsx         # 自动对冲计划
│   │   │   ├── Trades.tsx       # 交易记录
│   │   │   ├── Stats.tsx        # 统计
│   │   │   └── Settings.tsx     # 系统设置
│   │   ├── components/          # 盘口、组标识、持仓条等
│   │   ├── api/                 # 调后端
│   │   └── styles/              # OKX 深色交易台风
│   └── dist/                    # 构建产物（可部署由 API 托管或 nginx）
└── scripts/                     # 运维/一次性工具（可选）
    └── smoke_market.py          # 只读行情连通性检查
```

技术栈可在开工时二选一（建议尽快定一种，避免双栈）：

- **推荐 A**：后端 Python（FastAPI）+ 前端 React/Vite（与现网 Python 生态接近，便于复制行情代码）。
- **推荐 B**：全 Node（Nest/Express + React）。

下文按 **推荐 A** 描述模块；若选 B，目录名对应平移即可。

---

## 2. 后端模块职责

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

```text
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/` — 本地模拟

```text
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/` — 自动对冲

```text
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）

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

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

### 2.5 `backend/app/api/` + `ws/`

```text
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. 前端结构

```text
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. 部署相关文件

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

```js
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. 配置与密钥

```text
.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 行情订阅、签名、深度解析到本仓库 | 修改 `C:\Users\dekun\Desktop\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. 当前仓库已有文件

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

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