# 架构设计

## 1. 核心原则

**CLI 和 GUI 共用同一套底层类库**，仅在表示层有差异：
- **CLI**：命令行参数输入，日志输出到终端
- **GUI**：PySide6 界面，参数输入界面化，日志输出到文本区

## 2. 项目结构

```
lesson-highlights/
├── src/
│   ├── main.py              # GUI 入口
│   ├── gui.py               # GUI（参数输入 → 调用底层）
│   ├── cli.py               # CLI 入口
│   └── core/                # 共享底层
│       ├── __init__.py
│       ├── ppt_parser.py    # PPT 解析 + LLM clips 提取
│       ├── pipeline.py      # 视频处理流水线
│       ├── subtitle.py      # 字幕生成
│       ├── video.py         # 视频处理（提取/合并/烧录）
│       ├── llm.py           # LLM 调用
│       ├── corrections.py    # 术语纠正
│       ├── constants.py     # 常量配置
│       └── errors.py        # 错误处理
├── config.ini               # API 配置（不提交 git）
├── config.ini.example      # 配置模板
├── start.bat               # GUI 启动器
├── run.bat                 # 通用 CLI 启动器
└── run_lesson1.bat        # 预设课程示例
```

## 3. 核心模块

### `parse_ppt_to_config()`

一键完成 PPT → clips 配置的完整流程：

1. **PPT 解析**：提取文本和知识点
2. **Whisper 转录**：视频 → `full_transcript.json`
3. **LLM 校正**：批量校正 → `corrected_transcript.json`
4. **LLM 提取片段**：根据知识点定位视频片段 → clips
5. **重叠合并**：合并重叠片段

### `Pipeline`

视频处理流水线：

1. **extract**：按时间戳提取片段
2. **transcribe**：逐片段 Whisper 转录
3. **correct_titles**：LLM 标题纠正
4. **generate_subtitles**：生成双轨字幕
5. **merge**：合并片段
6. **burn**：烧录字幕

## 4. 数据流

```
视频 + PPT
    ↓
parse_ppt_to_config()
    ↓
config = {
    "video_src": ...,
    "clips": [{"title": ..., "start": ..., "end": ...}, ...],
    "output_dir": ...,
    "term_corrections": {...}
}
    ↓
Pipeline(config).run()
    ↓
final.mp4
```

## 5. 配置来源

API 配置统一从 `config.ini` 读取，不硬编码在代码中。

CLI 支持参数覆盖：
- `--api-key`
- `--api-host`
- `--verbose`

## 6. 状态持久化

中间结果保存在 `output/intermediates/`：
- `full_transcript.json` - 原始转录
- `corrected_transcript.json` - LLM 校正后
- `ppt_knowledge_and_cleaned.json` - PPT 知识点和清理后文本

复用时检测 checkpoint，避免重复 LLM 调用。