# 功能说明文档

国内期货交易监控复盘系统（Flask + SQLite + PM2）各模块使用说明与技术要点。

---

## 系统概览

| 项目 | 说明 |
|------|------|
| 访问端口 | 默认 `6600` |
| 数据存储 | SQLite `futures.db`（品种、计划、监控、持仓、交易记录、复盘、费率等） |
| 行情来源 | 默认新浪财经（免费）；可选同花顺 iFinD（机构 token） |
| 合约代码 | 同花顺格式（如 `ag2606`、`SR609`、`IF2606`） |
| 主题 | 支持深色 / 浅色切换（页头左侧） |

### 导航结构

| 菜单 | 路径 | 作用 |
|------|------|------|
| 开单计划 | `/plans` | 当日计划录入与历史 |
| 关键位监控 | `/keys` | 关键位突破监控与历史 |
| 持仓监控 | `/positions` | 模拟持仓录入与实时卡片 |
| 交易记录与复盘 | `/records` | 平仓记录 + 复盘上传与历史 |
| 统计分析 | `/stats` | 胜率、手续费、盈亏汇总 |
| 手续费配置 | `/fees` | 本地费率表与倍率 |
| 品种简介 | `/contract` | 合约规格查询 |
| 系统设置 | `/settings` | 资金、微信、改密码 |

---

## 开单计划

**路径**：`/plans`

### 功能

- 制定**当日**开单计划：主力合约、方向、决策区间（上/下沿）、止损、止盈、决策理由。
- 计划状态：`planned`（待触发）→ `active`（已激活）→ `closed` / `expired`。
- 列表**实时现价**与距区间上下沿距离（约 1 秒轮询 `/api/plan_prices`）。

### 触发逻辑（后台线程，约 3 秒）

1. **待触发**：现价进入决策区间 `[下限, 上限]` → 企业微信通知，状态变为「已激活」。
2. **已激活**：持续监控止盈 / 止损；触发后写入 `trade_records`（系统自动止盈止损记录），计划关闭。

### 操作

- 左侧表单添加计划；右侧为进行中计划列表。
- 下方可按日期筛选历史计划。

---

## 关键位监控

**路径**：`/keys`

### 功能

- 监控类型：箱体突破、收敛突破、关键阻力位、关键支撑位。
- 录入：品种、类型、方向、上沿/下沿（阻力/支撑）。
- 列表显示现价、距上沿、距下沿（约 1 秒轮询 `/api/key_prices`）。
- **监控历史**：删除的监控归档，可查看上沿、下沿、归档时间。

### 推送逻辑

| 类型 | 规则 |
|------|------|
| 箱体 / 收敛 | 突破上沿、跌破下沿各推送一次（去重） |
| 阻力 / 支撑 | 单向突破推送一次 |

---

## 持仓监控

**路径**：`/positions`

### 功能

模拟盘持仓管理，与关键位页面分离。

### 持仓录入

| 字段 | 说明 |
|------|------|
| 主力合约 | 品种联想，同花顺代码 |
| 开仓时间 | 与合约、张数同一行，避免标签错位 |
| 张数 | 手数 |
| 成交价格 / 止损 / 止盈 | 用于方向推断与盈亏计算 |

- **方向**：未选手动方向时，根据止损与成交价自动判断（止损低于成交 → 做多，反之做空）。
- **风险比例**：依赖系统设置中的「实盘资金」。

### 实时持仓卡片

约 1 秒轮询 `/api/position_live`，展示：

- 成交价、止损、止盈、盈亏比、标记价、浮盈亏
- **预估手续费**、**扣费后浮盈亏**（按本地费率表估算）
- 保证金、仓位占比、开仓时间、持仓时长、张数
- **平仓**：按现价平仓，写入「交易记录」，并从持仓列表移除

### 平仓 → 交易记录

平仓时自动：

1. 拉取现价作为平仓价；
2. 计算毛盈亏、手续费、净盈亏；
3. 写入 `trade_logs`；
4. 删除 `position_monitors` 对应行。

---

## 交易记录与复盘

**路径**：`/records`（`/trades` 自动跳转到此页）

页面上方为**交易记录**，下方为**复盘上传**与**复盘历史**。

### 交易记录

来源主要为「持仓监控」平仓；字段包括：

