架构与数据流

本页聚焦客户端核心架构、会话生命周期、后台任务与主要业务链路，帮助快速理解整体运行方式。

总体架构

Vue UI (前端)
   |  /v2 API
   v
HTTP Bridge (127.0.0.1:4399)
   |  调用 Rust Core
   v
Rust Core (业务模块 + 会话 + 缓存)
   |  访问校内系统 / 解析数据
   v
SQLite 缓存与本地快照

UI 与 Core 完全分离，所有业务请求通过 Bridge 统一封装为结构化响应，便于外部应用对接。

启动与会话流程

启动时读取本地 cookie 快照与用户缓存。
检测会话有效性，失效则触发 CAS 重新登录。
Bridge 启动监听，UI 通过 /v2 语义调用。
业务数据写入 SQLite 缓存，离线可读。

业务链路概览

成绩 / 课表

拉取教务系统页面并解析，写入 grades_cache / schedule_cache。

电费 / 消费记录

通过 SSO 获取 token，调用一码通接口，失败时走刷新与重试。

全校课表

先获取选项与节次，再分页请求列表并清洗 HTML。

空教室 / 排名 / 考试

统一走 HbutClient 会话，结果落入缓存，支持离线展示。

图书查询

通过馆藏接口检索并解析详情，前端侧支持筛选和封面展示。

资料分享（WebDAV）

目录列表与文件流通过统一代理链路处理，支持预览、下载与分享。

后台检查与通知链路

检查项：课表静默刷新、成绩变更检测、考试提醒、电费余额监控。

触发策略：应用启动立即执行 1 次，之后按通知设置周期轮询。

电费逻辑：读取电费模块已选房间缓存，实时请求余额，低于 10 度触发通知。

去重策略：基于签名缓存避免重复发送同一类通知。

移动端：基于 Capacitor Background Fetch，支持 kill 后周期拉起任务（受系统省电策略约束）。

缓存与离线策略

所有可复用数据统一写入 SQLite，避免频繁登录与重复请求。

当网络不可用时，优先读取缓存并标记“缓存时间”。

缓存更新失败不会阻塞 UI，提示用户手动刷新或稍后重试。

目录类数据（如资料分享）采用 TTL 机制（默认 15 分钟）避免重复远程请求。

OCR 识别链路支持远程配置优先 + 本地兜底，保障验证码登录可用性。

字体、pdf.js、xgplayer、katex 等资源采用首次加载 + 缓存复用策略，降低包体积。

推荐阅读路径