#客户端相关

#客户端打开没有任何显示

1. 检查是否处于离线状态。鼠标悬停在任务栏图标上即可查看客户端网络状态。在客户端第一次正确连接到服务端之前，为了防止显示异常，不会显示任何 UI。

2. 检查是否处于滞留启动。滞留启动是客户端的一种启动流程，正常完成启动流程但不显示任何 UI。启动流程受服务端控制，请在控制台中对应班级的通用设置页检查启动行为是否为"正常"。

#客户端一打开就退出

客户端在两种情况下会主动退出：

1. 启动行为被设置为"退出"。修复方法见上一个问题。

2. 系统主题不是 Aero。软件创建透明窗口依赖 Aero 主题效果。

针对第二种情况，仍然存在两种情况会导致系统主题不是 Aero：

1. 人为调整：

   • 右键桌面空白处
   • 打开"个性化"
   • 在"Aero 主题"中任意选择一个
   • 再次启动应用

2. 其他软件干扰（见下一个问题）

#软件运行过程中莫名其妙退出

这极有可能是其他软件干扰。目前已知的是，腾讯会议在录屏或共享屏幕时会把系统主题暂时切换为 Windows Basic，即关闭 Aero 效果。此时如果强行运行软件，软件会发生严重的显示错误。经验而言，许多老师在面对一个错误提示框时往往不知所措，所以软件会静默退出。

部分软件可能会在运行结束后恢复 Aero 主题效果，此时只要重新打开软件即可。如果软件没有自动恢复，可以通过重启来尝试恢复。如果仍然不行，可参考上一个问题中"人为调整"的解决方案。

#客户端窗口遮挡了白板或课件？

AstraSchedule 窗口设计为半透明悬浮窗，支持以下操作：

• 鼠标悬停 → 窗口降至几乎透明，不遮挡内容
• 鼠标移开 → 窗口恢复不透明度，可正常查看
• 托盘菜单 → 可开关「窗口置顶」

「点击穿透」为固定开启（悬停时自动临时关闭以便操作），无需也无法在菜单中关闭。

#天气不显示或显示错误？

排查步骤：

1. 检查 config.toml 中天气 API 配置是否正确：

   [apikey]
   apihost = "YOURS.re.qweatherapi.com"  # 和风天气 API 域名
   weather = "YOUR_API_KEY"               # API Key
2. 检查客户端托盘菜单 → 「当前地区」，确认选中的地区正确
3. 检查和风天气 API 调用配额：
   • API Key 方式：1000 次/天（按 IP 计数），多个客户端共用可能超限
   • JWT 方式：无调用次数限制，推荐使用
4. 如果使用 API Key 方式且客户端数量较多（如 30+ 个班级），建议升级到和风天气 JWT 认证，免费且不限制调用次数。

#倒数日窗口不显示？

排查步骤：

1. 确认管理端已配置倒数日（「倒数日管理」页面）
2. 检查倒数日的「生效域」是否覆盖了当前班级：在倒数日配置中，查看「生效年级」和「生效班级」，确保当前班级在生效范围内
3. 检查倒数日是否已过期：过期的倒数日会自动隐藏
4. 确认倒数日日期未过期（倒数日按单日计算，仅在其日期当天生效）

#自动更新失败？

常见原因及解决：

1. 更新源设置错误：托盘菜单 → 「更新源设置」，确认 URL 正确
2. 网络不通：内网防火墙可能设置了白名单，需要自建镜像源
3. Windows 7 特殊情况：
   • 安装 KB2999226 和 KB2533623 补丁
   • 或手动下载安装包覆盖安装（Releases 页面下载 .exe 安装包）

#课表上科目名称显示不对？

检查「科目管理」中的简称和全名映射关系：

• 简称：显示在课表上的文字，支持 @ 下角标语法（如 自@物 → 自ᵥ）
• 全名：完整的科目名称，用于识别

简称和全名对应错的话，更新科目管理中的映射即可。

#为什么客户端课表没有自动更新？

客户端在以下时机拉取最新配置：启动、WebSocket 重连成功、收到服务端 SyncConfig 推送、托盘菜单手动点「更新课表」。如果课表没有自动更新：

1. 手动更新：托盘菜单 → 「更新课表」，立即拉取最新配置（任何模式下都可用）
2. WebSocket 模式下，后台保存配置后服务端会自动向相关班级广播 SyncConfig 通知客户端刷新
3. 检查 WebSocket 连接是否正常：鼠标悬停任务栏图标可查看客户端连接状态，如果显示离线，排查网络和后端状态
4. 极低成本方案（Serverless）不使用 WebSocket，配置变更后不会推送；客户端仅在启动或重连时拉取，修改配置后请手动点击「更新课表」。