first commit

开发方案.md

@@ -0,0 +1,383 @@
+# 比特骆驼行情采集分析 — 开发方案
+
+> **独立仓库**，与 `eth_hedge_sim`（策略 / 中控）**无代码共用、无进程共用、无交易密钥共用**。  
+> 本系统只做：**行情采集 → 落库 → 分析统计 → 只读展示 / API**。  
+> **不下单、不持仓、不替代策略选约。**  
+> Git 仓库由负责人在 `git.bz121.com` 创建；本目录为方案与后续工程落点。
+
+---
+
+## 1. 命名与定位
+
+| 项 | 约定 |
+|----|------|
+| **产品名** | **比特骆驼行情采集分析** |
+| **项目名称（对外）** | 比特骆驼行情采集分析系统 |
+| **仓库名称 / 工程名** | `market_intel` |
+| **Git 地址（拟）** | `https://git.bz121.com/dekun/market_intel.git` |
+| **安装目录（生产）** | `/opt/market_intel` |
+| **部署操作系统** | **Ubuntu 22.04 LTS**（与策略仓一键脚本一致） |
+| **运行方式** | **Docker Compose**（采集 + API + Web 同栈编排） |
+| **一键入口** | `deploy/manage.sh` 交互菜单（对齐 `eth_hedge_sim`） |
+
+### 1.1 硬边界
+
+- **只读行情**：REST / WebSocket；禁止任何交易类 API。
+- **与策略解耦**：策略机挂了，本系统仍可继续采；本系统挂了，策略仍可独立交易。
+- **第一期标的**：ETH（OKX 指数 + ETH-USD_UM 期权盘口）；架构预留多币种 / 多所，但实现标准先钉死 OKX ETH。
+- **时区**：统计与「日 / 周 / 月」切分一律 **Asia/Shanghai**。
+
+### 1.2 核心分析目标（作战地图数据底座）
+
+1. **期权杠杆 × 日内时段**  
+   口径：`杠杆 = 标的指数 ÷ 期权卖一`（与策略选约门限一致）。  
+2. **该时段 → 期权到期 的波动点数**  
+   口径：到期时刻指数 − 该时段代表指数（可同时存带符号与绝对值）。  
+3. **范围**：按 **日 / 周 / 月** 过滤样本，横轴均为 **日内时段桶**（默认 1 小时）。
+
+---
+
+## 2. 实现标准
+
+### 2.1 技术栈
+
+| 层 | 标准 |
+|----|------|
+| 语言 | Python 3.11+（采集 / API / 聚合） |
+| Web API | FastAPI |
+| 前端 | React + Vite（只读看板：采集状态、时段图、日周月切换） |
+| 数据库 | 第一期 **SQLite**（volume 持久化）；上量后可换 Postgres，表结构先按可迁移设计 |
+| 容器 | Docker + Docker Compose v2 |
+| 反向代理（可选） | 同 Compose 内 Caddy/Nginx，或宿主机已有反代 |
+| 配置 | 仓库根 `.env`（密钥、交易所、采样间隔、端口）；**已有非空值不覆盖** |
+
+### 2.2 代码与工程规范
+
+- 仓库根英文名固定 `market_intel`；文档可用中文。
+- 配置项集中、可环境变量覆盖；禁止把 API Key 写进镜像层。
+- 采集与 API **可同容器或分服务**；Compose 内用服务名互访。
+- 所有时间戳存 **UTC ms**；展示与「自然日」按上海转换。
+- 杠杆 / 波动口径写进代码常量 + 本文档，变更需改版本号与迁移说明。
+- 日志：结构化或按日滚动；脱敏（不打完整密钥）。
+- 测试：采集解析、杠杆计算、时段聚合、到期回填 有单元测试。
+
+### 2.3 采集标准（第一期）
+
+| 项 | 标准 |
+|----|------|
+| 交易所 | OKX（只读） |
+| 指数 | ETH-USD 指数（或与策略一致的 index） |
+| 期权 | 最近合资格到期的 ATM Call + ATM Put（规则文档化：最接近指数的行权价） |
+| 杠杆采样间隔 | 默认 **30s**（可配 15–120s） |
+| 指数采样 | 可与杠杆同频，或单独 **60s** |
+| 字段最小集 | `ts_ms, exchange, underlying, expiry_ymd, strike, side(C/P), index_px, ask, bid, ask_sz, bid_sz, leverage, inst_id` |
+| 失败策略 | 单次失败记日志并跳过；连续失败告警（可选企微，后期） |
+
+### 2.4 统计标准
+
+| 项 | 标准 |
+|----|------|
+| 时段桶 | 默认 **1 小时**（0–23，上海）；可扩展 30 分钟 |
+| 日 | 上海自然日 `YYYY-MM-DD` |
+| 周 | **滚动近 7 个上海自然日**（第一期）；后期可加自然周 |
+| 月 | **滚动近 30 日** 或自然月（设置可选，默认滚动 30 日） |
+| 杠杆聚合 | 桶内：样本数、均值、中位数、P25/P75、≥`min_leverage` 占比 |
+| 波动点数 | 到期后回填；桶内：均值/中位/分位；同时提供 **signed** 与 **abs** |
+| 未到期 | API 标记 `pending_expiry=true`，不假装有完整「到到期」分布 |
+
+### 2.5 安全与权限
+
+- 仅行情只读 Key（若需要）；无交易权限。
+- Web / API 默认需登录或 Token（对齐策略仓简单鉴权即可）。
+- 局域网部署时可绑 `127.0.0.1` / 内网 IP；公网必须 HTTPS + 强密码。
+
+---
+
+## 3. 系统架构
+
+```text
+                    ┌─────────────────────────────────────┐
+                    │  market_intel（本仓库 · Docker）       │
+  OKX 行情 ────────►│  collector → SQLite/DB               │
+  (REST/WS)         │  analytics（日/周/月 · 时段聚合）      │
+                    │  api + web（只读看板）                 │
+                    └─────────────────────────────────────┘
+                                      │
+                                      │ 可选：只读 API
+                                      ▼
+                         人工浏览器 / 其它系统（后期）
+```
+
+- **不**嵌入 `eth_hedge_sim` 进程。  
+- 后期若中控要展示，由中控 **HTTP 调用本系统 API**，本仓仍独立演进。
+
+---
+
+## 4. 代码结构（目标仓库）
+
+```text
+market_intel/
+├── README.md
+├── 开发方案.md                 # 可从本文件迁入 docs/
+├── .env.example
+├── .gitignore
+├── docker-compose.yml          # 一键编排入口
+├── Dockerfile                  # API + 采集（或多阶段）
+├── requirements.txt
+├── deploy/
+│   ├── manage.sh               # 交互式菜单（curl | bash）
+│   ├── bootstrap.sh            # 缺 git/docker 时引导
+│   └── lib/
+│       ├── common.sh           # 日志、读入、路径、.env 合并
+│       ├── install.sh          # 一键部署（clone + compose up）
+│       ├── update.sh           # git pull + compose build/up
+│       └── uninstall.sh        # 停容器；可选保留 data volume
+├── apps/
+│   ├── collector/              # 行情采集进程
+│   │   ├── __init__.py
+│   │   ├── main.py             # 入口：循环 / WS
+│   │   ├── okx_rest.py
+│   │   ├── okx_ws.py
+│   │   └── selectors.py        # ATM / 到期选择
+│   ├── api/                    # FastAPI
+│   │   ├── main.py
+│   │   ├── routes/
+│   │   │   ├── health.py
+│   │   │   ├── samples.py      # 原始/明细（调试）
+│   │   │   └── stats.py        # 日周月 · 杠杆 · 波动
+│   │   └── auth.py
+│   └── worker/                 # 可选：到期回填、日终聚合
+├── packages/
+│   ├── db/                     # schema、迁移、repository
+│   ├── domain/                 # option_leverage、bucket、move_points
+│   └── config/                 # settings from env
+├── web/                        # React 看板
+│   ├── package.json
+│   └── src/
+│       ├── pages/
+│       │   ├── Dashboard.tsx   # 采集心跳、最新杠杆
+│       │   └── OpsMap.tsx      # 作战地图：杠杆 + 波动 · 日/周/月
+│       └── api/
+├── data/                       # 本地/挂载：SQLite（.gitignore 内容）
+├── scripts/
+│   ├── smoke_collect.py
+│   └── backfill_index.py       # 可选：历史指数回填波动
+└── tests/
+    ├── test_leverage.py
+    ├── test_buckets.py
+    └── test_move_points.py
+```
+
+> 实现时可把 `apps/` 收成单包 `src/market_intel/`，但 **deploy / docker / web / 采集与 API 分离** 的边界保持不变。
+
+---
+
+## 5. 数据模型（摘要）
+
+### 5.1 `option_quotes`（杠杆明细）
+
+| 字段 | 说明 |
+|------|------|
+| id | 自增 |
+| ts_ms | UTC |
+| exchange | `okx` |
+| inst_id | 合约 ID |
+| expiry_ymd | `YYMMDD` |
+| strike | 行权价 |
+| side | `C` / `P` |
+| index_px | 指数 |
+| ask / bid | 卖一 / 买一 |
+| ask_sz / bid_sz | 可选 |
+| leverage | `index_px / ask`（ask>0） |
+
+### 5.2 `index_ticks`（指数明细）
+
+| 字段 | 说明 |
+|------|------|
+| ts_ms | UTC |
+| underlying | `ETH` |
+| index_px | 指数 |
+
+### 5.3 `expiry_settlements`（到期锚点）
+
+| 字段 | 说明 |
+|------|------|
+| expiry_ymd | 到期日 |
+| settle_ts_ms | 到期时刻（OKX：UTC 08:00） |
+| settle_index_px | 结算/到期指数 |
+
+波动点数：对历史某桶代表时刻 \(t\)，  
+`move = settle_index_px - index_at(t)`（同 `expiry_ymd`）。
+
+---
+
+## 6. API 约定（第一期）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/health` | 存活；可选返回采集延迟 |
+| GET | `/api/stats/leverage` | `range=day\|week\|month` + 日期；返回各时段桶聚合 |
+| GET | `/api/stats/move_points` | 同上；返回时段→到期波动 |
+| GET | `/api/stats/ops-map` | 一次返回杠杆 + 波动（看板主接口） |
+| GET | `/api/meta/latest` | 最新一条 Call/Put 杠杆、采集时间 |
+
+查询参数统一：`range`、`date`（锚点日）、`side=C|P|both`、`bucket_minutes=60`。
+
+---
+
+## 7. Docker 运行标准
+
+### 7.1 服务划分（Compose）
+
+| 服务名 | 职责 | 说明 |
+|--------|------|------|
+| `collector` | 写库 | 重启策略 `unless-stopped` |
+| `api` | FastAPI + 静态前端（或挂 `web` 构建产物） | 默认端口 **5170**（可配，避开策略 5155 / 中控 5160） |
+| `db` | 第一期可省略（SQLite 挂 volume） | 后期 Postgres 再加 |
+
+```yaml
+# docker-compose.yml 示意（实现时落地）
+services:
+  collector:
+    build: .
+    command: ["python", "-m", "apps.collector.main"]
+    env_file: .env
+    volumes:
+      - mi_data:/app/data
+    restart: unless-stopped
+  api:
+    build: .
+    command: ["uvicorn", "apps.api.main:app", "--host", "0.0.0.0", "--port", "5170"]
+    env_file: .env
+    ports:
+      - "${MI_PORT:-5170}:5170"
+    volumes:
+      - mi_data:/app/data
+    depends_on:
+      - collector
+    restart: unless-stopped
+volumes:
+  mi_data:
+```
+
+### 7.2 本地开发（非必须 Docker）
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+python -m apps.collector.main          # 终端 1
+uvicorn apps.api.main:app --reload     # 终端 2
+cd web && npm i && npm run dev         # 终端 3
+```
+
+**生产标准路径以 Docker Compose 为准。**
+
+---
+
+## 8. 一键部署（对齐 eth_hedge_sim）
+
+### 8.1 新机器（免克隆）
+
+```bash
+curl -fsSL https://git.bz121.com/dekun/market_intel/raw/branch/main/deploy/manage.sh | bash
+```
+
+要求：Ubuntu 22.04；脚本内检测并安装 **Git、Docker、Docker Compose 插件**（已有则跳过）。
+
+### 8.2 已安装
+
+```bash
+bash /opt/market_intel/deploy/manage.sh
+```
+
+### 8.3 交互菜单（实现标准）
+
+与策略仓 `deploy/manage.sh` 同级体验：**数字选项 + 读 `/dev/tty`**，支持 `curl | bash`。
+
+| 选项 | 作用 |
+|------|------|
+| **1) 一键部署** | 检测 Docker → clone 到 `/opt/market_intel` → 生成/补全 `.env`（已有非空不覆盖）→ `docker compose up -d --build` → 健康检查 |
+| **2) 更新** | `git pull` + `compose build/up`；保留 `.env` 与 data volume |
+| **3) 停止** | `docker compose stop` |
+| **4) 启动** | `docker compose start` / `up -d` |
+| **5) 查看状态** | `compose ps` + `/health` |
+| **6) 一键卸载** | 停容器；询问是否删除 data volume；备份 `.env` 到 `/root/backups/market_intel/`；按确认删除 `/opt/market_intel` |
+| **0) 退出** | — |
+
+已存在安装目录时，选项 1 进入子菜单：**取消 / 修复（保留 .env 与数据）**，行为对齐策略仓 `install.sh`。
+
+### 8.4 `.env` 交互补全（首次部署）
+
+脚本可交互询问（有默认值，回车采用默认）：
+
+- `OKX` API Key / Secret / Passphrase（只读；可留空若仅用公开行情）
+- `MI_PORT`（默认 `5170`）
+- `SAMPLE_INTERVAL_SEC`（默认 `30`）
+- `MIN_OPTION_LEVERAGE`（统计达标线，默认 `100`）
+- 管理员密码 / `AUTH_SECRET`
+
+原则：**文件中已有非空值不覆盖**（对齐中控 `.env.control` 行为）。
+
+### 8.5 部署后验收
+
+1. `curl -fsS http://127.0.0.1:5170/health` 返回 ok  
+2. 等待 ≥1 个采样周期后，库中有 `option_quotes` 行  
+3. 打开 Web 看板能看到最新杠杆  
+4. `manage.sh` → 更新 → 容器重建后数据 volume 仍在  
+
+---
+
+## 9. Web 看板（第一期页面）
+
+| 页面 | 内容 |
+|------|------|
+| 总览 | 采集是否正常、延迟、当前 ATM Call/Put 杠杆 |
+| 作战地图 | 切换 **日 / 周 / 月**；上图时段杠杆；下图时段→到期波动点数 |
+| 设置（简） | 只读展示当前采样参数（改参走 `.env` + 更新重启） |
+
+UI 要求：暗色可与策略仓风格接近，但 **独立品牌标题「行情采集分析」**，避免与对冲策略页混淆。
+
+---
+
+## 10. 分期计划
+
+| 阶段 | 交付 |
+|------|------|
+| **P0** | 仓库骨架、Docker Compose、manage.sh 菜单、健康检查 |
+| **P1** | OKX 指数 + ATM Call/Put 采样落库 |
+| **P2** | `/api/stats/leverage` 日周月；Web 作战地图杠杆图 |
+| **P3** | 到期回填 + 波动点数统计与下图 |
+| **P4** | 鉴权加固、企微采集异常推送、可选历史指数回填 |
+| **P5** | （可选）中控只读嵌入；多 underlying |
+
+---
+
+## 11. 与 `eth_hedge_sim` 的关系（再强调）
+
+| | `eth_hedge_sim` | `market_intel`（本仓） |
+|--|-----------------|------------------------|
+| 职责 | 对冲交易 / 中控运维 | 行情采集与统计分析 |
+| 运行 | PM2（现状） | **Docker Compose** |
+| 端口 | 5155 / 5160 | **5170**（默认） |
+| 密钥 | 可含交易权限 | **仅只读行情** |
+| 依赖 | 互不依赖 | 互不依赖 |
+
+---
+
+## 12. 验收清单（方案级）
+
+- [ ] 仓库名 `market_intel`，产品名「比特骆驼行情采集分析」  
+- [ ] `curl | bash` 出交互菜单，可一键部署 / 更新 / 卸载  
+- [ ] 全程 Docker 运行，数据落 volume  
+- [ ] 杠杆口径 = 指数 ÷ 卖一；时段统计支持日 / 周 / 月  
+- [ ] 波动点数 = 时段指数 → 到期指数；未到期显式标记  
+- [ ] 零交易 API；与策略仓进程隔离  
+
+---
+
+## 13. 文档修订
+
+| 日期 | 说明 |
+|------|------|
+| 2026-07-31 | 初稿：独立仓、Docker、交互式一键部署、作战地图数据标准 |