## 一、项目定位与核心目标

**产品名称**：建议命名为 **"ReadFlow"** 或 **"墨阅"**（强调沉浸式阅读体验）

**核心定位**：面向开发者和技术阅读者的高性能桌面阅读工具，兼顾专业文档阅读与休闲电子书阅读

---

## 二、功能需求完善

### 2.1 电子书阅读模块

| 功能项 | 详细需求 | 优先级 |
|--------|----------|--------|
| **格式支持** | PDF（核心）、EPUB、MOBI、AZW3、TXT | P0 |
| **PDF渲染** | 基于PDFium或mupdf，支持矢量缩放、文本选择、搜索高亮 | P0 |
| **排版引擎** | 自定义CSS样式系统，支持主题（深色/浅色/羊皮纸/自定义） | P0 |
| **微信读书式UI** | 仿真翻页/滑动翻页、进度条、章节导航、字体/字号/行距调节 | P0 |
| **阅读进度** | 多设备同步（可选）、阅读时间统计、书签/笔记管理 | P1 |
| **批注系统** | 高亮、下划线、波浪线、页边笔记、导出批注为Markdown | P1 |

### 2.2 翻译功能模块

**画词翻译（P0）**
- 双击/长按选词，悬浮显示翻译（Google Translate/DeepL/本地词典）
- 支持OCR识别扫描版PDF文字
- 翻译结果支持朗读（TTS）

**全文双语对照（P1）**
- 分栏对照模式：左原文右译文
- 行内对照模式：段落交替显示
- 支持EPUB/PDF整书翻译缓存
- 翻译API：DeepL API、Google Cloud Translation、本地LLM（Ollama）

### 2.3 Markdown阅读模块

| 模式 | 说明 | 快捷键 |
|------|------|--------|
| **原文模式** | 纯文本编辑，语法高亮 | Ctrl+1 |
| **渲染模式** | 类Typora的实时预览 | Ctrl+2 |
| **对照模式** | 左右分屏，左侧编辑右侧实时渲染 | Ctrl+3 |

**增强功能**：
- 支持YAML frontmatter解析（书籍元数据）
- 支持Mermaid图表、数学公式（KaTeX/MathJax）
- 图片本地路径自动适配
- 大纲导航（TOC）自动生成

### 2.4 代码阅读模块

**格式化与显示（P0）**
- 支持50+语言语法高亮（基于tree-sitter或syntect）
- 自动检测文件编码（UTF-8/GBK/UTF-16等）
- 代码折叠、缩进向导线、minimap概览

**智能格式化（P1）**
- 集成prettier/rustfmt/gofmt等格式化工具
- 快捷键触发格式化（Ctrl+Shift+F）
- 格式化前自动保存备份点
- 支持`.editorconfig`读取

**代码阅读增强**
- 符号跳转（ctags/LSP支持）
- 文件目录树侧边栏
- 多标签页管理
- 代码搜索（当前文件/当前目录/全局）

---

## 三、非功能需求（NFR）

### 3.1 性能指标（Rust+Dioxus优势体现）

| 指标 | 目标值 | 实现策略 |
|------|--------|----------|
| **冷启动时间** | < 500ms | 懒加载非核心模块，使用tokio异步初始化 |
| **大文件打开** | 100MB PDF < 2s | 内存映射+分页加载，虚拟列表渲染 |
| **内存占用** | 空闲<150MB，阅读中<300MB | 引用计数管理，大文件分块缓存 |
| **翻页延迟** | < 16ms（60fps） | GPU加速渲染，预加载相邻页 |
| **搜索速度** | 10万字文档<100ms | 后台索引构建，使用tantivy搜索引擎 |

### 3.2 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                        UI Layer (Dioxus)                    │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │
│  │  EPUB View  │ │  PDF View   │ │  MD Editor  │ │ Code    │ │
│  │  (自定义)    │ │ (PDFium)    │ │ (Monaco/CM) │ │ Viewer  │ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ │
├─────────────────────────────────────────────────────────────┤
│                      Core Services                          │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │
│  │  Document   │ │  Translation│ │  Formatting │ │  Config │ │
│  │  Engine     │ │  Service    │ │  Service    │ │  Manager│ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ │
├─────────────────────────────────────────────────────────────┤
│                      Infrastructure                           │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │
│  │  File I/O   │ │  Cache      │ │  Plugin     │ │  Event  │ │
│  │  (tokio)    │ │  (sled/rocksdb)│  System    │ │  Bus    │ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### 3.3 技术栈细化

