单文件数据看板

看板整体效果（示例数据，非真实主体）：

Image: 效果示例

什么时候用

• 成果要传给不会装环境的人——对方双击就能看，不需要服务器、数据库、构建工具、也不联网；
• 数据不适合放到线上（经营数据、内部排名），但又需要给多个人看；
• 台账还会持续更新，希望接收方自己也能改几个数、改完还能再传出去。

如果只是给自己看、且不在乎离线，用常规的网页 + 后端更省事。这个 skill 的全部价值就在"文件即数据、文件即应用"这一条约束上。

四条硬约束

违反任何一条，这个方案就不成立了：

1. 单文件——HTML 里不能有外链的 CSS / JS / 图片 / 字体。CDN 一断、内网一隔离，页面就白屏。
2. 数据嵌在文件里——不请求任何接口，数据以加密串的形式写在 <script> 里。
3. 零构建——接收方拿到的是成品文件，不需要 npm install。
4. 保存 = 下载——没有后端可写，用户点的"保存"是把当前状态序列化后另存为一个新的 HTML 文件。

工作流

第 1 步：先把数据摸清楚，再动手做界面

不要拿到 Excel 就开始写 HTML。 先跑 excel-data-pipeline/scripts/inspect_excel.py，它会把这个工作簿的真实结构 dump 成一个文本文件：sheet 名单、行列范围、逐列的列号与表头文字、前若干行的样例值。

这一步跳过，后面 90% 的返工都来自它。真实台账的常见形态：表头不在第一行、有合并单元格、中间夹着空行做视觉分隔、同一份数据里并排放着好几个"年度块"。

第 2 步：定列契约，写进脚本

把上一步看出来的列位置显式写进提取脚本的顶部配置区，不要在代码中间散落魔法数字 row[9]。参考 excel-data-pipeline skill 的 scripts/extract.py。

同时在脚本开头加一道列名校验：读第 1 行的表头文字，和预期的列名逐个比，对不上就报错退出。台账被人删过两列、整体前移这种事，校验能在生成阶段拦住，而不是等交付后被人发现数字错了。

第 3 步：从骨架开始，不要从零写

assets/dashboard-skeleton.html 是一个能跑的最小可用看板，已经打通了下面这条完整链路：

输入密码 → PBKDF2 派生密钥 → AES-GCM 解密 → 解析 JSON → 渲染 KPI + SVG 图表 + 表格

把它复制成你的目标文件，然后只做三件事：改 __META__ 里的标题机构等文案、改渲染函数贴合你的指标、调整配色。不要改加密与解密那一段——两端必须严格对称，改错一边就是永远解不开。

第 4 步：把数据加密后注入

# 装依赖（只需要 xlsx 一个）
npm install xlsx

# 编辑 scripts/dashboard_build.js 顶部的可配置区，然后：
node scripts/dashboard_build.js

脚本做四件事：读 Excel → 按列契约解析成 JSON → 用 PBKDF2 + AES-GCM 加密 → 用正则把密文替换进 HTML 的两个标记位之间。可以反复运行，每次都用 Excel 的最新内容覆盖，不会叠加。

替换用的是带捕获组的正则（(window\.__ENCRYPTED__\s*=\s*")[^"]*(")），而不是字符串查找替换——这样标记位周围的代码被改动了也还能定位到。

第 5 步：交付

发出去的是那一个 HTML 文件。不要连 node_modules、不要连脚本、不要连源 Excel。接收方需要知道的只有两件事：双击打开、密码是多少。

关键设计决策

这几条是踩过坑才定下来的，照做可以省掉整轮返工。

为什么不用 localStorage 存数据？ 数据无法跨设备共享，换台电脑就没了。改为"序列化后下载新 HTML"，文件本身成了载体——转发这个文件就等于转发数据。

为什么图表不用 ECharts / Chart.js？ 它们要么走 CDN（断网即废），要么得把几百 KB 的库内联进文件（文件体积失控）。原生 SVG 手绘没有依赖、体积小、还能被打印和截图工具正确处理。折线、柱状、环形这三类靠几十行代码就能画完。

为什么加密用 PBKDF2 + AES-GCM，而不是简单的 XOR？ XOR 用固定密钥时，密钥就明文躺在文件里，谁打开源码都能解。改成从密码派生密钥后，密码本身成了密钥——不知道密码就是解不开，而不是"看得到但懒得看"。浏览器原生 crypto.subtle 和 Node 的 crypto.webcrypto 都支持，零依赖。

⚠️ 说清楚它的强度边界：这是防肩窥、防随手复制、防文件被转发后被无关的人看懂，不是防定向攻击。文件本身可以被离线暴力破解，密码强度直接决定安全上限。所以：密码要够长，真正的核心机密不要走这条路。

为什么表格要"就地可编辑"？ 接收方拿到数据后总有小修改（补一个月的数、修一个录错的值）。如果必须回到 Excel 改完再重新生成，这个文件在对方手里就是死的。就地可编辑 + 保存即下载，让接收方能自己完成一个完整的迭代闭环。

为什么冻结列要用 position: sticky 并动态重算 left？ 冻结前几列时，每列的 left 偏移等于它前面所有列的宽度之和。列宽一旦被拖拽调整，这个偏移就必须重算，否则冻结列会重叠或者露出缝隙。所以拖拽结束后必须调一次重算函数。

常见坑

更多实现细节见 references/editable-table-patterns.md。

目录内容

single-file-dashboard/
├── SKILL.md                            本文件
├── scripts/
│   └── dashboard_build.js              Excel → 加密 JSON → 注入 HTML（第 4 步）
├── references/
│   └── editable-table-patterns.md      可编辑表格 / 树形 / 冻结列 / 拖拽的实现要点
└── assets/
    └── dashboard-skeleton.html         能跑的最小看板骨架（第 3 步从这里复制）

数据层的探结构与列契约见 excel-data-pipeline skill（第 1、2 步的工具在那里）；要做幻灯汇报而不是看板，见 html-slide-report。