technical-patterns-lab/docs/系统架构.md

# Technical Patterns Lab 系统架构

本文档描述收敛三角形检测系统的完整架构设计。

---

## 1. 整体系统架构

```mermaid
flowchart TD
    subgraph DataLayer [数据层]
        PKL[PKL数据文件<br/>open/high/low/close/volume]
    end
    
    subgraph CoreAlgorithm [核心算法层]
        Pivot[枢轴点检测<br/>pivots_fractal/hybrid]
        Fit[边界线拟合<br/>fit_pivot_line]
        Detect[三角形检测<br/>detect_converging_triangle]
        Batch[批量检测<br/>detect_converging_triangle_batch]
    end
    
    subgraph ConfigLayer [配置层]
        Config[triangle_config.py<br/>参数/模式配置]
    end
    
    subgraph ScriptLayer [脚本层]
        Run[run_converging_triangle.py<br/>批量检测]
        Report[report_converging_triangles.py<br/>生成报告]
        Plot[plot_converging_triangles.py<br/>绘制图表]
        Pipeline[pipeline_converging_triangle.py<br/>一键流水线]
    end
    
    subgraph OutputLayer [输出层]
        CSV[all_results.csv<br/>检测结果]
        MD[report.md<br/>选股报告]
        PNG[charts/*.png<br/>可视化图表]
    end
    
    PKL --> Run
    Config --> Run
    Config --> Report
    Config --> Plot
    
    Run --> Batch
    Batch --> Detect
    Detect --> Pivot
    Detect --> Fit
    
    Run --> CSV
    Report --> CSV
    Report --> MD
    Plot --> CSV
    Plot --> PNG
    
    Pipeline --> Run
    Pipeline --> Report
    Pipeline --> Plot
```

---

## 2. 核心检测流程

```mermaid
flowchart LR
    subgraph Input [输入]
        OHLCV[OHLCV数据<br/>120天窗口]
        Params[检测参数<br/>ConvergingTriangleParams]
        Mode[检测模式<br/>standard/realtime]
    end
    
    subgraph PivotDetection [枢轴点检测]
        CheckMode{实时模式?}
        StandardPivot[标准检测<br/>pivots_fractal]
        HybridPivot[混合检测<br/>pivots_fractal_hybrid]
        
        CheckMode -->|False| StandardPivot
        CheckMode -->|True| HybridPivot
        
        StandardPivot --> ConfirmedOnly[确认枢轴点]
        HybridPivot --> ConfirmedAndCandidate[确认+候选枢轴点]
    end
    
    subgraph TriangleDetection [三角形检测]
        FitLines[拟合上下沿线<br/>fit_pivot_line]
        CheckSlope[斜率检查<br/>相向收敛]
        CheckConverge[收敛检查<br/>width_ratio]
        CheckTouch[触碰检查<br/>touches_upper/lower]
        CalcBreakout[突破强度<br/>calc_breakout_strength]
        
        FitLines --> CheckSlope
        CheckSlope --> CheckConverge
        CheckConverge --> CheckTouch
        CheckTouch --> CalcBreakout
    end
    
    subgraph Output [输出]
        Result[ConvergingTriangleResult<br/>检测结果+置信度]
    end
    
    OHLCV --> CheckMode
    Params --> CheckMode
    Mode --> CheckMode
    
    ConfirmedOnly --> FitLines
    ConfirmedAndCandidate --> FitLines
    
    CalcBreakout --> Result
```

---

## 3. 双模式架构对比

