成绩与过程性评价对接手册

本文说明希悦 OpenAPI 成绩与过程性评价相关接口的读取方式、主要字段及同步顺序。

本手册覆盖以下 5 类接口：

• System
• Reflection
• AdminClass
• Klass
• Assessment

本文仅覆盖读取场景，不包含回写接口。

1. 接口范围

各接口分类的职责如下：

常见的数据实体如下：

• 词汇表 term
• 学期 semester
• 学生/教师 reflection
• 行政班 admin_class
• 课程班 klass
• 课程班成员 class_selection
• 评价主体 assessment
• 评价项 assessment_item
• 评价项分数 assessment_score
• 总成绩 class_grade

2. 对接前准备

2.1 鉴权

平台使用 OAuth 2.0 client_credentials 模式获取 access_token。详细说明见 docs/oauth.md。

Token 接口：

POST /api/v3/oauth/tokens

OpenAPI： 申请 OAuth AccessToken

业务接口请求头：

Authorization: Bearer {access_token}
X-School-Id: {school_id}

要求：

• X-School-Id 是业务接口的公共请求头。

2.2 权限范围

读取基础数据、过程性评价和总成绩时，通常需要以下 Scope：

• semester.read
• term.read
• student.read_all 或 student.read_basic
• teacher.read_all 或 teacher.read_basic
• reflection.read_all 或 reflection.read_basic
• admin_class.read
• class.read

class.read 用于查询过程性评价、课程班和成绩数据。

2.3 分页与 expand 约定

分页

对于集合类型的接口，通过以下 URI 参数控制分页：

启用分页后，响应 Header 中会返回：

详见 接口调用约定。

expand

部分接口支持 expand 查询参数，用于在响应中内嵌关联对象，减少额外请求。多个字段用逗号分隔，例如 expand=items,klass。各接口可用的 expand 值在下文对应章节中说明。

3. 数据关系图

semester
  │
  └── klass ──── class_selection ── reflection
        │            (选课关系)      (学生/教师)
        │                               │
        │                          admin_class
        │
        └── assessment ── item ── score
               │
               └──────── grade

 term (词汇字典：学科、届别、学年等，被多个实体引用)

关键关联：

• 一个 semester（学期）下有多个 klass（课程班）
• 一个 klass 对应一个 assessment（评价主体）
• 一个 assessment 包含多个 item（评价项），每个 item 下有多条 score（过程分）
• 一个 assessment 产出多条 grade（总成绩），每条 grade 对应一个学生
• class_selection 记录 klass 与 reflection（学生/教师）的成员关系

4. 总体对接顺序

推荐顺序如下：

1. 通过 OAuth 获取 Token
2. 同步学期、词汇字典
3. 同步学生、教师
4. 同步行政班
5. 同步课程班与课程班成员
6. 为目标课程班查询评价主体
7. 获取评价项
8. 获取过程性评价分数
9. 获取总成绩

5. 第一步：同步基础主数据

5.1 学期列表

接口：

GET /api/v3/system/semesters

OpenAPI： 获取学期列表

请求参数：

• id_in
• paginated、page、per_page — 分页参数，详见 2.3 分页与 expand 约定
• expand — 可选值：academic_year（学年）、category（学期类型）

返回字段：

5.2 基础词汇字典

接口：

GET /api/v3/term/{type}/terms

OpenAPI： 获取基础词汇字典

常用 type：

• system.graduates_in
• system.academic_year
• system.semester_category
• course.subject
• course.domain

请求参数：

• name — 按名称筛选
• parent_id — 按父级 ID 筛选
• archived_at_is_empty — 仅返回未归档数据
• sort — 排序方式

该接口用于获取学期、年级届别、学科、教师学科归属等字典数据。

返回字段：

6. 第二步：同步人员与组织关系

6.1 用户主表（包含学生、教师）

接口：

GET /api/v3/reflection/reflections

OpenAPI： 获取用户数据

常用参数：

• role
• expand
• updated_at_egt
• with_trashed
• paginated、page、per_page — 分页参数

该接口用于获取用户主表数据，也可作为增量同步入口。返回结果仅包含基础字段，不包含完整身份扩展信息。

返回字段：

说明：

• role 可见枚举包括：teacher、student、staff、guardian
• 成绩相关场景通常至少需要学生和教师数据

6.2 学生数据

接口：

GET /api/v3/reflection/students

