feat(risk): add account cooldown and daily freeze after manual/external close

Implements shared account_risk_lib with 4h/1h cooloff and daily freeze rules, wires hooks into all four exchange apps and hub monitor UI, with tests and docs. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-17 17:05:19 +08:00
parent b77741ee21
commit e307eef690
18 changed files with 1015 additions and 5 deletions
@@ -0,0 +1,54 @@
+# 账户冷静期 / 日冻结风控
+
+四所实例（币安 / OKX / Gate / Gate 趋势）共用 `account_risk_lib.py`，在手动平仓、外部平仓与交易复盘保存时更新 `account_risk_state` 表，并在开仓前 `precheck_risk` 拦截。
+
+## 状态展示
+
+实例页顶「交易所」标签旁、中控监控卡片账户名后显示：
+
+| 状态 | 含义 |
+|------|------|
+| 正常 | 可新开仓 |
+| 1h冻结 | 冷静期中（通常为复盘后缩短的 1 小时） |
+| 4h冻结 | 冷静期中（默认 4 小时） |
+| 日冻结 | 当日禁止一切新开仓 |
+
+## 触发规则
+
+| 事件 | 行为 |
+|------|------|
+| 页面手动平仓 | 默认 **4h** 冷静期；累计手动平仓次数 +1 |
+| 当日第 2 次手动平仓 | **日冻结**（默认上限 2 次，可配置） |
+| 复盘：离场触发=手动平仓 且补充说明非空 | 将当前冷静期降为 **1h**（自上次平仓时刻起算） |
+| 复盘：情绪标签任一项勾选 | **日冻结** |
+| 外部平仓（`result=外部平仓`） | **4h** 冷静期（正常止盈/止损不触发） |
+
+情绪标签（`mood_issues`）：怕踏空、报复开仓、盈利飘了、拿不住单、扛单、重仓违规。
+
+## 环境变量
+
+在各实例目录 `.env` 中配置（模板见各所 `.env.example`）：
+
+```env
+RISK_CONTROL_ENABLED=true
+RISK_COOLING_HOURS_MANUAL=4
+RISK_COOLING_HOURS_EXTERNAL=4
+RISK_COOLING_HOURS_MANUAL_JOURNAL=1
+RISK_MANUAL_CLOSE_DAILY_LIMIT=2
+RISK_MOOD_ISSUES_DAILY_FREEZE=true
+```
+
+- `RISK_CONTROL_ENABLED=false` 时关闭整套逻辑，状态始终为「正常」。
+- 交易日切换（`TRADING_DAY_RESET_HOUR`）会清零当日手动平仓计数与日冻结标记；未过期的冷静期按 `cooloff_until_ms` 自然到期。
+
+## API
+
+- 实例：`GET /api/account_snapshot` 返回 `risk_status`；`GET /api/account_risk_status`（hub_bridge）供中控拉取。
+- 中控：`hub_monitor` 载荷含 `risk_status`，卡片标题旁展示 `status_label`。
+
+## 相关代码
+
+- `account_risk_lib.py` — 核心状态机
+- 各所 `app.py` — `on_manual_close` / `on_external_close` / `on_journal_saved` 钩子
+- `hub_bridge.py` — 中控聚合 `risk_status`
+- `tests/test_account_risk_lib.py` — 单元测试