technical-patterns-lab/docs/功能与文档总览.md

# 收敛三角形检测系统 - 功能与文档总览

> 更新时间：2026-01-27  
> 版本：v1.0

## 🎯 核心功能

### 1. 收敛三角形检测
- 自动识别K线中的收敛三角形形态
- 枢轴点检测与拟合算法
- 相向收敛约束（过滤通道形态）
- 突破方向判断（向上/向下/无）

### 2. 强度分评分系统
- **价格突破**（50%）：突破幅度评估
- **收敛程度**（20%）：蓄势充分度
- **成交量**（15%）：放量确认
- **拟合贴合度**（15%）：形态纯度

### 3. 可视化系统
- **静态图表**：K线图 + 三角形趋势线
- **HTML查看器**：交互式强度分筛选
- **详细模式**：显示枢轴点和拟合点

### 4. 批量处理
- 支持多日期、多股票批量检测
- 自动生成报告和图表
- 一键流水线脚本

## 📊 输出内容

### 1. 数据文件
```
outputs/converging_triangles/
├── all_results.csv              # 完整检测结果（CSV格式）
├── YYYYMMDD_stocks.pkl          # 单日结果（Pickle格式）
└── report.md                    # 可读性报告
```

### 2. 可视化
```
outputs/converging_triangles/
├── stock_viewer.html            # HTML交互式查看器 ⭐
├── QUICK_START.md               # 查看器快速指南
├── README_viewer.md             # 查看器详细文档
└── charts/                      # 图表图片
    ├── YYYYMMDD_代码_名称.png
    └── YYYYMMDD_代码_名称_detail.png  # 详细模式
```

## 🚀 快速开始

### 最简使用（3步）

```powershell
# 1. 激活环境（首次需要创建和安装依赖）
python -m venv .venv
.venv\Scripts\activate
pip install numpy pandas matplotlib

# 2. 一键运行（生成所有数据和HTML查看器）
python scripts/pipeline_converging_triangle.py --all-stocks

# 3. 打开HTML查看器
start outputs/converging_triangles/stock_viewer.html
```

### 常用命令

```powershell
# 指定日期
python scripts/pipeline_converging_triangle.py --date 20260120 --all-stocks

# 详细模式（显示枢轴点和拟合点）
python scripts/pipeline_converging_triangle.py --show-details --all-stocks

# 只生成HTML（数据已存在）
python scripts/generate_stock_viewer.py --all-stocks

# 默认模式（仅满足条件的股票）
python scripts/pipeline_converging_triangle.py
```

## 📚 文档体系

### 入门文档（必读）

1. **README.md** - 项目概述和快速开始
2. **USAGE.md** - 完整使用指南（参数、数据格式等）⭐
3. **outputs/converging_triangles/QUICK_START.md** - HTML查看器快速指南

### 核心功能文档

4. **docs/突破强度计算方法.md** - 强度分算法详解（v3.0）
5. **docs/强度分计算示例.md** - 详细计算步骤与示例
6. **docs/all-stocks-feature.md** - 全股票图表功能说明
7. **docs/2026-01-27_HTML查看器功能.md** - HTML查看器设计与实现

### 算法原理文档

8. **docs/枢轴点检测原理.md** - 枢轴点算法详解
9. **docs/枢轴点分段选择算法详解.md** - 拟合点选择算法 ⭐
10. **docs/枢轴点边界问题分析.md** - 边界盲区问题与解决方案
11. **docs/2026-01-26_相向收敛约束改进.md** - 过滤通道形态的改进
12. **docs/2026-01-26_枢轴点检测与可视化修复.md** - 末端枢轴点问题修复

### 高级功能文档

13. **docs/方案4-混合策略详解.md** - 实时模式完整说明 ⭐
14. **docs/实时模式使用指南.md** - 实时模式快速上手
15. **docs/2026-01-26_图表详细模式功能.md** - 图表可视化改进
16. **docs/file-naming-fix.md** - ST股票文件名修复

### 其他文档

17. **docs/converging_triangles_outputs.md** - 输出字段说明
18. **docs/收敛三角形检测系统-使用指南.md** - 旧版使用指南
19. **outputs/converging_triangles/README_viewer.md** - HTML查看器详细文档

### 讨论与记录

20. **discuss/20260126-讨论.md** - 问题分析与解决方案记录

## 🎨 HTML查看器使用指南

### 功能特性

- ✅ **交互式滑块**：0.00 ~ 1.00 实时筛选强度分
- ✅ **全股票模式**：显示所有108只股票（包括无形态的）
- ✅ **实时统计**：总数、筛选数、平均强度分
- ✅ **图表放大**：点击图表全屏查看
- ✅ **颜色分级**：绿色(≥0.5) / 黄色(0.3~0.5) / 灰色(<0.3)
- ✅ **响应式设计**：适配PC/平板/手机
- ✅ **离线可用**：数据内嵌，无需服务器

