故障排查

先判断范围

• 只有一个模块异常时，优先在对应页面刷新、切换筛选项、重新选择学期或房间；多个教务模块同时失败时，先判断是否是教务系统维护或登录会话问题。
• 只有桌面端异常时，检查 Tauri、HTTP Bridge、系统通知、文件导出和 WebView2；只有移动端异常时，检查 Capacitor 权限、后台白名单、系统电池策略和 iOS 证书。

再看状态文案

• 出现会话过期、登录失效、验证码识别失败、教务系统维护、离线、sync_time、请求超时、权限被拒绝等文案时，不要直接清空数据，先保留现场。
• 有离线缓存时，页面一般会继续显示旧数据并附带 sync_time；没有缓存时，首次请求失败只能重试或重新登录。

最后收集证据

• 用户反馈前先进入设置 → 调试日志，筛选 Error 或 Warn，复制最近日志；进入问题反馈页时也可以点击复制最近 error。
• 开发者复现前先记录平台、版本、账号登录方式、触发页面、网络环境、是否启用云同步、是否存在远程配置覆盖和完整复现步骤。

Windows SmartScreen

Windows 首次安装或运行时提示未知发布者、SmartScreen 拦截。

1. 确认安装包来自发布页或可信下载源。
2. 点击“更多信息”后选择“仍要运行”。
3. 如果 WebView2 安装失败，重新联网安装或使用系统组件修复后再启动。

macOS 无法验证开发者

macOS 打开应用时提示无法验证开发者或应用已损坏。

1. 在系统设置的隐私与安全性中允许打开 Mini-HBUT。
2. 必要时对 App 执行 xattr -cr 清理隔离属性。
3. 如果仍打不开，重新下载完整 dmg，避免半包或浏览器拦截造成损坏。

Linux WebKit2GTK

Linux AppImage 或 deb 启动失败，常见原因是系统缺少 WebKit2GTK 运行库。

1. Debian/Ubuntu 系发行版优先安装 libwebkit2gtk-4.1-0。
2. AppImage 需要执行权限，可通过 chmod +x 处理。
3. 如果命令行启动有缺依赖提示，先补齐系统包再反馈。

Android 覆盖安装

Android 更新后担心数据丢失，或安装失败。

1. 同一包名的新版 APK 可直接覆盖安装，通常保留本地登录态、缓存和设置。
2. 安装失败时检查签名是否来自同一发布渠道；签名不一致时系统会拒绝覆盖。
3. 通知不准或后台任务中断时，将 Mini-HBUT 加入后台白名单并关闭过度省电限制。

iOS 证书

iOS 侧载后无法打开、证书过期或闪退。

1. 在 VPN 与设备管理中信任开发者证书。
2. 个人 Apple ID 签名通常有有效期限制，过期后需要重新签名安装。
3. SideStore、LiveContainer 或其他容器异常时，先确认容器本身可运行，再重新导入应用。

教务系统维护

• 前端会用 looksLikeMaintenanceIssue 判断 timed out、维护、暂不可用、连接失败等文本，并写入 hbu_jwxt_maintenance、hbu_jwxt_maintenance_time、hbu_jwxt_maintenance_hint。
• 维护期间教务类缓存键可能显示离线缓存。离线缓存带 offline 和 sync_time，只能说明数据来自上次成功请求。
• 维护结束后重新打开页面或手动刷新；如果 hbu_jwxt_maintenance 长时间残留，先完成一次成功请求再判断是否仍异常。

离线缓存与容量

• fetchWithCache 会先读内存和 localStorage 的 cache:*，网络失败时可能用 withOfflineMeta 包装旧数据。
• localStorage 写入遇到 QuotaExceeded 时，会调用 trimLocalCacheStorage 清理旧 cache:* 条目，再尝试写入。
• 首次使用没有缓存时，离线模式不会凭空生成数据；用户看到空状态不一定是 bug。

成绩/课表不是最新

• 成绩、课表、考试、排名、校历等模块会使用缓存减少重复请求。需要最新数据时，优先手动刷新或切换学期触发重新请求。
• 如果页面显示 sync_time，说明当前数据来自缓存或后端离线兜底，不代表教务系统实时状态。
• 课表预热、Widget 快照和通知检查也会消费缓存，用户应先确认主页面数据已刷新。

全校课表没有结果

• 先减少筛选条件，只保留学年学期或关键字段，再逐步增加院系、专业、教师、课程名。
• 筛选条件组合过窄、教务维护、学期不匹配或公共缓存过期都可能导致空结果。
• 如果 qxzkb_public_cache 存在旧数据，页面可能显示离线兜底；否则需要等待远端恢复。

电费查询失败

• 首次使用需要完成校区、楼栋、楼层、房间选择；通知中心也依赖这个房间信息检查低余额。
• 电费查询涉及 SSO token、电费 token 和 refresh token，过期后会尝试刷新；刷新失败时重新登录更可靠。
• 照明用电和空调用电是两个查询维度，单边失败时先确认房间选择和学校服务状态。

资料分享连接失败

• 资料分享依赖远程配置中的 WebDAV endpoint、用户名和密码。
• 连接失败时先检查网络、校园网/VPN、远程配置是否加载成功，以及 WebDAV 服务是否临时不可用。
• 图片预览、PDF 预览、Office 在线预览和直链下载是不同链路，某一种失败不代表全部文件不可用。

AI 助手无响应

• 校园助手依赖远程 AI 服务、本地会话、一码通 token 或 AI token。初始化失败时先查看设置中的后端状态。
• 文件上传受大小和格式限制，20 MB 以上文件或不支持的格式会被拒绝。
• 远程模型列表来自远程配置，模型暂时不可用时可切换模型或稍后重试。

导出 ICS

• 课表 ICS 导出后需要使用支持 .ics 的日历应用导入。
• 桌面端通常保存到用户选择的路径，移动端更依赖系统分享能力。
• 导入后时间不对时，先确认学期开始日期、周次、课程节次和日历应用时区。