# 项目概述

<cite>
**本文档引用的文件**
- [PROJECT_README.md](file://PROJECT_README.md)
- [main.py](file://main.py)
- [package.json](file://package.json)
- [requirements.txt](file://requirements.txt)
- [remotion.config.ts](file://remotion.config.ts)
- [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts)
- [backend/data_builder.py](file://backend/data_builder.py)
- [backend/scripter.py](file://backend/scripter.py)
- [backend/media_fetcher.py](file://backend/media_fetcher.py)
- [src/LifePlanChart.tsx](file://src/LifePlanChart.tsx)
- [src/CashFlowChart.tsx](file://src/CashFlowChart.tsx)
- [src/Root.tsx](file://src/Root.tsx)
- [tests/test_video_processor.py](file://tests/test_video_processor.py)
</cite>

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

## 简介

AI-video-lifeplan-demo项目是一个混合式Python/Node.js系统，能够自动将静态财务规划PDF报告和访谈视频转换为动态解说视频。该系统结合了AI生成的日语脚本、财务数据可视化图表、B-Roll素材集成和视频片段同步技术，生成个性化的3-5分钟人生规划视频。系统采用前后端分离架构，通过render_props.json文件作为数据契约进行通信。

**Section sources**
- [PROJECT_README.md](file://PROJECT_README.md#L1-L246)

## 项目结构

项目采用清晰的目录结构，分为资产文件、后端模块、前端组件和测试文件。主要目录包括：

- **assets/**: 存储共享资源，包含输入、处理中和输出三个子目录
- **backend/**: Python后端模块，负责数据处理和AI功能
- **frontend/src/**: Node.js/TypeScript前端，使用Remotion进行视频渲染
- **src/**: 核心React组件和类型定义
- **tests/**: 测试文件和测试数据

```mermaid
graph TD
A[项目根目录] --> B[assets]
A --> C[backend]
A --> D[frontend/src]
A --> E[src]
A --> F[tests]
B --> G[0_input]
B --> H[1_processed]
B --> I[2_output]
C --> J[video_processor]
C --> K[__init__.py]
C --> L[data_builder.py]
C --> M[extractor.py]
C --> N[investigate_media_fetch.py]
C --> O[investigate_subtitle_extraction.py]
C --> P[investigate_video_extraction.py]
C --> Q[media_fetcher.py]
C --> R[scripter.py]
D --> S[index.ts]
D --> T[Root.tsx]
D --> U[render-props-types.ts]
D --> V[types.ts]
E --> W[CashFlowChart.tsx]
E --> X[Composition.tsx]
E --> Y[DualChartView.tsx]
E --> Z[LifePlanBarChart.tsx]
E --> AA[LifePlanChart.tsx]
E --> AB[Root.tsx]
E --> AC[index.ts]
E --> AD[mock-cashflow-original.json]
E --> AE[mock-cashflow.json]
E --> AF[mock-data.json]
E --> AG[types.ts]
F --> AH[fixtures]
F --> AI[test_video_cli.py]
F --> AJ[test_video_processor.py]
```

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

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

## 核心组件

系统的核心组件包括Python后端的数据处理模块和Node.js前端的视频渲染组件。后端负责PDF解析、脚本生成、B-Roll获取和财务数据模拟，前端使用Remotion框架将数据渲染为视频。数据通过render_props.json文件在两个系统之间传递，确保了前后端的解耦和灵活性。

**Section sources**
- [main.py](file://main.py#L1-L305)
- [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts#L1-L251)

## 架构概述

系统采用混合式Python/Node.js架构，后端作为指挥中心负责数据处理和AI功能，前端作为渲染引擎负责视频生成。这种架构设计充分利用了Python在AI和数据处理方面的优势，以及Node.js在视频渲染和前端开发方面的优势。

```mermaid
graph TD
A[Python后端] --> |生成| B[render_props.json]
B --> |消费| C[Remotion前端]
A --> D[Google Gemini]
A --> E[OpenAI Whisper]
A --> F[FFmpeg]
A --> G[Pexels API]
C --> H[React 19 + TypeScript]
C --> I[Recharts]
C --> J[Zod]
D --> K[PDF解析]
D --> L[脚本生成]
E --> M[音频转录]
F --> N[视频处理]
G --> O[B-Roll素材]
H --> P[视频渲染]
I --> Q[动态图表]
J --> R[模式验证]
```

**Diagram sources**
- [PROJECT_README.md](file://PROJECT_README.md#L16-L32)
- [package.json](file://package.json#L1-L43)

**Section sources**
- [PROJECT_README.md](file://PROJECT_README.md#L14-L49)

## 详细组件分析

### 后端数据处理分析

后端数据处理模块负责从PDF报告中提取财务数据，并生成用于视频渲染的结构化数据。FinancialSimulator类实现了财务预测模拟，包括通货膨胀计算、赤字复利计算和投资回报计算。

```mermaid
classDiagram
    class FinancialSimulator {
        +inflation_rate : float
        +deficit_interest_rate : float
        +investment_return : float
        +simulate_timeline(current_age, retirement_age, life_expectancy, current_assets, annual_income, annual_expenses) : List[Dict]
        +_get_event_cost(year, life_events) : float
        +_get_event_labels(year, life_events) : List[str]
        +build_cashflow_data(timeline) : List[Dict]
    }
    class YearlySnapshot {
        +year : int
        +ages : Dict[str, int]
        +financials : Dict[str, float]
        +events : List[str]
        +isCritical : bool
    }
    class CashFlowData {
        +year : int
        +age : int
        +income : Dict[str, float]
        +expenses : Dict[str, float]
        +totalExpense : float
        +netCashFlow : float
        +assetBalance : float
    }
    FinancialSimulator --> YearlySnapshot : "生成"
    FinancialSimulator --> CashFlowData : "生成"
```

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

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

### 前端视频渲染分析

前端视频渲染组件使用Remotion框架将数据渲染为视频。LifePlanChart和CashFlowChart组件使用Recharts库创建动态财务图表，通过动画效果展示财务数据随时间的变化。

```mermaid
sequenceDiagram
participant Backend as Python后端
participant Frontend as Remotion前端
participant Chart as 财务图表
participant Animation as 动画引擎
Backend->>Frontend : 生成render_props.json
Frontend->>Chart : 加载财务数据
Chart->>Animation : 请求动画参数
Animation->>Chart : 返回插值数据
Chart->>Chart : 渲染动态图表
Chart->>Frontend : 输出视频帧
Frontend->>Backend : 完成视频渲染
```

**Diagram sources**
- [src/LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [src/CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)

**Section sources**
- [src/LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [src/CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)

### 数据契约分析

render_props.json文件作为前后端之间的数据契约，定义了视频渲染所需的所有数据结构。TypeScript接口确保了数据类型的正确性，Zod模式用于运行时验证。

```mermaid
erDiagram
RENDER_PROPS {
object meta
object charts
array script
object assets
}
CHARTS {
object assetDepletion
object cashFlow
}
SCRIPT {
int id
string text
float duration
string type
string assetUrl
object chartSync
}
ASSETS {
object broll
array videoClips
string ttsAudio
}
RENDER_PROPS ||--o{ CHARTS : "包含"
RENDER_PROPS ||--o{ SCRIPT : "包含"
RENDER_PROPS ||--o{ ASSETS : "包含"
```

**Diagram sources**
- [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts#L1-L251)

**Section sources**
- [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts#L1-L251)

## 依赖分析

项目依赖分为Python后端依赖和Node.js前端依赖。后端依赖包括AI/LLM库、媒体处理库和数据处理库，前端依赖包括Remotion、React和Recharts等。

```mermaid
graph TD
    A["AI-video-lifeplan-demo"] --> B["Python依赖"]
    A --> C["Node.js依赖"]
    B --> D["google-generativeai"]
    B --> E["openai"]
    B --> F["ffmpeg-python"]
    B --> G["requests"]
    B --> H["python-dotenv"]
    C --> I["@remotion/cli"]
    C --> J["react"]
    C --> K["react-dom"]
    C --> L["recharts"]
    C --> M["remotion"]
    C --> N["@types/react"]
    C --> O["typescript"]
    D --> P["PDF解析"]
    D --> Q["脚本生成"]
    E --> R["音频转录"]
    F --> S["视频处理"]
    G --> T["HTTP请求"]
    H --> U["环境变量"]
    I --> V["视频渲染"]
    J --> W["UI组件"]
    K --> X["UI组件"]
    L --> Y["图表"]
    M --> Z["视频渲染"]
    N --> AA["类型定义"]
    O --> AB["类型检查"]
```

**Diagram sources**
- [requirements.txt](file://requirements.txt#L1-L34)
- [package.json](file://package.json#L1-L43)

**Section sources**
- [requirements.txt](file://requirements.txt#L1-L34)
- [package.json](file://package.json#L1-L43)

## 性能考虑

系统在性能方面考虑了多个方面，包括数据处理效率、视频渲染优化和资源管理。后端使用模拟算法快速生成财务预测数据，前端使用React.memo优化组件渲染，Remotion配置优化了视频输出格式。

**Section sources**
- [remotion.config.ts](file://remotion.config.ts#L1-L12)
- [src/LifePlanChart.tsx](file://src/LifePlanChart.tsx#L70-L349)

## 故障排除指南

常见问题包括API密钥未找到、Remotion渲染失败和PDF提取失败。解决方案包括确保.env文件存在且包含有效密钥、检查npm install是否成功完成，以及确保PDF可读且未受密码保护。

**Section sources**
- [PROJECT_README.md](file://PROJECT_README.md#L217-L232)

## 结论

AI-video-lifeplan-demo项目成功实现了将静态财务规划PDF和访谈视频自动转换为动态解说视频的功能。系统采用混合式Python/Node.js架构，通过render_props.json进行数据契约通信，结合AI生成日语脚本、财务数据可视化图表、B-Roll素材集成和视频片段同步技术，生成个性化的3-5分钟人生规划视频。该架构设计充分利用了Python在AI和数据处理方面的优势，以及Node.js在视频渲染和前端开发方面的优势，为用户提供了一种创新的财务规划展示方式。