基础数据对接指南

本文说明如何通过希悦开放平台 API 从平台获取基础数据，用于对接外部系统。本文覆盖以下数据能力：

• 学年学期
• 用户数据（学生、教师）
• 组织架构（年级、学科组等）
• 班级数据（行政班、教学班）
• 教师任课（每个教师任教哪些班级）
• 班级与学生对应关系

本文仅覆盖数据读取场景，不包含写入、删除等变更操作。

1. 接口范围

2. 对接前准备

2.1 鉴权

平台使用 OAuth 2.0 Client Credentials 模式获取 access_token。详见 docs/oauth.md。

Token 接口：

POST /api/v3/oauth/tokens

业务接口请求头：

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

要求：

• Authorization 用于传递访问令牌。
• X-School-Id 按平台通用约定传递学校上下文。

2.2 权限范围（Scope）

各接口通过 OAuth Scope 鉴权，所需 Scope 如下：

说明：

• read_basic 仅返回基础字段，read_all 返回全部字段。按需选择最低授权范围。
• 请在申请时按需开通，遵循最小授权原则。

2.3 分页与筛选约定

分页

集合类接口均支持 paginated、page、per_page 参数，分页响应头约定详见 docs/conventions.md。

关联展开（expand）

部分接口支持 expand 参数，用逗号分隔需要展开的关联资源，例如 expand=students,teachers。

增量同步

用户、班级、教学班、成员等接口支持 updated_at_egt（仅查询指定时间之后更新或新建的数据）与 with_trashed（是否包含软删除数据）参数，可用于实现增量同步，详见第 12 节。

3. 数据关系总览

semester（学年学期）
  ├── academic_year（学年）
  ├── category（学期类型）
  └── is_current（是否当前学期）

admin_class（行政班）
  ├── teachers（班主任）
  ├── students（班级学生）
  └── classes（关联的教学班）

class（教学班/课程班）
  ├── semester_id（所属学期）
  ├── teachers（任课教师）
  ├── students（班级学生）
  └── admin_class_ids（关联的行政班）

reflection（用户身份）
  ├── student（学生）
  ├── teacher（教师）
  └── guardian（家长）

关键关系：

• 一个 semester 属于一个 academic_year，属于一个学期类型 category
• 一个 admin_class 下有多个学生 students 和多个班主任 teachers
• 一个 class 属于一个 semester，有多个任课教师 teachers 和多个学生 students
• 一个 class 可关联多个 admin_class，一个 admin_class 可关联多个 class

4. 总体调用顺序

推荐调用顺序如下：

1. 通过 OAuth 获取 Token
2. 确认应用已开通所需 Scope
3. 调用学期接口，确定目标学期 semester_id（优先使用 is_current=true 的当期学期）
4. 调用用户数据接口，全量或增量同步学生、教师
5. 调用行政班接口，同步行政班及其学生、班主任
6. 调用教学班接口，同步教学班及其任课教师、成员
7. 调用架构接口，获取架构详情（年级、学科组等）
8. 按需使用 updated_at_egt 做增量更新

5. 获取学年学期

接口：

GET /v3/system/semesters

OpenAPI：获取学期列表

说明：

• 用于获取学年学期列表，是所有班级、教学班数据的挂载点。
• 使用 expand=academic_year 展开学年，expand=category 展开学期类型，expand=is_current 标记是否当前学期。

请求参数：

返回字段（Semester）：

同步建议：

• 优先使用 is_current=true 的学期作为默认同步目标。
• 若需同步历史学期数据，按 id_in 或循环逐学期拉取即可。

6. 获取用户数据

用户数据分为三类接口，均返回 Reflection 对象：

• 通用用户：GET /v3/reflection/reflections（OpenAPI：获取用户数据）
• 学生：GET /v3/reflection/students（OpenAPI：获取学生数据）
• 教师：GET /v3/reflection/teachers（OpenAPI：获取教师数据）

说明：

• reflections 接口通过 role 参数可筛选 teacher、student、guardian。
• students、teachers 接口为按角色定向获取，参数更细化。
• 三者返回的 Reflection.id 即用户在班级成员、任课关系中的 reflection_id，是跨接口关联的关键。

请求参数：

返回字段（Reflection）：

7. 获取组织架构

接口：

GET /v3/structure/structures

OpenAPI：获取组织架构列表

说明：

