# ePub Bilingual Translator - Architecture & Data Flow (Revised)

本文档详细描述了程序处理一个 EPUB 文件的完整生命周期。整个流程旨在实现**结构稳定性**（不丢段落）与**内容精细度**（不丢格式）的最佳平衡。

## High Level Data Flow

```mermaid
graph TD
    Input[Input EPUB] --> Cleaner[EpubCleaner]
    Cleaner --> CleanedEPUB[1. Cleaned EPUB Temp]
    
    CleanedEPUB --> Profiler[Book Profiler]
    Profiler -->|Identify| Profile[Book Profile / Style]
    
    CleanedEPUB --> Extractor[FineGrainedExtractor]
    
    subgraph Extraction
        Extractor -->|Step 1: P/H Tags| P[Source Paragraph]
        P -->|Step 2: FormatExtract| PhText[Analyzed Text]
        PhText -->|Register| Manifest[Manifest DB]
    end
    
    Manifest -->|Batch| LLM[LLM Translation]
    Profile -->|Prompt Context| LLM
    
    LLM -->|Translation| Manifest
    
    Manifest --> Restorer[FormatRestorer]
    Restorer -->|Reconstruct HTML| TargetHtml[Target HTML]
    
    CleanedEPUB --> Backfiller[Backfill Engine]
    TargetHtml --> Backfiller
    
    Backfiller -->|Bilingual/Chinese Mode| DOM[Final DOM]
    DOM --> Builder[BilingualBuilder]
    Builder --> Output[Output EPUB]
```

## Detailed Workflow

### 1. Preprocessing (预处理)
**模块**: `src/epub_cleaner.py`
*   **Flatten Structure**: 消除嵌套 `div`，统一转为 `<p>`，消除结构性漏译风险。
*   **Auto-Fix**: 修复 TOC 死链、缺失 UID、由于 `ebooklib` bug 导致的样式丢失。
*   **Result**: 产生一个标准的临时文件，后续所有操作基于此文件，不再受原始糟糕格式影响。

### 2. Intelligent Extraction (智能提取)
**模块**: `src/fine_grained_extractor.py` + `src/format_extractor.py`

#### A. 结构层 (Macro)
使用 `FineGrainedExtractor` 锁定所有正文元素 (`p`, `h1`-`h6`)。
*   **Filter**: 排除页码、页眉脚。
*   **Optimization**: 针对目录章节，识别 **罗马数字 (I, II)**、**单独数字 (1, 2)**、**修饰符 (***)**，这些内容**不送翻译**，直接在回填时保留原文，以维持原书排版美感。

#### B. 内容层 (Micro)
对每个提取的段落调用 `FormatExtractor`：
*   **Inline Style**: 将 `<b>`, `<i>` 转为配对占位符 `φ1φ...φ/1φ`。
*   **Formula Protection**: 识别 $E=mc^2$ 等数学公式，保护为不可变占位符。
*   **Drop Cap Handling**: 
    - 原始: `<span class="dropcap">T</span>he`
    - 提取给 LLM: "The" (完整单词，无格式干扰)
    - 记录: Prefix 包含 Drop Cap 样式。

### 3. Manifest Management (清单管理)
**模块**: `src/manifest_manager.py`
Manifest 是系统的**核心状态中心 (Source of Truth)**。
*   **作用**: 解耦提取和翻译。提取器只管往 Manifest 填数据，翻译器只管从 Manifest 取数据。
*   **Persistence**: 支持中断续传，翻译进度实时保存。

### 4. Translation with Profiling (翻译)
**模块**: `src/book_profiler.py` & `src/translator.py`
*   **Profiling**: 在翻译前，抽取部分文本分析书籍的类型（技术、小说、诗歌）、核心术语和语言风格，生成 `System Prompt`。
*   **Translation**: 这是纯文本层面的转换，LLM 处理的是带有 `φ` 占位符的文本。

### 5. Robust Restoration (健壮还原)
**模块**: `src/format_restorer.py`
负责将 LLM 返回的文本还原为 HTML。
*   **Drop Cap Logic**: 
    - **原文回填**: 需要 Prefix `<span class="dropcap">T</span>`。
    - **译文回填**: **丢弃** Drop Cap Prefix。中文不需要首字母下沉，否则会出现 "T这本书..." 的怪诞结果。
*   **Error Handling**:
    - **Missing Placeholders**: 如果 LLM 丢了 `φ1φ`，自动在末尾补全或报错重试。
    - **Hallucinated Placeholders**: 移除 LLM 臆造的不存在 ID。

### 6. Backfill Strategy (回填策略)
**模块**: `src/fine_grained_extractor.py` (backfill method)
支持多种模式，且**严格遵循一对一 (One-to-One) 映射**，绝不依赖顺序，而是依赖元素的内存引用或唯一 ID。

*   **Mode A: Bilingual (双语)**
    - 保留原文 DOM。
    - 在原文后 `append` 一个新元素 `<p class="translation">译文</p>`。
    - 样式继承：译文元素复制原文的 `margin`, `text-align` 等关键样式。

*   **Mode B: Chinese Only (仅中文)**
    - **Replace**: 直接用译文元素替换原文元素。
    - **Drop Cap 适配**: 此时译文通常为普通段落，不再保留首字母下沉样式，以符合中文排版习惯。

### 7. Assembly (组装)
**模块**: `src/bilingual_builder.py`
将内存中的 DOM 序列化，重新打包资源，生成最终 EPUB。