| 层级 | 技术选型 | 说明 |
|------|----------|------|
| **框架** | Dioxus 0.5+（桌面端） | 类React的Rust GUI框架，支持WebView/原生渲染 |
| **构建** | Tauri（可选）或纯Dioxus | Tauri提供原生API，Dioxus提供纯Rust方案 |
| **PDF渲染** | pdfium-render（Rust绑定）或mupdf | pdfium-render更稳定，mupdf更轻量 |
| **EPUB解析** | epub-rs | 纯Rust实现，支持EPUB3 |
| **Markdown** | pulldown-cmark + syntect | 高性能解析+语法高亮 |
| **代码编辑** | CodeMirror 6（WASM）或自定义 | 需评估Rust原生编辑器方案 |
| **数据库** | sled或rusqlite | 配置、书签、阅读进度存储 |
| **样式系统** | Tailwind CSS + 自定义CSS变量 | Dioxus支持CSS-in-Rust |
| **国际化** | fluent-rs | Mozilla的本地化系统 |

---

## 四、UI/UX设计规范

### 4.1 微信读书式界面要素

**阅读界面布局**：
```
┌────────────────────────────────────────┐
│ [菜单] 书名                    [搜索] │
├────────────────────────────────────────┤
│                                        │
│           正文阅读区域                  │
│      （自定义字体/背景/边距）             │
│                                        │
├────────────────────────────────────────┤
│ 章节目录 │ 进度条（可拖拽） │ 设置/主题 │
└────────────────────────────────────────┘
```

**设置面板**（底部弹出）：
- 字号调节（12px-24px，步进2px）
- 字体选择（系统字体+内置开源字体）
- 行距（1.0/1.2/1.5/1.8/2.0）
- 边距（窄/中/宽/自定义）
- 翻页动画（无/滑动/仿真）
- 背景色（预设5种+自定义）

### 4.2 翻译交互流程

```
选词/划句 → 悬浮按钮出现 → 点击翻译 → 侧边栏/弹窗显示结果
                              ↓
                    添加到生词本 → 导出Anki/CSV
```

---

## 五、开发路线图

### Phase 1: MVP
- [ ] 项目脚手架（Dioxus+Tauri）
- [ ] PDF基础阅读（渲染、缩放、滚动）
- [ ] 基础主题系统（深色/浅色）
- [ ] 文件浏览器（最近阅读、书架）

### Phase 2: 核心功能
- [ ] EPUB/MOBI支持
- [ ] Markdown渲染模式
- [ ] 画词翻译（集成一个翻译API）
- [ ] 批注/书签系统

### Phase 3: 高级功能
- [ ] 代码格式化集成
- [ ] 全文双语对照
- [ ] 阅读进度同步（WebDAV/自建服务）
- [ ] 插件系统（WASM插件）

### Phase 4: 优化与生态
- [ ] 性能优化（大文件处理）
- [ ] 社区主题市场
- [ ] 移动端适配调研（Dioxus支持移动端）

### 交付物
- [ ] 源代码（Rust 项目，包含完整的 Cargo.toml 和文档）。
- [ ] 跨平台安装包（Windows .exe，macOS .dmg，Linux .deb/.AppImage）。
- [ ] 用户手册与开发者文档。

---

## 六、关键风险与对策

| 风险 | 影响 | 对策 |
|------|------|------|
| PDF渲染性能 | 大文件卡顿 | 采用分页+瓦片渲染，限制内存缓存池大小 |
| 翻译API成本 | 用户量大时费用高 | 支持本地LLM（Ollama）作为免费替代 |
| 跨平台兼容性 | Windows/macOS/Linux差异 | 优先Windows/Linux，CI多平台测试 |
| Dioxus成熟度 | 框架较新，生态不完善 | 预留Tauri迁移路径，避免深度绑定 |

---

## 七、建议的Rust Crate选型清单

```toml
[dependencies]
# 核心框架
dioxus = { version = "0.5", features = ["desktop"] }
dioxus-router = "0.5"

# 文档处理
pdfium-render = "0.8"      # PDF渲染
epub = "2.0"               # EPUB解析
mobi = "0.2"               # MOBI解析（可选）

# Markdown与代码
pulldown-cmark = "0.9"     # Markdown解析
syntect = "5.1"            # 语法高亮
tree-sitter = "0.20"       # 代码解析（高级功能）

# 基础设施
tokio = { version = "1", features = ["full"] }
sled = "0.34"              # 嵌入式KV存储
serde = { version = "1.0", features = ["derive"] }
config = "0.14"            # 配置管理

# 工具
anyhow = "1.0"             # 错误处理
tracing = "0.1"            # 日志
rayon = "1.8"              # 并行计算（搜索/索引）
```

---