crypto_monitor/crypto_monitor_gate_bot/趋势回调策略说明.md

趋势回调策略（机器人）说明

本文描述本仓库内 「趋势回调」 自动交易计划的业务规则与实现口径，便于单独策略账户使用与审计。

---

1. 适用场景

• 单独用于跑策略的 Gate.io USDT 永续 子账户（建议与主资金隔离）。
• 你已明确：方向、止损价、补仓上沿、止盈价、杠杆，并接受程序按风险预算拆分 首仓 50% + 多档补仓 50%。

---

2. 名词与参数

名称	含义
合约 USDT 可用余额	生成预览时通过 API 读取的 swap 账户 USDT free 快照；确认执行时再次读取并与快照比对偏差。
风险比例	默认 5%：指「若整笔计划在 补仓上沿 这一侧的最坏价格结构下触及止损」，目标亏损上限约为 可用余额快照 × 风险比例（实现上用 calc_risk_fraction 与 prepare_order_amount 反推总张数，受交易所最小张数与精度约束）。
止损价	用户填写；开仓后挂 交易所仓位类止损触发单（全平）。
补仓上沿	用户填写；仅在该价位与止损价构成的区间内 才允许程序触发剩余 50% 的市价补仓（做多：止损 < 补仓上沿；做空：止损 > 补仓上沿）。
止盈价	用户填写的 固定价格；不由交易所条件止盈单触发，由应用后台 按标记价/行情价轮询，达到后 市价全平。
杠杆	计划内固定写入；用于 set_leverage 与名义换算。
补仓档位数	默认 5 档（环境变量 TREND_PULLBACK_DCA_LEGS 可调）；程序在满足最小张数前提下可能 自动减少档数。

---

3. 执行流程（时间顺序）

3.1 预览阶段（不下单）

1. 风控：与「机器人下单监控」互斥——存在活跃机器人持仓或运行中趋势计划时，不可生成预览。
2. 读取可用余额快照 get_available_trading_usdt()，失败则拒绝。
3. 计算（写入表 trend_pullback_previews，并跳转带 preview_id）：
   • 在 补仓上沿 ↔ 止损 区间内生成 N 个补仓触发价；
   • 将 剩余 50% 计划张数 拆成 N 份写入 leg_amounts_json。
4. 预览有效期：默认 120 秒（TREND_PULLBACK_PREVIEW_TTL_SECONDS），超时须重新点「生成预览」。

3.2 确认执行（实盘）

5. 再次校验：预览未过期；当前可用余额与预览快照相对偏差 ≤ TREND_PREVIEW_MAX_BALANCE_DRIFT_PCT（默认 5%），否则拒绝执行并要求重新预览。
6. 首仓：立即市价 开立 总计划张数 × 50%（不附带交易所止盈单）。
7. 止损：撤销旧条件单后，挂 仅止损 的仓位触发单；之后每次补仓成交会 刷新 止损挂单。
8. 补仓：当价格 穿越 下一档触发价（做多为自上向下穿越）时，按该档张数 市价加仓；直至 N 档执行完毕或计划结束。
9. 止盈监控：后台线程若发现价格触及止盈，则 市价全平。
10. 止损触发：若仓位被交易所止损打光，本地检测到 持仓为 0 后记账为 止损 并结束计划。
11. 计划结束：任一结束路径（止盈 / 止损 / 用户手动结束）均会 撤单（条件单 + 普通挂单，尽力而为）。

3.3 取消预览

用户可「取消预览」删除 trend_pullback_previews 中对应记录；过期记录会在新预览或页面加载时清理。

---

4. 与「机器人下单监控」的差异

项目	机器人下单监控	趋势回调
开仓	单次市价 + 条件止盈+止损	首仓 50% 市价 + 多档补仓 + 仅止损在交易所
止盈	条件单 + 本地监控	仅本地监控市价止盈
仓位基数	以损定仓（表单/会话基数）	可用余额快照 × 风险比例 推导
移动保本	支持	不支持（未实现）

---

5. 风险声明（必读）

• 市价单存在 滑点；极端行情下实际亏损可能 大于 理论 5%。
• 补仓触发依赖应用 轮询间隔（MONITOR_POLL_SECONDS），非毫秒级高频。
• 交易所 最小张数 / 精度 可能导致计划张数被截断，实际风险略低于或偏离纸面计算。
• 请使用 单独 API Key / 子账户，并先在 LIVE_TRADING_ENABLED=false 环境验证流程（若需沙盒请自行对接测试网，本仓库默认实盘接口）。

---

6. 相关环境变量

变量	说明	默认
TREND_PULLBACK_DCA_LEGS	剩余 50% 拆档数量上限	5
TREND_PULLBACK_PREVIEW_TTL_SECONDS	预览有效时间（秒）	120
TREND_PREVIEW_MAX_BALANCE_DRIFT_PCT	确认执行时允许「当前可用 / 预览快照」最大相对偏差（%）	5
MONITOR_POLL_SECONDS	监控轮询间隔（秒）	3
LIVE_TRADING_ENABLED	是否允许真实下单	false
FULL_MARGIN_BUFFER_RATIO	计划保证金相对可用余额上限比例	0.98

---

7. 数据库

• trend_pullback_previews：未执行的预览行（含 expires_at_ms），执行成功或取消后删除；过期可被清理。
• trend_pullback_plans：已执行且运行中的计划；字段含快照可用余额、计划保证金、总张数、首仓张数、补仓 JSON、网格价 JSON、已补仓档数、均价、状态等。平仓结果写入 trade_records，monitor_type 为 趋势回调。