```mermaid
flowchart TD
    subgraph StandardMode [标准模式 - 历史回测]
        SM_Input[窗口数据<br/>120天]
        SM_Pivot[pivots_fractal<br/>k=15]
        SM_Range[可检测范围<br/>索引15-104<br/>共90天]
        SM_Blind[盲区30天<br/>前15+后15]
        SM_Quality[枢轴点质量<br/>高★★★★★]
        SM_Lag[确认滞后<br/>15天]
        
        SM_Input --> SM_Pivot
        SM_Pivot --> SM_Range
        SM_Pivot --> SM_Blind
        SM_Range --> SM_Quality
        SM_Blind --> SM_Lag
    end
    
    subgraph RealtimeMode [实时模式 - 实时选股]
        RT_Input[窗口数据<br/>120天]
        RT_Pivot[pivots_fractal_hybrid<br/>k=15, flex=5]
        RT_Confirmed[确认枢轴点<br/>索引15-104]
        RT_Candidate[候选枢轴点<br/>索引115-119]
        RT_Quality1[确认质量高<br/>★★★★★]
        RT_Quality2[候选质量中<br/>★★★☆☆]
        RT_NoLag[无滞后<br/>捕获最新]
        
        RT_Input --> RT_Pivot
        RT_Pivot --> RT_Confirmed
        RT_Pivot --> RT_Candidate
        RT_Confirmed --> RT_Quality1
        RT_Candidate --> RT_Quality2
        RT_Candidate --> RT_NoLag
    end
    
    StandardMode -.切换.-> RealtimeMode
```

---

## 4. 数据流架构

```mermaid
flowchart TD
    subgraph DataSource [数据源]
        OpenPKL[open.pkl]
        HighPKL[high.pkl]
        LowPKL[low.pkl]
        ClosePKL[close.pkl]
        VolumePKL[volume.pkl]
    end
    
    subgraph DataLoad [数据加载]
        LoadFunc[load_ohlcv_from_pkl]
        Matrix[矩阵数据<br/>shape: stocks×days]
        Metadata[元数据<br/>dates/tkrs/names]
    end
    
    subgraph Detection [批量检测]
        Loop[循环检测<br/>每股票×每日]
        Window[滑动窗口<br/>120天]
        SingleDetect[单点检测]
        ResultList[结果列表]
    end
    
    subgraph Processing [结果处理]
        DataFrame[转DataFrame]
        AddMeta[添加元数据<br/>代码/名称/日期]
        Filter[筛选过滤]
        Sort[排序]
    end
    
    subgraph Export [导出]
        CSV_All[all_results.csv<br/>完整结果]
        CSV_Up[strong_breakout_up.csv<br/>向上突破]
        CSV_Down[strong_breakout_down.csv<br/>向下突破]
    end
    
    OpenPKL --> LoadFunc
    HighPKL --> LoadFunc
    LowPKL --> LoadFunc
    ClosePKL --> LoadFunc
    VolumePKL --> LoadFunc
    
    LoadFunc --> Matrix
    LoadFunc --> Metadata
    
    Matrix --> Loop
    Loop --> Window
    Window --> SingleDetect
    SingleDetect --> ResultList
    
    ResultList --> DataFrame
    Metadata --> AddMeta
    DataFrame --> AddMeta
    AddMeta --> Filter
    Filter --> Sort
    
    Sort --> CSV_All
    CSV_All --> CSV_Up
    CSV_All --> CSV_Down
```

---

## 5. 模块依赖关系

```mermaid
flowchart TB
    subgraph Core [核心模块 src/]
        CT[converging_triangle.py<br/>核心算法实现]
        
        subgraph CTComponents [组件]
            Params[ConvergingTriangleParams<br/>参数类]
            Result[ConvergingTriangleResult<br/>结果类]
            PivotFunc[枢轴点检测函数]
            DetectFunc[检测函数]
            BatchFunc[批量检测函数]
        end
    end
    
    subgraph Scripts [脚本模块 scripts/]
        Config[triangle_config.py<br/>配置管理]
        Run[run_converging_triangle.py<br/>批量运行]
        Report[report_converging_triangles.py<br/>报告生成]
        Plot[plot_converging_triangles.py<br/>图表绘制]
        Pipeline[pipeline_converging_triangle.py<br/>流水线]
        Test[test_realtime_mode.py<br/>测试验证]
    end
    
    subgraph Docs [文档 docs/]
        UserGuide[使用指南]
        TechDoc[技术文档]
        ArchDoc[架构文档]
    end
    
    CT --> Params
    CT --> Result
    CT --> PivotFunc
    CT --> DetectFunc
    CT --> BatchFunc
    
    Config --> Run
    Config --> Report
    Config --> Plot
    
    Run --> DetectFunc
    Run --> BatchFunc
    Report --> Config
    Plot --> DetectFunc
    
    Pipeline --> Run
    Pipeline --> Report
    Pipeline --> Plot
    
    Test --> PivotFunc
    Test --> DetectFunc
    
    Core -.文档说明.-> Docs
    Scripts -.文档说明.-> Docs
```

