软件模块介绍

本指南将详细介绍 XJTUToolBox 的各个模块及其功能，帮助您快速定位开发所需的部分，并深入了解其设计。

总体结构

XJTUToolBox 是一个基于 PyQt5 的桌面应用，支持 Windows、macOS 与 GNU/Linux。项目主要目录结构如下：

.
├── .github/        # GitHub Action 定义文件
├── app/            # 应用 GUI 界面
├── assets/         # 界面资源 (图标, QSS 样式表)
├── attendance/     # 本科/研究生考勤系统 API
├── auth/           # 统一身份认证登录 API
├── docs/           # 应用文档 (本网站源代码)
├── gmis/           # 研究生管理信息系统 API (课表, 成绩)
├── gste/           # 研究生评教系统 API
├── jwapp/          # 移动教务 API（成绩）
├── jwxt/           # 本科教务系统 API (课表, 成绩, 评教, 空闲教室)
├── notification/   # 通知查询 API (爬虫及相关类)
├── schedule/       # 课表数据库相关 (时间计算, 数据库, 节假日)
├── test/           # 模块测试
├── ywtb/           # 新师生服务大厅 API
├── app.py          # 应用主程序
└── updater.py      # Windows 自动更新子程序

软件主要分为三个核心部分：

1. API 部分: 负责与西安交通大学的各项服务进行交互。这部分代码（如 attendance, auth, jwxt 等模块）不包含任何 GUI 逻辑，完全独立，可用于构建你自己的应用。
2. GUI 界面部分: 位于 app 文件夹，包含了应用的所有图形界面代码。
3. 文档部分: 位于 docs 文件夹，是你当前正在浏览的这个文档网站的源代码。

在开始设计时，我们希望程序的 UI 界面部分和服务器 API 请求部分相互分离，这样服务器 API 请求相关的代码可以被独立使用，而不依赖于 GUI 主程序。 因此，API 部分的代码分散在各个子目录中，和 GUI 部分代码分离，完全不包含任何与界面相关的逻辑。

API 部分

此部分是整个项目的数据核心，封装了与西安交通大学各项服务的 API 交互。

auth

此模块是所有功能的基础，用于登录采用统一身份认证的校内系统。通过它，您可以使用用户名和密码获取一个已登录的 Session 对象，用于后续的 API 请求。

通用与专用登录

大多数情况下，登录不同系统只需更换“触发登录的 URL”即可。但部分系统有特殊的认证机制（例如，要求在请求头中携带特定的 JWT），我们为这些系统提供了专用的登录类（通常命名为 xxxxLogin）。开发时请优先使用这些专用类。

存在特殊登录机制的系统如下：

1. attendance: 本科生/研究生考勤系统
   • 要求: 请求头需携带 Synjones-Auth 字段，其值为特定 Token。
2. jwapp: 本科生移动教务系统
   • 要求: 请求头需携带 Authorization 字段，其值为特定 Token。
3. ywtb: 新师生综合服务大厅
   • 要求: 请求头需携带 x-device-info, x-terminal-info 以及值为特定 Token 的 x-id-token。

详情请见 auth 模块 介绍。

attendance

此模块用于查询本科生及研究生的考勤信息，支持查询周考勤、自定义时间范围考勤、考勤流水与详情等。

网络限制

考勤系统仅限校内网络访问。在校外，您需要通过 WebVPN 才能连接，本模块已内置 WebVPN 登录支持。

详情请见 attendance 模块 介绍。

教务系统

此模块对应本科教务系统，功能包括：课表查询、成绩查询、一键评教、空闲教室查询。

详情请见 教务系统模块 介绍。

gmis

此模块对应研究生管理信息系统，目前支持研究生的课表查询与成绩查询。

详情请见 gmis 模块 介绍。

jwapp

此模块对应本科生移动教务系统，支持课表与成绩查询。

此系统曾提供排名查询接口，但该功能已于 2024 年末被学校下线，相关接口现已失效。

详情请见 jwapp 模块 介绍。

notification

此模块用于聚合与解析来自各渠道的通知，主要包含：

1. 通知筛选规则、通知存储器等实用工具类。
2. 教务处、研究生院、软件学院等网站的通知爬虫。

详情见 notification 模块 介绍。

ywtb

此模块对应新师生综合服务大厅，支持登录、查询学生基本信息（姓名、学号）以及学期开始日期。

详情见 ywtb 模块 介绍。

GUI 部分

此部分包含了程序所有与图形界面相关的代码，绝大部分位于 app 文件夹内。

• app 文件夹下的 *Interface.py 文件对应了主窗口侧边栏的各个一级界面，如主页、课表、成绩等。
• sub_interfaces/ 包含了所有对话框及二级界面，如一键评教、通知查询等。
• cards/ 和 components/ 存放了自定义的 UI 组件。
• sessions/ 定义了程序中使用的所有 Session 对象。详情请参考 Session 设计 页面。
• threads/ 存放了所有与网络通信相关的子线程。为防止界面卡顿，所有耗时操作均在子线程中进行。详情请参考 子线程设计 页面。
• utils/ 包含各类实用工具，如账户管理、配置读写、日志记录等。

文档部分

文档部分即为本网站的源代码，位于 docs 文件夹。如果您有兴趣参与完善文档，请参考 文档站设计 页面，了解如何在本地预览和修改。