2_Architecture

系统架构

整体架构

FormulaFix 采用分层架构设计：

lib/
├── core/                    # 核心层
│   ├── constants/          # 常量定义
│   ├── parser/             # Markdown/LaTeX 解析器
│   │   ├── formula_extractor.dart  # 公式提取
│   │   └── markdown_parser.dart    # Markdown 解析
│   ├── renderers/          # 渲染器
│   │   ├── svg_ast.dart         # SVG AST
│   │   ├── svg_parser.dart # SVG 解析器
│   │   └── svg_to_pdf.dart      # SVG → PDF
│   ├── router/            # 路由
│   ├── services/          # 核心服务
│   └── utils/             # 工具函数
├── data/                   # 数据层
│   └── models/            # 数据模型
│ └── document.dart  # 文档模型
├── domain/                 # 业务层
│   ├── providers/         # 状态管理 (Riverpod)
│   └── services/ # 业务服务
│       ├── export_service.dart   # 导出服务
│       └── exporters/           # 导出器
│           ├── pdf_exporter.dart      # PDF 导出
│           ├── word_exporter.dart     # Word 导出
│           └── text_exporter.dart # 文本导出
└── presentation/           # 表现层
    ├── screens/           # 页面
    │   ├── editor_screen.dart   # 编辑器
    │   └── file_manager_screen.dart  # 文件管理
    ├── widgets/           # 组件
    │   ├── preview_content.dart  # 预览内容
    │   └── mermaid_host.dart     # Mermaid 图表
    └── theme/             # 主题

核心模块

1. 解析层 (core/parser)

MarkdownParser

• 解析 Markdown 语法
• 提取文档元素（标题、段落、列表、表格、代码块）

FormulaExtractor

• 提取 LaTeX 公式（行内和块级）
• 支持 $...$ 和 $$...$$ 语法

2. 渲染层 (core/renderers)

SvgParser

• SVG AST 解析
• 路径数据提取
• 样式属性解析

SvgToPdf

• SVG 到 PDF 的矢量绘制
• 支持路径、形状、文本
• 字体嵌入

3. 导出层 (domain/services/exporters)

PdfExporter

• 公式预渲染为 PNG
• 页面布局编排
• PDF文档生成

WordExporter

• OOXML 文档构建
• 公式渲染为 PNG
• Mermaid 图表为 SVG

4. 状态管理 (domain/providers)

使用 Riverpod 进行状态管理：

• documentProvider - 当前文档状态
• themeProvider - 主题状态
• exportStateProvider - 导出状态

数据流

用户输入 → MarkdownParser → DocumentElement 树
                              ↓
                        FormulaExtractor
                              ↓
                       公式列表 → FormulaPdfRenderer
                              ↓
                        渲染缓存
                              ↓
                        PdfExporter/WordExporter
                              ↓
                        最终文档

关键设计决策

1. 公式渲染策略

• 公式预渲染到缓存，避免重复渲染
• 使用不同的 pixelRatio 对应 PDF 和 Word
• 失败时提供文本回退

2. SVG 矢量渲染

• 自写 SVG AST 解析器
• PDF 直接绘制矢量路径
• 避免 rasterize 再转 PDF 的质量损失

3. Word 导出编码处理

• UTF-8 编码确保中文正常
• Surrogate pairs特殊处理
• ZIP 头部大小计算修正

---

由 Claude Code 生成