gold_monitor/docs/technical.md

技术文档（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. 主要数据表

表	用途
users	登录用户：role=admin/user，普通用户必绑唯一 account_id
accounts	交易账户与标注（仅管理员创建，禁止自助注册）
machines	机器、指纹、在线时间
activations	激活码、token、状态、created_by 发放人
trades	成交与复盘字段（entry_style / review_note / snapshot_json）
bars	K 线缓存（symbol+timeframe+ts 唯一）

权限：管理员看全部；普通用户复盘/激活码仅限自己的 account_id。激活码可由 admin 与 user 发放（user 仅自己账户）。

4. HTTP API

健康检查

GET /health → { ok, service, port }

激活

POST /api/v1/activate

{
  "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

{
  "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）

{
  "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. 用户与密码

• 表 users：密码为 Werkzeug hash；首次启动用 .env 的 ADMIN_USER / ADMIN_PASSWORD 种子管理员
• 网页「系统设置」改当前用户密码，不写回 .env
• 普通用户由管理员在 /users 创建并绑定账户

8. 客户端（desktop/）

文件	说明
gold_order_app.py	下单主程序；含「打开复盘」→ 浏览器 /login
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