From 54ff70c5d7c68b179216b35d207c168923238379 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=A4=9A=E5=AE=8F=E5=85=89?= <542672041@qq.com> Date: Wed, 4 Mar 2026 15:46:21 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E6=8A=80=E6=9C=AF?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 内容包括： - 数据流程说明 - K 线聚合逻辑（日K/周K/月K） - 趋势线绘制逻辑 - 周K/月K 形态检测说明 - 常见问题解答 - 相关源码位置 Co-Authored-By: Claude Opus 4.6 --- docs/triangle-validator-guide_20260304.md | 200 ++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 docs/triangle-validator-guide_20260304.md diff --git a/docs/triangle-validator-guide_20260304.md b/docs/triangle-validator-guide_20260304.md new file mode 100644 index 0000000..d3e2a36 --- /dev/null +++ b/docs/triangle-validator-guide_20260304.md @@ -0,0 +1,200 @@ +# 收敛三角形形态可视化验证工具 - 技术文档 + +> 文档更新日期：2026-03-04 + +## 1. 项目概述 + +收敛三角形（Converging Triangle）形态检测可视化验证工具。通过 HTTP API 调用远程公式执行，绘制 K 线图 + 三角形趋势线，帮助快速目测验证形态检测结果。 + +**支持**： +- A 股和美股（如英伟达、苹果等） +- 日K / 周K / 月K 三种频率 +- 中文名称自动搜索转换为股票代码 + +## 2. 数据流程 + +``` +validate.py + │ + ├─① GET {SEARCH_API_URL}/smartstock/assets/search?q=<关键词> + │ └─ 获取正确的 ticker（中控技术 → SH688777，英伟达 → NVDA.O） + │ + ├─② 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 + │ └─ 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=&begin_date= + │ └─ 获取 K 线 OHLC 数据（默认 3 年历史） + │ + └─⑤ chart.draw_triangle_chart(detail) + ├─ K 线数据按频率聚合（日K/周K/月K） + ├─ mplfinance 绘制 K 线 + 趋势线 + ├─ Y 轴自动调整以包含趋势线 + └─ output/{ticker}_{freq}K_{date}.png +``` + +## 3. K 线聚合逻辑 + +### 3.1 与前端一致 + +K 线数据聚合逻辑与前端 `TechPattern.vue` 中的 `filterAndProcessKLineData` 函数完全一致。 + +### 3.2 聚合规则 + +| 频率 | 聚合方式 | +|------|----------| +| 日K | 原始数据，不聚合 | +| 周K | 同一周的日K聚合成一根（开=首日开，高=最高，低=最低，收=末日收）| +| 月K | 同一月的日K聚合成一根（开=首日开，高=最高，低=最低，收=末日收）| + +### 3.3 代码示例 + +```python +# validate.py 中的 aggregate_klines 函数 +def aggregate_klines(klines: dict, freq: str) -> dict: + """ + 将日K数据聚合成周K或月K + """ + if freq == '日': + return klines + + # 按周/月分组 + for d in daily_data: + if freq == '周': + # 计算该日期所在周的周一 + monday = date_obj - timedelta(days=day_of_week) + key = monday.strftime('%Y%m%d') + else: # 月 + key = date_str[:6] # YYYYMM + + # 聚合每组数据 + result_open.append(group[0]['open']) # 开盘取第一天 + result_high.append(max(d['high'] for d in group)) # 最高取最高 + result_low.append(min(d['low'] for d in group)) # 最低取最低 + result_close.append(group[-1]['close']) # 收盘取最后一天 +``` + +## 4. 趋势线绘制逻辑 + +### 4.1 与前端一致 + +趋势线绘制逻辑与前端 `TechPattern.vue` 中的 `getExtendedLinePoints` 函数完全一致。 + +### 4.2 关键点 + +1. **趋势线延伸**：从 `window_start_date` 延伸到 `window_end_date` +2. **斜率计算**：使用公式数据中的 `index` 字段计算 +3. **坐标映射**：将日期映射到 K 线数据的索引位置 +4. **Y 轴调整**：自动调整 Y 轴范围以包含趋势线（增加 5% 边距） + +### 4.3 代码示例 + +```python +# chart.py 中的趋势线绘制逻辑 +def make_extended_aline(line_pts, pivot_point, color): + # 使用原始 index 计算斜率 + slope = (p2['price'] - p1['price']) / (p2['index'] - p1['index']) + + # 前端: startIdx = 0 (window_start_date 对应 index 0) + start_idx = 0 + + # 查找 window_end_date 对应的 index + end_idx = p2['index'] + + # 计算延伸后的价格 + start_price = pivot_price + slope * (start_idx - pivot_index) + end_price = pivot_price + slope * (end_idx - pivot_index) + + return ((kline_start_idx, start_price), (kline_end_idx, end_price)) +``` + +## 5. 周K/月K 形态检测说明 + +### 5.1 检测逻辑 + +收敛三角形详情函数会根据传入的频率参数（日/周/月）在**对应周期的数据**上寻找形态。 + +### 5.2 默认参数（来自 config.py） + +| 参数 | 日K (D) | 周K (W) | 月K (M) | +|------|---------|---------|---------| +| window | 240 | 104 | 60 | +| pivot_k | 15 | 5 | 3 | +| breakout_threshold | 0.005 | 0.010 | 0.020 | +| vol_window | 20 | 8 | 4 | +| volume_multiplier | 1.5 | 1.5 | 1.3 | +| min_convergence | 0.45 | 0.45 | 0.50 | +| false_break_m | 5 | 2 | 1 | +| flexible_zone | 15 | 5 | 2 | +| display_bars | 300 | 130 | 72 | + +### 5.3 形态有效性判定条件 + +1. **收敛比 (width_ratio)**：`width_end / width_start <= shrink_ratio`（默认 0.8） +2. **触碰点数量**：`touches_upper >= 2` 和 `touches_lower >= 2` +3. **违规点限制**：违规点不能超过枢轴点的 1/3 + +### 5.4 不同股票的检测结果示例 + +| 股票 | 日K | 周K | +|------|-----|-----| +| 中控技术 | ✅ 有效 | ❌ 无效（收敛不足或触碰点不够）| +| 比亚迪 | - | ✅ 有效 | +| 贵州茅台 | - | ❌ 无效 | + +**结论**：不是所有股票在周K/月K上都有有效的收敛三角形形态，这是正常现象。 + +## 6. 常见问题 + +### Q1: 为什么周K/月K没有收敛三角形？ + +**A**: 这是因为该股票在周K/月K数据上没有形成有效的收敛三角形形态，可能原因： +- 收敛比例不足（`width_ratio > 0.8`） +- 触碰点不足（需要上下各至少 2 个触碰点） + +### Q2: 为什么 K 线图显示 3 年数据，但形态窗口只有几个月？ + +**A**: 这是正常的设计： +- K 线数据：显示 `--window` 参数指定的时间范围（默认 3Y） +- 形态窗口：由公式检测到的有效形态范围，通常只是 K 线数据的一部分 + +### Q3: 美股如何获取 K 线数据？ + +**A**: 使用中文名称（如"英伟达"），程序会自动通过搜索接口获取正确的 ticker（如 `NVDA.O`），然后获取 K 线数据。 + +### Q4: 趋势线价格超出 K 线范围怎么办？ + +**A**: 代码会自动调整 Y 轴范围以包含趋势线，并增加 5% 边距（与前端一致）。 + +## 7. 文件结构 + +``` +triangle-validator/ +├── validate.py # 主入口：单股验证 +├── batch_validate.py # 批量验证多只股票 +├── chart.py # K 线 + 三角形绘图模块 +├── config.py # API 端点 & 认证配置 +├── requirements.txt # Python 依赖 +├── docs/ # 文档目录 +│ └── triangle-validator-guide_20260304.md +├── output/ # 生成的图片（自动创建） +├── README.md # 使用说明 +└── CLAUDE.md # Claude Code 指引 +``` + +## 8. 相关源码位置 + +- 收敛三角形详情函数：`D:\project\dunhe_dataServer\src\library\expression\funcs\pattern.py` +- 形态检测核心逻辑：`D:\project\dunhe_dataServer\src\library\pattern\converging_triangle.py` +- 参数配置：`D:\project\dunhe_dataServer\src\library\pattern\config.py` +- 前端 K 线图表：`D:\project\frontend_mobile\src\views\workflow\components\assetRatingV2\components\TechPattern.vue`