single-file-dashboardlisted

# 单文件数据看板 看板整体效果（示例数据，非真实主体）：  ## 什么时候用 - 成果要**传给不会装环境的人**——对方双击就能看，不需要服务器、数据库、构建工具、也不联网； - 数据**不适合放到线上**（经营数据、内部排名），但又需要给多个人看； - 台账**还会持续更新**，希望接收方自己也能改几个数、改完还能再传出去。 如果只是给自己看、且不在乎离线，用常规的网页 + 后端更省事。这个 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 步：��数据加密后注入 ```bash # 装依赖（只需要 xlsx 一个） npm install xlsx # 编辑 scripts/dashboard_build.js 顶部的可配置区，然后： node scripts/dashboard_build.js ``` 脚本做四件事：读 Excel → 按列契约解析成 JSON → 用 PBKDF2 + AES-GCM 加密 → 用正则把密文替换进 HTML 的两个标记位之间。**可以反复运行**，每次都用