# 配置管理

<cite>
**本文引用的文件**
- [.env.example](file://.env.example)
- [remotion.config.ts](file://remotion.config.ts)
- [tsconfig.json](file://tsconfig.json)
- [requirements.txt](file://requirements.txt)
- [PROJECT_README.md](file://PROJECT_README.md)
- [main.py](file://main.py)
- [backend/data_builder.py](file://backend/data_builder.py)
- [backend/media_fetcher.py](file://backend/media_fetcher.py)
- [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts)
- [frontend/src/types.ts](file://src\types.ts)
</cite>

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

## 简介
本文件系统性梳理本项目的配置管理，覆盖以下方面：
- 环境变量与密钥：.env 中各 API 密钥的作用与设置方法
- 财务模拟参数：DEFAULT_INFLATION_RATE 等参数在数据模拟中的使用
- 视频渲染配置：remotion.config.ts 的渲染行为
- TypeScript 编译配置：tsconfig.json 的编译选项与排除规则
- Python 依赖管理：requirements.txt 的依赖策略与可选组件
- 配置与代码分离最佳实践与密钥安全建议
- 为所有用户提供清晰的配置清单与修改指南

## 项目结构
本项目采用“Python 后端 + Node.js 前端（Remotion）”混合架构，配置文件分布于根目录与子模块中，便于按层分离与维护。

```mermaid
graph TB
A[".env.example<br/>环境变量示例"] --> B["main.py<br/>主流程入口"]
B --> C["backend/data_builder.py<br/>财务模拟与图表数据构建"]
B --> D["backend/media_fetcher.py<br/>B-Roll 获取待实现"]
B --> E["frontend/src/render-props-types.ts<br/>渲染数据契约TypeScript"]
F["remotion.config.ts<br/>视频渲染配置"] --> G["Remotion 渲染引擎"]
H["tsconfig.json<br/>TypeScript 编译选项"] --> E
I["requirements.txt<br/>Python 依赖清单"] --> B
```

图示来源
- [PROJECT_README.md](file://PROJECT_README.md#L50-L80)
- [remotion.config.ts](file://remotion.config.ts#L1-L12)
- [tsconfig.json](file://tsconfig.json#L1-L18)
- [requirements.txt](file://requirements.txt#L1-L34)
- [main.py](file://main.py#L1-L305)
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L1-L72)
- [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts#L1-L251)

章节来源
- [PROJECT_README.md](file://PROJECT_README.md#L50-L80)

## 核心组件
- 环境变量与密钥
  - .env.example 提供了 GEMINI_API_KEY、OPENAI_API_KEY、PEXELS_API_KEY 等密钥占位符，以及 DEFAULT_INFLATION_RATE、DEFAULT_DEFICIT_INTEREST_RATE、DEFAULT_INVESTMENT_RETURN 等财务模拟参数占位符。
  - 运行时通过 dotenv 加载密钥，用于调用外部服务（如 Pexels、Gemini、OpenAI）。
- 财务模拟参数
  - 在 backend/data_builder.py 中，FinancialSimulator 从配置字典读取通胀率、赤字利率、投资回报率等参数，驱动年金模拟与现金流计算。
- 视频渲染配置
  - remotion.config.ts 设置图像格式与输出覆盖策略，影响最终视频生成行为。
- TypeScript 编译配置
  - tsconfig.json 定义严格模式、JSX 处理、模块解析策略与排除项，确保前端类型检查与构建稳定性。
- Python 依赖管理
  - requirements.txt 明确列出核心依赖与可选组件，指导安装与版本选择。

章节来源
- [.env.example](file://.env.example#L1-L23)
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)
- [remotion.config.ts](file://remotion.config.ts#L1-L12)
- [tsconfig.json](file://tsconfig.json#L1-L18)
- [requirements.txt](file://requirements.txt#L1-L34)

## 架构总览
下图展示配置在整体流程中的作用与流向。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Env as ".env/.env.example"
participant Py as "main.py"
participant Sim as "backend/data_builder.py"
participant MF as "backend/media_fetcher.py"
participant TS as "frontend/src/render-props-types.ts"
participant RC as "remotion.config.ts"
Dev->>Env : 创建 .env 并填写密钥与参数
Dev->>Py : 运行主流程
Py->>Env : 读取环境变量密钥
Py->>Sim : 传入 PDF 数据与可选配置含财务参数
Sim->>Sim : 使用 DEFAULT_INFLATION_RATE 等参数进行模拟
Py->>MF : 传入脚本关键词用于 B-Roll 获取
MF->>Env : 读取 PEXELS_API_KEY
Py->>TS : 生成 render_props.json前端契约
Py->>RC : 触发 Remotion 渲染受配置影响
```

图示来源
- [.env.example](file://.env.example#L1-L23)
- [main.py](file://main.py#L1-L305)
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L1-L72)
- [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts#L1-L251)
- [remotion.config.ts](file://remotion.config.ts#L1-L12)

## 详细组件分析

### 环境变量与密钥配置（.env）
- 位置与用途
  - .env.example 提供密钥占位符与财务参数占位符，用于指导用户创建 .env 文件。
  - 运行时通过 dotenv 加载密钥，供后端模块使用。
- 关键条目说明
  - GEMINI_API_KEY：用于 PDF 解析与脚本生成（例如 Pexels 关键词翻译、脚本生成等）。
  - OPENAI_API_KEY：用于 Whisper 转录（若提供视频输入）。
  - PEXELS_API_KEY：用于 B-Roll 资源检索与下载。
  - GOOGLE_APPLICATION_CREDENTIALS（可选）：用于 Google Cloud TTS（如启用）。
  - DEFAULT_INFLATION_RATE、DEFAULT_DEFICIT_INTEREST_RATE、DEFAULT_INVESTMENT_RETURN：财务模拟参数，用于 FinancialSimulator。
- 设置步骤
  - 复制 .env.example 为 .env，填入真实密钥与参数值。
  - 不要将 .env 提交到版本控制。
- 安全建议
  - 将 .env 放入 .gitignore；使用只读权限；在 CI/CD 中使用加密变量注入；定期轮换密钥。

章节来源
- [.env.example](file://.env.example#L1-L23)
- [PROJECT_README.md](file://PROJECT_README.md#L97-L111)

### 财务模拟参数与使用
- 参数来源
  - .env 中的 DEFAULT_INFLATION_RATE、DEFAULT_DEFICIT_INTEREST_RATE、DEFAULT_INVESTMENT_RETURN 作为默认值。
  - backend/data_builder.py 的 FinancialSimulator 会从传入配置字典中读取对应键，若未提供则使用默认值。
- 模拟逻辑要点
  - 通胀调整支出：基于年份指数增长。
  - 现金流平衡：收入减去支出得到净现金流。
  - 资产余额更新：正余额按投资回报增长，负余额按赤字利率复利增长。
  - 现金流明细：将总支出拆分为生活、住房、教育、税、事件等分项。
- 修改指南
  - 若需调整模拟参数，可在运行时传入配置字典或通过环境变量映射到配置字典，再传递给 FinancialSimulator。

```mermaid
flowchart TD
Start(["开始：接收财务参数"]) --> Init["初始化资产余额与年份"]
Init --> Loop{"是否达到寿命预期？"}
Loop --> |否| Income["计算当年收入退休前为年收入，否则为0"]
Income --> Inflate["按通胀率调整支出"]
Inflate --> NetCF["计算净现金流"]
NetCF --> Balance{"资产余额是否为正？"}
Balance --> |是| Pos["按投资回报率增长资产余额"]
Balance --> |否| Neg["按赤字利率复利增长资产余额"]
Pos --> Snapshot["生成年度快照"]
Neg --> Snapshot
Snapshot --> Next["推进到下一年"]
Next --> Loop
Loop --> |是| End(["结束：返回完整时间线"])
```

图示来源
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)

章节来源
- [.env.example](file://.env.example#L19-L23)
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)

### 视频渲染配置（remotion.config.ts）
- 配置项说明
  - 图像格式：设置为 jpeg，影响帧导出质量与体积。
  - 输出覆盖：开启覆盖输出，避免重复渲染导致的冲突。
- 影响范围
  - 该配置仅对 Node.js API 生效；当使用 Node.js API 时，配置文件不生效，需直接向 API 传入选项。
- 修改建议
  - 如需 PNG 或 WebP，可调整图像格式；如需保留中间产物，关闭覆盖输出。

章节来源
- [remotion.config.ts](file://remotion.config.ts#L1-L12)

### TypeScript 编译配置（tsconfig.json）
- 关键选项说明
  - target/module：ES2018 与 commonjs，适配 Node.js 环境。
  - jsx：react-jsx，支持 React 组件 JSX 渲染。
  - strict：启用严格模式，提升类型安全性。
  - noEmit：仅类型检查，不生成 JS 文件（由构建工具处理）。
  - lib/moduleResolution：指定库与模块解析策略。
  - resolveJsonModule：允许导入 JSON 模块。
  - exclude：排除 remotion.config.ts，避免其参与前端编译。
- 修改建议
  - 如需支持新语法特性，可调整 target；如需切换打包器，注意 moduleResolution 与 lib 的兼容性。

章节来源
- [tsconfig.json](file://tsconfig.json#L1-L18)

### Python 依赖管理（requirements.txt）
- 核心依赖
  - python-dotenv：加载 .env 文件中的环境变量。
- 可选组件（按需安装）
  - google-generativeai：Gemini 相关功能（按官方文档选择版本）。
  - openai：Whisper 转录（按官方文档选择版本）。
  - ffmpeg-python：视频处理。
  - requests：网络请求。
  - numpy/pandas（可选）：高级仿真与数据分析。
  - PyPDF2/pdfplumber（可选）：PDF 处理（Gemini 可直接处理 PDF）。
  - tqdm/rich：进度条与 CLI 界面美化。
  - pytest/pytest-cov（可选）：测试与覆盖率。
- 安装建议
  - 先安装核心依赖，再根据需要安装可选组件，避免不必要的依赖污染。

章节来源
- [requirements.txt](file://requirements.txt#L1-L34)

### 渲染数据契约（frontend/src/render-props-types.ts）
- 作用
  - 定义 render_props.json 的 TypeScript 接口与 Zod 校验，确保前后端数据一致。
- 关键结构
  - YearlySnapshot、CashFlowData：年度快照与现金流数据。
  - AssetDepletionChartData、CashFlowChartData：图表数据结构。
  - ScriptSegment：脚本段落，包含类型与可选的图表同步信息。
  - AssetCollection：B-Roll 与视频片段等资源集合。
  - RenderProps：顶层渲染契约。
- 使用建议
  - 保持前端类型与后端生成的数据结构一致；使用校验函数在运行时验证数据完整性。

章节来源
- [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts#L1-L251)

### 前端类型基础（src/types.ts）
- 作用
  - 定义前端图表组件的基础类型（如 YearlySnapshot、LifePlanChartProps），与渲染契约互补。
- 使用建议
  - 在组件中使用这些类型，确保数据消费侧的类型安全。

章节来源
- [frontend/src/types.ts](file://src\types.ts#L1-L30)

## 依赖关系分析
- 配置与模块耦合
  - main.py 通过命令行参数与配置字典驱动后端流程；FinancialSimulator 依赖配置字典中的财务参数。
  - backend/media_fetcher.py 依赖环境变量中的 PEXELS_API_KEY。
  - frontend/src/render-props-types.ts 与后端生成的数据结构强绑定，需保持同步。
- 外部依赖
  - Python：dotenv、requests、ffmpeg-python、google-generativeai、openai（按需）、tqdm、rich。
  - Node.js：Remotion、React、Zod（类型与校验）。

```mermaid
graph LR
ENV[".env/.env.example"] --> PY["main.py"]
PY --> SIM["backend/data_builder.py"]
PY --> MF["backend/media_fetcher.py"]
PY --> RPT["frontend/src/render-props-types.ts"]
RC["remotion.config.ts"] --> REND["Remotion 渲染"]
TS["tsconfig.json"] --> RPT
REQ["requirements.txt"] --> PY
```

图示来源
- [.env.example](file://.env.example#L1-L23)
- [main.py](file://main.py#L1-L305)
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L1-L72)
- [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts#L1-L251)
- [remotion.config.ts](file://remotion.config.ts#L1-L12)
- [tsconfig.json](file://tsconfig.json#L1-L18)
- [requirements.txt](file://requirements.txt#L1-L34)

## 性能考虑
- 环境变量加载
  - 使用 dotenv 一次性加载 .env，避免频繁 IO；在生产环境中建议通过进程环境变量注入，减少文件系统访问。
- 渲染配置
  - 图像格式与覆盖策略直接影响输出体积与磁盘占用；在调试阶段可使用更高分辨率格式，在发布阶段使用更高效的格式。
- 类型检查
  - 严格模式与 noEmit 配合，确保类型错误在开发期暴露，减少运行时开销。
- 依赖安装
  - 仅安装必要依赖，避免冗余包带来的冷启动与内存占用。

## 故障排查指南
- “找不到 API 密钥”
  - 确认 .env 已创建且包含有效密钥；检查密钥名称与 .env 中一致；确认未提交 .env 到版本控制。
- “Remotion 渲染失败”
  - 确认已执行 npm install；检查 frontend/src 结构是否正确；确认渲染命令参数与 render_props.json 路径无误。
- “PDF 解析失败”
  - 确认 PDF 可读且未加密；检查 Gemini API 配额与限制；确认网络连通性。
- “B-Roll 获取失败”
  - 确认 PEXELS_API_KEY 已正确设置；检查网络与 API 返回状态；关注翻译与下载流程的实现进度。

章节来源
- [PROJECT_README.md](file://PROJECT_README.md#L217-L233)

## 结论
本项目的配置管理遵循“配置与代码分离”的原则：密钥与参数集中于 .env，财务模拟参数通过配置字典注入，渲染与编译配置分别位于 remotion.config.ts 与 tsconfig.json，依赖管理集中在 requirements.txt。通过严格的类型契约与运行时校验，前后端数据一致性得到保障。建议在团队协作中统一密钥管理策略与版本控制规范，持续优化渲染与编译配置以满足性能目标。

## 附录

### 配置清单与修改指南
- 环境变量（.env）
  - 必填项：GEMINI_API_KEY、OPENAI_API_KEY、PEXELS_API_KEY
  - 可选项：GOOGLE_APPLICATION_CREDENTIALS（如使用 TTS）
  - 财务参数：DEFAULT_INFLATION_RATE、DEFAULT_DEFICIT_INTEREST_RATE、DEFAULT_INVESTMENT_RETURN
  - 修改方式：复制 .env.example 为 .env，填入真实值
- 财务模拟参数
  - 位置：backend/data_builder.py 的 FinancialSimulator
  - 修改方式：在调用处传入配置字典，或通过环境变量映射到配置字典
- 视频渲染配置
  - 位置：remotion.config.ts
  - 修改方式：调整图像格式与覆盖策略
- TypeScript 编译配置
  - 位置：tsconfig.json
  - 修改方式：根据项目需求调整 target、module、lib、moduleResolution 等
- Python 依赖
  - 位置：requirements.txt
  - 修改方式：按需安装可选组件，避免无关依赖

章节来源
- [.env.example](file://.env.example#L1-L23)
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)
- [remotion.config.ts](file://remotion.config.ts#L1-L12)
- [tsconfig.json](file://tsconfig.json#L1-L18)
- [requirements.txt](file://requirements.txt#L1-L34)
- [PROJECT_README.md](file://PROJECT_README.md#L97-L111)