晓如老师_动态看板

这份技能解决的事：把一份表格变成能点的看板——筛选会重算、换数据会刷新、颜色能换——而不是一张截图或一堆静态图表。

产出的永远是一个 HTML 文件，图表引擎与解析库全部内联，断网、拷 U 盘、发微信都能直接双击打开。

一、什么时候用

用户表达以下任一意图即启用：

• 「做个动态看板 / dashboard / 仪表板 / 数据看板 / 可视化看板 / 驾驶舱 / BI 大屏」
• 「把这些数据做成图表，能筛选」「做个能上传新数据的看板」
• 在已有分析报告之后说「把结论做成看板」

不适用：单张静态图表、PPT 版图表、需要后端实时数据流的监控系统。

二、交付物的固定结构

┌─ 顶栏：标题 / 副标题 / 数据源 / 更新时间 / 重置 / 上传数据 ─┐
├─ 切片器：维度1 chips · 维度2 chips · 搜索框 · 当前筛选计数 ─┤
├─ KPI 行：6 张卡片（2–3 张用 warn/danger 色标风险项）      ─┤
├─ 第1行：主维度组合图（柱=合计 / 线=均值）｜结构环形图      ─┤
├─ 第2行：次维度组合图                ｜分布图（等宽分档）   ─┤
├─ 第3行：存在问题（3 条）             ｜建议措施（4 条）     ─┤
└─ 页脚：数据口径说明                                       ─┘

这套结构不要随意改动——它是经过验证的阅读动线：先看总量（KPI）→ 再拆结构（维度图+环形图）→ 再看分布（长尾/异常）→ 最后读结论。

三、工作流程

五个步骤，前四步必做，第五步必做一次。

Step 1　摸清数据

python "<skill>/scripts/extract_data.py" -i 数据.xlsx --profile-only

输出每列的 kind（numeric / categorical / id / text）、唯一值数、空值数、样例。

判读要点：
- kind=categorical 且有 2–20 个唯一值 → 可做维度（切片器 + 坐标轴）
- kind=numeric → 可做度量
- kind=id（唯一值 = 行数）→ 只能进搜索框，不能做维度
- 唯一值 > 40 的文本列 → 不要做切片器，改 "slicer": "select" 或干脆不用

多 sheet 用 --sheet 1，表头不在第一行用 --header-row 2。

Step 2　写 spec.json

spec 是看板的「声明」：有哪些维度、算哪些指标、四张图画什么、结论区写什么。

不要手搓字段名——先让脚本出草稿，再改：

python "<skill>/scripts/extract_data.py" -i 数据.xlsx -o data.json --draft draft.json --title "XX看板"

草稿只是能跑的骨架，必须继续做三件事：

1. 改写 aliases：把真实表头的各种变体补全（实发工资 / 实发 / 实发合计），否则用户上传同类文件时会识别不到列
2. 改写 KPI 与图表标题：把「f1 合计」换成业务语义（「实发工资总额」）
3. 补 issues / advice：这是看板的结论价值所在，草稿里是空的

字段含义见 references/spec-schema.md。

Step 3　抽数

python "<skill>/scripts/extract_data.py" -i 数据.xlsx -o data.json --spec spec.json

会回报 mapped_keys（成功映射的键）与 unmapped_columns（没被用到的列）。确认没有关键列落在 unmapped_columns 里。

Step 4　构建

python "<skill>/scripts/build_dashboard.py" --spec spec.json --data data.json \
    --out 看板.html --source-name "原始文件名.xlsx" [--theme "#0093DD"]

构建脚本自带三重门禁，任一不过会直接报错而不是交付一个空白页：
- 占位符残留检查
- 输出体积检查
- 用 node 对内联引擎脚本做 --check 语法检查

Step 5　视觉校验（不可跳过）

用浏览器截一次图确认渲染。Windows 上用 Edge headless：

E="/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
"$E" --headless=new --disable-gpu --no-sandbox --hide-scrollbars --no-first-run \
  --user-data-dir="C:/tmp/_ed_dash" --virtual-time-budget=7000 \
  --force-device-scale-factor=2 --window-size=1600,1200 \
  --screenshot="C:/tmp/dash.png" "file:///C:/path/看板.html"

必须逐项确认的六点（这些是实际踩过的坑）：