| 列 | 说明 |
|----|------|
| 品种 / 类型 / 方向 | 类型多为「持仓监控」 |
| 成交 / 止损 / 止盈 | 开仓时价格 |
| 基数 | 张数 + 保证金 |
| 持仓分钟 | 开平时间差 |
| 盈亏(元) | 毛盈亏（未扣费） |
| 手续费 | 开+平合计（本地费率估算） |
| 净盈亏 | 毛盈亏 − 手续费 |
| 结果 | 止盈 / 止损 / 手动平仓等 |

**修改/核对开关**（小字单行）：开启后可编辑关键字段并「核对修改」保存（标记 `verified`）。

**填入复盘**：跳转本页复盘表单，自动预填品种、方向、价格、时间、盈亏等，并滚动到「复盘上传」区域。

### 复盘上传

手动复盘表单，支持：

- 品种、方向、张数、周期、成交价、止损、止盈、平仓价
- 开仓/平仓时间 → 自动计算持仓时长、初始/实际盈亏比
- 开仓类型、离场触发、行为标签（勾选为情绪单）
- 截图上传；**自动 K 线**（matplotlib 生成复盘图）
- 保存时自动计算**手续费**与**净盈亏**写入 `review_records`

### 复盘历史

- 筛选：本日 / 本周 / 本月 / 自定义日期
- 列表含盈亏、手续费、净盈亏；支持全屏详情弹窗
- 另含「系统自动记录（止盈/止损）」：来自开单计划/关键位触发的 `trade_records`

---

## 统计分析

**路径**：`/stats`

### 监控触发统计（trade_records）

- 总交易、止盈、止损、胜率
- 按品种 / 类型 / 方向分组胜率

### 手续费与盈亏汇总（trade_logs + review_records）

| 指标 | 说明 |
|------|------|
| 累计手续费 | 交易记录 + 复盘记录手续费之和 |
| 毛盈亏合计 | 未扣费盈亏 |
| 净盈亏合计 | 扣费后盈亏 |
| 计费笔数 | 有手续费字段的记录数 |
| 按品种手续费 | 交易记录中各品种累计手续费 |

### 最近交易

展示最近 10 笔 `trade_logs`：毛盈亏、手续费、净盈亏、结果。

---

## 手续费配置

**路径**：`/fees`

模拟盘参考费率，**非期货公司实盘账单**。

### 数据来源

1. **本地 JSON**：`data/fee_rates.json`（首次空库自动加载，已为常见品种写入约 **交易所标准 × 2**）
2. **第三方同步**：`pip install akshare` 后，点击「从第三方同步（AKShare）」
3. **手工编辑**：表格内修改单品种费率并保存

### 倍率

- 设置项「第三方标准费率 × N」，默认 **2**
- 从 AKShare 同步时：拉取参考标准后乘以该倍率写入 `fee_rates` 表
- 已写入表的数值即为当前生效费率，改倍率后需重新同步或手工调整

### 费率字段

| 字段 | 含义 |
|------|------|
| 开仓(元/手) | 固定每手费用 |
| 开仓(比例) | 成交价 × 合约乘数 × 手数 × 比例 |
| 平昨(元/手) / 平昨(比例) | 非当日平仓 |
| 平今(元/手) / 平今(比例) | 当日平仓（部分品种平今更高） |

### 计费规则

- 一笔往返 = **开仓费 + 平仓费**
- 开仓日与平仓日相同 → 用**平今**；否则用**平昨**
- 合约乘数见 `contract_specs.py`，与保证金估算共用

相关代码：`fee_specs.py`（计算）、`fee_sync.py`（AKShare 同步）、`contract_specs.py`（乘数/保证金）。

---

## 品种简介

**路径**：`/contract`

### 功能

查询指定合约的**交易所规格说明**，展示风格与看盘软件「合约简介」类似：

- 交易品种、交易代码、交易单位、报价单位
- 最小变动价位（附一手最小波动估算）
- 最低交易保证金、涨跌停幅度
- 合约月份、交易时间、最后交易日、交割日期
- 交割方式、交割地点、交割品级、上市日期、交易所

### 使用

1. 导航进入「品种简介」
2. 输入中文品种名或同花顺合约代码（如 `螺纹钢`、`rb2510`）
3. 从联想列表选择或点击「查询」

