# 数据统计模块说明 > 面向开发、测试人员:说明当前原型的页面结构、角色权限、数据流向、字段口径与交互规则。 > 更新日期:2026-10-15(系统配图已按当前版本重新生成) ## 协作预览 - 本机:[http://127.0.0.1:5173/](http://127.0.0.1:5173/) - 局域网:[http://192.168.1.2:5173/](http://192.168.1.2:5173/) - 局域网访问要求:协作人员与部署电脑处于同一网络,并允许 Windows 防火墙访问 `5173` 端口。 - 本项目使用本地 Vite 开发服务;服务或电脑关闭后,以上预览地址会失效。 ## 1. 模块范围与页面结构 本仓库仅交付“数据统计”独立模块,包含以下五个页面状态。 > `README.md` 是本模块唯一的需求说明文档,页面内不再提供“需求说明”入口。 ```text 数据统计首页 ├─ 数据报表 │ ├─ 考试情况统计(分级考试 / 应知应会 / 入学考试)─→ 考试人员明细 │ ├─ 实验室与人员匹配 ─→ 实验室匹配人员明细 │ └─ 学时统计 └─ 常规考试 ├─ 常规考试汇总统计 ─→ 常规考试明细(人员列表) └─ 学时统计(与数据报表使用相同卡片) ``` | 页面 | 用途 | 主要入口 | | --- | --- | --- | | 数据统计首页 | 通过“数据报表 / 常规考试”切换两类统计视图;不同学校项目可配置常规考试页签是否显示 | 系统菜单列表 | | 常规考试汇总统计 | 按学院汇总常规考试结果,并按单场考试查看列表 | 数据统计首页“常规考试”页签 | | 学时统计 | 按用户类别、学院及年级展示人员安全教育学时 | 数据报表、常规考试页签 | | 考试人员明细 | 展示分级、应知应会、入学等考试对应人员结果 | 考试类型行“人员明细” | | 常规考试明细 | 展示某一单场常规考试对应人员结果 | 常规考试汇总统计行“人员明细” | | 实验室匹配人员明细 | 展示人员的实验室匹配状态与实验室信息 | 实验室匹配列表“人员明细” | ## 2. 人员权限与数据边界 | 角色 | 首页数据范围 | 考试明细范围 | 实验室匹配明细范围 | 页面表现 | | --- | --- | --- | --- | --- | | 校级管理员(最高权限) | 可查看全校范围及所有学院创建的全部考试数据 | 可查看全校范围及所有学院创建的全部考试明细 | 可查看全校范围匹配数据 | 展示学院筛选、全校汇总行、导出入口 | | 院级管理员 | 查看自己创建的考试,以及校级创建且考试范围包含所属学院的考试数据 | 仅查看上述考试在所属学院范围内的人员明细 | 仅所属学院人员 | 不展示跨学院数据与全校汇总 | 权限实现要求: 1. 角色、所属学院、考试创建层级与考试覆盖范围应由登录态及后端权限接口提供;前端不可只依赖隐藏控件实现数据隔离。 2. 院级管理员的考试数据集必须限定为“本人/本院创建”或“校级创建且考试范围包含所属学院”;查询、统计、导出必须使用同一权限条件,导出不可绕过列表权限。 3. 校级管理员与院级管理员切换仅用于原型展示。正式系统应使用实际登录角色,不提供自行切换权限的能力。 ## 3. 数据流向 ```text 人员主数据 + 学籍/人员类别 + 考试报名/应考范围 + 考试作答与成绩 + 补考记录 + 实验室分级与匹配记录 │ ▼ 权限范围过滤 │ ┌───────────┴───────────┐ ▼ ▼ 考试情况聚合 实验室匹配聚合 学院 + 考试类型 学院 + 实验室风险等级 │ │ ▼ ▼ 类型/单场考试人员明细 学院/全校人员匹配明细 ``` 建议接口处理顺序:先按角色和所属学院限定数据集,再按学年、人员类别、学院、考试类型等条件筛选,最后计算统计指标或返回明细。聚合数值、列表数据和导出数据必须来自同一筛选后的数据集。 ## 4. 数据报表:考试情况统计 ![考试情况统计模块](./docs/exam-statistics-module.png) ### 4.1 首页筛选与图表 | 项目 | 规则 | | --- | --- | | 学年 | 统计与明细页均提供学年筛选;当前原型默认 `2026-2027 学年` | | 人员类别 | 研究生、本科生、博士、教职工;应与查询、统计、导出使用相同条件 | | 学院筛选 | 校级管理员可选择学院;院级管理员固定为所属学院 | | 考试类型 | 仅统计分级考试、应知应会、入学考试三类特殊考试;支持按考试类型缩小首页列表,仅展示存在考试数据的类型 | | 堆叠柱图 | 每个学院作为一个组合,组内依次展示分级考试、应知应会、入学考试三根堆叠柱;每根柱按通过、未通过、未考展示。原型提供 10 个学院示例数据,底部支持横向滚动查看全部学院;悬停展示对应考试类型及三项人数 | | 结果环图 | 展示当前权限与筛选范围内通过、未通过、未考人数及通过率 | | 文案 | 使用“未考”作为未参加考试的统一表述 | ### 4.2 学院 / 考试类型列表字段 | 字段 | 口径 | | --- | --- | | 学院 | 统计归属学院;全校行显示“全校”并在列表底部展示 | | 考试类型 | 分级考试、应知应会、入学考试;仅展示有数据类型,常规考试不在数据报表列表展示 | | 应考人数 | 当前筛选范围内,被纳入该考试的人员数 | | 实考人数 | 已参加考试人数,等于通过人数 + 未通过人数 | | 通过人数 | 考试结果为通过的人数 | | 未通过人数 | 已参加但结果未通过的人数 | | 未考人数 | 应考但未参加考试的人数 | | 通过率 | `通过人数 / 实考人数`;实考人数为 0 时返回 `--` 或按后端约定处理 | | 操作 | 考试类型行为明细入口;学院汇总行与全校汇总行操作列留空 | 分级考试聚合规则:同一学院内的Ⅰ—Ⅳ级及五个分类组合按分级考试类型汇总展示,即合并统计 20 个分级分类组合的数据。 学年归档规则:学年结束时,系统自动归档该学年三类特殊考试(分级考试、应知应会、入学考试)的统计与明细数据;归档数据应保留原始统计口径,并可按学年查询。 ### 4.3 考试明细流转规则 | 首页考试类型行 | 操作文案 | 目标页面 | 传递条件 | | --- | --- | --- | --- | | 分级考试 | 人员明细 | 考试人员明细 | 学院 + 考试类型 = 分级考试 | | 应知应会 | 人员明细 | 考试人员明细 | 学院 + 考试类型 = 应知应会 | | 入学考试 | 人员明细 | 考试人员明细 | 学院 + 考试类型 = 入学考试 | | 学院汇总 / 全校汇总 | 无 | 无 | 汇总行仅用于展示统计结果 | ### 4.4 学时统计卡片 数据报表页依次展示考试情况统计、实验室与人员匹配、学时统计卡片;常规考试页签复用完全相同的学时统计卡片。柱图按学院展示研究生、本科生、博士、教职工的完成学时,柱顶常显数值。人员列表字段为姓名、学号、年级、所属学院、第一年至第四年及总时长;支持用户类型、学院、年级、姓名/学号筛选与导出。 ## 5. 常规考试汇总统计 常规考试页签采用两级数据结构:先展示“单场考试”汇总,再查看该场考试的人员结果。校级管理员视图在分页学院列表底部固定展示按当前年份、考试名称与学院筛选条件聚合的“全校”汇总行;该行不提供人员明细入口。 | 字段 | 说明 | | --- | --- | | 考试名称筛选 | 位于筛选区首位并加宽展示,支持输入或从单场考试名称中选择;选择后仅展示该单场考试对应列表数据 | | 学院 | 单场考试所属或统计归属学院 | | 应考人数 / 实考人数 | 口径与考试情况统计一致 | | 通过人数 / 未通过人数 / 未考人数 | 按该单场考试和当前筛选范围汇总 | | 通过率 | `通过人数 / 实考人数` | | 操作 | “人员明细”,进入当前单场考试的常规考试明细 | 页面筛选:年份(首位,默认当前年份,支持“全部年份”)、考试名称(首位加宽输入选择框,候选项随年份变化)、学院;不提供用户类别筛选。年份与考试名称可组合查询。列表按页展示,默认每页 3 条数据。列表右侧显示“共组织常规考试 * 次”,次数随当前筛选结果统计;进入人员页时自动带入学院、考试类型 `常规考试` 与考试名称。 ## 6. 考试人员明细与常规考试明细 | 项目 | 说明 | | --- | --- | | 页面标题 | 分级/应知应会/入学考试使用“考试类型 + 人员明细”;常规考试使用“常规考试明细” | | 普通考试筛选 | 学年、学院、考试类型(分级考试、应知应会、入学考试)、考试结果、补考结果、人员类别、姓名/学工号;不显示常规考试 | | 分级分类 | 仅当考试类型为“分级考试”时显示;可选Ⅰ—Ⅳ级,每个等级均可选择化学类、生物类、机电类、辐射类、其他类 | | 常规考试明细筛选 | 学院、考试结果、补考结果、人员类别(下拉框)、姓名/学工号;不显示学年、考试类型与考试名称筛选,单场考试由上一页传递 | | 表格字段 | 姓名、学工号、学院、用户类别、考试类型/分级分类、学习情况、考试成绩、考试结果、补考成绩、补考结果;学习情况示例为已学习、学习中、未学习、无要求;不展示考试状态 | | 展示方式 | 所有人员明细以右侧抽屉打开,保留来源报表与筛选上下文;关闭抽屉后返回原位置 | | 分页与导出 | 人员明细列表默认每页 5 条;导出按钮下拉提供导出全部数据、导出筛选数据、导出勾选数据三种范围,并按当前角色权限控制导出边界 | 补考结果取值:通过、未通过、未考;补考成绩无补考或未考时显示 `—`。考试结果建议值:通过、未通过、未考。 ### 已考 / 未考人员标签 - 数据报表考试人员明细与常规考试人员明细均在抽屉顶部提供“已考人员 / 未考人员”标签。 - 已考人员:仅展示已参加考试的人员,保留实际考试与补考结果、成绩。 - 未考人员:仅展示未参加考试的人员;考试结果、补考结果统一显示“未考”,考试成绩、补考成绩统一显示 `-`。 - 两类列表均不展示“考试状态”字段;未考标签下的考试结果、补考结果筛选固定为“未考”。 ## 7. 实验室与人员匹配 ![实验室与人员匹配模块](./docs/lab-matching-module.png) ### 7.1 首页规则 | 项目 | 规则 | | --- | --- | | 头部筛选 | 在导出各学院数据左侧提供年级(全部年级、2025级、2026级)、研究生/本科生/博士筛选 | | 柱图分类 | 研究生、本科生、博士均展示Ⅰ级(重大风险)、Ⅱ级(高风险)、Ⅲ级(中风险)、Ⅳ级(低风险)、未匹配 | | 无需进入实验室 | 已完成选择操作,但未进入实验室的人员 | | 未操作 | 尚未操作实验室绑定的人员 | | 本科生特殊规则 | 切换为本科生后,柱状图与列表均隐藏“未操作”统计,并将“无需进入实验室”改为“未绑定”;总人数口径不变 | | 列表操作 | 学院行显示“人员明细”;全校行显示“全部明细” | ### 7.2 学院匹配列表字段 | 字段 | 口径 | | --- | --- | | 学院 | 人员所属学院;校级管理员可查看全校行 | | Ⅰ—Ⅳ级人数 | 按人员已匹配实验室的风险分级统计 | | 状态人数 | 研究生显示“无需进入实验室人数”;本科生显示“未绑定人数”,均为已完成选择操作但未进入实验室的人员数 | | 未操作人数 | 未进行实验室绑定选择的人数;仅研究生视图展示该字段 | | 总人数 | 当前学院所有人员数,包含已绑定、无需进入实验室(本科生文案为未绑定)与未操作人员 | | 操作 | 进入当前学院或全校范围的匹配人员明细 | ## 8. 实验室匹配人员明细 | 项目 | 说明 | | --- | --- | | 进入范围 | 学院行进入当前学院;全校行进入全部学院;均需继续受当前用户权限限制 | | 同步筛选 | 年级(全部年级、2025级、2026级)、研究生/本科生,与实验室匹配首页保持一致 | | 明细筛选 | 学院、分级分类、匹配状态、姓名/学工号 | | 表格字段 | 姓名、学工号、学院、状态、分级、分类、实验室 | | 状态 | 研究生、本科生、博士均仅展示已绑定、未匹配;筛选项与列表记录保持一致 | | 实验室展示 | 使用 `房间号-实验室名称` 格式;无匹配实验室时显示 `—` | | 导出 | 导出按钮下拉提供导出全部数据、导出筛选数据、导出勾选数据;均受当前权限范围限制 | ## 9. 开发与测试检查清单 - 校级、院级权限均在接口层验证,前端筛选项与返回数据范围一致。 - 考试情况统计仅包含分级考试、应知应会、入学考试;学年结束时自动归档该学年数据。 - 考试统计的应考人数 = 实考人数 + 未考人数;实考人数 = 通过人数 + 未通过人数。 - 数据统计顶部通过“数据报表 / 常规考试”页签切换;不同学校项目可通过配置开关决定是否显示“常规考试”页签。 - 常规考试页签按年份(默认当前年份,可选全部年份)与考试名称组合展示单场考试汇总,并可继续进入单场考试“人员明细”。 - 学院汇总与全校汇总行不提供考试人员明细入口。 - 分级分类筛选只在分级考试出现;常规考试名称筛选只在常规考试出现。 - 实验室匹配在研究生、本科生、博士视图中均统一使用“未匹配”字段,不再拆分未操作、未绑定或无需进入实验室统计。 - 所有列表均需分页;全校汇总行固定在学院列表分页区之后。 - 所有导出结果与可见列表使用相同的权限、筛选条件和字段口径。 ## 10. 当前版本交互补充 ### 10.1 数据报表列表与图表 - 考试情况统计、实验室匹配、学时统计的学院/人员列表均提供分页;考试与实验室学院列表的“全校”汇总行不参与分页,固定显示在分页列表下方。 - 考试情况统计柱图按学院分组:每组包含分级考试、应知应会、入学考试三根堆叠柱,横轴仅显示学院名称;悬停单根柱仅显示该考试类型的通过人数、未通过人数、未考人数。原型提供 10 个学院,用横向滚动轴查看。 - 数据报表页不统计常规考试,且从该页进入的人员明细考试类型筛选不显示“常规考试”。 ### 10.2 常规考试统计 - 常规考试统计顶部展示学院维度的通过、未通过、未考堆叠柱和结果环图;该图表按学院汇总,不区分单场考试。校级管理员原型展示 10 个学院,院级管理员仅展示所属学院。 - 年份筛选默认当前年份,支持“全部年份”;考试名称输入选择框置于首位并加宽,候选考试随年份变化,二者可组合查询。 - 常规考试汇总列表不展示“考试名称”列;通过筛选框选定单场考试后,列表显示对应学院的结果汇总。点击“人员明细”以右侧抽屉打开单场考试人员列表。 ### 10.3 人员明细抽屉 - 考试人员明细与实验室匹配人员明细均为右侧抽屉,不离开来源报表页面。 - 考试人员明细顶部提供“已考人员 / 未考人员”标签:已考人员展示参加考试记录;未考人员统一展示未考结果与 `-` 成绩。 - 考试人员明细筛选顺序统一为:学院/考试类型(适用时)→ 考试结果 → 补考结果 → 用户类别 → 姓名/学工号 → 查询、重置;表格包含用户类别、补考成绩、补考结果,不展示考试状态。 - 实验室匹配人员明细在研究生、本科生、博士视图中均只提供已绑定、未匹配两种状态。 ## 11. 系统页面配图 以下配图均为当前版本本地预览截图,随模块页面迭代同步更新;人员明细采用右侧抽屉交互,字段与筛选说明见第 6、8 节。 ### 数据统计总览 ![数据统计总览页面](./docs/data-statistics-dashboard.png)