## 立项背景与目标
MUS Booking System 面向香港中文大学(深圳)音乐学院琴房预约,解决官方系统登录繁琐、网络敏感、热门琴房成功率低等问题。项目提供生产级(v2.10.0)自动化工具,在 VPN、校园网或 Reqable 环境下一键完成登录、批量与定时抢房,在满足校内安全要求前提下提升成功率和体验。
## 软件功能与核心模块
### 自动登录与 Cookie
通过 GUI 一键登录,自动填写学号与密码、提交表单并抓取 Cookie,保证身份合法和会话稳定。
### 智能网络适配
自动识别校园网/VPN、Reqable(127.0.0.1:9000)及系统代理,也可在 Cookie 面板手动检测,确保对 SSL 要求严格的校内接口在不同网络下可访问。
### 定时与批量预订
支持“立即执行”与“定时执行”,可将多个琴房与日期组合成一个任务并按优先级依次尝试,一旦成功即停止;超过 2 小时的请求会自动拆分为多个 2 小时时段,以符合教务规则。
### GUI 客户端与预订引擎
桌面端由 src/GUI.py 提供主窗口、设置、Cookie、自动登录与任务管理等界面;核心逻辑由 src/main.py 中的 CrazyRequests 与 book() 完成,封装 SSL 容错、代理路由、统一 UA/Cookie 头及琴房 ID 映射,并在失败时返回可读错误信息。
### 配置与质量保障
config.yaml 统一保存启动时间、执行模式、代理与 Cookie 信息、用户档案及请求列表,便于在“单次抢房/连续预约”等场景间复用。测试脚本覆盖网络、SSL、Qt 代理、预约接口和自动登录,配合 PySide6、WebEngine、PyYAML、requests 等依赖,保证主要平台的一致行为。
## 业务流程与功能路径
###准备:下载并解压发行包,在“设置”中填写学号、密码、联系方式等,可通过“自动检测”完成 VPN/代理适配和配置初始化。
###建模:在主界面点击“+ 添加一组预定请求”,选择琴房、日期和时间段,可设置多个备选方案,自动写入 config.yaml。
###执行:选择立即或定时启动后,AutoLogin 获取最新 Cookie,BookingWorker 依次调用 book() 提交请求,并按规则进行 2 小时拆分与“成功即停”。
###结果与复盘:日志实时显示成功记录及失败原因(如 Cookie 过期、网络异常、放号竞争失败等),用户可据此排查网络或更新 Cookie,并结合历史记录优化后续策略。
综合来看,MUS Booking System 通过可视化配置界面、稳健预订引擎、智能网络适配及完善测试文档,构建了“准备 → 建模 → 执行 → 反馈与复盘”的闭环流程,有效降低琴房预约的人力成本和失败风险。
## 整体架构与设计思路
项目按 MVC 分层:PySide6 组件树做 View,MainWindow 负责信号-slot 调度与任务编排;config、workers 承载数据与业务,配合 requests 和自研 CrazyRequests 组成网络层对接订房接口。目录按“核心逻辑 + GUI 组件 + 对话框 + 工具层”拆分,旧版 GUI.py 与新模块并行,便于重构排错。
配置用 dataclass + YAML,用于持久化用户数据及 UI 默认值、表单回填。BookingWorker 将定时器、拆单和日志信号放入 QThread,避免界面阻塞。CrazyRequests 自动处理 SSL、代理和 Cookie,并与 ProxyDetector 联动,使“开始”按钮一键串起 Cookie 捕获、请求构造与日志展示。
##模块与技术栈
View 由 widgets、dialogs 组成;Controller 为 MainWindow;Model / Service 为 AppConfig、RequestItemData、book()、timer_run()、BookingWorker,对订房接口做封装与调度。通过 PyInstaller 多文件打包和自定义 spec 生成约 207MB 的开箱即用发行版。主要依赖 PySide6/QtWebEngine、requests/CrazyRequests、PyYAML/dataclasses 及系统接口;tests 覆盖网络、SSL、代理和自动登录回归。
##坑与难点及解决方案
1)SSL 握手失败
AnyConnect VPN 下接口对 requests 持续抛出握手失败,而 Qt WebEngine 与 Reqable 可正常 TLS。最终方案:自动登录走 WebEngine 直连,请求统一经 Reqable 代理;ProxyDetector 按“直连 → Reqable → 系统代理”回退,并将结果落盘,重启可复现稳定路径。
2)自动获取 Cookie 与降级
通过 AutoLoginDialog 内嵌 QtWebEngine,集成浏览器控件,在捕获成功 URL 后延迟提取 Cookie,同时将 Reqable 写入 QtNetwork.QNetworkProxy,保持与流程代理一致;缺少 WebEngine 时提供手动粘贴 Cookie 的降级,并校验关键字段,避免写入无效配置。
3)多线程定时抢房
热门琴房需在时间窗口内 POST 并拆分时段。BookingWorker 将等待与请求循环放入 QThread,通过信号回传日志和完成事件,防止卡顿;timer_run() 统一“立即/定时启动”的等待逻辑,只靠延迟区分;时段拆分、防重入与批量备选顺序集中在 worker 中,便于调试扩展。