---

## 6. 枢轴点检测架构

```mermaid
flowchart TB
    subgraph Input [输入]
        High[high数组<br/>最高价]
        Low[low数组<br/>最低价]
        K[参数k<br/>窗口大小]
        FlexZone[flexible_zone<br/>灵活区域]
    end
    
    subgraph StandardDetection [标准检测 pivots_fractal]
        SD_Loop[遍历范围k到n-k]
        SD_CheckHigh{high[i]==max?}
        SD_CheckLow{low[i]==min?}
        SD_AddHigh[添加高点枢轴]
        SD_AddLow[添加低点枢轴]
        
        SD_Loop --> SD_CheckHigh
        SD_Loop --> SD_CheckLow
        SD_CheckHigh -->|Yes| SD_AddHigh
        SD_CheckLow -->|Yes| SD_AddLow
    end
    
    subgraph HybridDetection [混合检测 pivots_fractal_hybrid]
        HD_Confirmed[确认枢轴点<br/>完整窗口k到n-k]
        HD_Candidate[候选枢轴点<br/>灵活区域n-flex到n]
        
        HD_Loop1[标准范围遍历]
        HD_Loop2[灵活区域遍历]
        
        HD_Check1{完整窗口检查}
        HD_Check2{缩短窗口检查}
        
        HD_Loop1 --> HD_Check1
        HD_Loop2 --> HD_Check2
        
        HD_Check1 --> HD_Confirmed
        HD_Check2 --> HD_Candidate
    end
    
    subgraph Output [输出]
        Std_PH[标准:高点数组]
        Std_PL[标准:低点数组]
        
        Hyb_ConfPH[混合:确认高点]
        Hyb_ConfPL[混合:确认低点]
        Hyb_CandPH[混合:候选高点]
        Hyb_CandPL[混合:候选低点]
    end
    
    High --> StandardDetection
    Low --> StandardDetection
    K --> StandardDetection
    
    High --> HybridDetection
    Low --> HybridDetection
    K --> HybridDetection
    FlexZone --> HybridDetection
    
    SD_AddHigh --> Std_PH
    SD_AddLow --> Std_PL
    
    HD_Confirmed --> Hyb_ConfPH
    HD_Confirmed --> Hyb_ConfPL
    HD_Candidate --> Hyb_CandPH
    HD_Candidate --> Hyb_CandPL
```

---

## 7. 配置管理架构

```mermaid
flowchart LR
    subgraph ConfigFile [triangle_config.py]
        subgraph Params [检测参数]
            Window[window=120<br/>检测窗口]
            PivotK[pivot_k=15<br/>枢轴周期]
            Shrink[shrink_ratio=0.6<br/>收敛比]
            Break[break_tol=0.005<br/>突破阈值]
        end
        
        subgraph Mode [模式配置]
            RTMode[REALTIME_MODE<br/>True/False]
            FlexZone[FLEXIBLE_ZONE<br/>灵活区域大小]
        end
        
        subgraph Data [数据配置]
            RecentDays[RECENT_DAYS<br/>计算范围]
            DisplayWin[DISPLAY_WINDOW<br/>显示范围]
        end
        
        subgraph Output [输出配置]
            OnlyValid[ONLY_VALID<br/>仅有效结果]
            Verbose[VERBOSE<br/>详细日志]
        end
    end
    
    subgraph Scripts [脚本使用]
        Run[run_converging_triangle.py]
        Report[report_converging_triangles.py]
        Plot[plot_converging_triangles.py]
    end
    
    Params --> Run
    Mode --> Run
    Data --> Run
    Output --> Run
    
    Params --> Plot
    Data --> Plot
    
    Output --> Report
```

