Kaynağa Gözat

feat: refine data statistics reporting

anne 1 ay önce
ebeveyn
işleme
3b4551f6a3

+ 177 - 49
README.md

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

Dosya farkı çok büyük olduğundan ihmal edildi
+ 1 - 1
docs/data-statistics-dashboard.svg


+ 4 - 4
docs/data-statistics-requirements-page.svg

@@ -35,8 +35,8 @@
       <rect x="28" y="25" width="28" height="28" rx="8" fill="#e8f2ff"/><text x="35" y="44" fill="#1768d5" font-size="11" font-weight="700">02</text>
       <rect x="28" y="25" width="28" height="28" rx="8" fill="#e8f2ff"/><text x="35" y="44" fill="#1768d5" font-size="11" font-weight="700">02</text>
       <text x="67" y="46" fill="#243751" font-size="17" font-weight="700">考试情况统计</text>
       <text x="67" y="46" fill="#243751" font-size="17" font-weight="700">考试情况统计</text>
       <text x="29" y="86" fill="#52647b" font-size="13">• 学年、人员类别、学院、考试类型筛选</text>
       <text x="29" y="86" fill="#52647b" font-size="13">• 学年、人员类别、学院、考试类型筛选</text>
-      <text x="29" y="116" fill="#52647b" font-size="13">• 图表悬浮显示应考、实考、缺考、通过、未通过</text>
-      <text x="29" y="146" fill="#52647b" font-size="13">• 增加实考人数;未考调整为缺考</text>
+      <text x="29" y="116" fill="#52647b" font-size="13">• 图表悬浮显示应考、实考、未考、通过、未通过</text>
+      <text x="29" y="146" fill="#52647b" font-size="13">• 增加实考人数;未考调整为未考</text>
       <text x="29" y="176" fill="#52647b" font-size="13">• 全校统计固定显示在列表底部</text>
       <text x="29" y="176" fill="#52647b" font-size="13">• 全校统计固定显示在列表底部</text>
       <text x="29" y="206" fill="#52647b" font-size="13">• 操作:人员明细 / 学院明细 / 全部明细</text>
       <text x="29" y="206" fill="#52647b" font-size="13">• 操作:人员明细 / 学院明细 / 全部明细</text>
     </g>
     </g>
@@ -44,8 +44,8 @@
       <rect width="414" height="260" rx="16" fill="white" stroke="#e4ebf5"/>
       <rect width="414" height="260" rx="16" fill="white" stroke="#e4ebf5"/>
       <rect x="28" y="25" width="28" height="28" rx="8" fill="#e8f2ff"/><text x="35" y="44" fill="#1768d5" font-size="11" font-weight="700">03</text>
       <rect x="28" y="25" width="28" height="28" rx="8" fill="#e8f2ff"/><text x="35" y="44" fill="#1768d5" font-size="11" font-weight="700">03</text>
       <text x="67" y="46" fill="#243751" font-size="17" font-weight="700">实验室与人员匹配</text>
       <text x="67" y="46" fill="#243751" font-size="17" font-weight="700">实验室与人员匹配</text>
-      <text x="29" y="86" fill="#52647b" font-size="13">• 图表增加未绑定、未选择人员</text>
-      <text x="29" y="116" fill="#52647b" font-size="13">• 列表增加未绑定、未选择人数</text>
+      <text x="29" y="86" fill="#52647b" font-size="13">• 图表增加无需进入实验室、未操作人员</text>
+      <text x="29" y="116" fill="#52647b" font-size="13">• 列表增加无需进入实验室、未操作人数</text>
       <text x="29" y="146" fill="#52647b" font-size="13">• 总人数包含全部匹配与未匹配人员</text>
       <text x="29" y="146" fill="#52647b" font-size="13">• 总人数包含全部匹配与未匹配人员</text>
       <text x="29" y="176" fill="#52647b" font-size="13">• 学院行进入人员明细;全校行进入全部明细</text>
       <text x="29" y="176" fill="#52647b" font-size="13">• 学院行进入人员明细;全校行进入全部明细</text>
     </g>
     </g>

Dosya farkı çok büyük olduğundan ihmal edildi
+ 1 - 1
docs/exam-people-detail.svg


BIN
docs/exam-statistics-module.png


Dosya farkı çok büyük olduğundan ihmal edildi
+ 1 - 1
docs/exam-statistics-module.svg


BIN
docs/lab-matching-module.png


Dosya farkı çok büyük olduğundan ihmal edildi
+ 8 - 1
docs/lab-matching-module.svg


Dosya farkı çok büyük olduğundan ihmal edildi
+ 1 - 1
docs/lab-people-detail.svg


Dosya farkı çok büyük olduğundan ihmal edildi
+ 70 - 13
src/App.jsx


Dosya farkı çok büyük olduğundan ihmal edildi
+ 13 - 3
src/styles.css