test.md

自动盈亏控制系统（Python脚本 + 平台对接）需求与设计文档

一、 核心业务流程

1. 【管理后台】管理员检索用户，并绑定该用户的盈亏控制模型（自负盈亏/强制盈利/强制亏损）。
2. 【行情分析】Python 脚本以固定周期（如 5分钟）轮询大盘历史行情。
3. 【逻辑决策】脚本根据设定的“盈亏模型”以及对应时间段的“大盘实际走势”，决定买卖方向。
4. 【平台执行】脚本调用平台 API，强制注入交易时的【历史成交价】与【历史时间戳】，解决网络延迟导致的价格不匹配问题。

---

二、 核心功能设计

1. 管理后台页面 (Python GUI 或 极简 Web)

• 用户搜索：支持输入 User_ID 快速定位用户。
• 模型绑定：单选框切换以下三种模式：
  • 0 - 自负盈亏 (脚本不干预)
  • 1 - 强制盈利 (让用户单子跟大盘方向一致)
  • 2 - 强制亏损 (让用户单子跟大盘方向相反)
• 全局控制：一键“启动/暂停”自动控制脚本。

2. 脚本控制逻辑 (Python Script)

脚本每个周期（如 $T_{-5}$ 到 $T_0$ 分钟）执行一次分析：

• 走势判断：
  • 获取大盘 5 分钟前价格 $P_{start}$，与当前价格 $P_{end}$。
  • $P_{end} > P_{start} \rightarrow$ 大盘上涨趋势 (UP)
  • $P_{end} < P_{start} \rightarrow$ 大盘下跌趋势 (DOWN)
• 交易决策矩阵：
  • 强制盈利模型：
    • 上涨 (UP) $\rightarrow$ 调用平台接口【买入 (BUY)】，指定成交价为 $P_{start}$，在 $P_{end}$ 时平仓盈利。
    • 下跌 (DOWN) $\rightarrow$ 调用平台接口【卖出 (SELL)】，指定成交价为 $P_{start}$，在 $P_{end}$ 时平仓盈利。
  • 强制亏损模型：
    • 上涨 (UP) $\rightarrow$ 调用平台接口【卖出 (SELL)】（逆市做空导致亏损）。
    • 下跌 (DOWN) $\rightarrow$ 调用平台接口【买入 (BUY)】（逆市接飞刀导致亏损）。

3. 时间差对齐机制 (关键攻关点)

• 痛点：脚本决策和接口调用存在网络延迟，12:00 发起的请求，成交时间可能变成 12:00:05，价格已发生变动。
• 解决方案（强制补单）：
  • Python 脚本调接口时，直接把大盘历史时间戳（如 11:55:00）以及对应的历史价格（如 2350.15）作为参数传给平台。
  • 平台接收到请求后，绕过系统当前时间和当前市价，直接将脚本传入的时间和价格写入交易数据库，确保完美的历史对齐。

---

三、 平台交易控制接口 (API) 定义

• 接口类型：POST
• 接口路径：/api/v1/trade/control
• 安全验证：Header 需携带签名或 api_key

1. 请求参数 (JSON)

{
  "api_key": "your_secure_control_token",
  "user_id": "U10025",             // 目标用户 ID
  "action": "BUY",                 // 交易动作：BUY / SELL
  "volume": 1.0,                   // 交易数量/手数

  // 核心：强控时间与价格参数（规避时间差延迟）
  "force_timestamp": 1781020500,   // 强行写入数据库的成交时间戳 (如 11:55:00)
  "force_price": 2350.15           // 强行以此价格成交，不采用平台当前实时市价
}

2. 返回结果 (JSON)

{
  "code": 200,
  "message": "控制订单补单成功",
  "data": {
    "order_id": "CTRL_20260610_0091",
    "status": "SUCCESS",
    "executed_price": 2350.15,
    "executed_at": 1781020500
  }
}