# 核心功能

<cite>
**本文档中引用的文件**   
- [extractor.py](file://backend/extractor.py)
- [scripter.py](file://backend/scripter.py)
- [media_fetcher.py](file://backend/media_fetcher.py)
- [data_builder.py](file://backend/data_builder.py)
- [index.ts](file://src/index.ts)
- [Root.tsx](file://src/Root.tsx)
- [types.ts](file://src/types.ts)
- [main.py](file://main.py)
- [PROJECT_README.md](file://PROJECT_README.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介
本项目是一个混合型Python/Node.js系统，能够将静态的财务规划报告（PDF）和原始访谈视频自动转换为动态、个性化的3-5分钟解说视频。系统整合了动画图表、AI生成的日语解说、情境化素材片段（B-Roll）以及同步的访谈剪辑，为用户提供直观的财务规划可视化服务。整个流程由Python后端驱动，利用AI模型进行数据提取和内容生成，再通过Remotion前端引擎完成视频渲染。

## 项目结构
项目采用分层架构，清晰地分离了数据处理逻辑与视频渲染逻辑。后端（Python）负责数据提取、AI生成和模拟计算，前端（Node.js/TypeScript）则专注于程序化视频渲染。两者通过一个名为`render_props.json`的数据契约文件进行通信。

```mermaid
graph TD
subgraph "Backend (Python)"
A[extractor.py] --> B[scripter.py]
B --> C[media_fetcher.py]
C --> D[data_builder.py]
D --> E[main.py]
end
subgraph "Frontend (Node.js/TypeScript)"
F[index.ts]
G[Root.tsx]
H[CashFlowChart.tsx]
I[LifePlanChart.tsx]
end
E --> |生成| J[render_props.json]
J --> |消费| F
```

**Diagram sources**
- [PROJECT_README.md](file://PROJECT_README.md#L14-L32)

**Section sources**
- [PROJECT_README.md](file://PROJECT_README.md#L50-L79)

## 核心组件
系统的核心功能由五个关键模块构成：PDF/视频数据提取器、AI日语解说脚本生成器、B-Roll素材自动获取器、财务数据模拟与图表构建器以及最终的视频渲染合成器。这些模块协同工作，形成一个从原始输入到最终视频输出的完整流水线。

**Section sources**
- [main.py](file://main.py#L5-L11)
- [PROJECT_README.md](file://PROJECT_README.md#L7-L12)

## 架构概述
系统的整体架构遵循“后端处理，前端渲染”的模式。Python后端作为“导演”，负责协调所有AI和数据处理任务；而Node.js前端作为“引擎”，专注于高质量的视频合成。`main.py`是整个流水线的入口点，它按顺序调用各个模块，最终生成`render_props.json`文件，触发Remotion进行视频渲染。

```mermaid
graph TD
A[PDF/视频输入] --> B[extractor.py]
B --> C[scripter.py]
C --> D[media_fetcher.py]
D --> E[data_builder.py]
E --> F[render_props.json]
F --> G[Remotion渲染]
G --> H[最终视频输出]
```

**Diagram sources**
- [main.py](file://main.py#L5-L11)
- [PROJECT_README.md](file://PROJECT_README.md#L16-L32)

## 详细组件分析

### PDF/视频数据提取器 (extractor.py)
该模块负责解析输入的PDF报告和视频文件，从中提取结构化数据。它利用Google Gemini Pro API来解析日语财务报告，并使用OpenAI Whisper API对访谈视频进行转录，获取时间戳和关键词。

**Section sources**
- [extractor.py](file://backend/extractor.py#L1-L84)

### AI日语解说脚本生成器 (scripter.py)
此模块是AI驱动内容生成的核心。它接收从PDF和视频中提取的数据，利用Google Gemini Pro生成自然流畅的日语解说脚本。脚本被划分为多个片段，每个片段都包含预计的持续时间，为后续的视频同步提供依据。

```mermaid
classDiagram
class ScriptGenerator {
+api_key : str
+__init__(api_key : Optional[str])
+generate(pdf_data : Dict, video_data : Optional[Dict], style : str) : Dict
-_build_prompt(pdf_data : Dict, style : str) : str
}
```

**Diagram sources**
- [scripter.py](file://backend/scripter.py#L14-L69)

**Section sources**
- [scripter.py](file://backend/scripter.py#L1-L69)

### B-Roll素材自动获取器 (media_fetcher.py)
该模块根据生成的脚本内容，自动从Pexels API获取相关的背景视频素材（B-Roll）。它会从脚本中提取关键词，将日语关键词翻译成英语，然后搜索并下载匹配的视频片段，为视频增添视觉吸引力。

```mermaid
sequenceDiagram
participant Script as 脚本
participant Fetcher as MediaFetcher
participant Pexels as Pexels API
Script->>Fetcher : 提供关键词列表
Fetcher->>Fetcher : 翻译关键词(日->英)
Fetcher->>Pexels : 搜索视频
Pexels-->>Fetcher : 返回视频URL
Fetcher->>Fetcher : 下载视频到本地
Fetcher-->>Script : 返回本地文件路径
```

**Diagram sources**
- [media_fetcher.py](file://backend/media_fetcher.py#L15-L72)

**Section sources**
- [media_fetcher.py](file://backend/media_fetcher.py#L1-L72)

### 财务数据模拟与图表构建器 (data_builder.py)
这是数据驱动视频渲染的关键。该模块包含一个财务模拟引擎，能够基于提取的财务数据，模拟未来几十年的资产耗尽和现金流情况。它考虑了通货膨胀、投资回报和债务复利等因素，生成精确的年度财务快照，并将其格式化为Remotion图表组件所需的格式。

```mermaid
classDiagram
class FinancialSimulator {
+config : Dict
+inflation_rate : float
+deficit_interest_rate : float
+investment_return : float
+__init__(config : Optional[Dict])
+simulate_timeline(...) : List[Dict]
+build_cashflow_data(timeline : List[Dict]) : List[Dict]
-_get_event_cost(...) : float
-_get_event_labels(...) : List[str]
}
```

**Diagram sources**
- [data_builder.py](file://backend/data_builder.py#L15-L200)

**Section sources**
- [data_builder.py](file://backend/data_builder.py#L1-L200)

### 视频渲染合成器 (src/index.ts)
前端部分使用Remotion库进行程序化视频渲染。`index.ts`是入口文件，它注册了`Root.tsx`作为根组件。`Root.tsx`中定义了多个`<Composition>`，每个都对应一个视频片段（如资产耗尽图、现金流图），并将`render_props.json`中的数据作为属性传递给相应的React组件。

```mermaid
flowchart TD
A[index.ts] --> B[Root.tsx]
B --> C[Composition: LifePlanChart]
B --> D[Composition: CashFlowChart]
B --> E[Composition: DualChartView]
C --> F[LifePlanChart.tsx]
D --> G[CashFlowChart.tsx]
E --> H[DualChartView.tsx]
```

**Diagram sources**
- [src/index.ts](file://src/index.ts#L1-L6)
- [src/Root.tsx](file://src/Root.tsx#L1-L68)

**Section sources**
- [src/index.ts](file://src/index.ts#L1-L6)
- [src/Root.tsx](file://src/Root.tsx#L1-L68)

## 依赖分析
系统的主要依赖关系清晰地体现在`main.py`的流水线设计中。`VideoGeneratorPipeline`类按顺序调用`extract_pdf`、`generate_script`、`fetch_broll`和`build_render_props`等方法，形成了一个强依赖的线性流程。外部API密钥通过环境变量注入，确保了配置的安全性。

```mermaid
graph TD
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.extract_pdf[extract_pdf]
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.generate_script[generate_script]
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.fetch_broll[fetch_broll]
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.build_render_props[build_render_props]
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.render_video[render_video]
```

**Diagram sources**
- [main.py](file://main.py#L48-L83)

**Section sources**
- [main.py](file://main.py#L33-L305)

## 性能考虑
虽然代码中包含了一些TODO注释，表明部分功能尚未完全实现，但其架构设计已考虑到性能。例如，`media_fetcher.py`中提到了翻译缓存，以避免重复的API调用。财务模拟使用了数学公式进行高效计算。对于视频渲染，Remotion支持并行渲染和缓存，可以显著缩短生成时间。

## 故障排除指南
常见问题主要集中在API密钥和环境配置上。确保`.env`文件存在且包含有效的`GEMINI_API_KEY`、`OPENAI_API_KEY`和`PEXELS_API_KEY`。如果遇到渲染失败，检查`npm install`是否成功，并确认`frontend/src/`目录结构正确。对于PDF解析失败，需确认PDF文件可读且未加密。

**Section sources**
- [PROJECT_README.md](file://PROJECT_README.md#L218-L231)

## 结论
该项目成功地将AI驱动的内容生成与数据驱动的视频渲染相结合，创造了一个自动化视频生成的解决方案。通过模块化的设计，每个核心功能都职责明确，易于维护和扩展。未来的工作应集中在实现`TODO`中提到的功能，如Gemini和Whisper的实际集成，并优化数据流以处理更复杂的财务场景。