{
  "module": "signals",
  "version": "1.0",
  "purpose": "信号与扫描数据。提供市场信号查询和小果扫描统计。",

  "human_help": {
    "title": "信号与扫描",
    "description": [
      "展示系统产生的交易信号和小果 LLM 扫描结果。",
      "信号来自多个来源：xiaoguo_scanner（全市场）、macro_context_collector（宏观）、divergence_detector（背离）。",
      "所有信号存储在 signal_news 表中。"
    ],
    "usage": [
      "GET /api/signals — 获取最近 20 条信号（含板块信号关联）",
      "GET /api/xiaoguo-scan — 获取小果扫描统计（扫描总数/发现信号数/近期记录/今日来源分布）"
    ],
    "troubleshooting": [
      "信号为空 → 检查 xiaoguo_scanner 和 macro_context_collector cron 状态",
      "小果扫描数据停更 → 检查小果 LLM API 是否可达"
    ]
  },

  "ai_spec": {
    "apis": [
      {"method": "GET", "path": "/api/signals", "returns": "[{id, sector, overall_sentiment, summary, source, created_at, signal_type, severity}] — 最近 20 条信号"},
      {"method": "GET", "path": "/api/xiaoguo-scan", "returns": "{total_scanned, found_signals, recent[{code, name, last_scanned_at, found_count}], source_today{source:cnt}}"}
    ],
    "dependencies": [
      "mofin_db.py — signal_news / xiaoguo_scan_tracker 表",
      "xiaoguo_scanner.py — 全市场扫描 cron（*/5 9-15）",
      "macro_context_collector.py — 宏观信号采集 cron",
      "divergence_detector.py — 背离检测 cron"
    ],
    "constraints": [
      "signal_news 和 sector_signals 通过 LEFT JOIN 关联",
      "xiaoguo_scan_tracker 的 source 统计只取最近 24 小时"
    ],
    "related_files": [
      "server.py — /api/signals, /api/xiaoguo-scan",
      "xiaoguo_scanner.py",
      "macro_context_collector.py"
    ]
  }
}