ClassHelper/docs/app/grades.md

---
title: 成绩
description: 录入、按学号查询、排名与关闭个人查询后的集体分析。
---

# 成绩

Web 管理端支持单条、批量和表格导入成绩；记录通过 Grade.studentId 关联学生名单。
科目来自班级课程与共享科目目录，分数、总分和等级按录入规则校验。
成绩写入需 grade:write 或相应导入权限，并通过班级和科目检查：
管理员可管理，教师只能编辑自己任课科目，无科目内容按班主任规则；班级端不能写成绩。
表格导入另有管理员/本班班主任门槛，班主任也只能导入符合科目权限的行；它与单条/批量录入的准入不同。

## 查看、排名与隐私

班级客户端可显示本班考试、成绩总览、等级分布，以及按学号查询明细。
是否允许读取个人数据由 Class.studentGradeQueryEnabled 控制，班级端只读该设置。

| 状态         | 班级端可读取内容                                                     |
| ------------ | -------------------------------------------------------------------- |
| 个人查询开启 | 本班原始成绩、个人明细、考试及排名，仍检查班级归属                   |
| 个人查询关闭 | 页面可打开，只返回服务端集体聚合；个人明细、原始全班成绩和排名被拒绝 |

聚合对少于 5 名学生的样本、稀疏分段及补集抑制，不提供最高/最低分。
客户端不会先拿个人成绩再做隐藏或聚合；教师/管理员按自身权限读取，不受班级端个人查询开关限制。

考试“是否计入总分”属于 Exam，教师在管理端设置，客户端只展示。
同一学生同一科多条成绩取最高分，排名并列用 1、2、2、4；总分只在开启时显示。
图表使用本地 HTML/CSS/SVG 组件。

## 接口入口

以下省略 /api 前缀，详情与参数以 grades.module.ts、grades.schemas.ts 为准。

| 方法与路径                                            | 用途                                               |
| ----------------------------------------------------- | -------------------------------------------------- |
| GET /grades/overview                                  | 班级端按开关返回原始总览或集体聚合                 |
| GET /grades/my                                        | 班级端原始成绩，关闭个人查询时拒绝；员工返回空数组 |
| GET /grades/collective?classId=                       | 服务端集体分析                                     |
| GET /grades/student/:studentNo                        | 按学号查询，班级端受班级开关控制                   |
| GET /grades?classId=&courseId=&studentId=&examName=   | 员工列表，功能键与范围检查                         |
| GET /grades/stats                                     | 员工统计                                           |
| GET/PUT /grades/exams                                 | 考试列表 / 设置总分口径                            |
| GET /grades/ranking                                   | 考试排名，班级端受个人查询开关控制                 |
| POST /grades、/grades/bulk                            | 单条或批量录入                                     |
| PATCH /grades/levels、/grades/:id；DELETE /grades/:id | 等级与成绩维护                                     |

变更发送 grade:updated，事件载荷同样须遵守个人数据保护，客户端按需重新读取。