# 技术文档（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. 管理员密码

- 表 `settings`：`admin_user` / `admin_password_hash`（Werkzeug hash）  
- 首次启动用 `.env` 的 `ADMIN_PASSWORD` 写入 hash  
- 网页「系统设置」可改密，**不写回 .env**，以数据库为准  

## 8. 客户端（desktop/）

| 文件 | 说明 |
|------|------|
| `gold_order_app.py` | 下单主程序（已迁入） |
| `activation_dialog.py` | 首次激活 UI |
| `hub_client.py` | HTTP 激活/上报 |
| `device_store.py` | `~/.gold_monitor/device.json` |

开仓/平仓成功返回 `(消息, report_dict)`，后台线程上报 trades + 四周期 bars。

## 9. 后续扩展（规划）

- 复盘筛选、统计面板、AI 点评（可对齐 crypto_monitor）  
- PostgreSQL 替换 SQLite（多写高并发时）  
- Nginx 反代与 HTTPS