---

## 8. 流水线执行流程

```mermaid
flowchart TD
    Start([开始执行]) --> Init[初始化配置]
    
    Init --> Step1{步骤1:批量检测}
    
    Step1 -->|--skip-detection| Skip1[跳过检测]
    Step1 -->|执行| Load[加载PKL数据]
    
    Load --> Detect[批量检测<br/>detect_converging_triangle_batch]
    Detect --> SaveCSV[保存CSV结果]
    
    Skip1 --> Step2{步骤2:生成报告}
    SaveCSV --> Step2
    
    Step2 -->|--skip-report| Skip2[跳过报告]
    Step2 -->|执行| ReadCSV[读取CSV]
    
    ReadCSV --> Filter[筛选强突破]
    Filter --> GenReport[生成Markdown报告]
    
    Skip2 --> Step3{步骤3:绘制图表}
    GenReport --> Step3
    
    Step3 -->|--skip-plot| Skip3[跳过图表]
    Step3 -->|执行| LoadData[加载数据和结果]
    
    LoadData --> DrawLoop[循环绘制图表]
    DrawLoop --> SavePNG[保存PNG文件]
    
    Skip3 --> Summary[输出执行总结]
    SavePNG --> Summary
    
    Summary --> End([执行完成])
    
    style Step1 fill:#e1f5ff
    style Step2 fill:#e1f5ff
    style Step3 fill:#e1f5ff
```

---

## 9. 关键技术决策

### 9.1 枢轴点检测

**标准模式（pivots_fractal）**
- 严格要求：左右各k天完整数据
- 优点：枢轴点质量高，稳定可靠
- 缺点：最近k天无法检测（15天滞后）
- 适用：历史回测、策略验证

**实时模式（pivots_fractal_hybrid）**
- 灵活窗口：候选区域右边数据可不完整
- 优点：无滞后，捕获最新转折点
- 缺点：候选枢轴点置信度较低
- 适用：实时选股、盘后快速筛选

### 9.2 相向收敛约束

防止下降/上升通道被误判为三角形：

```python
# 检查是否同向运动
both_descending = (a_u < -0.01) and (a_l < -0.01)  # 都向下
both_ascending = (a_u > 0.01) and (a_l > 0.01)      # 都向上

if both_descending or both_ascending:
    return invalid_result  # 拒绝通道形态
```

### 9.3 突破强度计算

加权求和 + tanh归一化：

- **价格突破分（60%）**: tanh(突破幅度 × 15)
- **收敛分（25%）**: 1 - width_ratio
- **成交量分（15%）**: min(1, volume_ratio - 1)

---

## 10. 性能优化策略

### 10.1 数据处理

- 使用 NumPy 向量化操作
- 预先过滤 NaN 值
- 批量处理减少函数调用

### 10.2 内存管理

- 滑动窗口避免全量复制
- DataFrame 延迟创建
- 大文件流式处理

### 10.3 并行潜力

当前串行处理，未来可优化：
- 股票级并行（多进程）
- 日期级并行（多线程）
- GPU 加速（矩阵运算）

---

## 11. 扩展性设计

### 11.1 新增形态

```python
# 遵循相同接口
def detect_xxx_pattern(
    high, low, close, volume,
    params,
    real_time_mode=False
) -> PatternResult:
    pass
```

### 11.2 新增数据源

