一、场景概述
通过对第三方对接内容进行收集，提供的一份场景参考说明文档，能够方便开发人员快速了解平台以及对接中的注意事项。
平台提供统一用户认证，API接入等主要包含以下公共接口：
统一用户认证
API接入
基础数据接口
课表数据接口
考勤数据接口
考务数据接口
选科数据接口
成绩数据接口
区域数据接口
二、统一用户认证
1、简述
单点登录指用户在认证中心登录后，即同时登录到所有与此认证中心关联的所有服务中。
举例：您只需登录 Google 即可以已登录用户的身份访问 Youtube 和 Gmail。
2、流程简述
平台提供灵活的单点接入方案，并在单点登录的过程中扮演服务端身份，流程大致如下：
服务端流程介绍：
- 用户登录后，请求进行应用跳转。
- 平台系统生成ticket与相关用户账号信息。
- 平台系统发起跳转请求并发送ticket至第三方应用。
- 第三方应用收到这个跳转请求与ticket，然后发请求并携带ticket到平台进行认证。
- 平台根据参数ticket进行验证，若通过验证，则返回用户帐号信息给第三方应用，否则，则返回相应的错误代号。
- 第三方应用校验用户账号信息，并返回相应用户登录后跳转的页面。
3、场景说明
统一认证使用场景，提供以下对接方案：
方案一
使用场景：单点登录+手动维护账号
场景描述：用户登录平台，并使用第三方应用时，能够直接访问第三方应用不需要再次登陆的过程。
对接优点：对接迅速，开发时间短，快速达到使用和演示的目的。
对接缺点：不方便统一管理账号，需要双方售后人员维护账号。
同步方式：无
对接内容：1.平台提供验证用户信息凭证接口。
2.第三方应用获取跳转用户的详细信息，绑定账号，创建账号，上传账号（自定义）。
接口使用：用户登录认证接口-服务端
方案二
使用场景：单点登录+同步账号
场景描述：用户登录平台，并使用第三方应用时，能够直接访问第三方应用不需要再次登陆的过程。
对接优点：账号统一维护方便， 减少了系统维护人员的工作。
对优缺点：同步平台账号信息，开发时间较长。
同步方式：同步平台账号
对接内容：1.同步平台基础数据信息，用户账号信息。
2.平台提供验证用户信息凭证接口。
3.第三方应用获取跳转用户的详细信息，绑定账号，创建账号，上传账号（自定义）。
接口使用：学校基础信息（班级结构，学生账号，教师账号），用户登录认证接口-服务端。
三、基础数据
1、简述
学校基础信息包括学校信息，学生信息，教师信息，行政班信息，教学班信息，选修班信息，学生详细信息，学生与班级对应关系，场地信息，科目信息等接口，关系如下图所示。
2、使用要求
基础数据同步时需根据id字段为唯一键更新其他字段。
第三方应用调用基础数据接口时，需设置请求超时大于1分钟。
3、场景说明
学校基础数据指学校内产生最基本的数据信息，第三方应用根据自身对接需求进行功能上的扩展和优化，适用于单点登录对接，课表对接，考勤对接，考务对接等业务模块。类似于微信家校通讯录中有校区，学段，年级班级，学生信息，教师信息，家长信息等，可以接入不同第三方应用和第三方授权身份验证等。
对接方案一
使用场景：同步基础数据+单点登录+第三方应用
场景描述：对接单点登录过程为方便账号统一维护，第三方应用需同步平台账号数据（学校基础数据），方便平台账号变更，减少第三方对账号维护和处理。
使用优点：账号维护方便，提高使用率，简化管理。
同步方式：手动或自动同步学校基础数据。
对接内容：1.同步学校基础数据接口，2.单点登录，3.第三方应用接入
接口使用：学校基础数据信息接口(行政班，学生信息，教师信息)等
对接方案二
使用场景：同步基础数据+同步课表数据+电子班牌展示
场景描述：在同步课表的过程中为班牌展示内容全面，需要同步学校基础数据作为课表基础接口，进行相关功能上使用，如用户信息，学生课表，教师课表，考勤打卡等内容。
使用优点：方便课表接口使用，拓展课表内容，丰富班牌信息。
同步方式：手动或自动同步学校基础数据。
对接内容：1.同步学校基础数据接口，2.同步课表数据，3.班牌内容展示
接口使用：学校基础数据信息接口(行政班，学生信息，教师信息)等，课表接口
四、课表与班牌
1、简述
班牌系统定期或手动拉取排课系统中基本数据（学生列表，老师列表，行政班列表，位置列表，科目列表）及课表数据到班牌后台服务器存储下来，班牌服务器再通过自身机制下发到班牌上展现所需数据。
2、课表数据
课表接口数据是由排课系统进行排课产生的课表数据，流程大致如下：
- 排课前：收集班级，学生，教师，场地，科目等基础数据数据。
- 排课中：排课系统使用并填写作息，教室，老师，上课节次，上课约束等条件进行系统计算结果。
- 排课后：系统计算后产生总课表，班级课表，学生课表，教师课表，教室课表等。
最后将排课任务进行发布，任务发布一学期（上半学期或下班学期）周期课表，例如9月发布到次年1月。
3、使用要求
排课系统位于云端，班牌系统服务器需要具有公网访问条件。
班牌系统中学生账号与排课系统中学生登录账号（学号）对应。
基础数据同步时需根据id字段为唯一键更新其他字段。
为减小传输量，返回结果可以使用gzip压缩；班牌系统可以通过在向排课系统请求的HTTP头部（HTTP HEADER）加入accept-encoding字段实现，如accept-encoding: gzip。
班牌系统调用排课系统接口时，需设置请求超时大于1分钟。
4、场景说明
平台班牌接口为了能够快速对接到第三方班牌系统，根据班牌接口在不同的场景使用情况，为此提供三种对接方案，供开发人员参考。
方案一
使用场景：同步基础数据+课表数据
使用频率：高
场景描述：在项目长期存在和需要对接多个学校情况，班牌系统完善同步班牌数据对以后对接更加方便。
对接优点：对接完整，开发功能多，利于课表维护和使用。
对优缺点：开发周期较长。
同步方式：定时拉取或手动拉取课表数据。
对接内容：1.同步基础数据，例如：学生接口数据，教师接口数据，行政班接口数据，教学班接口数据，场地接口数据等。
2.同步课表数据，例如：课表接口（本周/下周）数据等。
3.通过基础数据对应接口，如年级唯一标识ID（qualifiedClassID），学生ID，教师ID等，通过课表接口组装班级课表，教学班课表，学生课表，老师课表，场地数据等。
接口使用：课表接口getSchedule，行政班接口getClasses，教学班接口getTeachingClasses，学生详细接口getStudentInfos，场地接口getLocations。
方案二
使用场景：手工同步课表数据
使用频率：中
场景描述：在项目售前期，获取课表数据不对接基础数据，能够快速进行演示使用或课表展示作用。
对接优点：方便快速对接到班牌系统。
对优缺点：需要人工维护。
同步方式：无
对接内容：1.基础数据双方各自导入，班牌系统班级名称，学生账号，教师账号相对应。
2.上传平台提供的课表，可达到课表同步的演示效果。
使用接口：无
方案三
使用场景：同步班级课表或学生课表
使用频率：低
场景描述：在项目处于一段时间或者短期时间内，并且在短期内需要进行不同数据展示作用。
对接优点：能够减少开发时间，只需要对接课表或者学生课表就能达到效果。
对接缺点：课表功能不全，基础数据不完善
同步方式：手动拉取课表数据
对接内容：1.同步课表数据，例如：课表接口（本周/下周）数据等，通过获取课表接口数据组装出行政班课表和教学班课表。
2.同步学生详细信息接口，根据接口中不同学生账号请求学生课表接口数据，班牌接口返回学生课表（本周/下周）数据，进行单个学生课表数据展示（可选，根据项目需求使用）。
接口使用: 获取课表接口getSchedule，获取单个学生课表接口（需要平台额外提供文档，不建议开发）。
5、注意事项【重要】
（1）课表接口返回数据可能增加字段，但不会删减字段，解析json时，请处理。
（2）课表获取全校本周课表，周一到周天【1-7天】。
（3）课表接口数据schedule为空，请联系排课系统人员发布课表，进行对接。
（4）课表接口教室，老师不是必填项，对班牌可能必填项，请联系排课系统完成补充完整且在同步数据时做处理。
（5）排课接口教师一节课教师是存在多个，默认是一个老师上课，但是代课老师，老师轮流周上课等情况。
（6）排课系统发布是按学校排课，例如高一，高二，高三联排，接口返回三个年级课表数据。
（7）课表发布总是以今天开始计算，昨天课表是上一张课表，每次发布课表按发布时间覆盖，例如：当天发布课表，当天之后有课，当天之前课表为空或上一个课表【如果需要可以联系提前发布课表】
（8）timeSettings全校作息时间（当天作息）【注：全校作息和年级作息只能生效一个，另一作息为空】
五、课表与考勤
1、简述
平台考勤系统是指一套管理学生上下课等考勤信息管理系统，电子班牌和考勤系统结合进行学生打卡记录工作，学校能够实时掌握学生的出勤状态。
2、使用要求
接口超时时间设置尽量长一些，减少并发访问。
基础数据同步时需根据id字段为唯一键更新其他字段。
为减小传输量，返回结果可以使用gzip压缩；班牌系统可以通过在向排课系统请求的HTTP头部（HTTP HEADER）加入accept-encoding字段实现，如accept-encoding: gzip。
3、场景说明
班牌系统定期向平台走班管理系统推送考勤数据，若使用班牌系统自带走班考勤功能则无需与平台对接考勤接口。
方案一
使用场景：同步基础数据+推送考勤数据
使用频率：高
场景描述：由班牌系统定时推送数据到考勤系统，考勤系统正确显示学生上课打卡记录。
同步方式：定时或定期推送考勤数据。
对接内容：1.基础数据和课表数据，例如：基础数据学生接口，课表接口（本周/下周）数据。
2.定期推送考勤打卡数据到考勤系统。
接口使用: ${BASEURL}/classadmin/loadCheckings 上传考勤数据接口。