• 架构是学校基于年级、学科组等维度建立的层级结构，行政班、教学班、用户均通过 structure_ids 关联到架构。
• 通过 expand=parent 展开父级架构，expand=children 展开子级架构，expand=managers 展开管理员列表。
• 通过 type 可按架构类型筛选，通过 parent_id 可获取指定父级下的子级架构。

请求参数：

返回字段（Structure，数组）：

补充说明：

• 如需获取整个架构树，可先拉取列表，再通过 expand=children 或按 parent_id 逐层展开。
• 如需获取单个架构的详情，可调用 GET /v3/structure/structures/{id}（OpenAPI：获取架构详情）。
• 架构类型 type 主要用于区分校区、学段、年级、学科组等层级。

8. 获取班级数据

8.1 行政班

接口：

GET /v3/admin_class/admin_classes

OpenAPI：获取行政班接口

说明：

• 行政班是学校按年级、班级划分的固定班制单位。
• 通过 expand=students 获取班级学生，expand=teachers 获取班主任，expand=classes 获取关联的教学班。
• status 为 archived 时表示历史行政班（已归档），同步时应过滤，仅保留 status=normal 的行政班。

请求参数：

返回字段（AdminClass）：

8.2 教学班（课程班）

教学班数据包含教学班列表与教学班成员两部分。

教学班列表

接口：

GET /v3/klass/classes

OpenAPI：获取课程班列表

说明：

• 教学班（课程班）隶属于某个学期，是选课走班后的授课单位。
• 推荐按 semester_id 拉取指定学期的教学班。
• 通过 expand=teachers 获取任课教师，expand=students 获取班级学生，expand=admin_class_ids 获取关联的行政班。

请求参数：

返回字段（Class）：

教学班成员

接口：

GET /v3/klass/class-selections

OpenAPI：获取课程班成员

说明：

• 教学班成员接口通过 class_id_in 指定一个或多个教学班，返回这些教学班的成员，type 区分成员类型，type=teacher 为任课教师，type=student 为班级学生。
• 必须指定 semester_id。
• 每个成员包含 class_id 标识所属教学班，class_id 与 reflection_id 组合即构成“用户属于哪些教学班”的映射。

请求参数：

返回字段（ClassSelection）：

9. 获取教师任课

教师任课关系指每个教师任教哪些班级。有两种方式：

方式一：教学班列表展开任课教师（推荐）

调用 GET /v3/klass/classes 并传 expand=teachers，返回的每个 Class 自带 id 与 teachers 数组（成员含 class_id、reflection_id），type=teacher 的成员即为该教学班的任课教师。可直接按 Class.id 得到每个班级的任课教师，适合需要一并获取班级属性的场景。

方式二：教学班成员接口

通过教学班成员接口按 type=teacher 获取，接口定义详见 §8.2 教学班成员。返回的成员含 class_id，按 class_id 分组即可得到每个教师任教的班级列表。

同步建议：

• 若需构建“教师 → 任教班级列表”映射，推荐使用 §8.2 教学班列表的 expand=teachers，按 Class.id 与 teachers[].reflection_id 组合即可。
• 也可通过教学班成员接口按 type=teacher 获取，按返回的 class_id 分组。

10. 获取班级与学生对应关系

10.1 行政班-学生

调用 GET /v3/admin_class/admin_classes 并传 expand=students，返回 students 数组（AdminClassMember），每个元素即行政班与学生的对应关系。

AdminClassMember 字段：

10.2 教学班-学生

推荐调用 GET /v3/klass/classes 传 expand=students，返回的每个 Class 自带 id，students 数组（成员含 class_id、reflection_id）即教学班与学生的对应关系。也可通过教学班成员接口按 type=student 获取（接口定义详见 §8.2 教学班成员），返回的成员含 class_id，class_id 与 reflection_id 组合即教学班与学生的对应关系。

10.3 行政班-教学班关联

• 行政班侧：GET /v3/admin_class/admin_classes 传 expand=classes，返回 ClassRelation（class_id、admin_class_id）。
• 教学班侧：GET /v3/klass/classes 传 expand=admin_class_ids，返回 admin_class_ids 数组。

11. 增量同步机制

以下接口支持增量拉取，用于降低全量同步成本：

增量同步建议：

1. 首次全量拉取，记录时间戳 last_sync_at。
2. 后续传入 updated_at_egt={last_sync_at} 拉取增量。
3. 配合 with_trashed=1 获取软删除数据，用于同步删除标记。
4. 每次同步成功后更新 last_sync_at 为本次拉取到的最大 updated_at。