378 lines
15 KiB
Markdown
378 lines
15 KiB
Markdown
# 数据模型与契约
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts)
|
||
- [types.ts](file://src/types.ts)
|
||
- [data_builder.py](file://backend/video_processor/data_builder.py)
|
||
- [main.py](file://main.py)
|
||
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx)
|
||
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx)
|
||
- [mock-data.json](file://src/mock-data.json)
|
||
- [mock-cashflow.json](file://src/mock-cashflow.json)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [引言](#引言)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 引言
|
||
本文件聚焦于“核心数据模型与系统间数据契约”，围绕 render-props-types.ts 中定义的 RenderPropsSchema 设计进行深入解析。该契约是 Python 后端与 Remotion 前端之间的唯一通信桥梁：后端生成 render_props.json，前端通过 Zod 运行时校验确保数据完整性，再驱动可视化组件渲染视频内容。本文将逐层拆解 YearlySnapshot、CashFlowData、ScriptSegment、AssetCollection 等关键数据结构的字段语义、类型约束与业务逻辑；阐明 Zod 如何在运行时保障数据一致性；并通过示例文件展示 render_props.json 的实际形态，帮助初学者理解数据契约的重要性与最佳实践。
|
||
|
||
## 项目结构
|
||
本项目采用前后端分离的模块化组织：
|
||
- 前端（Remotion）位于 src 与 frontend/src，负责渲染与可视化；
|
||
- 后端（Python）位于 backend，负责数据模拟与 render_props.json 生成；
|
||
- 契约文件 render-props-types.ts 定义了 TypeScript 接口与 Zod Schema，确保前后端对同一份数据结构达成一致。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "后端"
|
||
PY_MAIN["main.py<br/>构建与保存 render_props.json"]
|
||
PY_DB["backend/video_processor/data_builder.py<br/>财务模拟与图表数据生成"]
|
||
end
|
||
subgraph "前端"
|
||
TS_TYPES["frontend/src/render-props-types.ts<br/>RenderPropsSchema 定义与运行时校验"]
|
||
REACT_LPC["src/LifePlanChart.tsx<br/>资产枯竭曲线图"]
|
||
REACT_CFC["src/CashFlowChart.tsx<br/>现金流分解图"]
|
||
TYPES_TS["src/types.ts<br/>YearlySnapshot 等类型"]
|
||
end
|
||
PY_MAIN --> PY_DB
|
||
PY_DB --> PY_MAIN
|
||
PY_MAIN --> TS_TYPES
|
||
TS_TYPES --> REACT_LPC
|
||
TS_TYPES --> REACT_CFC
|
||
TYPES_TS --> REACT_LPC
|
||
```
|
||
|
||
**图表来源**
|
||
- [main.py](file://main.py#L145-L199)
|
||
- [data_builder.py](file://backend/video_processor/data_builder.py#L150-L200)
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L117-L231)
|
||
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
|
||
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
|
||
- [types.ts](file://src/types.ts#L1-L30)
|
||
|
||
**章节来源**
|
||
- [main.py](file://main.py#L145-L199)
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L117-L231)
|
||
|
||
## 核心组件
|
||
本节从“数据契约”的角度，系统梳理 RenderProps 及其子结构，明确字段含义、类型与业务约束，并说明 Zod Schema 的作用。
|
||
|
||
- RenderProps（顶层契约）
|
||
- meta：视频元信息，包含标题、货币单位、总时长、可选客户名与生成时间戳
|
||
- charts：两类图表数据
|
||
- assetDepletion：资产枯竭曲线的时间序列与元信息（货币单位、起始年份）
|
||
- cashFlow：现金流分解的时间序列与元信息（货币单位）
|
||
- script：脚本段落数组，描述旁白、图表介绍/高亮、视频片段、转场等
|
||
- assets：媒体资源集合，包含 B-Roll 映射、视频片段引用、可选 TTS 音频路径
|
||
|
||
- YearlySnapshot（年度快照）
|
||
- year：年份
|
||
- ages：代表者年龄与可选配偶年龄
|
||
- financials：收入、支出、资产余额
|
||
- events：当年事件标签列表
|
||
- isCritical：资产余额是否为负（标记风险临界点）
|
||
|
||
- CashFlowData（年度现金流）
|
||
- year、age：年份与年龄
|
||
- income.total：年度总收入
|
||
- expenses：生活、住房、教育、税金、事件等细项
|
||
- totalExpense、netCashFlow、assetBalance：派生或补充字段（由后端计算）
|
||
|
||
- ScriptSegment（脚本段落）
|
||
- id、text、duration：段落标识、日文旁白文本、时长（秒）
|
||
- type：段落类型枚举（旁白、图表介绍、图表高亮、视频片段、转场）
|
||
- assetUrl：B-Roll 或视频片段 URL/路径
|
||
- chartSync：可选的图表同步参数（图表 ID、高亮年份、动画起始帧）
|
||
|
||
- AssetCollection（媒体资源集合）
|
||
- broll：关键词到视频 URL/路径的映射
|
||
- videoClips：视频片段引用数组（id、源路径、起止时间、输出路径）
|
||
- ttsAudio：可选的 TTS 语音文件路径
|
||
|
||
- Zod Schema（运行时校验）
|
||
- YearlySnapshotSchema、CashFlowDataSchema、ScriptSegmentSchema、RenderPropsSchema
|
||
- 提供 parse/safeParse 两种校验方式，前者失败抛错，后者返回布尔判断
|
||
- validateRenderProps/isRenderProps 两个辅助函数，分别用于强制校验与类型守卫
|
||
|
||
**章节来源**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L18-L231)
|
||
- [types.ts](file://src/types.ts#L1-L30)
|
||
|
||
## 架构总览
|
||
RenderPropsSchema 作为 Python 后端与 Remotion 前端之间的“数据契约”，贯穿以下流程：
|
||
- 后端根据 PDF 输入与财务模拟器生成 render_props.json
|
||
- 前端读取 render_props.json，使用 Zod Schema 进行运行时校验
|
||
- 校验通过后，前端组件（如 LifePlanChart、CashFlowChart）消费数据并渲染视频
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Backend as "Python 后端"
|
||
participant Builder as "data_builder.py"
|
||
participant Main as "main.py"
|
||
participant Frontend as "Remotion 前端"
|
||
participant Schema as "render-props-types.ts"
|
||
participant Charts as "LifePlanChart/CashFlowChart"
|
||
Backend->>Builder : "输入PDF数据"
|
||
Builder->>Builder : "财务模拟与图表数据生成"
|
||
Builder-->>Main : "返回 charts 财务数据"
|
||
Main->>Main : "拼装 meta/script/assets"
|
||
Main-->>Frontend : "render_props.json"
|
||
Frontend->>Schema : "validateRenderProps/isRenderProps"
|
||
Schema-->>Frontend : "校验结果"
|
||
Frontend->>Charts : "传入 RenderProps 渲染"
|
||
Charts-->>Frontend : "输出视频帧"
|
||
```
|
||
|
||
**图表来源**
|
||
- [data_builder.py](file://backend/video_processor/data_builder.py#L150-L200)
|
||
- [main.py](file://main.py#L145-L199)
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L194-L250)
|
||
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
|
||
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
|
||
|
||
## 详细组件分析
|
||
|
||
### RenderPropsSchema 设计与运行时校验
|
||
- 设计要点
|
||
- 严格嵌套结构：meta、charts、script、assets 四大块，每块内部字段一一对应
|
||
- 类型精确：数值、字符串、枚举、可选字段均有明确约束
|
||
- 元信息与数据一致性：charts.meta 携带货币单位与起始年份，保证图表显示一致
|
||
- 运行时校验
|
||
- parse：失败即抛异常，适合强约束场景
|
||
- safeParse：返回成功/失败，便于条件分支处理
|
||
- 辅助函数：validateRenderProps 与 isRenderProps 提供统一入口
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始"]) --> Load["读取 render_props.json"]
|
||
Load --> Parse["调用 RenderPropsSchema.parse/safeParse"]
|
||
Parse --> Valid{"校验通过？"}
|
||
Valid --> |否| Throw["抛出错误/返回失败"]
|
||
Valid --> |是| Use["前端组件消费数据"]
|
||
Use --> End(["结束"])
|
||
Throw --> End
|
||
```
|
||
|
||
**图表来源**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L237-L250)
|
||
|
||
**章节来源**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L194-L250)
|
||
|
||
### YearlySnapshot 与 CashFlowData 的字段语义与业务逻辑
|
||
- YearlySnapshot
|
||
- 年度视角的财务快照，支持代表者与配偶双人年龄，便于双人财务规划可视化
|
||
- financials.income/expenditure/assetBalance 三元组构成资产枯竭曲线的核心
|
||
- events 与 isCritical 用于标注重大事件与风险节点
|
||
- CashFlowData
|
||
- 将 YearlySnapshot 转换为更利于“收入-支出”分解展示的数据形式
|
||
- expenses 细分五类，便于堆叠柱状图呈现
|
||
- totalExpense、netCashFlow、assetBalance 为派生字段，便于 HUD 展示与动画控制
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class YearlySnapshot {
|
||
+number year
|
||
+ages
|
||
+financials
|
||
+string[] events?
|
||
+boolean isCritical?
|
||
}
|
||
class CashFlowData {
|
||
+number year
|
||
+number age
|
||
+income
|
||
+expenses
|
||
+number totalExpense?
|
||
+number netCashFlow?
|
||
+number assetBalance?
|
||
}
|
||
class incomes {
|
||
+number total
|
||
}
|
||
class expenses {
|
||
+number living
|
||
+number housing
|
||
+number education
|
||
+number tax
|
||
+number event
|
||
}
|
||
YearlySnapshot --> incomes : "financials.income"
|
||
YearlySnapshot --> expenses : "financials.expenditure"
|
||
CashFlowData --> incomes : "income"
|
||
CashFlowData --> expenses : "expenses"
|
||
```
|
||
|
||
**图表来源**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L18-L49)
|
||
- [types.ts](file://src/types.ts#L1-L18)
|
||
|
||
**章节来源**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L18-L49)
|
||
- [types.ts](file://src/types.ts#L1-L18)
|
||
|
||
### ScriptSegment 与 AssetCollection 的脚本与媒体资源
|
||
- ScriptSegment
|
||
- 类型枚举覆盖旁白、图表介绍/高亮、视频片段、转场等场景
|
||
- chartSync 支持与图表联动，实现高亮年份与动画起始帧的同步
|
||
- AssetCollection
|
||
- broll 关键词到视频资源的映射，便于按主题检索
|
||
- videoClips 记录剪辑片段的来源与裁剪参数，便于复用与导出
|
||
- ttsAudio 为可选的人工合成语音路径
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class ScriptSegment {
|
||
+number id
|
||
+string text
|
||
+number duration
|
||
+string type
|
||
+string assetUrl?
|
||
+chartSync?
|
||
}
|
||
class AssetCollection {
|
||
+Record~string,string~ broll
|
||
+VideoClipReference[] videoClips
|
||
+string ttsAudio?
|
||
}
|
||
class VideoClipReference {
|
||
+string id
|
||
+string sourcePath
|
||
+number startTime
|
||
+number duration
|
||
+string outputPath?
|
||
}
|
||
ScriptSegment --> AssetCollection : "引用媒体资源"
|
||
AssetCollection --> VideoClipReference : "包含"
|
||
```
|
||
|
||
**图表来源**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L74-L111)
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L99-L111)
|
||
|
||
**章节来源**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L74-L111)
|
||
|
||
### 前端消费与可视化组件
|
||
- LifePlanChart（资产枯竭曲线）
|
||
- 使用 YearlySnapshot 渲染面积图，支持插值与渐变色（正负资产区域）
|
||
- HUD 展示当前年份、资产余额、收支差额
|
||
- CashFlowChart（现金流分解）
|
||
- 使用 CashFlowData 渲染堆叠柱状图与收入线，支持分段顺序增长动画
|
||
- HUD 展示当前年份、收入、总支出、净现金流
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Frontend as "Remotion 前端"
|
||
participant Schema as "RenderPropsSchema"
|
||
participant LPC as "LifePlanChart"
|
||
participant CFC as "CashFlowChart"
|
||
Frontend->>Schema : "校验 render_props.json"
|
||
Schema-->>Frontend : "校验通过"
|
||
Frontend->>LPC : "传入 assetDepletion 数据"
|
||
Frontend->>CFC : "传入 cashFlow 数据"
|
||
LPC-->>Frontend : "渲染资产曲线帧"
|
||
CFC-->>Frontend : "渲染现金流帧"
|
||
```
|
||
|
||
**图表来源**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L194-L231)
|
||
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
|
||
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
|
||
|
||
**章节来源**
|
||
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
|
||
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
|
||
|
||
## 依赖关系分析
|
||
- 后端到前端的数据流
|
||
- main.py 负责组装 render_props.json 并保存
|
||
- data_builder.py 生成 charts 数据（资产枯竭与现金流）
|
||
- 前端 render-props-types.ts 以 Zod Schema 对齐数据结构
|
||
- 前端组件对数据的依赖
|
||
- LifePlanChart 依赖 YearlySnapshot 类型
|
||
- CashFlowChart 依赖 CashFlowData 类型
|
||
- 两者均依赖 RenderPropsSchema 的校验结果
|
||
|
||
```mermaid
|
||
graph LR
|
||
PY["main.py"] --> DB["data_builder.py"]
|
||
DB --> JSON["render_props.json"]
|
||
JSON --> TS["render-props-types.ts"]
|
||
TS --> LPC["LifePlanChart.tsx"]
|
||
TS --> CFC["CashFlowChart.tsx"]
|
||
TYPES["types.ts"] --> LPC
|
||
```
|
||
|
||
**图表来源**
|
||
- [main.py](file://main.py#L145-L199)
|
||
- [data_builder.py](file://backend/video_processor/data_builder.py#L150-L200)
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L117-L231)
|
||
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
|
||
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
|
||
- [types.ts](file://src/types.ts#L1-L30)
|
||
|
||
**章节来源**
|
||
- [main.py](file://main.py#L145-L199)
|
||
- [data_builder.py](file://backend/video_processor/data_builder.py#L150-L200)
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L117-L231)
|
||
|
||
## 性能考量
|
||
- 数据规模与渲染开销
|
||
- 大时间序列（如多代人、长周期）会增加 Recharts 渲染压力
|
||
- 建议在后端进行数据采样或聚合，减少前端渲染负担
|
||
- 动画与插值
|
||
- 插值与顺序增长动画需谨慎使用，避免在长序列上产生过多帧级计算
|
||
- 校验成本
|
||
- Zod 校验在开发阶段建议开启，生产环境可考虑缓存校验结果或仅在首帧执行
|
||
|
||
[本节为通用指导，不直接分析具体文件]
|
||
|
||
## 故障排查指南
|
||
- 校验失败
|
||
- 现象：validateRenderProps 抛错；isRenderProps 返回 false
|
||
- 排查：检查字段类型（数字/字符串）、可选字段是否遗漏、枚举值是否正确
|
||
- 参考：Zod Schema 定义与辅助函数
|
||
- 数据不一致
|
||
- 现象：图表显示货币单位不一致、起始年份错位
|
||
- 排查：确认 charts.meta.currencyUnit 与 charts.meta.startYear 是否与 timeline 对齐
|
||
- 脚本与媒体资源不匹配
|
||
- 现象：ScriptSegment.chartSync 未生效或 assetUrl 无法加载
|
||
- 排查：确认 chartId、highlightYear、animationStart 与 assets.broll/videoClips 的键值一致
|
||
|
||
**章节来源**
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L194-L250)
|
||
|
||
## 结论
|
||
RenderPropsSchema 通过严格的类型与运行时校验，将 Python 后端的 render_props.json 与 Remotion 前端的可视化组件紧密耦合，形成稳定、可演进的数据契约。YearlySnapshot 与 CashFlowData 的清晰边界，配合 ScriptSegment 与 AssetCollection 的脚本与媒体资源管理，使得系统在保持前后端松耦合的同时，具备良好的扩展性与可维护性。建议在后续迭代中持续对齐契约版本，确保前后端同步更新。
|
||
|
||
[本节为总结性内容，不直接分析具体文件]
|
||
|
||
## 附录
|
||
|
||
### render_props.json 实例与字段对照
|
||
- 示例文件
|
||
- mock-data.json：资产枯竭曲线的 timeline 与 meta
|
||
- mock-cashflow.json：现金流分解的 timeline 与 meta
|
||
- 字段对照
|
||
- meta.title、meta.currencyUnit、meta.duration、meta.clientName、meta.generatedAt
|
||
- charts.assetDepletion.timeline、charts.assetDepletion.meta.currencyUnit、charts.assetDepletion.meta.startYear
|
||
- charts.cashFlow.timeline、charts.cashFlow.meta.currencyUnit
|
||
- script[].id、script[].text、script[].duration、script[].type、script[].assetUrl、script[].chartSync
|
||
- assets.broll、assets.videoClips[]、assets.ttsAudio
|
||
|
||
**章节来源**
|
||
- [mock-data.json](file://src/mock-data.json#L1-L61)
|
||
- [mock-cashflow.json](file://src/mock-cashflow.json#L1-L800)
|
||
- [render-props-types.ts](file://frontend/src/render-props-types.ts#L117-L231) |