### 使用场景

**场景1：快速筛选强势股**
```
1. 拖动滑块到 0.5
2. 只显示强度分 ≥ 0.5 的股票
3. 点击图表查看细节
```

**场景2：全面浏览**
```
1. 滑块保持在 0.00
2. 显示所有 108 只股票
3. 按强度分从高到低排序浏览
```

**场景3：渐进式分析**
```
1. 先看 ≥ 0.5 的强势股
2. 降到 ≥ 0.4 查看次强势
3. 降到 ≥ 0.3 查看中等强度
4. 对比不同强度级别的形态差异
```

### 数据更新

```powershell
# 每天收盘后运行
python scripts/pipeline_converging_triangle.py --all-stocks

# 刷新浏览器
F5
```

## 🔧 命令行参数

### pipeline_converging_triangle.py

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--date` | 检测日期（YYYYMMDD） | 最新交易日 |
| `--all-stocks` | 为所有108只股票生成图表 | 否 |
| `--show-details` | 图表显示枢轴点和拟合点 | 否 |
| `--skip-detection` | 跳过检测（仅生成报告和图表） | 否 |
| `--skip-viewer` | 跳过HTML查看器生成 | 否 |

### generate_stock_viewer.py

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--date` | 指定日期（YYYYMMDD） | 最新日期 |
| `--all-stocks` | 显示所有108只股票 | 否 |
| `--input` | 输入CSV路径 | `outputs/.../all_results.csv` |
| `--output` | 输出HTML路径 | `outputs/.../stock_viewer.html` |

### plot_converging_triangles.py

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--date` | 绘图日期（YYYYMMDD） | 最新日期 |
| `--all-stocks` | 为所有股票生成图表 | 否 |
| `--show-details` | 显示枢轴点和拟合点 | 否 |
| `--output-dir` | 输出目录 | `outputs/.../charts` |

## 📦 数据格式

### all_results.csv 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `date` | int | 检测日期（YYYYMMDD） |
| `stock_idx` | int | 股票索引 |
| `stock_code` | str | 股票代码（如SH600000） |
| `stock_name` | str | 股票名称 |
| `breakout_strength_up` | float | 向上突破强度分（0~1） |
| `breakout_strength_down` | float | 向下突破强度分（0~1） |
| `breakout_dir` | str | 突破方向（up/down/none） |
| `width_ratio` | float | 宽度比（收敛程度） |
| `touches_upper` | int | 上沿触碰次数 |
| `touches_lower` | int | 下沿触碰次数 |
| `volume_confirmed` | str | 放量确认（是/否） |
| `price_score_*` | float | 价格突破分项得分 |
| `convergence_score` | float | 收敛程度分项得分 |
| `volume_score` | float | 成交量分项得分 |
| `fit_adherence_*` | float | 拟合贴合度分项得分 |

### HTML内嵌数据格式

```javascript
{
    "code": "SH600000",
    "name": "浦发银行",
    "idx": 0,
    "strength": 0.381,           // 强度分（0~1）
    "strengthUp": 0.381,         // 向上突破强度
    "strengthDown": 0.0,         // 向下突破强度
    "direction": "down",         // 突破方向
    "widthRatio": 0.13,          // 宽度比
    "touchesUpper": 3,           // 上沿触碰次数
    "touchesLower": 4,           // 下沿触碰次数
    "volumeConfirmed": "否",     // 放量确认
    "date": 20260120,            // 日期
    "chartPath": "charts/...",   // 图表路径
    "hasTriangle": true          // 是否有三角形形态
}
```

## 🎯 典型工作流

### 工作流1：日常选股

```powershell
# 1. 每日收盘后运行（默认模式）
python scripts/pipeline_converging_triangle.py

# 2. 查看报告（快速浏览）
cat outputs/converging_triangles/report.md

# 3. 打开HTML查看器（交互式筛选）
start outputs/converging_triangles/stock_viewer.html

# 4. 调整滑块到 0.5，查看强势股
```

### 工作流2：全面研究

```powershell
# 1. 生成所有股票的数据（全股票模式）
python scripts/pipeline_converging_triangle.py --all-stocks --show-details

# 2. 打开HTML查看器
start outputs/converging_triangles/stock_viewer.html

# 3. 滑块保持 0.00，浏览所有 108 只股票
# 4. 对比有/无形态的股票差异
# 5. 点击图表查看详细的枢轴点和拟合点
```

### 工作流3：算法调试

```powershell
# 1. 指定日期，详细模式
python scripts/pipeline_converging_triangle.py --date 20260120 --all-stocks --show-details

