feat: scaffold gold_monitor web hub, API, PM2 deploy and docs

2026-10-17 17:43:17 +08:00
commit fb35968a1f
35 changed files with 2080 additions and 0 deletions
@@ -0,0 +1,123 @@
+# 技术文档（gold_monitor）
+
+## 1. 架构
+
+```
+Browser (复盘/管理) ──HTTP:5800──► Flask(gunicorn) + SQLite
+                                         ▲
+Windows exe (通用包+激活) ──API───────────┘
+         │
+         └── MetaTrader5 (本机)
+```
+
+- **不直连数据库**：多机只走 HTTP API。  
+- **通用包 + 首次激活**：下载同一 exe；激活后获得 `token` 绑定 `account_id` / `machine_id`。
+
+## 2. 技术栈
+
+| 层 | 选型 |
+|----|------|
+| Web/API | Flask 3 + Jinja2 |
+| 进程 | gunicorn + PM2 |
+| 存储 | SQLite（`data/gold_monitor.db`） |
+| 前端复盘图 | 自研轻量 canvas 蜡烛图（无 CDN 依赖） |
+| 客户端 | Python/Tk + MetaTrader5（见 `desktop/`，逻辑迁移自既有方案） |
+
+## 3. 主要数据表
+
+| 表 | 用途 |
+|----|------|
+| `accounts` | 交易账户与标注 |
+| `machines` | 机器、指纹、在线时间 |
+| `activations` | 激活码、token、状态 |
+| `trades` | 成交与复盘字段（entry_style / review_note / snapshot_json） |
+| `bars` | K 线缓存（symbol+timeframe+ts 唯一） |
+
+## 4. HTTP API
+
+### 健康检查
+
+`GET /health` → `{ ok, service, port }`
+
+### 激活
+
+`POST /api/v1/activate`
+
+```json
+{
+  "code": "xxxx",
+  "fingerprint": "stable-machine-id",
+  "machine_name": "书房PC"
+}
+```
+
+响应：`{ ok, token, account_id, machine_id, public_base }`
+
+### 心跳
+
+`GET /api/v1/ping`  
+Header：`X-Device-Token: <token>`
+
+### 上报成交
+
+`POST /api/v1/trades`  
+Header：`X-Device-Token`
+
+```json
+{
+  "ticket": "2700219994",
+  "symbol": "XAUUSDm",
+  "side": "buy",
+  "volume": 0.1,
+  "open_price": 4175.02,
+  "close_price": 4178.10,
+  "open_time": 1729000000,
+  "close_time": 1729001000,
+  "profit": 12.5,
+  "sl": 4170.0,
+  "tp": 4190.0,
+  "entry_style": "",
+  "snapshot": { "m15_dir": 1, "m1_engulf": true }
+}
+```
+
+### 上报 / 查询 K 线
+
+`POST /api/v1/bars`（需 token）
+
+```json
+{
+  "symbol": "XAUUSDm",
+  "timeframe": "M15",
+  "bars": [
+    { "ts": 1729000000, "open": 1, "high": 2, "low": 0.5, "close": 1.5, "volume": 0 }
+  ]
+}
+```
+
+`GET /api/v1/bars?symbol=&timeframe=&start=&end=`（需网页登录 Session）
+
+## 5. 安全建议
+
+- 修改默认管理员密码与 `FLASK_SECRET_KEY`  
+- 仅局域网开放 5800；如需外网务必加 HTTPS 反代与强密码  
+- 激活码一次性绑定后状态为 `active`；可在后续版本增加作废接口  
+- token 等同设备凭证，泄露需重新签发  
+
+## 6. 目录与入口
+
+| 路径 | 说明 |
+|------|------|
+| `wsgi.py` | 应用入口 |
+| `app/factory.py` | create_app |
+| `app/routes.py` | 页面与 API |
+| `app/db.py` | SQLite 访问 |
+| `deploy/ecosystem.config.cjs` | PM2 |
+| `deploy/manage.sh` | 交互部署 |
+
+## 7. 后续扩展（规划）
+
+- 客户端完整激活窗与成交/Bars 自动上报（对接 `desktop/`）  
+- 复盘筛选、统计面板、AI 点评（可对齐 crypto_monitor）  
+- PostgreSQL 替换 SQLite（多写高并发时）  
+- Nginx 反代与 HTTPS