household-finance-dashboard-builder

家庭财务仪表板构建器

目录

• 概览
• 输出结构
• 输入约定
• 工作流
• 六个面板
• 应用的认知原则
• 叙事层
• HTML 脚手架
• 防护措施

概览

这是更通用的 d3-visualization 技能的静态输出版本。它会生成一个独立的 HTML 文件，其中内联了所有数据和图表代码，无需服务器即可在任何浏览器中打开。该仪表板旨在根据家庭的 JSON 数据存储每周重新生成，并提交到 reports/dashboards/YYYY-MM-DD-weekly.html。

此技能假定 JSON 存储符合家庭财务架构（账户、交易、余额、定期项目、目标、投资、抵押贷款、提醒）。

输出结构

一个单独的 HTML 文件，包含：

• 内联 <style> 块（不使用外部 CSS）。
• 内联数据块：<script id="dashboard-data" type="application/json">{...}</script>。
• 内联随附的 D3 v7（或在可接受离线渲染的情况下，通过一个带完整性哈希的 <script> 标签引入）。
• 使用 CSS Grid 渲染的六个面板。
• 通过 visual-storytelling-design 生成的简短叙事标题。
• 页脚，包含生成时间戳和源数据版本。

目标文件大小：小于 1 MB。如果数据超出此大小，请在嵌入前对时间序列降采样（从每日聚合到每周通常就足够了）。

输入约定

调用方提供：

• data_root — 家庭财务 data/ 目录的路径。
• output_path — HTML 文件的写入位置。
• generated_for — weekly 或 monthly（会更改时间范围和标题）。
• as_of — 快照的 ISO 日期。
• prior_snapshot_path（可选）— 之前仪表板的数据块，用于计算周环比变化。

此技能会读取：

• accounts.json
• balances.json
• transactions.json（筛选到相关时间范围）
• recurring.json
• goals.json
• investments.json
• mortgage.json
• reports/alerts/ 中的近期文件
• 最新的 reports/monthly/*.json，用于提供叙事背景。

工作流

Dashboard Build Progress:
- [ ] Step 1: Read data; validate completeness; compute snapshot
- [ ] Step 2: Compute the six panel datasets
- [ ] Step 3: Apply cognitive-design principles to layout choices
- [ ] Step 4: Generate narrative header via visual-storytelling-design
- [ ] Step 5: Render HTML scaffold + inline data + D3 code per panel
- [ ] Step 6: Run cognitive-fallacies-guard self-check on charts
- [ ] Step 7: Write to output_path; emit data quality footer

第 1 步 — 快照

计算关键数字：

• net_worth_cents — 现金 + 投资 + 房屋净值估算 − 负债（抵押贷款 + 其他）。
• delta_vs_prior_cents — 与之前的快照相比的变化（如果有）。
• month_to_date_spend_cents、month_to_date_income_cents、month_to_date_savings_rate。
• goals_on_track、goals_behind、goals_ahead 计数。
• alerts_open 计数。

如果缺少任何必需文件，请妥善降级处理：隐藏相应面板，并在页脚显示一行 data_gap。

第 2 步 — 面板数据集

仅计算各面板所需的数据（见六个面板）。保持数组精简——预先聚合到图表所需的分辨率。

第 3 步 — 认知原则

应用以下默认原则（详细推理委托给 cognitive-design）：

• 视觉层级。 页面上最重要的数字是净资产变化。将其以最大字号显示在左上角。
• 分块。 将六个面板排列成 3×2 网格；每个面板只传达一个要点。
• 编码层级。 位置 > 长度 > 斜率 > 面积 > 色相（依据 Cleveland & McGill）。比较类面板使用位置编码；颜色仅用于类别编码。
• 工作记忆。 每个面板要求用户比较的项目不超过 7 个。将较小类别合并为“其他”。
• 优先识别而非回忆。 在图表上直接标注每个数据系列。不要只通过图例编码。

第 4 步 — 叙事标题

调用 visual-storytelling-design 生成 3–5 行叙事：

• 开头直接给出要点，而非主题（例如“本周净资产增长了 $4,200，主要由 401k 缴款和股权收益带动”，而非“每周更新”）。
• 用一句话说明背景（与上周／上月／去年相比）。
• 用一句话指出提醒流中需要关注的事项。

步骤 5 — 渲染

构建 HTML 框架（参见 HTML 框架）。内嵌：

• 数据块。
• 一个小型 D3 v7 包（或带完整性哈希的外部 CDN）。
• 每个面板对应一个 renderPanel*() 函数。

每个渲染函数都遵循 d3-visualization 中的标准 D3 数据绑定模式。

步骤 6 — 自检

写入之前，对渲染后的 SVG（或其数据和坐标轴配置）运行一次 cognitive-fallacies-guard 检查：

• 坐标轴不得截断，以免夸大变化。
• 不使用 3D 效果。
• 环形图：在图内显示总计。
• 饼图 / 环形图：最多显示 6 个扇区，其余合并。
• 时间序列：包含零基线，除非这样会掩盖信号；若如此，则明确标注基线变化。

如果自检发现问题，请修正并重新渲染。

步骤 7 — 写入

写入 output_path。在页脚中注明生成时间戳、架构版本、最近数据日期以及任何数据缺口。

六个面板

面板 1 — 净资产随时间变化

数据：balances.json + investments.json + mortgage.json（将 current_principal 作为负债）+ 房屋净值估算（房屋价值 - current_principal）的月度净资产数据点。

图表：折线图，标注关键事件（抵押贷款发放、大额缴款、市场波动）。Y 轴从 0 开始（这是一个零值具有重要意义的净资产刻度）；X 轴覆盖完整历史记录。

标题注释：最新值 + 相较于上一快照的变化量。

面板 2 — 月度现金流

数据：过去 12 个月的每月收入（正向柱）和支出（负向柱），并以折线显示滚动 6 个月储蓄率。

图表：正负向柱状图（收入向上，支出向下），叠加储蓄率折线。颜色：收入使用柔和的青绿色，支出使用柔和的珊瑚色。

下钻（可选，悬停时显示）：最新月份支出最高的 5 个类别。

面板 3 — 定期支出和订阅

数据：recurring.json 中所有处于有效状态的条目，按 annualized_cost_cents 降序排列。

图表：显示年化费用最高的前 15 项的水平条形图。每个条形标注商户 + 周期 + 月均金额。

注释：在顶部显示所有有效定期支出的年化总费用。突出显示 status: suspected_dormant 的项目或金额变更事件。

面板 4 — 目标进度

数据：goals.json 中包含 current_cents、target_cents、target_date 的所有条目。

图表：水平堆叠条形图 — 已完成 vs. 剩余 — 每个目标占一行。根据按线性进度达到目标日期的情况，为每个目标标注“按计划进行 / 落后 / 超前”。

标题：“X / Y 个目标按计划进行。”

面板 5 — 资产配置

数据：按 asset_class 汇总 investments.json 中的持仓（涵盖应税账户 + 401k + HSA），并包含目标配置。

图表：两个并排的环形图（当前配置 vs. 目标配置），或一个叠加目标环的环形图。直接在每个扇区上标注资产类别 + 百分比。

注释：最大偏差（百分点）；若 > 5pp，则标记。

面板 6 — 重点提醒

数据：reports/alerts/ 中最近的 10 条记录，并按严重程度标记。

图表：带样式的列表，而非图表。每条记录包含：严重程度徽章 + 一行证据 + 建议操作。

此面板有意采用较多文本。仪表板既用于提供信息，也用于执行操作；用户应能快速浏览并找到需要处理的事项。

应用的认知原则

原则	在此仪表盘中的应用
前注意属性	警觉面板中的严重程度徽章使用色相；其他内容均使用位置
格式塔接近律	每个面板都以留白、细边框和标题依次划分
格式塔相似律	所有数值标签使用相同的等宽字体；所有图表使用相同的坐标轴样式
阅读顺序（F 形模式）	净资产位于左上角；警觉面板位于右下角（阅读顺序中可采取行动的位置）
工作记忆	每张图表最多显示 6 个类别；其余类别汇总显示
识别优于回忆	直接标注，不使用仅靠图例说明的图表
数据墨水比	不使用 3D、图表装饰或装饰性渐变
心智模型	现金流图表采用广为认可的绿色表示上涨、红色表示下跌的惯例

叙事层

叙事标题遵循：背景 → 变化 → 驱动因素 → 需要关注的事项。

示例：

净资产为 $1,247,300——本周增加了 $4,200。 增长主要来自 $3,800 的 401k 缴款，以及应税经纪账户的小幅市场收益。本月至今的支出稳定在 $7,840，略低于 $8,500 的目标。有一点需要关注：你的投资组合偏离至 62.5% 的美国股票配置，比 55% 的目标高出 7.5 个百分点——本周提醒中已排入一项再平衡提案。

HTML 框架

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Household Finance — [date]</title>
  <style>
    /* layout: 3x2 grid; max-width 1280px; light theme */
    /* typography: Inter for text, JetBrains Mono for numbers */
    /* colors: muted, accessible, single accent for "needs attention" */
  </style>