四、主题色

用户指定了颜色就用用户的，两种传法等价：

--theme "#C8102E"          # 命令行覆盖，方便快速试色

"theme": {"primary": "#C8102E", "accent": "#FFB020", "danger": "#D92B2B"}

primary 一个值就能推导出全套 10 阶色带（深色标题、浅色底纹、按钮、柱子渐变、切片器高亮），不需要手配。

用户没说颜色怎么办：不要默认穿别人的品牌色。先问一句「想用哪个主色」，同时给三个预设让他选（见 references/theme-presets.md）；确实不想问就用中性深蓝 #1B6EC2。

深色主色（如藏青 #0A2A4A）会自动切白字，浅色主色自动切深字，无需额外处理。

五、上传数据功能

这个能力是内置的，不用额外开发。上传后看板会：重新解析 → 按 aliases 重映射列 → 重算全部指标 → 重建切片器。

能否正常刷新，取决于 aliases 写得够不够全。写 aliases 的原则：

"aliases": {
  "net": ["实发工资", "实发", "实发合计", "net"],
  "dept": ["部门", "所属部门", "部门名称", "一级部门"]
}

• 每个键至少给 2–3 个常见变体，含下发的原始表头
• 匹配时会自动忽略空格、换行、全角/半角括号、标点，所以 社保(个人） 与 社保（个人） 视为同一列
• 缺 应付工资 这类派生列时，只要分项齐全仍能算（先补分项再算）

上传失败时页面会弹出红色提示，明确告知缺哪些列 + 读到了哪些列，用户据此调整表头即可。这个反馈是有意设计的，不要吞掉错误。

六、写结论区的四条硬规矩

issues 与 advice 是看板的价值所在，也是最容易注水的地方。

1. 每个数字必须能由 spec 里的 stat 算出来，用 {statName} 占位，不要手写死数字——筛选一变，手写的数字立刻变成谎话
2. 一条结论 = 一个发现 + 一组证据 + 一个影响，不写「需要加强管理」这类无主语的话
3. 测算与实测要分开说：静态推演、倒推值必须标注口径（如「按月度静态测算」「按津贴倒推」），不能当既成事实
4. 建议必须带责任方与时限（meta: ["责任：财务部", "时限：本月发薪前", "优先级：P0"]），否则不是建议是感想

七、常见错误（都踩过，别再踩）

环形图混入不同量纲的项
把「销售额」和「数量」放进同一个环形图求和，得到的是无意义的数字。环形图的 measures 模式只用于同量纲的构成项（工资的各收入项、成本的各科目）。类别占比请用 "mode": "dimension"。

把分类列当数值列转换
{"stat":"distinct","field":"dept"} 里的 dept 是分类列。构建脚本已自动排除该字段与所有维度键，但如果手写 spec.numeric 时把维度列写进去，上传后 dept 会变成 0，切片器全空、图表只剩一个「0」类别。

单类目柱宽失控
组合图的柱子必须设 barMaxWidth。只设 barWidth:'34%' 时，筛到只剩一个类别，柱子会撑满半个图。

切片器全选与全不选混淆
空集合表示「全部」，不是「全不选」。默认不点亮任何 chip 是正确状态，靠「当前筛选 X / Y 条」传达筛选状态。

下载 JS 库被截断
内联前必须校验文件尾部（ECharts 以 })); 结尾，SheetJS 以 make_xlsx_lib(XLSX) 结尾）。下载被中断时浏览器会只报一句 Unexpected end of input，极难排查。build_dashboard.py 已内置尾部校验与自动重下。

用 </body> 作为注入锚点
调试时往 HTML 注入探针，不能用 </body> 定位——库源码里有 '<body style=...>' 字符串，会把脚本插进 JS 内部导致整页变纯文本。用唯一元素如 <div id="toast"></div>。

八、资源清单

Python 依赖：pandas、openpyxl。缺 pandas 时先装，不要回退到手写解析。

九、交付话术

给用户交代三件事即可：

1. 文件在哪、多大、能不能离线（单文件内联，双击即开）
2. 能做什么（筛选哪些维度、上传后怎么刷新、换色怎么换）
3. 哪一处口径需要他确认（如果有测算值或异常数据，明确点出来，别藏在一堆百分比里）

不要罗列功能清单充数。