OpenAPI： 获取学生数据

常用参数：

• id_in
• name_in
• name_like
• keyword_identity
• expand
• updated_at_egt
• with_trashed
• paginated、page、per_page — 分页参数

该接口用于获取学生主数据及学生身份相关字段。

返回字段：

6.3 教师数据

接口：

GET /api/v3/reflection/teachers

OpenAPI： 获取教师数据

常用参数：

• id_in
• name_in
• name_like
• expand
• updated_at_egt
• with_trashed
• paginated、page、per_page — 分页参数

该接口用于获取教师主数据及教师身份相关字段。

返回字段：

6.4 行政班

接口：

GET /api/v3/admin_class/admin_classes

OpenAPI： 获取行政班接口

常用参数：

• id
• id_in
• name_like
• outer_id
• outer_id_in
• teacher_id
• place_id
• status
• expand — 可选值：teachers（班主任）、students（学生列表）、classes（关联课程班）
• paginated、page、per_page — 分页参数

返回字段：

该接口用于获取学生所属行政班关系，以及班级、班主任等数据。

7. 第三步：同步课程班与成员关系

7.1 课程班列表

接口：

GET /api/v3/klass/classes

OpenAPI： 获取课程班列表

常用参数：

• semester_id
• id_in
• updated_at_egt
• admin_class_id
• with_trashed
• expand — 可选值：teachers（任课教师）、students（学生）、admin_class_ids（关联行政班 ID）、class_lessons（课节）、tag（课程班标签）
• paginated、page、per_page — 分页参数

课程班查询应以学期为主维度，并带上 semester_id。

返回字段：

7.2 课程班成员

接口：

GET /api/v3/klass/class-selections

OpenAPI： 获取课程班成员

必填参数：

• semester_id

常用参数：

• class_id_in
• updated_at_egt
• with_trashed
• paginated、page、per_page — 分页参数

该接口用于获取课程班与学生之间的选课或成员关系。

返回字段：

8. 第四步：获取过程性评价数据

过程性评价相关接口顺序如下：

1. 先定位课程班
2. 再查询课程班对应的评价主体
3. 再获取评价项列表
4. 最后获取每个评价项下的学生分数

8.1 查询课程班评价主体与评价项

接口：

GET /api/v3/class-assessment/classes/{id}/assessment

OpenAPI： 根据课程班 ID 获取评价主体

常用参数：

• expand — 可选值：items（评价项列表）

该接口根据课程班 ID 返回评价主体 assessment。评价项和分数数据均依附于该对象。传 expand=items 时，返回的 assessment 对象中会包含一个 items 字段，表示该评价主体下的评价项列表。

返回字段（assessment）：

返回字段（items 中的每个评价项）：

相关枚举：

• ItemTypeEnum: dimension、sub_dimension、item、special_item、attendance_item
• ScoringTypeEnum: score、star、level、addition、tag、review
• DisplayTypeEnum: score、star、level
• ComputeTypeEnum: sum、avg、weighted_avg

8.2 查询评价项分数

接口：

GET /api/v3/class-assessment/items/{id}/scores

OpenAPI： 查询评价项分数

常用参数：

• owner_id_in
• type
• valid
• tag
• tag_in
• score_egt
• score_elt
• expand
• paginated、page、per_page — 分页参数

该接口用于获取指定评价项下的学生过程分明细。

返回字段：

说明：

• 一个课程班通常对应多个评价项，查询时需要按 item_id 分批处理
• type 可见枚举：raw、item_score

9. 第五步：同步总成绩

9.1 查询总成绩

接口：

GET /api/v3/class-assessment/class/grades?class_ids={class_ids}

OpenAPI： 查询课程班学生总成绩

常用参数：

• class_ids，必填，多个课程班用逗号分隔
• updated_at_egt，支持增量查询
• paginated
• page
• per_page

该接口用于获取课程班学生总成绩，并支持按更新时间增量查询。

返回字段：

相关枚举：

• GradeSourceEnum：class、moral、dorm、custom、teacher_assessment、awarded_credit、stage 但一般只关注 class 即可。
• GradeStatusEnum：pending（未发布）、published（已发布）、delayed（暂不评价）、passed（已通过）
• GradePassStatusEnum：pending、warning、passed、failed

说明：

• source_id 对应 Assessment ID，而非课程班 ID；如需关联课程班，应通过 Assessment 的 scope_id 字段获取