```python
# 实现统一加载接口
def load_from_xxx(data_dir) -> tuple:
    # 返回 (ohlcv, dates, codes, names)
    pass
```

### 11.3 新增输出格式

```python
# 添加导出器
def export_to_xxx(df, output_path):
    pass
```

---

## 12. 部署架构（未来）

```mermaid
flowchart TB
    subgraph DataSource [数据源]
        DB[(实时数据库)]
        API[行情API]
    end
    
    subgraph Schedule [调度层]
        Cron[定时任务<br/>盘后执行]
        Trigger[触发器<br/>实时监控]
    end
    
    subgraph Compute [计算层]
        Worker1[Worker 1<br/>标准模式回测]
        Worker2[Worker 2<br/>实时模式选股]
    end
    
    subgraph Storage [存储层]
        ResultDB[(结果数据库)]
        Cache[Redis缓存]
    end
    
    subgraph Service [服务层]
        WebAPI[Web API]
        Report[报告服务]
        Alert[告警服务]
    end
    
    DB --> Worker1
    API --> Worker2
    
    Cron --> Worker1
    Trigger --> Worker2
    
    Worker1 --> ResultDB
    Worker2 --> Cache
    
    ResultDB --> WebAPI
    Cache --> WebAPI
    
    WebAPI --> Report
    WebAPI --> Alert
```

---

## 13. 目录结构映射

```
technical-patterns-lab/
│
├── src/                          # 核心算法层
│   └── converging_triangle.py   # 主算法文件
│       ├── 数据类
│       │   ├── ConvergingTriangleParams
│       │   └── ConvergingTriangleResult
│       ├── 枢轴点检测
│       │   ├── pivots_fractal (标准)
│       │   └── pivots_fractal_hybrid (实时)
│       ├── 边界拟合
│       │   └── fit_pivot_line
│       ├── 单点检测
│       │   └── detect_converging_triangle
│       └── 批量检测
│           └── detect_converging_triangle_batch
│
├── scripts/                      # 脚本层
│   ├── triangle_config.py       # 配置管理
│   ├── run_converging_triangle.py      # 批量检测
│   ├── report_converging_triangles.py  # 报告生成
│   ├── plot_converging_triangles.py    # 图表绘制
│   ├── pipeline_converging_triangle.py # 流水线
│   └── test_realtime_mode.py          # 测试验证
│
├── data/                         # 数据层
│   ├── open.pkl
│   ├── high.pkl
│   ├── low.pkl
│   ├── close.pkl
│   └── volume.pkl
│
├── outputs/                      # 输出层
│   └── converging_triangles/
│       ├── all_results.csv
│       ├── strong_breakout_up.csv
│       ├── strong_breakout_down.csv
│       ├── report.md
│       └── charts/*.png
│
└── docs/                         # 文档层
    ├── 系统架构.md (本文档)
    ├── 实时模式使用指南.md
    ├── 方案4-混合策略详解.md
    └── ...
```

---

## 14. 版本演进

### v1.0 - 基础检测
- 标准枢轴点检测
- 对称三角形识别
- 基础突破判断

### v2.0 - 相向收敛约束
- 过滤下降/上升通道
- 提高检测精度

### v3.0 - 方案4混合策略（当前）
- 实时模式支持
- 混合枢轴点检测
- 候选点置信度管理

### v4.0 - 未来规划
- 多形态支持
- 实时数据接入
- Web服务化部署

---

## 总结

本系统采用**分层架构**设计，核心算法与应用脚本分离，通过配置文件统一管理参数。方案4的实施引入了**双模式架构**，在保持向后兼容的同时，提供了实时选股能力。

**核心优势**：
- 模块化设计，易于扩展
- 配置驱动，灵活调整
- 双模式支持，适应不同场景
- 完整的测试和文档体系

**适用场景**：
- 标准模式：历史回测、策略验证
- 实时模式：实时选股、盘后筛选