学页｜学情进度仪表盘
概述
学页｜学情进度仪表盘是一款面向 K12 教培机构学管师、班主任与学校教师的班级学情监控技能。团队只需上传班级学习数据（平台导出或人工台账），即可一键生成零依赖单文件 HTML 交互式仪表盘，解决学情管理中的四大痛点：
- 全班扫不完——一人带 3-6 个班、上百学员，逐行翻表格找问题不现实
- 问题浮不出——预警信号淹没在几十列数据里，发现掉队时已晚两周
- 例会没抓手——周例会学情汇报全靠口头，缺一张能投屏、能留档的总览页
- 工具装不起——专业 BI 工具要账号、要部署、要培训，机构用不起来
本技能把 30 列的学员明细表变成"打开即用"的学情驾驶舱：顶部 KPI 卡片一屏看清班级健康度，中部预警榜直指最该跟进的学员，底部知识点热力图暴露全班共性短板——5 分钟完成一次全班巡检。
产出为单文件 HTML（无外部依赖、可离线打开、可投屏、可微信发送），同时附班级快照 .xlsx（留档/二次分析）与 dashboard_data.json（供下游技能消费）。
触发场景
以下情况触发本技能：
- 直接关键词：学情仪表盘、学情看板、班级学情、学情总览、学习进度看板、学情驾驶舱、学情速览、班级进度、学情监控、学情大屏
- 语境触发：用户描述班级学情巡检需求（如"每周要看一眼全班学情""周一例会要汇报各班学习情况""把这份班级数据做成看板"）
- 材料触发：用户上传班级学习数据（.csv/.xlsx：出勤、作业、测验、进度等），要求生成看板/仪表盘/总览
- 组合触发：用户已用 xueye-lesson-prep 上完课要看班级吸收情况；已用 xueye-quiz-generator 出完题要看答题分布；周期末先看仪表盘定位问题学员，再逐个生成深度报告
不触发的场景：逐人深度报告（用 xueye-learning-report-generator）、完课归因诊断（用 xueye-completion-attributor）、互动教室工具（用 xueye-interactive-classroom）、非学情数据的常规可视化（常规表格任务）。
与其他学页技能的关系：
- xueye-learning-report-generator（学习报告生成器）→ 本技能管"一眼看全班"的日常监控，报告生成器管"逐人讲清楚"的成果沟通；两者同口径（H1-H4 分级、五维雷达），仪表盘 H3/H4 学员可流转给报告生成器出个人深度报告
- xueye-completion-attributor（完课状态归因器）→ 本技能发现"谁掉队"，归因器回答"为什么掉队"；仪表盘 H4 风险学员建议走归因流程
- xueye-lesson-prep（AI备课）→ 知识点热力图暴露的共性短板，可用备课技能快速产出针对性补弱微课
- xueye-quiz-generator（课堂互动题目）→ 热力短板可联动出一套课堂巩固题
- 本技能是学页系列"监控中枢"：数据从教学侧流入（备课/出题/上课），仪表盘持续巡检，异常分流到报告（沟通）与归因（诊断），形成闭环
交付物一览
| 交付物 | 格式 | 内容 |
|---|---|---|
| 学情仪表盘 | .html（单文件零依赖） | KPI 总览 + 健康分布 + 五维雷达（班级vs个人）+ 预警学员榜 + 知识点热力 + 学管行动清单，支持交互筛选 |
| 班级快照 | .xlsx | 三 Sheet：班级总览（H等级着色）、预警清单（仅H3/H4）、指标口径说明 |
| 仪表盘源数据 | dashboard_data.json | 机器可读完整数据，供下游技能与跨期对比 |
工作流程
仪表盘生成遵循六步标准化工作流。按顺序执行，每一步的输出作为下一步的输入。
Step 1: 需求采集
从用户输入中提取仪表盘生成要素。如信息不完整，提问补充。
需采集的要素：
| 要素 | 必填 | 默认值 | 示例 |
|---|---|---|---|
| 班级/课程名 | 是 | — | "初二数学提高班 C2026-08" |
| 班级学习数据 | 是 | — | .csv/.xlsx（学员粒度） |
| 学段学科 | 是 | — | 初中·数学 |
| 统计周期 | 否 | 数据日期推断 | "2026秋季第1-8周" |
| 快照日期 | 否 | 今天 | 数据导出日 |
| 管理范围 | 否 | 全部学员 | "只看八年级3班" |
| 预警阈值调整 | 否 | 默认阈值 | "出勤预警线调到85%" |
| 落款信息 | 否 | 无 | 机构名 + 学管师称呼 |
采集规则：
1. 最多提问 3 个问题，一轮问完，禁止多轮追问
2. 只问缺失的必填项；用户已表达的信息不重复问
3. 用户上传数据文件后，先运行解析器探查列名，再决定是否提问
4. 非必填项未提供时使用默认值，不提问
5. 信息齐全时直接进入 Step 2，无需确认
数据最低要求（学员粒度）：student_id 必须有；出勤/作业/测验/进度/互动/进步六类数据至少有一类非空，否则无法成盘，提示用户补导。
Step 2: 数据解析与指标计算
对班级数据做结构化解析，计算指标、分档、五维雷达与健康等级。
实现方式： 运行 scripts/dashboard_parser.py 解析数据
python scripts/dashboard_parser.py class_data.csv --json
python scripts/dashboard_parser.py class_data.csv --snapshot 2026-08-18 --meta meta.json
加载参考文档： references/dashboard-metrics.md — 指标体系与数据口径
解析产出：
1. 20+ 指标：出勤/提交/测验/进度/互动/进步六类，缺数据记 null 不编造
2. 五维雷达：坚持度/完成度/掌握度/互动度/进步度，0-100 归一化
3. 健康等级：H1 优质（0 预警维）/ H2 稳定（1）/ H3 波动（2）/ H4 风险（≥3）
4. 班级基准：各项均值/中位数/分布，供分位对比
5. 预警明细：触发预警的学员×维度清单，按预警数排序
解析规则：
1. 列名宽容匹配（中英文列名、大小写、下划线均识别）
2. 数据残缺记录跳过并报错提示，不静默丢弃
3. 快照原则：全部指标基于同一快照日期计算
4. 班级基准两遍计算：先算全班，再带基准重算个人互动分位与预警
Step 3: 预警规则应用
加载预警规则，对解析结果逐人逐维扫描，生成预警清单与学管行动清单。
实现方式： dashboard_parser.py 内置默认规则，可用 --thresholds 传入自定义阈值 JSON 覆盖。
python scripts/dashboard_parser.py class_data.csv --json --thresholds custom_thresholds.json
加载参考文档： references/alert-rules.md — 预警规则与阈值配置
默认预警规则（8 条）：
| 编号 | 规则 | 默认阈值 |
|---|---|---|
| A1 | 出勤率预警 | < 85% |
| A2 | 作业提交率预警 | < 80% |
| A3 | 随堂测均分预警 | < 70 分 |
| A4 | 完课进度预警 | 落后时间进度 ≥ 15 个百分点 |
| A5 | 学习沉默预警 | 近 14 天无学习行为 |
| A5' | 互动预警 | 互动次数 < 班级 P25 |
| A6 | 成绩下滑预警 | 本期 vs 上期下降 ≥ 10 分 |
| A7 | 排名下滑预警 | 排名后退 ≥ 5 名 |
输出：
1. 预警清单：每条含学员、维度、触发规则、当前值、建议动作
2. 学管行动清单：按预警数×严重度排序的跟进队列，含建议首次触达方式（微信/电话/约谈）
3. 预警配置快照：本次实际生效的阈值（写入 JSON，跨期对比时声明口径）
Step 4: 仪表盘生成
将解析与预警结果渲染为单文件 HTML 仪表盘。
实现方式： 运行 scripts/dashboard_builder.py 渲染 HTML
python scripts/dashboard_builder.py dashboard_data.json -o 学情仪表盘_初二数学_2026-08-18.html
加载参考文档： references/dashboard-design-guide.md — 仪表盘布局与交互规范
仪表盘结构（六区）：
| 区块 | 内容 | 回答的问题 |
|---|---|---|
| 顶部 KPI 条 | 学员数/出勤率/提交率/均分/进度/预警数 六卡片 | 班级整体怎么样 |
| 健康分布 | H1-H4 人数分布条 + 占比 | 班级健康结构如何 |
| 五维雷达 | 班级均值雷达 + 点击学员叠加个人雷达 | 哪一维是全班短板 |
| 预警学员榜 | 预警数降序，学员×维度×规则×建议动作 | 谁最需要现在跟进 |
| 知识点热力 | 薄弱知识点 × 班级通过率热力矩阵 | 全班共性短板在哪 |
| 行动清单 | 按优先级排列的学管跟进队列 | 今天该做什么 |
交互能力（零依赖，原生 JS 实现）：
1. 预警榜/总览表点击学员行 → 弹出个人详情面板（五维雷达叠加 + 指标明细 + 预警明细）
2. 健康等级筛选器（H1/H2/H3/H4）→ 联动过滤总览表与预警榜
3. 维度筛选器（出勤/作业/测验/进度/互动/进步）→ 切换热力图与雷达焦点维
4. 明暗双主题切换（投屏亮环境/办公暗环境）
设计规范（详见 dashboard-design-guide.md）：
- 单文件自包含：CSS/JS/数据全部内联，无 CDN、无外链字体、离线可用
- 预警红/关注橙/稳定蓝/优质绿四色语义系统，色盲友好
- 1366×768 投屏不横向滚动，一屏聚焦核心区
- 数据脱敏：默认展示 student_id，display_name 仅在用户提供时显示
Step 5: 班级快照导出
将仪表盘数据导出为 Excel 留档。
实现方式： 运行 scripts/dashboard_export.py 导出 xlsx
python scripts/dashboard_export.py dashboard_data.json -o 班级快照_初二数学_2026-08-18.xlsx
三 Sheet 结构：
1. 班级总览：一行一学员，全指标 + H 等级着色（H1绿/H2蓝/H3橙/H4红）
2. 预警清单：仅 H3/H4 及触发预警学员，含规则、当前值、建议动作
3. 指标口径：每个指标的计算方式与本次生效阈值，家长/上级问到时对照解释
Step 6: 成果整合交付
将仪表盘与快照统一交付。
实现方式： 调用 present_files 统一展示。
交付物： 学情仪表盘.html + 班级快照.xlsx + dashboard_data.json
交付后提示：
- 告知 HTML 可直接双击打开、可投屏、可微信发送学员家长前先脱敏
- 建议每周固定时间（如周一晨会前）用最新数据重跑一次，跨期对比看趋势
- H4 风险学员建议流转 xueye-completion-attributor 做完课归因
- H3/H4 学员建议流转 xueye-learning-report-generator 出个人深度报告
参考文档索引
以下参考文档按需加载，不必一次性全部读取：
| 文档 | 路径 | 加载时机 |
|---|---|---|
| 指标体系与口径 | references/dashboard-metrics.md |
Step 2 数据解析 |
| 预警规则与阈值 | references/alert-rules.md |
Step 3 预警应用 |
| 仪表盘布局规范 | references/dashboard-design-guide.md |
Step 4 生成仪表盘 |
| 数据字段规范 | references/data-schema.md |
Step 1 数据探查 / 用户数据异常时 |
工具脚本
以下脚本可直接执行，提供确定性能力：
| 脚本 | 路径 | 用途 | 调用时机 |
|---|---|---|---|
| 数据解析器 | scripts/dashboard_parser.py |
解析班级数据，计算指标/雷达/健康等级/预警，输出 dashboard_data.json | Step 2-3 |
| 仪表盘渲染器 | scripts/dashboard_builder.py |
由 JSON 渲染单文件 HTML 仪表盘 | Step 4 |
| 快照导出器 | scripts/dashboard_export.py |
由 JSON 导出三 Sheet 班级快照 xlsx | Step 5 |
数据解析用法：
python scripts/dashboard_parser.py class_data.csv # 人类可读摘要
python scripts/dashboard_parser.py class_data.csv --json # dashboard_data.json
python scripts/dashboard_parser.py class_data.csv --snapshot 2026-08-18
python scripts/dashboard_parser.py class_data.csv --meta meta.json # 附班级元信息
python scripts/dashboard_parser.py class_data.csv --thresholds th.json # 自定义阈值
仪表盘渲染用法：
python scripts/dashboard_builder.py dashboard_data.json -o 学情仪表盘.html
python scripts/dashboard_builder.py dashboard_data.json -o out.html --title "初二数学·第8周学情"
快照导出用法：
python scripts/dashboard_export.py dashboard_data.json -o 班级快照.xlsx
依赖的 WorkBuddy 内置技能
| 技能 | 用途 | 调用步骤 |
|---|---|---|
present_files |
统一交付仪表盘与快照 | Step 6 |
| （无其他外部依赖） | 全部脚本为 Python 标准库实现，xlsx 用 openpyxl 可选依赖 | — |
重要约束
- 单文件零依赖铁律：仪表盘 HTML 必须自包含（CSS/JS/数据全内联），禁止 CDN、外链字体、外部图片——教室电脑无网也要能打开
- 口径一致性：本技能与 xueye-learning-report-generator 保持同一套指标口径与 H1-H4 分级，跨技能流转学员时数字不打架
- 缺数不编造：某类数据缺失时对应指标记 null，仪表盘区块标注"数据未采集"并降级显示，禁止用 0 或均值填充冒充实测
- 数据脱敏：仪表盘默认展示 student_id；display_name/联系方式等 PII 仅在用户明确提供且要求展示时显示；提示用户对外分享前先脱敏
- 监控不替代诊断：仪表盘回答"谁有问题"，不回答"为什么"；H4 学员必须引导走归因流程，禁止在仪表盘上直接下干预结论
- 阈值透明：所有预警阈值在仪表盘"指标口径"区与快照 Sheet3 完整披露，禁用黑箱阈值
