# 架构设计

## 1. 技术栈

| 层级 | 技术 | 选型理由 |
|------|------|----------|
| GUI 框架 | PySide6 (Qt for Python) | LGPL 许可，功能完备，信号槽机制适合异步更新 |
| 打包工具 | Nuitka | 编译为 C，性能好，体积小 |
| 状态持久化 | JSON 文件 | 简单，无需数据库依赖 |
| 核心模块 | 复用现有脚本 | video.py, subtitle.py, llm.py, corrections.py |
| 配置格式 | YAML/JSON | 用户友好，可读性好 |

## 2. 项目结构

```
piano-highlight-app/
├── src/
│   ├── __init__.py
│   ├── main.py                 # 应用入口
│   ├── app.py                  # QMainWindow 主窗口
│   ├── gui/                    # GUI 组件
│   │   ├── __init__.py
│   │   ├── config_panel.py     # 配置面板
│   │   ├── progress_view.py    # 进度监控
│   │   ├── title_editor.py     # 标题编辑器
│   │   └── log_view.py         # 日志窗口
│   ├── logic/                  # 业务逻辑
│   │   ├── __init__.py
│   │   ├── config_manager.py   # 配置管理
│   │   ├── pipeline_controller.py  # 流水线控制
│   │   ├── state_manager.py    # 状态管理
│   │   └── worker.py           # 后台工作线程
│   └── core/                   # 核心模块（复用）
│       ├── __init__.py
│       ├── constants.py         # 常量
│       ├── utils.py            # 工具函数
│       ├── video.py            # 视频处理
│       ├── subtitle.py          # 字幕处理
│       ├── llm.py              # LLM 调用
│       └── corrections.py       # 纠错规则
├── assets/                     # 资源文件
│   └── icons/
├── requirements.txt             # 依赖
├── pyproject.toml              # 项目配置
├── nuitka_options.py           # Nuitka 打包配置
└── README.md
```

## 3. 核心类设计

### StateManager（状态管理）

负责状态持久化，支持暂停/恢复。

### PipelineController（流水线控制）

管理处理流程的 6 个步骤：
1. extract - 片段提取
2. transcribe - 语音转录
3. title_correct - 标题生成与纠错
4. generate_subtitles - 字幕生成
5. merge - 片段合并
6. burn - 字幕烧录

### Worker（后台工作线程）

在独立线程中执行流水线，通过信号与 UI 通信。

## 4. 流水线状态机

```
Ready → Extracting → Transcribing → Title Correcting → Generating Subtitles → Merging → Burning → Completed
                    ↑                                              ↓
                    └───────────── 用户可暂停并编辑标题 ─────────────┘
```

## 5. 信号流

| 信号 | 方向 | 说明 |
|------|------|------|
| config_changed | UI → Controller | 配置变更 |
| progress_signal | Worker → UI | 进度更新 |
| titles_ready_signal | Worker → UI | 标题列表准备好 |
| titles_confirmed_signal | UI → Controller | 用户确认的标题 |

## 6. 状态文件格式

JSON 格式，包含配置、流水线状态、clips 列表等。

详见 design.md。