lesson-highlights/docs/ARCHITECTURE.md

架构设计

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。