成绩可视化看板（StudentsScoreAnalyzer）

一个基于 Streamlit 的多次考试成绩/排名可视化应用。支持多 Excel 文件上传、可视化排序与标签、科目选择、单/多学生对比、打印导出优化，以及 Windows 打包（含图标与版本信息、关闭窗口即退出服务）。

功能特性

• 多文件上传与顺序管理

  • 同时上传多个 Excel；侧边栏可自定义“考试标签”和展示顺序
  • 可选拖拽排序（安装 streamlit-sortables 后启用），否则可在表格内编辑顺序
  • “可视”开关：支持对每次考试设置是否参与后续统计/图表

• 科目与年级设置

  • 科目多选：语文、数学、英语、物理、化学、生物，扩展包含 政治/历史/地理/技术
  • 年级总人数输入：用于雷达图排名反转与后续百分位扩展

• 单学生视图（选择某个学生）

  • 全部考试成绩明细表（行=考试标签；列=总分+各科，自动一位小数格式化）
  • 排名明细表（总分与各科的“校次”排名，按考试列展示）
  • 排名时间序列折线图：
    • 可选查看内容：校次排名 / 班次排名 / 分数
    • 可选一个或多个项目（总分或多个科目）同时对比
    • 颜色=科目/项目；线型（和点形）=学生
    • 排名类 y 轴自动反转（名次越小越靠上）
  • 总分跨考试柱状图：支持自动调整 y 轴起点以放大分差
  • 各科成绩跨考试分组柱状图（颜色=考试标签，不含总分）
  • 各科校次排名跨考试分组柱状图（颜色=考试标签，y 轴反转）
  • 雷达图：多次考试叠加对比各科校次排名（将名次反转为“面积越大越好”）

• 多学生对比

  • 在排名时间序列中可选择多个学生同时对比（列表会自动包含主学生）

• 打印优化

  • 注入防分页 CSS，Plotly 图、表格等在浏览器打印时不被分页拆分

Excel 列结构假设

建议统一列结构，至少包含以下列（缺失列将自动忽略或标成未知列）：

准考证号, 班级, 姓名, 总分, 总分_校次, 总分_班次,
语文, 语文_校次, 语文_班次,
数学, 数学_校次, 数学_班次,
英语, 英语_校次, 英语_班次,
物理, 物理_校次, 物理_班次,
化学, 化学_校次, 化学_班次,
生物, 生物_校次, 生物_班次

说明：如果文件列名不完全一致，程序会按固定顺序重命名前若干列；其余列保留为 未知列*。应用会尽量将分数/排名列自动转为数值，避免混合类型问题。

安装与运行（Windows PowerShell）

# 1) （可选）创建并激活虚拟环境
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 2) 安装依赖
pip install -r requirements.txt

# 3) 运行（二选一）
# 方式A：直接运行 Streamlit
streamlit run .\gy.py

# 方式B：通过 run.py（保持一些全局参数一致）
python .\run.py

打开页面后：

• 在侧边栏上传多个 Excel 文件
• 编辑“考试标签”和展示顺序（可拖拽或表格编辑），并勾选“可视”
• 选择参与分析的科目、年级总人数、是否自动调整分数图 y 轴
• 筛选班级、选择学生；按需选择多个学生与多个项目进行对比

打印导出建议

浏览器端：Ctrl+P（或系统打印）即可得到不被分页拆分的图表/表格版式。若需要导出高分辨率图片，可结合 Plotly 的导出（或安装 kaleido）。

打包（PyInstaller）

项目已包含 run.spec，集成了：

• 图标：使用 favicon.ico
• 版本信息：使用 version_info.txt（FileVersion/ProductVersion 等）
• 运行时钩子：hooks/close_on_console_exit.py，在 Windows 上关闭控制台窗口即可退出服务

打包命令：

pyinstaller run.spec --clean

生成的可执行文件位于 dist 目录（默认名称为 StudentScoreAnalyzer.exe）。

修改图标

• 替换根目录下的 favicon.ico 或在 run.spec 中调整 ICON_PATH

修改版本号

• 编辑根目录 version_info.txt：
  • filevers=(1, 0, 0, 0) 与 prodvers=(1, 0, 0, 0)
  • StringStruct('FileVersion', '1.0.0.0') 与 StringStruct('ProductVersion', '1.0.0.0')
• 重新运行打包命令

关闭窗口即退出服务

• 打包后的程序有控制台窗口，直接点击“X”关闭会触发运行时钩子立刻退出，不会残留后台进程

常见问题（FAQ）

• 打包时报错 PermissionError: 无法删除 dist 下的 exe？

  • 先结束正在运行的旧实例：

    tasklist /FI "IMAGENAME eq StudentScoreAnalyzer.exe"
    taskkill /F /IM StudentScoreAnalyzer.exe

  • 然后再执行 pyinstaller run.spec --clean

• 拖拽排序没出现？

  • 安装可选依赖并重启应用：

    pip install streamlit-sortables

• 为什么排名图 y 轴是反的？

  • 排名名次越小越靠前，为了直观比较，图中将 y 轴反向（越靠上名次越好）

• 雷达图为什么“面积越大越好”？

  • 对“名次”做了反转，名次越靠前数值越大，面积也更大

• 没有显示某个科目？

  • 原始文件缺少该科列或命名不规范（如缺 科目_校次），应用会自动忽略不存在的列

目录结构（关键文件）

• gy.py：应用主程序
• run.py：命令行入口（以 Streamlit 方式运行）
• run.spec：PyInstaller 打包配置（图标/版本/运行时钩子）
• version_info.txt：Windows 版本资源定义
• hooks/close_on_console_exit.py：关闭控制台即退出的运行时钩子（Windows）
• requirements.txt：依赖清单