### 数据来源

- 主数据：**东方财富** 合约详情接口
- 补充：**新浪财经** 合约页（交割地点、上市日期等）
- 若已安装 AKShare，优先走 AKShare 封装；否则直接请求上述数据源

API：`GET /api/contract_profile?symbol=rb2510` 返回 JSON。

---

## 系统设置

**路径**：`/settings`

| 功能 | 说明 |
|------|------|
| 实盘资金 | 用于持仓监控的风险金额、仓位占比计算 |
| 行情说明 | 当前行情源展示 |
| 企业微信 Webhook | 计划/关键位触发推送 |
| 修改密码 | 修改管理员密码 |

### 账号与密码

- 账号存在 `futures.db` 的 `settings` 表
- 改 `.env` 不会自动改密码，需 `ADMIN_SYNC_FROM_ENV=true` 并重启，或网页改密
- 忘记密码：`python reset_admin.py`

---

## 品种与行情

### 品种联想

- 输入中文或代码，调用 `/api/symbols/search`
- 自动匹配主力合约，写入 `symbol`、`symbol_name`、`market_code`、`sina_code`
- 实现：`symbols.py` + `static/js/symbol.js`

### 合约代码格式

| 交易所 | 示例 | 格式 |
|--------|------|------|
| 上期所 / 大商所 / 能源中心 | `ag2606`、`rb2605` | 小写品种 + 4 位年月 |
| 郑商所 | `SR609`、`MA606` | 大写品种 + 3 位年月 |
| 中金所 | `IF2606` | 大写品种 + 4 位年月 |

### 行情

| 配置 | 说明 |
|------|------|
| `QUOTE_SOURCE=sina` | 默认，新浪 `hq.sinajs.cn` |
| `QUOTE_SOURCE=ths` | 仅 iFinD 机构 token |
| `QUOTE_SOURCE=auto` | 有 token 时优先同花顺，失败回退新浪 |

个人用户：**看同花顺代码，价格走新浪**，满足监控需求。

---

## 数据库表（简要）

| 表名 | 用途 |
|------|------|
| `settings` | 密码哈希、微信、实盘资金、手续费倍率等 |
| `order_plans` | 开单计划 |
| `key_monitors` | 关键位监控（active / archived） |
| `position_monitors` | 当前持仓 |
| `trade_logs` | 平仓交易记录（含 fee、pnl_net） |
| `trade_records` | 计划/关键位自动止盈止损记录 |
| `review_records` | 复盘记录（含 fee、pnl_net） |
| `fee_rates` | 品种手续费本地配置 |

数据库文件：`futures.db`（项目根目录，运行后生成）。

---

## 后台任务

| 任务 | 频率 | 说明 |
|------|------|------|
| 计划/关键位行情轮询 | 约 3 秒 | 触发判断、微信推送 |
| 关键位列表现价 | 约 1 秒 | 前端 `/api/key_prices` |
| 计划列表现价 | 约 1 秒 | 前端 `/api/plan_prices` |
| 持仓实时卡片 | 约 1 秒 | 前端 `/api/position_live` |
| 过期计划清理 | 启动时 | 非当日计划标记 expired |

---

## 目录与核心文件

```
qihuo/
├── app.py                 # 路由、业务、DB
├── market.py              # 新浪 / 同花顺行情
├── symbols.py             # 品种搜索与主力映射
├── contract_specs.py      # 合约乘数、保证金比例
├── fee_specs.py           # 手续费计算
├── fee_sync.py            # AKShare 费率同步
├── contract_profile.py    # 品种/合约简介查询
├── kline_chart.py         # 复盘 K 线图
├── data/fee_rates.json    # 默认费率表
├── reset_admin.py         # 重置管理员密码
├── templates/             # 页面模板
├── static/js/             # 前端脚本
├── docs/                  # 文档
├── futures.db             # SQLite（运行后生成）
└── uploads/               # 复盘截图与 K 线图
```

---

## 安全提示

- 部署后立即修改默认密码
- 勿将 `.env` 提交到仓库
- 生产环境建议 Nginx 反代 + HTTPS
- 限制 6600 端口访问范围（内网 / VPN）

---

## 仓库

https://git.bz121.com/dekun/qihuo.git