327 lines
15 KiB
Markdown
327 lines
15 KiB
Markdown
# 配置管理
|
||
|
||
<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) |