{
  "module": "decisions",
  "version": "1.0",
  "purpose": "策略决策库。管理持仓和自选股的策略决策（止损/止盈/买入区/操作建议），支持新旧格式兼容。",

  "human_help": {
    "title": "策略决策库",
    "description": [
      "存储每只持仓/自选股的策略决策数据，包括止损价、止盈价、买入区间、操作建议等。",
      "数据来自知微 LLM 分析，通过 /api/analysis/batch 写入。",
      "支持新旧两种数据格式的自动兼容（新格式：stop_loss/take_profit 顶层字段；旧格式：trigger 对象）。"
    ],
    "usage": [
      "GET /api/decisions — 获取全部决策（按标签+执行状态排序）",
      "POST /api/decisions/add — 新增/更新一条决策（同股票旧决策自动标记 superseded）",
      "POST /api/decisions/tag — 设置/清除推荐标签（current_recommend / active_manual）",
      "GET /api/decisions/pending — 获取有未确认建议的条目"
    ],
    "troubleshooting": [
      "决策列表为空 → 确认 regenerate_all 已执行或知微已写入",
      "旧格式不显示 → 检查归一化逻辑（/api/decisions GET handler）"
    ]
  },

  "ai_spec": {
    "apis": [
      {"method": "GET", "path": "/api/decisions", "returns": "{decisions[{code, name, type, status, tag, action, trigger{stop_loss, take_profit, entry_zone}, current, zone_breach, updated_reason, advice_timeline, changelog, execution, analysis}], total, regenerated_at}"},
      {"method": "POST", "path": "/api/decisions/add", "returns": "{status:'ok', entry:{...}}"},
      {"method": "POST", "path": "/api/decisions/tag", "returns": "{status:'ok', code, tag}"},
      {"method": "GET", "path": "/api/decisions/pending", "returns": "[{code, name, current, pending_advice[{date, direction, price, summary, status}]}]"}
    ],
    "dependencies": [
      "mo_data.py — read_decisions()",
      "mofin_db.py — write_holding_strategy()",
      "strategy_lifecycle.py — regenerate_all 触发全量重评"
    ],
    "constraints": [
      "支持新旧两种格式的读取兼容（normalized 逻辑）",
      "同股票新决策会自动将旧决策标记为 superseded",
      "排序规则：current_recommend 标签 > 执行状态（partial_exit > executing > observing） > code",
      "advice_timeline 去重：同日期+同方向+摘要前40字相同 → skip"
    ],
    "must_not": [
      "不要在决策中硬编码价格阈值（应由 LLM 分析生成）",
      "不要删除 superseded 的旧决策（保留历史记录）"
    ],
    "related_files": [
      "server.py — /api/decisions* 路由",
      "mo_data.py — read_decisions()",
      "mofin_db.py — holding_strategies 表"
    ]
  }
}