</head>
<body>
  <header>
    <h1 class="net-worth-headline">$</h1>
    <p class="net-worth-delta">[+/-]$ this </p>
    <p class="narrative">[generated narrative]</p>
  </header>

  <main class="grid">
    <section id="panel-net-worth"></section>
    <section id="panel-cash-flow"></section>
    <section id="panel-recurring"></section>
    <section id="panel-goals"></section>
    <section id="panel-allocation"></section>
    <section id="panel-vigilance"></section>
  </main>

  <footer>
    <p>Generated [timestamp] from data/ as of [last-drop-date]. Schema version [X].</p>
    <p>Data gaps: [if any].</p>
  </footer>

  <script id="dashboard-data" type="application/json">
    { /* inlined data */ }
  </script>
  <script src="https://cdn.jsdelivr.net/npm/d3@7" integrity="sha384-..." crossorigin></script>
  <script>
    /* renderPanelNetWorth(), renderPanelCashFlow(), renderPanelRecurring(),
       renderPanelGoals(), renderPanelAllocation(), renderPanelVigilance() */
  </script>
</body>
</html>

如需完全离线使用，请将 D3 内嵌，而不是通过 CDN 加载。仪表盘 Agent 会根据环境决定。

防护措施

• 独立文件。 不获取外部数据。用户可以通过电子邮件发送文件或保存到磁盘，文件仍可正常工作。
• 图表诚实。 条形图从零开始；不截断 y 轴；不使用 3D 或图表装饰。
• 隐私。 此仪表盘包含家庭财务信息——嵌入账户掩码（****1234），绝不包含完整账号。不要包含 SSN；可用掩码代替的地方不要填写全名。
• 可复现性。 相同的输入数据和生成日期应生成字节完全相同的 HTML（时间戳除外）。渲染前对所有数组进行确定性排序。
• 性能。 对数据序列进行降采样，使文件大小低于 1 MB。仪表盘在普通笔记本电脑上的渲染时间低于 200 ms。
• 无障碍性。 所有图表都有标题和摘要 aria-labels；每张图表都提供可通过“显示数据”切换项访问的表格数据替代内容。
• 适配移动设备。 宽度低于 768px 时，网格折叠为单列；字体大小会相应调整。
• 版本管理。 页脚包含架构版本和生成脚本版本，以便追溯未来的重新生成。