# triangle-validator

收敛三角形（Converging Triangle）形态检测可视化验证工具。

通过调用远程 HTTP API 执行公式并拉取结果，绘制 K 线图 + 三角形趋势线，
帮助快速目测验证形态检测结果是否准确。**无需本地数据库，无需 dunhe 虚拟环境。**

**支持 A 股和美股**（如英伟达、苹果等）。

**技术文档**：[docs/triangle-validator-guide_20260304.md](docs/triangle-validator-guide_20260304.md)

---

## 目录结构

```
triangle-validator/
├── validate.py        # 主入口：单股验证
├── batch_validate.py  # 批量验证多只股票
├── chart.py           # K 线 + 三角形绘图模块
├── config.py          # API 端点 & 认证配置
├── requirements.txt   # Python 依赖
├── output/            # 生成的图片（自动创建）
└── README.md
```

---

## 前提条件

只需要系统 Python（3.8+）及两个依赖包：

```bash
pip install requests mplfinance
```

---

## 单股验证

```bash
# 基本用法（日K，弹出窗口）
python validate.py 中远海控

# 使用中文名称（自动搜索转换为股票代码）
python validate.py 比亚迪 日 --window 3Y --save --no-show 
python validate.py 比亚迪 周 --window 10Y --save --no-show 
python validate.py 比亚迪 月 --window 3Y --save --no-show 
# 美股也支持
python validate.py 英伟达 日 --window 3Y --save

# 周K，保存图片
python validate.py 中远海控 周 --save

# 月K，不弹窗，只保存
python validate.py SH600519 月 --no-show --save

# 指定截止日期
python validate.py 贵州茅台 日 --date 20260120 --save

# 使用激进模式（mode=1）
python validate.py 宁德时代 周 --mode 1 --save
```

### 参数说明

| 参数 | 说明 |
|------|------|
| `ticker` | 股票名称（如"中远海控"、"英伟达"）或代码（如"SH601919"）|
| `freq` | 频率：`日` / `周` / `月`，默认 `日` |
| `--save` | 保存 PNG 到 `output/` 目录 |
| `--no-show` | 不弹出交互窗口（适合服务器/批量场景）|
| `--date` | 截止日期，格式 `YYYYMMDD`，默认最新数据日 |
| `--mode` | 强度模式：0=等权 1=激进 2=保守 3=放量，默认 0 |
| `--window` | K 线时间窗口：`1Y` / `3Y` / `5Y` / `ALL`，默认 `3Y` |

---

## 批量验证

```bash
# 默认批量（内置测试列表，日/周/月各一批）
python batch_validate.py

# 只保存，不弹窗
python batch_validate.py --no-show --save
```

修改 `batch_validate.py` 中的 `BATCH_CASES` 列表可自定义验证标的。

---

## 图表说明

生成的图表包含以下元素：

| 元素 | 颜色 | 含义 |
|------|------|------|
| 红色趋势线 | `#ef4444` | 上沿（压力线），从窗口起点延伸到终点 |
| 绿色趋势线 | `#10b981` | 下沿（支撑线），从窗口起点延伸到终点 |
| 红色虚线 | `#ef4444` | 上突破价位 |
| 绿色虚线 | `#10b981` | 下突破价位 |

标题格式：`{ticker} {频率}K  强度={score:.3f}  {方向}  窗口 yyyyMMdd ~ yyyyMMdd`

---

## 数据流

```
validate.py
  ① GET {SEARCH_API_URL}/smartstock/assets/search?q=<关键词>
        → 获取正确的 ticker（如 "中控技术" → "SH688777"）

  ② POST {GPT_SERVER_URL}/innerServer/runOneFormula
        body: { formula_str: "结果=收敛三角形详情(ticker,freq,True,mode)" }
        → response.output = MongoDB _id

  ③ GET {DATA_SERVER_URL}/api/timeSeries/requestIndexDetail?id=<_id>
        header: Authorization: Bearer <token>
        → data.data_info.detail
             ├─ strength / direction / is_valid
             ├─ breakout_price_up / breakout_price_down
             └─ chart_data
                  ├─ upper_line / lower_line  (趋势线端点)
                  ├─ upper_pivots / lower_pivots  (枢轴点)
                  └─ window_start_date / window_end_date

  ④ GET {KLINE_API_URL}/dataSupport/getKLineDataByTicker?ticker=<ticker>&begin_date=<begin_date>
        → 获取 K 线 OHLC 数据（3年历史）

  ⑤ chart.draw_triangle_chart(detail)
        → mplfinance 绘制 K 线 + 趋势线
        → Y 轴自动调整以包含趋势线
        → output/{ticker}_{freq}K_{date}.png
```

---

## 常见问题

**Q: 报错 `ModuleNotFoundError: No module named 'requests'`**
A: 执行 `pip install requests mplfinance`。

**Q: 报错 `ConnectionError` 或 `404`**
A: 检查 `config.py` 中的 `GPT_SERVER_URL` / `DATA_SERVER_URL` 是否正确，以及 token 是否过期。

**Q: 公式执行失败，未返回 _id**
A: 确认 ticker 名称正确，或改用标准代码（如 `SH600519`）。

**Q: 图表中文乱码（显示方框）**
A: 安装中文字体，推荐 `Microsoft YaHei`（Windows 自带）或 `SimHei`。chart.py 会自动检测并应用。

**Q: 美股 K 线数据获取失败**
A: 使用中文名称（如"英伟达"）而非股票代码，程序会自动通过搜索接口获取正确的 ticker。