# 2. 查看图表目录
ls outputs/converging_triangles/charts/*_detail.png

# 3. 验证枢轴点识别和拟合效果
# 4. 调整算法参数（如果需要）
# 5. 重新运行验证
```

### 工作流4：历史回测

```powershell
# 批量检测多个日期
for date in 20260115 20260116 20260117 20260120; do
    python scripts/pipeline_converging_triangle.py --date $date --all-stocks
done

# 合并结果分析
python -c "import pandas as pd; df = pd.read_csv('outputs/converging_triangles/all_results.csv'); print(df.groupby('date')['breakout_strength_up'].mean())"
```

## 🔬 核心算法

### 1. 枢轴点检测
- **标准区域**（前220天）：左右15天窗口
- **灵活区域**（后15天）：对称短窗口
- **处理NaN值**：使用 `nanmin/nanmax`
- **末端候选**：包含未确认的潜在枢轴点

### 2. 拟合点选择
- **迭代离群点移除**：3轮迭代，每轮移除最差点
- **Z-score阈值**：2.0（正态分布下约5%异常点）
- **最小点数**：保留至少3个枢轴点

### 3. 收敛判断
- **相向收敛**：上沿斜率 < 0，下沿斜率 > 0
- **宽度比**：收敛端宽度 / 起始端宽度
- **触碰次数**：上沿≥2次，下沿≥2次

### 4. 强度分计算
```python
强度分 = 价格突破×50% + 收敛程度×20% + 成交量×15% + 拟合贴合度×15%

其中：
- 价格突破 = tanh(突破幅度% × 15)  # 0~1
- 收敛程度 = 1 - width_ratio       # 0~1
- 成交量 = 1 if 放量确认 else 0     # 0或1
- 拟合贴合度 = exp(-mean_rel_error × 20)  # 0~1
```

## 🐛 已知问题与限制

1. **数据覆盖**：部分股票可能因停牌、退市缺少数据
2. **窗口限制**：检测窗口固定240天，可能漏掉更早的形态
3. **图片路径**：HTML查看器需要与charts目录在同一父目录
4. **浏览器兼容**：推荐Chrome 90+，其他浏览器可能有兼容问题

## 📈 性能指标

- **检测速度**：108只股票约30秒（Intel i7）
- **图表生成**：108张图约1分钟
- **HTML加载**：数据内嵌，<1秒即可打开
- **内存占用**：峰值约500MB（数据加载时）

## 🎓 学习路径

### 新手路径（1小时）
1. 阅读 `README.md` - 了解项目概述（5分钟）
2. 运行快速开始命令（10分钟）
3. 打开HTML查看器，体验交互（15分钟）
4. 阅读 `QUICK_START.md` - 掌握基本用法（10分钟）
5. 查看几个图表示例（20分钟）

### 进阶路径（半天）
6. 阅读 `USAGE.md` - 掌握所有参数（30分钟）
7. 阅读 `docs/突破强度计算方法.md` - 理解强度分（1小时）
8. 阅读 `docs/强度分计算示例.md` - 跟随示例计算（1小时）
9. 尝试不同参数组合，观察效果（1小时）

### 专家路径（1-2天）
10. 阅读所有算法原理文档（3小时）
11. 阅读源代码 `src/converging_triangle.py`（2小时）
12. 尝试修改参数、调整算法（2小时）
13. 运行历史回测，分析有效性（2小时）
14. 阅读讨论文档，理解设计决策（1小时）

## 🤝 贡献与反馈

- **问题反馈**：在讨论文档中记录问题和解决方案
- **功能建议**：在 `docs/` 目录创建新文档记录设计思路
- **代码改进**：遵循现有代码风格，添加完整注释和文档

## 📝 版本历史

- **v1.0**（2026-01-27）：
  - ✅ HTML可视化查看器
  - ✅ 全股票图表生成
  - ✅ 强度分评分系统（v3.0）
  - ✅ 枢轴点末端识别修复
  - ✅ 相向收敛约束
  - ✅ 拟合点离群值移除

- **v0.9**（2026-01-26）：
  - ✅ 枢轴点检测系统
  - ✅ 收敛三角形识别
  - ✅ 图表详细模式
  - ✅ 批量处理流水线

## 🔗 快速链接

### 必读文档
- [README.md](../README.md) - 项目概述
- [USAGE.md](../USAGE.md) - 使用指南
- [QUICK_START.md](../outputs/converging_triangles/QUICK_START.md) - HTML查看器快速指南

### 热门文档
- [强度分计算方法](./突破强度计算方法.md)
- [HTML查看器功能](./2026-01-27_HTML查看器功能.md)
- [全股票功能](./all-stocks-feature.md)
- [枢轴点算法详解](./枢轴点分段选择算法详解.md)

### 输出文件
- `outputs/converging_triangles/stock_viewer.html` - HTML查看器
- `outputs/converging_triangles/all_results.csv` - 检测结果
- `outputs/converging_triangles/charts/` - 图表图片

---

**最后更新**：2026-01-27  
**维护者**：技术形态检测实验室