# 统一信息显示层（UnifiedHUD）

<cite>
**本文引用的文件**
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx)
- [types.ts](file://src/types.ts)
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx)
- [DualChartView.tsx](file://src/DualChartView.tsx)
- [Root.tsx](file://src/Root.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. [附录：扩展与定制指南](#附录扩展与定制指南)

## 简介
UnifiedHUD 是一个位于视频画面顶部的状态仪表盘，用于集中展示关键财务指标，帮助观众在观看生命周期模拟视频时快速把握当前年度与主要财务状态。它采用线性渐变背景、分组布局与响应式间距，通过 MetricCard 子组件动态呈现“收入”“支出”“净现金流”“资产余额”等指标，并对正负值进行颜色与图标的差异化处理，确保信息传达直观清晰。

## 项目结构
本仓库包含多个图表组件与统一入口，UnifiedHUD 作为可复用的头部仪表盘，既可独立使用，也可嵌入到其他图表组件中，例如 LifePlanChart 与 CashFlowChart 的 HUD 区域，以及在 DualChartView 中与图表主体同步展示。

```mermaid
graph TB
subgraph "视频渲染入口"
Root["Root.tsx<br/>注册 Composition"]
end
subgraph "图表组件"
LifePlan["LifePlanChart.tsx"]
CashFlow["CashFlowChart.tsx"]
Dual["DualChartView.tsx"]
Unified["UnifiedHUD.tsx"]
end
subgraph "数据"
MockData["mock-data.json"]
MockCash["mock-cashflow.json"]
end
Root --> LifePlan
Root --> CashFlow
Root --> Dual
Dual --> LifePlan
Dual --> CashFlow
LifePlan --> Unified
CashFlow --> Unified
LifePlan -. 使用 .-> MockData
CashFlow -. 使用 .-> MockCash
Dual -. 使用 .-> MockCash
```

图表来源
- [Root.tsx](file://src/Root.tsx#L1-L68)
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L1-L164)
- [mock-data.json](file://src/mock-data.json#L1-L61)
- [mock-cashflow.json](file://src/mock-cashflow.json#L1-L200)

章节来源
- [Root.tsx](file://src/Root.tsx#L1-L68)
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L1-L164)
- [mock-data.json](file://src/mock-data.json#L1-L61)
- [mock-cashflow.json](file://src/mock-cashflow.json#L1-L200)

## 核心组件
UnifiedHUD 提供统一的头部仪表盘，包含：
- 年度与年龄信息区
- 指标卡片区（收入、支出、净现金流、资产余额）
- MetricCard 子组件，支持标签、数值、单位、颜色、图标与“大号”模式

其 props 接口 UnifiedHUDProps 定义如下：
- year：当前年份
- age：当前年龄
- income：年度收入
- expense：年度支出
- netCashFlow：年度净现金流
- assetBalance：年末资产余额
- currencyUnit：货币单位字符串

章节来源
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L3-L11)

## 架构总览
UnifiedHUD 与图表组件的关系如下：

```mermaid
sequenceDiagram
participant Root as "Root.tsx"
participant LifePlan as "LifePlanChart.tsx"
participant CashFlow as "CashFlowChart.tsx"
participant Dual as "DualChartView.tsx"
participant Unified as "UnifiedHUD.tsx"
Root->>LifePlan : 注册并传入 timeline/meta
Root->>CashFlow : 注册并传入 timeline/meta
Root->>Dual : 注册并传入 cashflowData
Dual->>LifePlan : 传入转换后的 timeline/metahideHeader=true
Dual->>CashFlow : 传入原始 timeline/metahideHeader=true
LifePlan->>Unified : 渲染 HUD独立或嵌入
CashFlow->>Unified : 渲染 HUD独立或嵌入
```

图表来源
- [Root.tsx](file://src/Root.tsx#L1-L68)
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L1-L164)

## 详细组件分析

### UnifiedHUD 组件
- 结构与布局
  - 外层容器采用水平分栏布局，左右两侧分别展示“年份/年龄”与“指标卡片组”，中间以等间距分隔，整体具有圆角、阴影与线性渐变背景，营造现代感与层次感。
  - 指标卡片组内部使用等间距布局，卡片按顺序排列，便于用户快速扫描关键指标。
- 数据来源与映射
  - 年份与年龄来自 props；其余指标（收入、支出、净现金流、资产余额）来自 props，并通过 MetricCard 呈现。
  - 货币单位由 props 传入，用于统一显示格式。
- 颜色与图标策略
  - 收入卡片：使用暖色调图标与颜色，强调增长与收益。
  - 支出卡片：使用中性偏警示色，突出成本与消耗。
  - 净现金流卡片：正数使用绿色系，负数使用红色系，配合“+/-”图标直观表达盈亏状况。
  - 资产余额卡片：正数使用浅绿系，负数使用浅红系，采用“💰”图标强调资产属性。
- 内联样式组织
  - 外层容器样式集中定义，包含布局、背景、圆角、阴影与间距。
  - 指标卡片内部样式按层级拆分：标签区（小字号、高对比度）、数值区（大字号、居右对齐、图标与单位组合），并支持“大号”模式以提升视觉权重。
- 响应式字体大小
  - 通过“大号”模式切换数值主字体大小，使资产余额等关键指标在有限空间内获得更强的可读性与视觉焦点。
- 与图表组件的复用
  - LifePlanChart 与 CashFlowChart 均提供独立 HUD 区域，但 UnifiedHUD 可作为通用组件在需要时直接复用，减少重复实现。
  - 在 DualChartView 中，两个图表均以 hideHeader=true 的方式嵌入，避免重复 HUD，同时在上层容器中自行管理统一的 HUD 展示逻辑。

章节来源
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L1-L164)

### MetricCard 子组件
- 功能与交互
  - 接收标签、数值、单位、颜色、图标与“是否大号”的布尔标志。
  - 数值显示时自动添加千位分隔符；对净现金流卡片，若为正值且标签为“NET FLOW”，会前置“+”号以增强可读性。
  - 图标与单位以右侧对齐的方式组合显示，形成紧凑而清晰的指标单元。
- 颜色与正负逻辑
  - 收入与支出卡片的颜色由调用方指定；净现金流卡片根据数值正负动态选择颜色与图标。
  - 资产余额卡片同样根据正负动态选择颜色与图标，确保视觉一致性。
- 字体与间距
  - 标签区采用较小字号与高字重，保证信息层级清晰。
  - 数值区支持“大号”模式，使关键指标在视觉上更突出。
  - 单位区采用略小于主数值的字号，保持整体平衡。

章节来源
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L111-L164)

### 与 LifePlanChart 的集成
- HUD 设计差异
  - LifePlanChart 自带 HUD，采用浅色背景与简洁排版，资产余额根据正负值切换蓝色/红色。
  - UnifiedHUD 采用深色背景与高对比度配色，适合在复杂图表上方叠加显示。
- 数据映射
  - LifePlanChart 的数据结构包含年份、年龄与财务三要素；UnifiedHUD 的数据来源于外部传入的指标集合。
  - 在 DualChartView 中，CashFlow 数据被转换为 LifePlan 所需的 YearlySnapshot 形态，以便在 LifePlanChart 中复用 HUD 逻辑。

章节来源
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [types.ts](file://src/types.ts#L1-L30)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)

### 与 CashFlowChart 的集成
- HUD 设计差异
  - CashFlowChart 的 HUD 采用横向分组布局，分别展示“总收入”“总支出”“结余”，并根据结余正负切换颜色。
  - UnifiedHUD 的 HUD 更聚焦于“收入/支出/净现金流/资产余额”四类核心指标，便于跨图表统一认知。
- 数据映射
  - CashFlowChart 的数据包含年、年龄、收入明细、支出明细、总支出、净现金流与资产余额，这些字段可直接映射到 UnifiedHUD 的 props。
  - 在 DualChartView 中，CashFlowChart 与 LifePlanChart 共享同一套动画进度，从而在 HUD 上保持一致的时间点。

章节来源
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)

### 数据模型与来源
- LifePlanChart 使用 YearlySnapshot 结构，包含年份、年龄与财务三要素，典型数据来自 mock-data.json。
- CashFlowChart 使用 CashFlowData 结构，包含年份、年龄、收入明细、支出明细、总支出、净现金流与资产余额，典型数据来自 mock-cashflow.json。
- DualChartView 将 CashFlow 数据转换为 LifePlan 所需形态，以便在 LifePlanChart 中统一展示 HUD。

章节来源
- [types.ts](file://src/types.ts#L1-L30)
- [mock-data.json](file://src/mock-data.json#L1-L61)
- [mock-cashflow.json](file://src/mock-cashflow.json#L1-L200)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)

## 依赖关系分析

```mermaid
graph LR
Unified["UnifiedHUD.tsx"]
Metric["MetricCard(内联)"]
LifePlan["LifePlanChart.tsx"]
CashFlow["CashFlowChart.tsx"]
Dual["DualChartView.tsx"]
Types["types.ts"]
Unified --> Metric
LifePlan --> Unified
CashFlow --> Unified
Dual --> LifePlan
Dual --> CashFlow
LifePlan --> Types
```

图表来源
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L1-L164)
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)
- [types.ts](file://src/types.ts#L1-L30)

章节来源
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L1-L164)
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)
- [types.ts](file://src/types.ts#L1-L30)

## 性能考量
- 内联样式的组织
  - 将外层容器与卡片内部样式拆分，避免重复计算与不必要的重绘。
  - 对字体大小、颜色与间距采用集中配置，便于统一维护与性能优化。
- 动画与渲染
  - 在图表组件中，通过外部传参控制 HUD 的可见性（如 hideHeader=true），减少重复渲染。
  - 在 DualChartView 中，通过统一的帧进度计算与外部数据索引传递，确保 HUD 与图表主体同步，避免额外的动画开销。
- 数据映射与缓存
  - 在 DualChartView 中，使用 useMemo 缓存 LifePlan 时间线的转换结果，避免每帧重建数组导致的图表抖动与重渲染。

章节来源
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)

## 故障排查指南
- HUD 不显示或显示异常
  - 检查是否正确传入 UnifiedHUD 的 props（year、age、income、expense、netCashFlow、assetBalance、currencyUnit）。
  - 若在图表组件中使用 hideHeader=true，请确认上层容器是否提供了替代 HUD。
- 颜色与图标不正确
  - 确认净现金流与资产余额的正负逻辑是否按预期设置；对于负值，应使用红色系与相应图标。
  - 检查 MetricCard 的 isLarge 标志是否按需启用，以确保关键指标的视觉权重。
- 数据错位或不一致
  - 在 DualChartView 中，确认 CashFlow 数据已正确转换为 LifePlan 所需形态，且外部传参的 externalDataIndex 与 externalFraction 正确传递。
- 字体大小与间距问题
  - 如需调整字体大小，优先通过“大号”模式或统一的样式配置进行修改；避免在多处硬编码字体尺寸。

章节来源
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L1-L164)
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)

## 结论
UnifiedHUD 通过统一的 UI 设计与灵活的 props 接口，为视频画面提供了清晰、一致的关键财务指标展示层。其 MetricCard 子组件支持动态颜色与图标，结合正负值的视觉策略，有效提升了信息传达效率。在 LifePlanChart、CashFlowChart 与 DualChartView 中，UnifiedHUD 可作为独立 HUD 或与图表主体协同工作，满足不同场景下的可视化需求。

## 附录：扩展与定制指南

### 扩展新的指标卡片
- 新增卡片步骤
  - 在 UnifiedHUD 中新增 MetricCard 实例，传入 label、value、unit、color、icon 与可选的 isLarge。
  - 若新指标存在正负值含义，建议沿用正数绿色/负数红色的策略，并在图标与文案上保持一致风格。
- 数据映射
  - 在图表组件中，将新指标从数据源提取并传入 UnifiedHUD 的对应 props。
  - 在 DualChartView 或其他容器中，确保外部传参包含新指标的数据。

章节来源
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L1-L164)
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)

### 修改现有卡片的视觉样式
- 字体与间距
  - 通过“大号”模式提升关键指标的视觉权重；对非关键指标维持常规字号。
  - 统一标签区与数值区的间距，确保信息层级清晰。
- 颜色主题
  - 收入/支出/净现金流/资产余额分别采用与其语义相符的颜色体系；保持与图表主体的整体色彩协调。
  - 如需调整主题，建议在组件外部集中管理颜色常量，避免散落的硬编码颜色值。
- 内联样式组织
  - 将外层容器样式与卡片内部样式分离，便于维护与复用。
  - 对常用样式（如字号、字重、间距、圆角、阴影）建立统一规范，减少重复定义。

章节来源
- [UnifiedHUD.tsx](file://src/UnifiedHUD.tsx#L1-L164)
- [LifePlanChart.tsx](file://src/LifePlanChart.tsx#L1-L349)
- [CashFlowChart.tsx](file://src/CashFlowChart.tsx#L1-L441)
- [DualChartView.tsx](file://src/DualChartView.tsx#L1-L176)